Merge pull request #7 from ACBC19/test

AB Tuto 1 AMBER

docs/source/AMBER/Tutorial-1.rst

@@ -1,4 +1,181 @@
-Tutorial 1. ADN
-================================
+This tutorial shows how to perform a coarse grained (CG) simulation of a double stranded DNA using the Generalized Born model for implicit solvent (GB) and the SIRAH force field. The main references
+for this tutorial are: `Dans et al. SIRAH DNA <https://pubs.acs.org/doi/abs/10.1021/ct900653p>`_ (latest parameters are those reported in: `Darré et al. WAT4?) <https://pubs.acs.org/doi/abs/10.1021/ct100379f>`_, `Machado et al. SIRAH Tools <https://academic.oup.com/bioinformatics/article/32/10/1568/1743152>`_. We strongly advise you to read these articles before starting the tutorial.
 
-This is the first tutorial of SIRAH implementation on AMBER 
+Required Software
+__________________
+
+.. _vmd: www.ks.uiuc.edu/Research/vmd
+
+AMBER 16 and AMBER Tools 16 or later versions properly installed and running in your computer. The molecular visualization program VMD 1.9.3 or later version (`freely available download <vmd>`_).
+
+
+Prior knowledge
+_______________
+
+How to perform a standard atomistic molecular dynamic simulation with AMBER and basic usage of
+VMD. If you are not familiar with DNA stuff we strongly recommend you to first perform the `AMBER
+tutorial on DNA <http://ambermd.org/tutorials/basic/tutorial1>`_.
+
+Download and set up SIRAH Force Field
+______________________________________
+
+Download the file ``sirah_[version].amber.tgz`` from www.sirahff.com and uncompress it into your
+working directory. Notice: ``[version]`` should be replaced with the actual package version e.g.: x2_18-09
+
+.. code-block:: bash
+
+    $ tar -xzvf sirah_[version].amber.tgz
+
+You will get a folder ``sirah_[version].amber/`` containing the force field definition, the SIRAH Tools in
+``sirah_[version].amber/tools/``, molecular structures to build up systems in ``sirah_[version].amber/PDB/``,
+frequently asked questions in ``sirah_[version].amber/tutorial/SIRAH_FAQs.pdf`` and the required
+material to perform the tutorial in ``sirah_[version].amber/tutorial/1/``
+
+Make a new folder for this tutorial in your working directory:
+
+.. code-block:: bash
+
+    $ mkdir tutorial1; cd tutorial1
+
+Create the following symbolic link in the folder tutorial1:
+
+.. code-block:: bash
+
+    ln -s ../sirah_[version].amber sirah.amber
+
+
+1. Build GC representations
+________________________________________________________________________
+
+Map the atomistic structure of a 20-mer DNA to its CG representation:
+
+.. code-block:: bash
+
+  ./sirah.amber/tools/CGCONV/cgconv.pl\
+  -i ./sirah.amber/tutorial/1/dna.pdb\
+  -o dna_cg.pdb
+
+The input file dna.pdb contains all the heavy atoms composing the DNA molecule, while the output
+dna_cg.pdb preserves a few of them. Please check both PDB structures using VMD:
+
+.. code-block:: bash
+
+    vmd -m ./sirah.amber/tutorial/1/dna.pdb dna_cg.pdb
+
+.. note::
+
+    This is the basic usage of the script cgconv.pl, you can learn other capabilities from its help:
+    ``./sirah.amber/tools/CGCONV/cgconv.pl -h``
+
+From now on it is just normal AMBER stuff!
+
+2. Prepare leap
+_______________
+
+Use a text editor to create the file ``gensystem.leap`` including the following lines:
+
+.. code-block:: console
+
+    # Load SIRAH force field
+    addPath ./sirah.amber
+    source leaprc.sirah
+
+    # Load model
+    dna = loadpdb dna_cg.pdb
+
+    # Save Parms
+    saveAmberParmNetcdf dna dna_cg.prmtop dna_cg.ncrst
+
+    # EXIT
+    quit
+
+
+3. Run LEAP
+____________
+
+Run the LEAP application to generate the molecular topology and initial coordinate files:
+
+.. code-block:: bash
+
+    tleap -f gensystem.leap
+
+.. caution::
+
+    Warning messages about long, triangular or square bonds in ``leap.log`` file are fine and
+    expected due to the CG topology.
+
+
+This should create a topology file dna_cg.prmtop and a coordinate file dna_cg.ncrst.
+Use VMD to check how the CG model looks like:
+
+.. code-block:: bash
+
+    vmd dna_cg.prmtop dna_cg.ncrst -e ./sirah.amber/tools/sirah_vmdtk.tcl
+
+.. tip::
+
+    VMD assigns default radius to unknown atom types, the script ``sirah_vmdtk.tcl`` sets the right
+    ones. It also provides a kit of useful selection macros, coloring methods and backmapping utilities.
+    Use the command ``sirah_help`` in the Tcl/Tk console of VMD to access the manual pages.
+
+
+4. Run the simulation
+_______________________
+
+Make a new folder for the run:
+
+.. code-block:: bash
+
+    mkdir -p run; cd run
+
+In the course of long MD simulations the capping residues may eventually separate, this effect is
+called helix fraying. To avoid such behavior create a symbolic link to the file ``dna_cg.RST``, which
+contains the definition of Watson-Crick restraints for the capping base pairs of this CG DNA:
+
+.. code-block:: bash
+
+    ln -s ../sirah.amber/tutorial/1/SANDER/dna_cg.RST
+
+.. important::
+
+    The file dna_cg.RST can only be read by SANDER, PMEMD reads a different restrain format.
+    The folder ``sirah.amber/tutorial/1/SANDER/`` contains typical input files for energy minimization
+    (em_GB.in), equilibration (eq_GB.in) and production (md_GB.in) runs. Please check carefully the input
+    flags therein.
+
+**Energy Minimization:**
+
+   .. code-block:: bash
+
+      $ sander -O -i ../sirah.amber/tutorial/1/SANDER/em_GB.in -p ../dna_cg.prmtop -c ../dna_cg.ncrst -o dna_cg_em.out -r dna_cg_em.ncrst &
+
+   - ``sander``: The AMBER program for molecular dynamics simulations.
+   - ``-i``: Input file.
+   - ``-o``: Output file.
+   - ``-p``: Parameter/topology file.
+   - ``-c``: Coordinate file.
+   - ``-r``: Restart file.
+
+**Equilibration:**
+
+    .. code-block:: bash
+
+        $ sander -O -i ../sirah.amber/tutorial/1/SANDER/md_GB.in -p ../dna_cg.prmtop -c dna_cg_eq.ncrst -o dna_cg_md.out -r dna_cg_md.ncrst
+
+
+.. note::
+
+    You can find example input files for CPU and GPU versions of pmemd at folders PMEMD.CPU/ and PMEMD.GPU/ within sirah.amber/tutorial/1/
+
+5. Visualising the simulation
+______________________________
+
+Now you can load, visualize and analize the trajectory file in VMD:
+
+.. code-block::
+
+    vmd ../dna_cg.prmtop ../dna_cg.ncrst dna_cg_md.nc -e ../sirah.amber/tools/sirah_vmdtk.tcl
+
+.. tip::
+
+    The file ``sirah_vmdtk.tcl`` is a Tcl script that is part of SIRAH Tools and contains the macros to properly visualize the coarse-grained structures in VMD.

docs/source/AMBER/Tutorial-2.rst

@@ -1,4 +1 @@
-Tutorial 3. Lipids and Membranes
-=================================
-
-This is the **second** tutorial of SIRAH implementation on AMBER 
+Tutorial 1 - Basic Usage of AMBER

docs/source/Tutorials.rst

@@ -1,43 +1,41 @@
-Tutorials
-=========
-
 AMBER
------
+======
 
 .. _AMBER:
 
-Tutorial 1
-~~~~~~~~~~
+Simulation of a coarse grained DNA molecule in implicit solvent
+----------------------------------------------------------------------------
 
 .. _Tutorial 1:
 
-    .. include:: /AMBER/Tutorial-1.rst
+.. include:: /AMBER/Tutorial-1.rst
 
 Tutorial 2
-~~~~~~~~~~
+------------
 
 .. _Tutorial 2:
 
   .. include:: /AMBER/Tutorial-2.rst
 
 Tutorial 3
-~~~~~~~~~~
+-----------
+
 .. _Tutorial 3:
 
   .. include:: /AMBER/Tutorial-3.rst
 
 GROMACS
-------------
+========
 
 .. _GROMACS:
 
 
 NAMD
-------------
+=====
 
 .. _NAMD:
 
 SIRAH tools
-------------
+===========
 
 .. _SIRAH tools:

docs/source/_static/custom.css

@@ -0,0 +1,3 @@
+p {
+    text-align: justify;
+}

docs/source/conf.py

@@ -53,3 +53,6 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+def setup(app):
+    app.add_css_file('custom.css')

docs/source/index.rst

@@ -19,8 +19,8 @@ Note
 
 This project is under active development.
 
-Check out the :doc:`Tutorials` section for further information, including how to
-:ref:`install <amber>` the project.
+Check out the :doc:`About SIRAH` section for further information, including how to
+:ref:`install <FAQ>` the project.
 
 .. note::
 
@@ -30,23 +30,19 @@ Contents
 --------
 
 .. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Manual
 
-  About SIRAH
-  Citation
-  Tutorials
-  Further reading
-  FAQ
-  Developers
+   About SIRAH
+   Citation
+   Further reading
+   FAQ
+   Developers
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-
-
-Indices and tables
-==================
+   :hidden:
+   :caption: Tutorials
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   Tutorials