From 6a35572f95e1a30d26ca51fdc3c45ec87d3f8865 Mon Sep 17 00:00:00 2001 From: recombinatrix Date: Fri, 21 Feb 2025 12:57:52 +1100 Subject: [PATCH 1/2] update documentation --- docs/source/getting_started.rst | 171 ++++++++++++++++++++++---------- 1 file changed, 117 insertions(+), 54 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 53bdf2d..4c7f801 100644 --- a/docs/source/getting_started.rst +++ b/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,36 +48,46 @@ 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. -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 `_ or -other sources. +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. -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. +*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. -PolyBuild leverages GROMACS tools and does require ITP files to be -pre-processed. For more information see the :ref:`PolyBuild` documentation. +*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 `, +`antechamber `, 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. + +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 and PolyTop, monomer .itp and .pdb files do not need to be pre-processed. + +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 @@ -82,47 +95,85 @@ 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 +190,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 From 1892b147c33d5c03cdfeff23abcfa062542d854d Mon Sep 17 00:00:00 2001 From: recombinatrix Date: Fri, 21 Feb 2025 13:06:22 +1100 Subject: [PATCH 2/2] update documentation --- docs/source/getting_started.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 4c7f801..01feb6f 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -49,7 +49,8 @@ Then, build the PolyTop, PolyConf and PolyBuild packages: -**Input files and monomer design:** +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