Merge branch 'main' of https://github.com/OMaraLab/polyconstruct into rename-polybuild-examples

Author: lunamorrow

.DS_Store

@@ -146,3 +146,7 @@ polyconf_examples/PMMA_*
 polytop_examples/data/ethylamine_dendrimer.*
 polytop_examples/data/four_arm_star.*
 polytop_examples/data/pei_linear_polymer.*
+
+# OS X nonsense
+
+.DS_store

.gitignore

@@ -1,31 +1,29 @@
-PolyConstruct
+Getting 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*
+*Rangika Munaweera, Ada Quinn, Luna Morrow, Richard A Morris, and Megan L O’Mara*
 
-Getting Started
-===============
 
 **Installing PolyConstruct:**
 
-From your home directory, clone *PolyConstruct* from GitHub:
+From your home directory, clone PolyConstruct from Git:
 
 .. code-block:: python
 
     cd ~
     git clone https://github.com/OMaraLab/polyconstruct.git
 
-Then navigate to `~/PolyConstruct`:
+Then navigate to polyconstruct:
 
 .. code-block:: python
 
     cd polyconstruct
 
-To setup an environment for *PolyConstruct*, run: 
+To setup an environment for polyconstruct, run: 
 
 .. code-block:: python
 
@@ -34,7 +32,7 @@ To setup an environment for *PolyConstruct*, run:
 
     pip install -r requirements.txt
 
-Then, build the *PolyTop*, *PolyConf* and *PolyBuild* packages:
+Then, build the PolyTop, PolyConf and PolyBuild packages:
 
 .. code-block:: python
 
@@ -86,8 +84,8 @@ Monomer design
 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/>`_. 
+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, 
@@ -98,8 +96,9 @@ and not the ammonium and carboxylate groups found in the precursor amino acids.
 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. 
 
+
 For *PolyConf* 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 <https://www.cgl.ucsf.edu/chimerax/>`_, with theoretical ideal bond lengths and 
+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.
@@ -112,8 +111,7 @@ Worked Examples
 PolyConf creates polymer coordinate files through the tiling and manipulation of monomer pdb files.
 
 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 
+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.
 
@@ -190,31 +188,18 @@ Here is one simple example, showing the construction of a linear polyethylenimin
     # end of example script
 
 
+**PolyBuild**
 
+Example input itp files and the resulting rtp database entries are presented in the folder `polybuild_examples/RTP_entries` 
 
-**PolyTop**
+RTP entries 
 
+**PolyTop**
 
-.. note::
-    The import path provided in the examples below is *different* to the path
-    in the examples contained within 'polyconstruct/data_paper_examples/', as
-    the path used to locate modules from within the package structure is
-    different. You must use the structure in the examples below for the module
-    import to be correctly resolved.
 
 
 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
@@ -252,6 +237,9 @@ Simple example - construction of a linear homopolymer:
     Visualize.polymer(polymer,infer_bond_order=False).draw2D('data_paper_examples/pei_linear_polymer.png',(400,300))
 
 
+.. 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. 
 
 
 Complex example - construction of a 4-arm PEG star polymer from single monomeric units:
@@ -266,9 +254,9 @@ Complex example - construction of a 4-arm PEG star polymer from single monomeric
     from polytop.Topology import Topology
 
     # Load in monomer topologies from ITP files
-    ethanol = Topology.from_ITP("data_paper_examples/extended_ethanol.itp") # main arm monomer
-    methane = Topology.from_ITP("data_paper_examples/extended_methane.itp") # terminal monomer
-    neopentane = Topology.from_ITP("data_paper_examples/extended_neopentane.itp") # central monomer
+    ethanol = Topology.from_ITP("polytop_examples/data/extended_ethanol.itp") # main arm monomer
+    methane = Topology.from_ITP("polytop_examples/data/extended_methane.itp") # terminal monomer
+    neopentane = Topology.from_ITP("polytop_examples/data/extended_neopentane.itp") # central monomer
 
     # Create junctions for each monomer with the bonding atom and then the leaving
     # atom specified, in that order, with a unique name. Note how each junction
@@ -331,18 +319,16 @@ Complex example - construction of a 4-arm PEG star polymer from single monomeric
     four_polymer.topology.title = "four arm star polymer" # renames the ITP header and image
 
     # save the polymer to a file and visualise the structure with RDKit for an easy visual structure check
-    four_polymer.save_to_file('data_paper_examples/four_arm_star_overlapped_monomers.json') # text dump
-    four_polymer.topology.to_ITP('data_paper_examples/four_arm_star_overlapped_monomers.itp')
-    Visualize.polymer(four_polymer,infer_bond_order=False).draw2D('data_paper_examples/four_arm_star_overlapped_monomers.png',(400,300))
+    four_polymer.save_to_file('polytop_examples/data/four_arm_star.json') # text dump
+    four_polymer.topology.to_ITP('polytop_examples/data/four_arm_star.itp')
+    Visualize.polymer(four_polymer,infer_bond_order=False).draw2D('polytop_examples/data/four_arm_star.png',(800,600))
 
-All of the monomer ITP files used in the above two examples, and the resulting
-polymer files, are also readily available at 'polyconstruct/data_paper_examples/'.
+--------------------------------------------------------------------------------------
 
+Find the above and additional worked examples as executable Python scripts on the `PolyConstruct GitHub repository <https://github.com/OMaraLab/polyconstruct>`_.
 
---------------------------------------------------------------------------------------
+Examples for *PolyTop* are available at `polyconstruct/polytop_examples/`
+
+Examples for *PolyConf* at `polyconstruct/polyconf_examples/`
 
-Find the above and additional worked examples as executable Python scripts or Jupyter
-Notebooks on the `PolyConstruct GitHub repository <https://github.com/OMaraLab/polyconstruct>`_.
-Examples for PolyTop are available at 'polyconstruct/paper_worked_examples.ipynb'
-and for PolyConf at 'polyconstruct/polyconf_examples/'; while instructions to
-use the two PolyBuild scripts are included under the :ref:`PolyBuild` documentation.
+Instructions to use *PolyBuild* are included under the :ref:`PolyBuild` documentation.