diff --git a/README.md b/README.md index d7bbf92..73b197c 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,48 @@ -# PolyConstruct Documentation +# *PolyConstruct*: a python library for polymer generation -Documentation for the PolyConstruct package, including the PolyBuild, PolyConf and PolyTop packages is available on ReadTheDocs. +*PolyConstruct* contains three python tools for generating polymer coordinate and topolgy files for molecular dynamics simulations. -[PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/) +*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. -# Setup for PolyConstruct +*PolyTop* is a tool for generating polymer topology files from monomer topology files. -From your home directory, install PolyConstruct from Git: +*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. + +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) + +## Quick and dirty installation + +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*: -``` -conda create --name polyconstruct-env python=3.10 -conda activate polyconstruct-env +```bash +conda create --name polyconstruct python=3.10 +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 pip install -e . diff --git a/docs/README.md b/docs/README.md index 025b736..73c6410 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,2 +1,25 @@ -Oops, you have found a non-human readable area! To view the PolyConstruct -documentation, please go to [PolyConstruct ReadTheDocs](https://polyconstruct.readthedocs.io/en/latest/). \ No newline at end of file +# 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 +``` + +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/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 79% rename from polyconf_examples/build_PMMA_02-syndiotactic.py rename to polyconf_examples/02b_build_PMMA_syndiotactic.py index 249aab2..17529eb 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) @@ -19,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 @@ -30,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 @@ -39,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 @@ -62,3 +67,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..ef8e161 --- /dev/null +++ b/polyconf_examples/README.md @@ -0,0 +1,64 @@ +# 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. + +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 + +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 + +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 + +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). + +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. + +### 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 `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). + +## 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