Update documentation

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 .

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/).
+# 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`).

polyconf_examples/build_PMMA_02-syndiotactic.py → 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.

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