From 4e28739f2dd3ea9d89e197e6c64bc520b0cf0274 Mon Sep 17 00:00:00 2001 From: recombinatrix Date: Mon, 17 Feb 2025 17:01:31 +1100 Subject: [PATCH 1/4] first pass at documentation update --- README.md | 24 ++++---- ...d_PEI_linear.py => 01_build_PEI_linear.py} | 0 ...otactic.py => 02a_build_PMMA_isotactic.py} | 0 ...ctic.py => 02b_build_PMMA_syndiotactic.py} | 7 +++ ...3-atactic.py => 02c_build_PMMA_atactic.py} | 0 ..._build_PMMA_atactic_with_linear_extend.py} | 0 polyconf_examples/README.md | 61 +++++++++++++++++++ 7 files changed, 80 insertions(+), 12 deletions(-) rename polyconf_examples/{build_PEI_linear.py => 01_build_PEI_linear.py} (100%) rename polyconf_examples/{build_PMMA_01-isotactic.py => 02a_build_PMMA_isotactic.py} (100%) rename polyconf_examples/{build_PMMA_02-syndiotactic.py => 02b_build_PMMA_syndiotactic.py} (87%) rename polyconf_examples/{build_PMMA_03-atactic.py => 02c_build_PMMA_atactic.py} (100%) rename polyconf_examples/{build_PMMA_04-atactic-linearized.py => 02d_build_PMMA_atactic_with_linear_extend.py} (100%) create mode 100644 polyconf_examples/README.md diff --git a/README.md b/README.md index 17b5196..73f8091 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,12 @@ -# Setup for PolyConstruct +# PolyConstruct: adapting biomolecular simulation pipelines for polymers with PolyBuild, PolyConf and PolyTop + +## Documentation + +The full documentation is available at the [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/index.html). This includes installation instructions, documentation for all polyconstruct methods, and several worked examples and tutorials. + +There are also example scripts demonstrating the use of PolyConf in the folder [polyconf_examples](https://github.com/OMaraLab/polyconstruct/tree/main/polyconf_examples), and example scripts demonstrating the use of PolyTop in the folder [polytop_examples](https://github.com/OMaraLab/polyconstruct/tree/main/polytop_examples) + +## How to install PolyConstruct From your home directory, install PolyConstruct from Git: @@ -16,21 +24,12 @@ cd polyconstruct To setup polyconstruct, run: ``` -conda create --name polyconstruct-env -conda activate polyconstruct-env +conda create --name polyconstruct python=3.10 +conda activate polyconstruct pip install -r requirements.txt ``` -If you recieve an error in the last step, it may be from the Python version on -your computer setup, as PolyTop has a strict requirement for version 3.10. Run -the below commands then repeat `pip install -r requirements.txt` : - -``` -conda uninstall python -conda install "python=3.10" -``` - Then, build the PolyTop, PolyConf and PolyBuild packages: ``` @@ -46,3 +45,4 @@ cd ../polybuild pip install -e . ``` + diff --git a/polyconf_examples/build_PEI_linear.py b/polyconf_examples/01_build_PEI_linear.py similarity index 100% rename from polyconf_examples/build_PEI_linear.py rename to polyconf_examples/01_build_PEI_linear.py diff --git a/polyconf_examples/build_PMMA_01-isotactic.py b/polyconf_examples/02a_build_PMMA_isotactic.py similarity index 100% rename from polyconf_examples/build_PMMA_01-isotactic.py rename to polyconf_examples/02a_build_PMMA_isotactic.py diff --git a/polyconf_examples/build_PMMA_02-syndiotactic.py b/polyconf_examples/02b_build_PMMA_syndiotactic.py similarity index 87% rename from polyconf_examples/build_PMMA_02-syndiotactic.py rename to polyconf_examples/02b_build_PMMA_syndiotactic.py index 249aab2..d30b7dc 100644 --- a/polyconf_examples/build_PMMA_02-syndiotactic.py +++ b/polyconf_examples/02b_build_PMMA_syndiotactic.py @@ -4,6 +4,7 @@ from polyconf.Polymer import Polymer from polyconf.PDB import PDB import random + random.seed(1) @@ -62,3 +63,9 @@ Saver = PDB(PMMA_syndiotactic) Saver.cleanup() # center in box Saver.save(dummies=dummies,fname='PMMA_syndiotactic_shuffled_and_solved') # save, excluding dummies atoms + + +# shuffler() will generate a random conformation by shuffling dihedrals. +# Some conformations generated with shuffler() cannot be easilly solved. In this example, we have chosen a random seed that will work reliably. +# Controlling the random seed can also be useful for replicability in your scripts. +# After you have completed the tutorial, try varying the random seed, and comparing the resulting conformations. diff --git a/polyconf_examples/build_PMMA_03-atactic.py b/polyconf_examples/02c_build_PMMA_atactic.py similarity index 100% rename from polyconf_examples/build_PMMA_03-atactic.py rename to polyconf_examples/02c_build_PMMA_atactic.py diff --git a/polyconf_examples/build_PMMA_04-atactic-linearized.py b/polyconf_examples/02d_build_PMMA_atactic_with_linear_extend.py similarity index 100% rename from polyconf_examples/build_PMMA_04-atactic-linearized.py rename to polyconf_examples/02d_build_PMMA_atactic_with_linear_extend.py diff --git a/polyconf_examples/README.md b/polyconf_examples/README.md new file mode 100644 index 0000000..1e43a7c --- /dev/null +++ b/polyconf_examples/README.md @@ -0,0 +1,61 @@ +# PolyConf examples + +This folder contains several example scripts demonstrating the use of PolyConf. All the files you need to run these examples are contained within this folder. + +## Tutorial 01: Building a linear polyethyleneimine polymer conformation using PolyConf + +The first tutorial is an example of how to make a linear 128 unit polyethyleneimine chain using `PolyConf`. It is contained in the file `01_build_PEI_linear.py` + +This tutorial showcases several approaches, including: + +* building a polymer chain with `extend()` +* two strategies for building a pseudo-linear polymer chain using `extend()` +* using `dihedral_solver()` to adjust the polyethyleneimine conformation +* using `shuffler()` and `dihedral_solver()` to generate a random polyethyleneimine conformation + +TYhis tutorial is all contained in a single script. There are detailed comments discussing the strategies used, and the limitations of the resulting conformations. You are encouraged to examine the conformations generated by this script in [VMD](https://www.ks.uiuc.edu/Research/vmd/), or another visualization tool of your choice, to understand the strengths and limitations of the different strategies. + +## Tutorial 02: Strategies for building conformations of polymers with different types of tacticity, or copolymers with different monomer distributions + +The second tutorial shows strategies for making polymers with different types of [tacticity](https://en.wikipedia.org/wiki/Tacticity). Using poly methyl methacrylate, this lesson showcases a strategy for making an isotactic polymer, a syndiotactic polymer, and an atactic polymer. These strategies use two monomers, `MMAD_bonds.pdb` and `MMAL_bonds.pdb`. + +In these examples, the two monomers are enantiomers. However, these strategies are also applicable to the creation of [copolymers](https://en.wikipedia.org/wiki/Copolymer), where the monomers are chemically distinct. + +This tutorial is split into four scripts. Each script includes detailed comments regarding the strategy used. After you read and execute each script, you should take a moment to examine the generated conformations in VMD, or another visualization tool of your choice. + +### Building an isotactic PMMA polymer + +`02a_build_PMMA_isotactic.py` shows a strategy for building an isotactic PMMA polymer, in which all monomers have the same tacticity. The method is very similar to the approach used in tutorial 01. + +### Building a sydniotactic PMMA polymer + +`02b_build_PMMA_syndiotactic.py` shows a strategy for building a syndiotactic PMMA polymer, where monomers alternate between two different enantiomers. + +This strategy could be adapted to make an [alternating copolymer](https://en.wikipedia.org/wiki/Copolymer). + +### Failing to build an atactic PMMA polymer + +`02c_build_PMMA_atactic.py` shows how to build an atactic PMMA polymer, with tacticity of the monomers distributed randomly along the chain. + +This approach could also be adapted to generate a [statistical copolymer](https://en.wikipedia.org/wiki/Copolymer). + +This tutorial will fail, intentionally! We have chosen a specific random seed, which will reliably fail to generate a valid starting conformation. We made this decision to showcase some of the challenges in generating polymers wherte monomers are arranged in a random or stochastic order. + +There is a discussion at the end of this script, which contain several suggestions for addressing these challenges. You should try implementing those strategies until you can successfully generate a valid starting conformation. + +### Building an ensemble of starting conformations for an atactic PMMA polymer, using `extend()` with `linearise=True` + + +`02d_build_PMMA_atactic_with_linear_extend.py` showcases one solution to generate an ensemble of starting conformations for an atactic PMMA polymer. + +This example is one solution to resolve the difficulties showcased in `02c_build_PMMA_atactic.py`. This strategy uses `extend()` with `linearize=True` to produce a pseudo-linear conformation. It then applies `shuffler()` and `dihedral_solver()` to generate an ensemble of five starting conformations for use in replicate molecular dynamics simulations. + +This type of approach could also be used to generate a [statistical copolymer](https://en.wikipedia.org/wiki/Copolymer). + +## Tutorial 03: Building a branched polyethyleneimine polymer conformation using PolyConf + +To be written + +## Tutorial 04: Building a hyperbranched polyethyleneimine polymer conformation using PolyConf + +To be written From 7ebf6b3230a01fe3b7316abf6e8d22533710788b Mon Sep 17 00:00:00 2001 From: recombinatrix Date: Mon, 17 Feb 2025 17:17:38 +1100 Subject: [PATCH 2/4] documentation and tutorials --- README.md | 25 ++++++++++--------- docs/README.md | 11 ++++---- .../02b_build_PMMA_syndiotactic.py | 8 ++++-- polyconf_examples/README.md | 17 +++++++------ 4 files changed, 34 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 73f8091..33a6abc 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,31 @@ -# PolyConstruct: adapting biomolecular simulation pipelines for polymers with PolyBuild, PolyConf and PolyTop +# PolyConstruct: a python library for polymer generation -## Documentation +PolyConstruct contains three python tools for generating polymer coordinate and topolgy files for molecular dynamics simulations. It was published in the paper *PolyConstruct: adapting biomolecular simulation pipelines for polymers with PolyBuild, PolyConf and PolyTop*. -The full documentation is available at the [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/index.html). This includes installation instructions, documentation for all polyconstruct methods, and several worked examples and tutorials. +## PolyConstruct guides -There are also example scripts demonstrating the use of PolyConf in the folder [polyconf_examples](https://github.com/OMaraLab/polyconstruct/tree/main/polyconf_examples), and example scripts demonstrating the use of PolyTop in the folder [polytop_examples](https://github.com/OMaraLab/polyconstruct/tree/main/polytop_examples) +Detailed documentation is available at the [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/index.html). This includes installation instructions, tutorials and worked examples, and api documentation for all polyconstruct methods. -## How to install PolyConstruct +There are also detailed tutorials for PolyConf in the folder [polyconf_examples](https://github.com/OMaraLab/polyconstruct/tree/main/polyconf_examples), and detailed tutorials for PolyTop in the folder [polytop_examples](https://github.com/OMaraLab/polyconstruct/tree/main/polytop_examples) -From your home directory, install PolyConstruct from Git: +## Quick and dirty installation -``` +From your home directory, clone PolyConstruct from Git: + +```bash cd ~ git clone https://github.com/OMaraLab/polyconstruct.git ``` Then navigate to polyconstruct: -``` +```bash cd polyconstruct ``` -To setup polyconstruct, run: +To setup polyconstruct, run: -``` +```bash conda create --name polyconstruct python=3.10 conda activate polyconstruct @@ -32,7 +34,7 @@ pip install -r requirements.txt Then, build the PolyTop, PolyConf and PolyBuild packages: -``` +```bash cd polytop pip install -e . @@ -45,4 +47,3 @@ cd ../polybuild pip install -e . ``` - diff --git a/docs/README.md b/docs/README.md index 71b7b24..3134f65 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,15 +1,18 @@ -# Compiling mda-openbabel-converter's Documentation +# THE DOCUMENTS IN THIS FOLDER ARE NOT INTENDED TO BE HUMAN READABLE + +If you are looking for the PolyConstruct documentation, please go to the [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/index.html) + +## Compiling Documentation The docs for this project are built with [Sphinx](http://www.sphinx-doc.org/en/master/). To compile the docs, first ensure that Sphinx and the ReadTheDocs theme are installed. - ```bash conda install sphinx sphinx_rtd_theme ``` - Once installed, you can use the `Makefile` in this directory to compile static HTML pages by + ```bash make html ``` @@ -17,8 +20,6 @@ make html The compiled docs will be in the `_build` directory and can be viewed by opening `index.html` (which may itself be inside a directory called `html/` depending on what version of Sphinx is installed). - A configuration file for [Read The Docs](https://readthedocs.org/) (readthedocs.yaml) is included in the top level of the repository. To use Read the Docs to host your documentation, go to https://readthedocs.org/ and connect this repository. You may need to change your default branch to `main` under Advanced Settings for the project. If you would like to use Read The Docs with `autodoc` (included automatically) and your package has dependencies, you will need to include those dependencies in your documentation yaml file (`docs/requirements.yaml`). - diff --git a/polyconf_examples/02b_build_PMMA_syndiotactic.py b/polyconf_examples/02b_build_PMMA_syndiotactic.py index d30b7dc..17529eb 100644 --- a/polyconf_examples/02b_build_PMMA_syndiotactic.py +++ b/polyconf_examples/02b_build_PMMA_syndiotactic.py @@ -20,7 +20,9 @@ Monomer_D='MMAD_bonds.pdb' Monomer_L='MMAL_bonds.pdb' -alternator=True +alternator=True # This is a boolean we will use to alternate between the two enantiomers. +# When the alternator is True, the next monomer will be Monomer_L. +# When the alternator is False, the next monomer will be Monomer_D. PMMA_syndiotactic=Polymer(Monomer(Monomer_D)) # initialise @@ -31,7 +33,7 @@ monomer=Monomer_L else: monomer=Monomer_D - alternator=not alternator + PMMA_syndiotactic.extend( # extend with one monomer, aligned along this step's linearization vector Monomer(monomer), # extend with this monomer n=PMMA_syndiotactic.maxresid(), # extend existing residue i @@ -40,6 +42,8 @@ joins=[('C','CA')],# new connection between N1_i and C1_i+1 ) + alternator=not alternator # flip the alternator after every monomer + Saver = PDB(PMMA_syndiotactic) Saver.cleanup() # center in box Saver.save(dummies=dummies,fname='PMMA_syndiotactic_vanilla-extend') # save, excluding dummies atoms diff --git a/polyconf_examples/README.md b/polyconf_examples/README.md index 1e43a7c..41e72fb 100644 --- a/polyconf_examples/README.md +++ b/polyconf_examples/README.md @@ -1,10 +1,12 @@ -# PolyConf examples +# PolyConf example scripts -This folder contains several example scripts demonstrating the use of PolyConf. All the files you need to run these examples are contained within this folder. +This folder contains several example scripts demonstrating the use of *PolyConf*. All the files you need to run these examples are contained within this folder. + +For detailed documentation of all PolyConf methods, please refer to the [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/index.html). ## Tutorial 01: Building a linear polyethyleneimine polymer conformation using PolyConf -The first tutorial is an example of how to make a linear 128 unit polyethyleneimine chain using `PolyConf`. It is contained in the file `01_build_PEI_linear.py` +The first tutorial is an example of how to make a linear 128 unit polyethyleneimine chain using *PolyConf*. It is contained in the file `01_build_PEI_linear.py` This tutorial showcases several approaches, including: @@ -39,16 +41,15 @@ This strategy could be adapted to make an [alternating copolymer](https://en.wik This approach could also be adapted to generate a [statistical copolymer](https://en.wikipedia.org/wiki/Copolymer). -This tutorial will fail, intentionally! We have chosen a specific random seed, which will reliably fail to generate a valid starting conformation. We made this decision to showcase some of the challenges in generating polymers wherte monomers are arranged in a random or stochastic order. +The script for this part of the tutorial will fail! This is intentional. We have chosen a specific random seed, which will reliably fail to generate a valid starting conformation. We made this decision to showcase some of the challenges in generating polymers wherte monomers are arranged in a random or stochastic order. -There is a discussion at the end of this script, which contain several suggestions for addressing these challenges. You should try implementing those strategies until you can successfully generate a valid starting conformation. +There is a discussion at the end of this script, which contain several suggestions for addressing these challenges. You should try implementing those strategies until you can successfully generate a valid starting conformation for atactic PMMA. ### Building an ensemble of starting conformations for an atactic PMMA polymer, using `extend()` with `linearise=True` +`02d_build_PMMA_atactic_with_linear_extend.py` showcases one solution to generate an ensemble of starting conformations for an atactic PMMA polymer. -`02d_build_PMMA_atactic_with_linear_extend.py` showcases one solution to generate an ensemble of starting conformations for an atactic PMMA polymer. - -This example is one solution to resolve the difficulties showcased in `02c_build_PMMA_atactic.py`. This strategy uses `extend()` with `linearize=True` to produce a pseudo-linear conformation. It then applies `shuffler()` and `dihedral_solver()` to generate an ensemble of five starting conformations for use in replicate molecular dynamics simulations. +This example is one solution to resolve the difficulties showcased in `02c_build_PMMA_atactic.py`. This strategy uses `extend()` with `linearise=True` to produce a pseudo-linear conformation. It then applies `shuffler()` and `dihedral_solver()` to generate an ensemble of five starting conformations for use in replicate molecular dynamics simulations. This type of approach could also be used to generate a [statistical copolymer](https://en.wikipedia.org/wiki/Copolymer). From a4748b6cf927749537c9566ac2cfbec10c61698b Mon Sep 17 00:00:00 2001 From: recombinatrix Date: Mon, 17 Feb 2025 17:23:33 +1100 Subject: [PATCH 3/4] landing page --- README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 33a6abc..e467b27 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,14 @@ -# PolyConstruct: a python library for polymer generation +# *PolyConstruct*: a python library for polymer generation -PolyConstruct contains three python tools for generating polymer coordinate and topolgy files for molecular dynamics simulations. It was published in the paper *PolyConstruct: adapting biomolecular simulation pipelines for polymers with PolyBuild, PolyConf and PolyTop*. +*PolyConstruct* contains three python tools for generating polymer coordinate and topolgy files for molecular dynamics simulations. -## PolyConstruct guides +*PolyConf* is a tool for generating ensembles of polymer conformations by combining monomer coordinate files. +*PolyBuild* is a tool for generating polymer topology files for simulaton from polymer coordinate files, leveraging the functionality of the gromacs tool pdb2gmx. +*PolyTop* is a tool for generating polymer topology files from monomer topology files. + +*PolyConstruct* was published in the paper *PolyConstruct: adapting biomolecular simulation pipelines for polymers with PolyBuild, PolyConf and PolyTop*. + +## Getting started Detailed documentation is available at the [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/index.html). This includes installation instructions, tutorials and worked examples, and api documentation for all polyconstruct methods. @@ -10,20 +16,20 @@ There are also detailed tutorials for PolyConf in the folder [polyconf_examples] ## Quick and dirty installation -From your home directory, clone PolyConstruct from Git: +From your home directory, clone *PolyConstruct* from this repository: ```bash cd ~ git clone https://github.com/OMaraLab/polyconstruct.git ``` -Then navigate to polyconstruct: +Then navigate to `~/polyconstruct` ```bash cd polyconstruct ``` -To setup polyconstruct, run: +Create a python environment and setup *PolyConstruct*: ```bash conda create --name polyconstruct python=3.10 @@ -32,7 +38,7 @@ conda activate polyconstruct pip install -r requirements.txt ``` -Then, build the PolyTop, PolyConf and PolyBuild packages: +Then, build the *PolyTop*, *PolyConf* and *PolyBuild* packages: ```bash cd polytop From 474161a0269df092e88c3663c5eb2c8c2a75cde8 Mon Sep 17 00:00:00 2001 From: recombinatrix Date: Mon, 17 Feb 2025 17:42:19 +1100 Subject: [PATCH 4/4] expand documentation --- README.md | 4 +++- polyconf_examples/README.md | 8 +++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e467b27..73b197c 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,12 @@ *PolyConstruct* contains three python tools for generating polymer coordinate and topolgy files for molecular dynamics simulations. *PolyConf* is a tool for generating ensembles of polymer conformations by combining monomer coordinate files. + *PolyBuild* is a tool for generating polymer topology files for simulaton from polymer coordinate files, leveraging the functionality of the gromacs tool pdb2gmx. + *PolyTop* is a tool for generating polymer topology files from monomer topology files. -*PolyConstruct* was published in the paper *PolyConstruct: adapting biomolecular simulation pipelines for polymers with PolyBuild, PolyConf and PolyTop*. +*PolyConstruct* was published in the paper *PolyConstruct: adapting biomolecular simulation pipelines for polymers with PolyBuild, PolyConf and PolyTop*. ## Getting started diff --git a/polyconf_examples/README.md b/polyconf_examples/README.md index 41e72fb..ef8e161 100644 --- a/polyconf_examples/README.md +++ b/polyconf_examples/README.md @@ -2,7 +2,9 @@ This folder contains several example scripts demonstrating the use of *PolyConf*. All the files you need to run these examples are contained within this folder. -For detailed documentation of all PolyConf methods, please refer to the [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/index.html). +For detailed documentation of all *PolyConf* methods, please refer to the [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/index.html). + +These tutorials are not intended as a primer on polymer design or stereochemistry. It is assumed that the reader is familiar polymer [tacticity](https://en.wikipedia.org/wiki/Tacticity), and common types of [copolymers](https://en.wikipedia.org/wiki/Copolymer). ## Tutorial 01: Building a linear polyethyleneimine polymer conformation using PolyConf @@ -15,7 +17,7 @@ This tutorial showcases several approaches, including: * using `dihedral_solver()` to adjust the polyethyleneimine conformation * using `shuffler()` and `dihedral_solver()` to generate a random polyethyleneimine conformation -TYhis tutorial is all contained in a single script. There are detailed comments discussing the strategies used, and the limitations of the resulting conformations. You are encouraged to examine the conformations generated by this script in [VMD](https://www.ks.uiuc.edu/Research/vmd/), or another visualization tool of your choice, to understand the strengths and limitations of the different strategies. +This tutorial is all contained in a single script. There are detailed comments discussing the strategies used, and the limitations of the resulting conformations. You are encouraged to examine the conformations generated by this script in [VMD](https://www.ks.uiuc.edu/Research/vmd/), or another visualization tool of your choice, to understand the strengths and limitations of the different strategies. ## Tutorial 02: Strategies for building conformations of polymers with different types of tacticity, or copolymers with different monomer distributions @@ -41,7 +43,7 @@ This strategy could be adapted to make an [alternating copolymer](https://en.wik This approach could also be adapted to generate a [statistical copolymer](https://en.wikipedia.org/wiki/Copolymer). -The script for this part of the tutorial will fail! This is intentional. We have chosen a specific random seed, which will reliably fail to generate a valid starting conformation. We made this decision to showcase some of the challenges in generating polymers wherte monomers are arranged in a random or stochastic order. +The script for this part of the tutorial **will fail!** This is intentional. We have chosen a specific random seed that will reliably fail to generate a valid starting conformations, in order to showcase some of the challenges in generating polymers where monomers are arranged in a random or stochastic order. There is a discussion at the end of this script, which contain several suggestions for addressing these challenges. You should try implementing those strategies until you can successfully generate a valid starting conformation for atactic PMMA.