update RTD

docs/source/getting_started.rst

@@ -1,8 +1,11 @@
 Getting Started
 ===============
 
-This page details how to get started with PolyConstruct.
+This page details how to get started with *PolyConstruct*.
 
+The design, testing, and validation of *PolyConstruct* is detailed in the manuscript "PolyConstruct: 
+adapting  biomolecular simulation pipelines for polymers with PolyBuild, PolyConf and PolyTop", by 
+**_Rangika Munaweera_**, **_Ada Quinn_**, Luna Morrow, Richard A Morris, Megan L O’Mara
 
 **Installing PolyConstruct:**
 
@@ -45,84 +48,133 @@ Then, build the PolyTop, PolyConf and PolyBuild packages:
     pip install -e .
 
 
-.. note::
-    When using PolyTop and PolyBuild (and thus PolyConf to produce matching coordinates),
-    it is always necessary for at least one of the molecules being joined at a polymerization
-    bond to lose at least 2 atoms in its leaving ‘residue’ for sufficient information to
-    exist to infer a dihedral constraint to rotation around the polymerization bond. 
 
-.. note::
-    Note that when more than one type of junction exists within a PolyTop polymer,
-    it is important that each junction type is given a unique name. In the case where
-    there exist multiple junctions in either molecule sharing the same name, the specific
-    junctions chosen will be randomly distributed among junctions with the same name,
-    allowing for stochastic extension of polymers. For repeatability it is therefore
-    necessary to use a consistent seed value (in python), and use PolyTop as a python
-    library rather than from the command line. If an exact structure is desired instead,
-    simply ensure that each junction type has a unique name that does not allow for any
-    discrepancy in exactly which junctions are joined and where.
+Input files and monomer design
+===============
+
+*PolyConf* assembles polymer pdb files by tiling individual monomer pdb files.  Monomer PDB files should 
+include all monomer atoms that will be present in the final polymer, dummy atoms corresponding to 
+connectivity with adjacent monomers, and `CONECT` records that describe the connectivity between
+monomer atoms.
+
+These coordinate files should represent a sensible monomer geometry as could be found in the final 
+polymer.  These might be created using tools like ChimeraX, with theoretical ideal bond lengths and 
+angles, by geometry optimization, or generated by automated parameterization tools.  Additionally, 
+it is often convenient if the monomer is in a conformation where atoms corresponding to adjacent monomers 
+are as far as possible from other atoms, and pointed away from other attachment points.
+
+*PolyBuild* requires monomer itp files, which are then converted into gromacs residue topology database 
+entries, and a coordinate file containing a complete structure of the intended polymer.  This structure can 
+be created with PolyConf, manually, or by using other structure creation packages.
+
+*PolyTop* requires monomer itp files describing all monomers that will be contained in the system.
+
+For both *PolyBuild* and *PolyTop*, monomer parameters should include all monomer atoms that will be present 
+in the simulation model of the final polymer, and dummy atoms correesponding to connectivity with adjacent monomers.  
+The method for preparing monomer .itp depends on the choice of force field, and a number of suitable automated tools 
+exist for small molecule parameterization such as the `Automated Topology Builder <https://atb.uq.edu.au>`, 
+`antechamber <https://ambermd.org/antechamber/ac.html>`, and `LigParGen https://zarbi.chem.yale.edu/ligpargen/`. 
 
+Monomer coordinates and parameters used as inputs should be designed to reflect the state of the monomer 
+in the mature polymer chain, rather than the isolated monomer molecule prior to polymerization.  For example, 
+when parameterising a peptide polymer synthesised through amide condensation reactions, monomers should be 
+parameterized with their connectivity described as the amide bonds that will occur in the mature polymer, 
+and not the ammonium and carboxylate groups found in the precursor amino acids.
 
-To utilise PolyConf and PolyTop, you will need extended topology files of the
-monomeric units used to build your polymer. These monomer PDB and ITP files,
-respectively can be obtained from the `ATB <https://atb.uq.edu.au/>`_ or
-other sources.
+Monomer parameters should be designed in a manner consistent with the desired force field.  We recommend you 
+do not combine monomer parameters from different force field families in a single polymer. 
 
-These files do not need to be pre-processed, and can simply be loaded into
-either a PolyConf or PolyTop Monomer object, depending on the file format. For
-more information see the worked examples below, which demonstrate how to load a
-monomer file into a Monomer object in both PolyConf and PolyTop. 
+For PolyConf and PolyTop, monomer .itp and .pdb files do not need to be pre-processed.
 
-PolyBuild leverages GROMACS tools and does require ITP files to be
-pre-processed. For more information see the :ref:`PolyBuild` documentation.
+PolyBuild leverages GROMACS tools to automatically parameterise polymers. and requires 
+.itp files to be converted to RTP database entries using the provided `ITP2RTP` program.  
+For more infomation, see the :ref:`PolyBuild` documentation.
 
 
 Worked Examples
 ==================
 
 **PolyConf**
 
+PolyConf creates polymer coordinate files through the tiling and manipulation of monomer pdb files.
 
-Simple example - construction of a PEI homopolymer:
+There are several detailed examples of the use of PolyConf to create ensembles of starting 
+conformations for a series of increasingly complex polymer architectures.  These are contained in the PolyConf repository in the folder 'polyconstruct/polyconf_examples/' contained in the 
+
+Here is one simple example, showing the construction of a linear polyethylenimine 128-mer.
 
 .. code-block:: python
 
-    # Import required classes from PolyConf
+    # start by loading PolyConf
+
     from polyconf.Monomer import Monomer
     from polyconf.Polymer import Polymer
     from polyconf.PDB import PDB
 
-    # Initialise Polymer from Monomer of the starting monomer PDB
-    polymer=Polymer(Monomer('PEI_start.pdb'))
-    imax=127 # define constant, to add an additional 127 monomers
+    PEI=Polymer(Monomer('PEI_start.pdb')) # initialize polymer with the starting monomer
+
+    for _ in range (0,126): 	# extend our polymer by adding new monomers 
+
+        n= PEI.maxresid() 	# we will extend the monomer with the highest resid
+        new_n= PEI.newresid() 	# generate a new resid for the new monomer
+
+        PEI.extend( 					# extend with one monomer
+                Monomer('PEI_monomer.pdb'), 	# create new monomer from pdb file
+                n=n,					# resid to extend from
+                nn=new_n,				# resid for new monomer
+                names=dict(P='C1', Q='CX', R='NX', S='N1'), 	# defines the mapping
+                joins=[('N1','C1')], 				# defines the new connectivity
+                ) 
+
+        # after adding each monomer, we will flag dummy atoms
+        PEI.renamer(n,'CX') # convert atom CXn to a dummy atom 
+        PEI.renamer(new_n,'NX') # convert atom NXnew_n to a dummy atom
 
-    # Extend the Polymer to the desired length (in this case 128)
-    for i in range(0, imax):
-        if not i==imax:
-            # Extend the Polymer for every step except the last one
-            # Extend by one monomer, WITHOUT aligning along this step's linearization vector
-            polymer.extend(Monomer('PEI_monomer.pdb'), # extend with this monomer
-                n=polymer.maxresid(), # extend existing residue i
-                nn=polymer.newresid(), # incoming monomer will have resid i+1
-                names=dict(P1='CX',P2='C1',Q1='N1',Q2='NX'), # C1_i+1 fit to CX_i, then rotate so NX_i+1 fit to N1_i 
-                joins=[('N1','C1')]) # new connection between N1_i and C1_i+1 
-        else:
-            # Extend and cap the Polymer by adding the terminating monomer
-            polymer.extend(Monomer('PEI_end.pdb'),i,i+1,
-                names=dict(P1='CX',P2='C1',Q1='N1',Q2='NX'),
-                joins=[('N1','C1')])
+    # now we add the final monomer
+    # the process is the same, but we are using a different pdb file 
 
-    # Save the polymer to a file without the dummy atoms, visually check the PDB with another package such as VMD
-    Saver = PDB(polymer)
-    Saver.cleanup() # center the Polymer in the PBC box
-    Saver.save(dummyAtoms='CX NX',fname='polymer_01_vanilla-extend') # save, excluding dummy atoms
+    n= PEI.maxresid()
+    new_n= PEI.newresid()
+
+    PEI.extend(
+                Monomer('PEI_end.pdb'),
+                n=n, 
+                nn=new_n,
+                names=dict(P='C1',Q='CX',R='NX',S='N1'),
+                joins=[('N1','C1')],
+                )
 
-    # When you examine the polymer, you can see that the resulting strucure is a tightly coiled helix, rather than linear/
-    # This structure is highly ordered, and the turns of the helix are very close.
+    # remove dummy atoms as before
 
+    PEI.renamer(n,'CX') 
+    PEI.renamer(new_n,'NX') 
+
+    # generate an ensemble of conformations
+    # begin by generating lists of dihedrals
+
+    NC_dh = PEI.gen_pairlist(J='N1',K='C1',first_resid=1,last_resid=127,mult=3,same_res=False) 
+    alkane_dh = PEI.gen_pairlist(J='C1',K='C2',first_resid=1,last_resid=128,mult=3)
+
+    # Then, we will generate five starting conformations.  
+
+    # For each conformation:
+    #   start by making a copy of our initial conformation
+    #   randomize the conformation by shuffling the N1n-C1n+1¬¬ torsions
+    #   solve the conformation by rotating the C1n-C2n torsions
+
+    for conf in range(1,6): 
+
+        newconf= PEI.copy() # make a duplicate of the original polymer
+
+        newconf.shuffler(NC_dh)
+        newconf.dihedral_solver(alkane_dh,cutoff=0.9)
+
+        Saver = PDB(newconf)
+        Saver.cleanup() # place the polymer in the center of the simulation box
+        Saver.save(fname=f'PEI_linear_conformation_{conf}')
+
+    # end of example script
 
-All of the monomer PDB files used in the above example and the resulting
-polymer file are readily available at 'polyconstruct/polyconf_examples/'.
 
 
 
@@ -139,6 +191,18 @@ polymer file are readily available at 'polyconstruct/polyconf_examples/'.
 
 Simple example - construction of a linear homopolymer:
 
+.. note::
+    Note that when more than one type of junction exists within a PolyTop polymer,
+    it is important that each junction type is given a unique name. In the case where
+    there exist multiple junctions in either molecule sharing the same name, the specific
+    junctions chosen will be randomly distributed among junctions with the same name,
+    allowing for stochastic extension of polymers. For repeatability it is therefore
+    necessary to use a consistent seed value (in python), and use PolyTop as a python
+    library rather than from the command line. If an exact structure is desired instead,
+    simply ensure that each junction type has a unique name that does not allow for any
+    discrepancy in exactly which junctions are joined and where.
+
+
 .. code-block:: python
 
     # Import required classes from PolyTop