Update docs [ci skip]

insilichem · Mar 1, 2018 · 726db86 · 726db86
1 parent 5ad7d0a
commit 726db86
Show file tree

Hide file tree

Showing 5 changed files with 94 additions and 58 deletions.
diff --git a/docs/development.rst b/docs/development.rst
@@ -0,0 +1,25 @@
+.. _development:
+
+Software architecture
+=====================
+
+OMMProtocol is a glue application, which means that the main business logic resides within the third-party modules it depends on. Nonetheless, this should not necessarily imply a disorganized architecture. The main codebase is clearly divided in two categories: input and output handling (*io* module) and MD settings (*md* module). A third module, utils, collects miscellaneous functions that do not fall within the previous scopes. Finally, code concerning *ommanalyze* is stored in the analyze module.
+
+Module *io*
+-----------
+
+This module hosts the input file handling logic, such as the precedence of format files (function *io.prepare_handler*), and the main container class (*io.SystemHandler*) that gives access to the components needed to create an OpenMM System object. Each of those components (*io.Topology*, *io.Positions*, *io.Velocities*, *io.BoxVectors*, and *io.Restart* objects) inherit from *io.MultiFormatLoader*, which supports the automated load of different formats based on the file extension, and io.InputContainer, a simple class that supports different attributes with light validation of the proper data structure.
+
+The custom reporters provided by OMMProtocol are also contained here: *SegmentedDCDReporter* and *ProgressBarReporter*. The first allows the generation of DCD trajectories in chunked files to prevent huge file sizes, and the second converts OpenMM’s *StateDataReporter* in a more interactive console reporter (only one line dynamically updated for each protocol stage).
+
+Module *md*
+-----------
+
+The goal of this module is to thread together the different stages of the protocol and run the corresponding simulations one after another. The main actor in this module is the *md.Stage* class, which contains all the needed logic to run a simulation in OpenMM: creation of the *System* object, application of restraints or constraints, preparation of the universe conditions such as temperature or pressure, configuration of the platform properties, construction of the Simulation object, setup of the output reporters… Each of these components is encapsulated in cached properties for maximum performance and ease of use in interactive sessions.
+
+A helper function, *md.run_protocol*, takes the options for each stage specified in the input file and builds the needed *Stage* objects to execute them one after the other, passing the final state of each stage as the initial state of the next one. Since each stage must be named uniquely in the input file, the generated output files are meaningfully titled, leading to easy identification during the analysis.
+
+Module *analyze*
+----------------
+
+The *ommanalyze* executable provides commands to perform routinary plots in trajectory analysis, like RMSD or potential energy plots. Currently, it only provides two subcommands: ``ommanalyze rmsd``, which requires the topology and one or more trajectory files, and outputs an interactive plot with matplotlib and ``ommanalyze log``, which simply plots the contents of the .log files generated during the trajectory. This module is only a stub that, if successful, could be further extended with more common analysis procedures thanks to the MDTraj library.
diff --git a/docs/index.rst b/docs/index.rst
@@ -16,9 +16,6 @@ Introducing OMMProtocol
 A command line application to launch molecular dynamics simulations with OpenMM
 
 
-Some cool features
-------------------
-
 + No coding required - just a YAML input file!
 + Smart support for different input file formats:
     + **Topology**: PDB/PDBx, Mol2, Amber's PRMTOP, Charmm's PSF, Gromacs' TOP, Desmond's DMS
@@ -32,55 +29,23 @@ Some cool features
 + Autochunk the trajectories for easy handling.
 
 
-Installation & usage
---------------------
-Download the `latest installer <https://github.com/insilichem/ommprotocol/releases/latest>`_ or use ``conda install -c omnia -c insilichem ommprotocol`` if you already have Anaconda/Miniconda installed. Further details in :ref:`install`.
-
-When installed, you should be able to run:
-
-::
-
-    ommprotocol <inputfile.yaml>
-
-Go to :ref:`input` to read more on how to create input files for OMMProtocol.
-
-
-Get help
---------
-
-If you have problems running ``ommprotocol``, feel free to `create an issue <https://github.com/insilichem/ommprotocol/issues>`_! Also, make sure to visit our main webpage at `insilichem.com <http://www.insilichem.com>`_.
-
-
-Citation
---------
-
-Ommprotocol is scientific software, funded by public research grants (Spanish MINECO's project ``CTQ2014-54071-P``, Generalitat de Catalunya's project ``2014SGR989`` and research grant ``2015FI_B00768``, COST Action ``CM1306``). If you make use of Ommprotocol in scientific publications, please cite it. It will help measure the impact of our research and future funding! A manuscript is in progress. In the meantime, please cite this repository URL.
-
-.. code-block:: latex
-
-    @misc{ommprotocol2017,
-    author       = {Jaime Rodríguez-Guerra Pedregal and
-                    Lur Alonso-Cotchico and
-                    Lorea Velasco and
-                    Jean-Didier Maréchal},
-    title        = {OMMProtocol: A command line application to launch molecular dynamics simulations with OpenMM},
-    url          = {https://github.com/insilichem/ommprotocol}
-    }
-
-Table of contents
------------------
-
 .. toctree::
     :maxdepth: 1
+    :caption: For users
 
     install.rst
     usage.rst
     input.rst
     forcefields.rst
 
-Indices and tables
-------------------
+.. toctree::
+    :maxdepth: 1
+    :caption: For developers
+
+    development.rst
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Support
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    support.rst
diff --git a/docs/input.rst b/docs/input.rst
@@ -73,11 +73,28 @@ OMMProtocol ships with some `ready-to-use example protocols <https://github.com/
 - `test.yaml <https://github.com/insilichem/ommprotocol/blob/master/examples/test.yaml>`_: Protocol meant to debug a problematic simulation (those that end in ``Particle position is NaN``, for example) by dumping states and trajectories every 10 steps. It runs very slow and consumes lots of disk space!
 - `simple.yaml <https://github.com/insilichem/ommprotocol/blob/master/examples/simple.yaml>`_: Toy example to show the simplest protocol implementable in OMMProtocol.
 
+Default behaviour
+.................
+
+In principle, OMMProtocol input files can be as simple as:
+
+::
+
+    topology: output.pdb
+    stages:
+    - minimization: True
+      steps: 100000
+
+This is possible due to the chosen default values for almost every key. Specific details for each key are provided below, but globally this results in the following behaviour:
+
+- OMMProtocol will report the simulation progress to the standard output and create an Amber NetCDF checkpoint file every 1,000,000 steps. If an error occurs during the simulation, it will attempt to save a OpenMM XML file with the current state of the simulation, which, if lucky, can be used to restart the simulation or, at least, to debug the problem that could lead to that error.
+- If PDB files are being used as topology sources and no forcefield is provided and, it will default to ``amber99sbildn.xml`` and ``tip3p.xml``.
+
 
 Top-level parameters
 --------------------
 
-All the parametes are optional except stated otherwise.
+*All the parametes are optional except stated otherwise.*
 
 Input options
 .............
@@ -128,8 +145,9 @@ General conditions of simulation
 - ``barostat``: *True* for NPT, *False* for NVT. Defaults to False.
 - ``pressure``: In bar. Only used if barostat is *True*. Defaults to 1.01325.
 - ``barostat_interval``: Update interval of barostat, in steps. Defaults to 25.
-- ``restrained_atoms``, `constrained_atoms`: Parts of the system that should remain restrained (a ``k*((x-x0)^2+(y-y0)^2+(z-z0)^2)`` force is applied to minimize movement) or constrained (no movement at all) during the simulation. Supports ``mdtraj``'s `DSL queries <http://mdtraj.org/latest/atom_selection.html>`_ or a list of 0-based atom indices. Default to None (no freezing).
+- ``restrained_atoms``: Parts of the system that should remain restrained (a ``k*((x-x0)^2+(y-y0)^2+(z-z0)^2)`` force is applied to minimize movement) during the simulation. Supports ``mdtraj``'s `DSL queries <http://mdtraj.org/latest/atom_selection.html>`_ (like ``not protein``) or a list of 0-based atom indices (like ``[0, 1, 40, 55, 67]``). Default to None (no freezing).
 - ``restraint_strength``: If restraints are in use, the strength of the applied force in kJ/mol. Defaults to 5.0.
+- ``constrained_atoms``: Parts of the system that should remain constrained (no movement at all) during the simulation. Supports ``mdtraj``'s `DSL queries <http://mdtraj.org/latest/atom_selection.html>`_ (like ``not protein``) or a list of 0-based atom indices (like ``[0, 1, 40, 55, 67]``). Default to None (no freezing).
 - ``integrator``: Which integrator should be used. Langevin by default.
 - ``friction``: Friction coefficient for integrator, if needed. In 1/ps. Defaults to 1.0.
 - ``minimization_tolerance``: Threshold value minimization should converge to. Defaults to 10 kJ/mole.
@@ -154,3 +172,4 @@ Hardware options
 
 - ``platform``: Which platform to use: *CPU*, *CUDA*, *OpenCL*. If not set, OpenMM will choose the fastest available.
 - ``platform_properties``: A sub-dict of keyworkds to configure the chosen platform. Check the `OpenMM docs <http://docs.openmm.org/7.1.0/api-python/generated/simtk.openmm.openmm.Platform.html#simtk.openmm.openmm.Platform>`_ to know the supported values. Please notice all values must be strings, even booleans and ints; as a result, you should quote the values like this ``'true'``.
+
diff --git a/docs/install.rst b/docs/install.rst
@@ -1,11 +1,14 @@
 .. _install:
 
-============
-Installation
-============
+======================
+Installation & Updates
+======================
+
+How to install OMMProtocol
+--------------------------
 
 First method: Standalone installer
-----------------------------------
+..................................
 
 If you haven't used Anaconda or Miniconda before (a Python distribution with a cool package manager), your best bet is to simply download the installer for the latest release, which includes everything you need.
 
@@ -16,7 +19,7 @@ If you haven't used Anaconda or Miniconda before (a Python distribution with a c
 3. The installer will create, by default, a new directory called ``ommprotocol`` in your ``$HOME``. Under ``ommprotocol/bin``(Linux) or ``ommprotocol/Scripts`` (Windows) you will find the ``ommprotocol`` executable.
 
 Second method: Conda package
-----------------------------
+............................
 
 OMMProtocol is also distributed as a separate ``conda`` package. If you already have Anaconda/Miniconda installed, you won't probably want to download a separate Python distribution. In that case, skip to step 2.
 
@@ -56,7 +59,7 @@ OMMProtocol is also distributed as a separate ``conda`` package. If you already
         ommanalyze -h
 
 Third method: From source
--------------------------
+.........................
 
 If there's no package for your platform, install the dependencies with ``conda`` and then install ``ommprotocol`` from pip or source.
 
@@ -76,16 +79,16 @@ Updating OMMProtocol
 Depending on the installation method, updating OMMProtocol involves different steps.
 
 First method: Standalone installer
-----------------------------------
+..................................
 
-Just `download the installer for the new version <https://github.com/insilichem/ommprotocol/releases>`_ and run it. In Linux/MacOS you will need to append the ``-U`` flag to the installer. In Windows, just follow the wizard.
+Just `download the installer for the new version <https://github.com/insilichem/ommprotocol/releases>`_ and run it. In Linux/MacOS you will need to append the ``-u`` flag to the installer. In Windows, just follow the wizard.
 
 Second method: Conda package
-----------------------------
+............................
 
 Within the activated environment, run ``conda update -c insilichem -c omnia ommprotocol``. That's it.
 
 Third method: From source
--------------------------
+.........................
 
 Simply pass the ``-U`` flag to pip: ``pip install -U ommprotocol`` or, for development version, ``pip install -U https://github.com/insilichem/ommprotocol/archive/master.zip``.
diff --git a/docs/support.rst b/docs/support.rst
@@ -0,0 +1,24 @@
+.. _support:
+
+========
+Get help
+========
+
+If you have any questions, please feel free to `submit an issue <https://github.com/insilichem/ommprotocol/issues>`_ in our `Github repository <https://github.com/insilichem/ommprotocol>`_.
+
+========
+Citation
+========
+
+OMMProtocol is scientific software, funded by public research grants (Spanish MINECO's project ``CTQ2014-54071-P``, Generalitat de Catalunya's project ``2014SGR989`` and research grant ``2017FI_B2_00168``, COST Action ``CM1306``). If you make use of Ommprotocol in scientific publications, please cite it. It will help measure the impact of our research and future funding! A manuscript is in progress. In the meantime, please cite this repository URL.
+
+.. code-block:: latex
+
+    @misc{ommprotocol2017,
+    author       = {Jaime Rodríguez-Guerra Pedregal and
+                    Lur Alonso-Cotchico and
+                    Lorea Velasco and
+                    Jean-Didier Maréchal},
+    title        = {OMMProtocol: A command line application to launch molecular dynamics simulations with OpenMM},
+    url          = {https://github.com/insilichem/ommprotocol}
+    }