first draft of martinize2 command tutorials

doc/source/tutorials/basic_usage.rst

@@ -34,6 +34,7 @@ Martinize2 can deal with secondary structure intelligently using dssp in one of
 To explain these more:
 
 1) If you have dssp installed locally, note that martinize2 is only validated for particular versions of dssp.
+   Currently the versions supported are 2.2.1 and 3.0.0.
    If a non-validated version is used, a warning will be raised and nothing is written.
    If you know what you're doing and are confident with what's been produced, you can override the warning
    with the ``-maxwarn`` flag. Otherwise, dssp can be used using the ``-dssp`` flag in martinize.
@@ -79,11 +80,81 @@ we must we the full length string again:
 
 ``martinize2 -f protein.pdb -o topol.top -x cg_protein.pdb -ss HHHHHCCCCC``
 
+Other basic features of martinize2
+==================================
 
+Side chain fixing
+-----------------
 
+One important addition for the generation of correct Martini protein topologies is side chain fixing.
+Side chain fixing is essential for ensuring correct sampling of side chain dynamics, and involves adding
+additional bonded terms into the structure of the protein, relating to the angles and dihedrals around
+side chain and backbone atoms. For further information on the background and motivation for these terms,
+please read the paper by `Herzog et. al <https://pubs.acs.org/doi/full/10.1021/acs.jctc.6b00122>`_.
 
+Building on the command we wrote above, side chain fixing is added into martini topologies through the
+`-scfix` flag:
 
+``martinize2 -f protein.pdb -o topol.top -x cg_protein.pdb -ff martini3001 -dssp -scfix``
 
+**PLEASE NOTE**: Side chain fixes are *essential* for martini3 proteins. Currently martinize2
+(version 0.11.0) *does not* add side chain fixing parameters automatically, and so `-scfix`
+must explictly be given as an argument. This will be fixed in future version of martinize2.
 
+Secondary and tertiary structure considerations
+-----------------------------------------------
+
+The examples given on this page show how to generate basic coarse grained topologies for the
+martini force field using martinize2. Martinize2 has many further features to
+transform your simulation from a physically naive coarse grained model to one that really
+reproduces underlying atomistic behaviour. One of the most important considerations in this
+is how to treat secondary structure in the absence of hydrogen bonding. Two such methods
+are described in both the
+`Martini protein tutorial <https://cgmartini.nl/docs/tutorials/Martini3/ProteinsI/>`_, which
+should be an essential route in to conducting simulations with the martini force field.
+
+We cover the documentation of these features in greater detail in the pages about
+`Elastic Networks <elastic_networks.rst>`_ and `Gō models <go_models.rst>`_.
+
+Cysteine bridges
+----------------
+
+If your protein contains cysteine bridges, martinize2 can attempt to identify linked residues
+and add correct Martini parameters between them using the `-cys` flag. When bridged residue pairs
+are identified, a constraint of length 0.24 nm will be added between the side chains of the two
+residues.
+
+The `-cys` flag can read one of two types of argments. `-cys auto` will look for pairs of residues
+within a short cutoff:
+
+``martinize2 -f protein.pdb -o topol.top -x cg_protein.pdb -ff martini3001 -dssp -scfix -cys auto``
+
+You can check if the correct bridges have been identified and added in the `[ constraints ]` directive
+of the output itp file. Disulfide bonds are written at the top of the directive like so::
+
+ [ constraints ]
+  5 25 1 0.24 ; Disulfide bridge
+ 30 50 1 0.24 ; Disulfide bridge
+
+Alternatively if you need to assert the identification of the bridges over a distance that isn't
+automatically identified, a distance in nm can be supplied to `-cys`, e.g.:
+
+``martinize2 -f protein.pdb -o topol.top -x cg_protein.pdb -ff martini3001 -dssp -scfix -cys 5``
+
+will look for cysteines within 5 nm of each other and apply the same disulfide bond as before.
+
+Citations
+---------
+
+At the end of the execution of martinize2, the final output log writes general information with
+requests to citate relevant papers. Martinize2 collects paper citation information dynamically
+based on what features have been used, such as force fields, extra parameters,
+how secondary structure has been determined, and so on. For posterity and to ensure ease of
+reference, the same paper citations are also printed to the header information of the output
+topology files.
+
+As the correct references are collected dynamically, all the papers printed here by martinize2
+should be cited, to ensure that relevant authors and features are credited. Please do so!
+Martinize2 is both free and open source, and continued citations help us to keep it this way.
 
 

doc/source/tutorials/elastic_networks.rst

@@ -4,6 +4,10 @@ Elastic Networks
 
 The first method applied to maintain the secondary and tertiary structure
 of Martini proteins was `Elastic Networks <https://doi.org/10.1021/ct9002114>`_.
+In Martini and other coarse-grained models, extra restraints are necessary to
+retain folded protein structure in the absense of hydrogen bonding. As the
+`Martini protein tutorial <https://cgmartini.nl/docs/tutorials/Martini3/ProteinsI/>`_
+suggests, try simulating a protein without them and seeing what happens!
 
 Elastic networks are formed by finding contacts between protein backbone
 beads within a particular cutoff distance, and applying harmonic bonds between them,

doc/source/tutorials/go_models.rst

@@ -1,18 +1,18 @@
 =========
-Go models
+Gō models
 =========
 
-GoMartini is a popular method for retaining the secondary and tertiary structures of proteins originating from the lab
-of `Adolfo Poma <https://pubs.acs.org/doi/full/10.1021/acs.jctc.6b00986>`_. In contrast to an elastic network, the Go
-model enforces interactions between specific pairs of beads within a protein based on residue overlap and restricted
-chemical structural unit criteria.
+The MartiniGō model is a method of maintaining secondary and tertiary structure using native contacts of proteins
+to create a `Gō-like model <https://pubs.acs.org/doi/full/10.1021/acs.jctc.6b00986>`_ between beads.
+In contrast to an elastic network, the Go model applies non-bonded interactions between pairs of
+beads within a protein based on residue overlap and restricted chemical structural unit criteria.
 
-The latest version of Martinize2 implements the newest version of the
-`Go model <https://www.biorxiv.org/content/10.1101/2024.04.15.589479v1>`_. In this version of the Go model, interactions
+The latest version of Martinize2 (version ≥ 0.10.0) implements the newest version of the
+`Gō model <https://www.biorxiv.org/content/10.1101/2024.04.15.589479v1>`_. In this version of the Go model, interactions
 are mediated through the addition of extra virtual sites on top of backbone beads in the protein. Interactions are in
 the form of Lennard-Jones interactions, which are written as an extra file to be included in the protein topology.
 
-The Go model is described in the help::
+The Gō model is described in the help::
 
  Virtual site based GoMartini:
    -go GO                Contact map to be used for the Martini Go model. Currently, only one format is supported. See docs. (default: None)
@@ -24,7 +24,7 @@ The Go model is described in the help::
    -go-res-dist GO_RES_DIST
                          Minimum graph distance (similar sequence distance) below which contacts are removed. (default: 3)
 
-To add a Go model to your protein, the first step is to calculate the contact map of your protein by uploading it
+To add a Gō model to your protein, the first step is to calculate the contact map of your protein by uploading it
 to the `web server <http://pomalab.ippt.pan.pl/GoContactMap/>`_.
 
 The contact map is then used in your martinize2 command:
@@ -70,7 +70,7 @@ depend on your protein)::
  molecule_0_23 molecule_0_19 1 0.53307395 9.41400000 ;go bond 0.5983552758317587
  ...
 
-To activate your Go model for use in Gromacs, the `martini_v3.0.0.itp` master itp needs the additional files included.
+To activate your Gō model for use in Gromacs, the `martini_v3.0.0.itp` master itp needs the additional files included.
 The additional atomtypes defined in the ``go_atomtypes.itp`` file should be included at the end of the `[ atomtypes ]`
 directive as::
 
@@ -108,26 +108,26 @@ directive::
  #endif
 
 Then in the .top file for your system, simply include `#define GO_VIRT` along with the other files
-to be included to active the Go network in your model.
+to be included to active the Gō network in your model.
 
 As a shortcut for writing the include statements above, you can simply include these files in your master
-``martini_v3.0.0.itp`` file with the following commands::
+``martini_v3.0.0.itp`` file with the following commands in a bash shell::
 
  sed -i "s/\[ nonbond_params \]/\#ifdef GO_VIRT\n\#include \"go_atomtypes.itp\"\n\#endif\n\n\[ nonbond_params \]/" martini_v3.0.0.itp
 
  echo -e "\n#ifdef GO_VIRT \n#include \"go_nbparams.itp\"\n#endif" >> martini_v3.0.0.itp
 
-The Go model should then be usable in your simulations following the `general protein tutorial <https://pubs.acs.org/doi/10.1021/acs.jctc.4c00677>`_.
-But careful! While the Go model specifies nonbonded interactions, the interactions are only defined
-internally for each molecule. This means that if you have multiple copies of your Go model protein
-in the system, the Go bonds are still only specified internally for each copy of the molecule,
+The Gō model should then be usable in your simulations following the `general protein tutorial <https://pubs.acs.org/doi/10.1021/acs.jctc.4c00677>`_.
+But careful! While the Gō model specifies nonbonded interactions, the interactions are only defined
+internally for each molecule. This means that if you have multiple copies of your Gō model protein
+in the system, the Gō bonds are still only specified internally for each copy of the molecule,
 not truly as intermolecular forces in the system as a whole. For more detail on this phenomenon,
 see the paper by `Korshunova et al. <https://pubs.acs.org/doi/10.1021/acs.jctc.4c00677>`_.
 
 
 Visualising Go networks
 ----------------------------
 
-If you want to look at your Go network in VMD to confirm that it's been constructed in the
+If you want to look at your Gō network in VMD to confirm that it's been constructed in the
 way that you're expecting, the `MartiniGlass <https://github.com/Martini-Force-Field-Initiative/MartiniGlass>`_
 package can help write visualisable topologies to view.