diff --git a/docs/source/AMBER/Tutorial-1.rst b/docs/source/AMBER/Tutorial-1.rst index 6990c38..4b56e1e 100644 --- a/docs/source/AMBER/Tutorial-1.rst +++ b/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 `_ (latest parameters are those reported in: `Darré et al. WAT4?) `_, `Machado et al. SIRAH Tools `_. 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 `_). + + +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 `_. + +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. diff --git a/docs/source/AMBER/Tutorial-2.rst b/docs/source/AMBER/Tutorial-2.rst index 0b9ad8e..941c050 100644 --- a/docs/source/AMBER/Tutorial-2.rst +++ b/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 diff --git a/docs/source/AMBER/Tutorials b/docs/source/AMBER/Tutorials new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/Tutorials.rst b/docs/source/Tutorials.rst index d1f0a27..83ac475 100644 --- a/docs/source/Tutorials.rst +++ b/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: diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..71cfd52 --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,3 @@ +p { + text-align: justify; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index 74615ee..826cc3f 100644 --- a/docs/source/conf.py +++ b/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') diff --git a/docs/source/index.rst b/docs/source/index.rst index 7a95352..039ae74 100644 --- a/docs/source/index.rst +++ b/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 ` the project. +Check out the :doc:`About SIRAH` section for further information, including how to +:ref:`install ` 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