Commit 2d91a08c authored by Alan O'Cais's avatar Alan O'Cais
Browse files

Merge branch 'master' into qtb_pim

parents 9478e886 4d56b60c
_build
_templates
*.pyc
*.DS_Store
image: umbrellium/sphinx-doc
image: cloudcompass/docker-rtdsphinx
spelling:
script:
- pip3 install codespell
- codespell --skip=".git,_static,_build,Diff*,*.patch" --quiet-level=2 --ignore-words-list="adress"
only:
- master
- merge_requests
orphans:
script:
# Report all the orphans but ignore the exit code
- find ./ -name "*.rst"|xargs -i grep -H orphan {} || true
# Now handle the error code
- if [ $(find ./ -name "*.rst"|xargs -i grep -H orphan {}|wc -l) -gt "1" ]; then $(exit 1); else $(exit 0); fi
only:
- master
pages:
script:
- apt-get update
- apt-get -y install dvipng
- pip3 install pygments --upgrade
- pip3 install Sphinx --upgrade
- pip3 install sphinx-bootstrap-theme --upgrade
- READTHEDOCS=True sphinx-build -nWT -b html . _build/html
- mv _build/html/ public/
artifacts:
......@@ -11,3 +30,4 @@ pages:
- public
only:
- master
- merge_requests
......@@ -9,9 +9,9 @@ This issue refers to Merge Request (insert MR reference)
- [ ] Is the module documentation sufficiently detailed?
- [ ] Is it mergeable? (i.e., there should be no merge conflicts)
- [ ] Are the build instructions sufficient? (If not the MR should be updated)
- [ ] Are the build instructions sufficient - source code locations, build instructions, etc.? (If not the MR should be updated)
- [ ] Did it pass the tests? (Are there unit/regression tests? Do they pass?)
- [ ] If it introduces new functionality, is it tested? (Unit tests?)
- [ ] Is it well formatted? (typos, line length, brackets,...)
- [ ] Is all new source code sufficiently documented? (functions, their arguments,...)
- [ ] Did it change any interfaces? Only additions are allowed without a major version increment (if >v1.0). Changing file formats also requires a major version number increment.
- [ ] Is there a description of any applications the module has? (This is a hard requirement for E-CAM PDRAs)
Add a brief description briefly here (which replaces this sentence), a line or two is usually enough.
## Module verification checklist (for reviewers)
*Checklist when the module is first submitted*
- [ ] Have the relevant labels been added to the MR
- [ ] If submitted on someone elses behalf, has the software author been referenced (if they have a GitLab account)
*Checklist when module is no longer "WIP"*
- [ ] Is the module documentation sufficiently detailed?
- [ ] Is it mergeable? (i.e., there should be no merge conflicts)
- [ ] Are the build instructions sufficient - source code locations, build instructions, etc.? (If not the MR should be updated)
- [ ] Did it pass the tests that were described? (Are there unit/regression tests? Do they pass?)
- [ ] Are the tests sufficient?
- [ ] If the module introduces new functionality, is it tested? (Unit/regression tests?)
- [ ] Is the associated source code well formatted? (typos, line length, brackets,...it should be consistent with existing source)
- [ ] Is all new source code sufficiently documented? (functions, their arguments,...)
- [ ] Is there a description of any applications the module has? (This is a hard requirement for E-CAM PDRAs)
*After Merging*
- [ ] Make sure the module appears in a toctree
- [ ] Add a link to the final result on https://e-cam.readthedocs.io
......@@ -184,6 +184,8 @@ The modules that are based on OPS, but remain separate, are:
./modules/ops_piggybacker/readme
./modules/contact_maps/readme
./modules/contact_maps_parallelization/readme
./modules/dw_dimer_testsystem/readme
./modules/lammps_ops/readme
Nine of these modules were part of
`E-CAM Deliverable 1.2 <https://www.e-cam2020.eu/deliverables/>`_. Those modules
......@@ -198,6 +200,21 @@ together with the partner and typically are to facilitate or improve the scope o
partner. The related code development for the pilot projects are open source (where the licence of the underlying
software allows this) and are described in the modules associated with the pilot projects.
More information on Classical MD pilot projects can be found on the main E-CAM website:
* `Project on binding kinetics <https://www.e-cam2020.eu/pilot-project-biki/>`_
* `Project on food and pharmaceutical proteins <https://www.e-cam2020.eu/pilot-project-food-proteins/>`_
The following modules were developed specifically for the Classical MD pilot projects.
.. toctree::
:glob:
:maxdepth: 1
./modules/contact_maps/readme
./modules/contact_maps_parallelization/readme
./modules/contact_concurrences/readme
Extended Software Development Workshops (ESDWs)
===============================================
......@@ -222,5 +239,9 @@ August 2017. The following modules have been produced:
:maxdepth: 1
./modules/OpenPathSampling/ops_spring_shooting/readme
./modules/OpenPathSampling/ops_sr_shooter/readme
./modules/OpenPathSampling/ops_web_throwing/readme
./modules/OpenPathSampling/ops_plumed_wrapper/readme
./modules/OpenPathSampling/ops_s_shooting/readme
.. _E-CAM: https://www.e-cam2020.eu/
.. _ops_plumed_wrapper:
###################################
PLUMED Wrapper for OpenPathSampling
###################################
.. sidebar:: Software Technical Information
The information in this section describes OpenPathSampling as a whole.
Information specific to the additions in this module are in subsequent
sections.
Language
Python (2.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later
.. contents:: :local:
Authors: Alberto Pérez de Alba Ortíz
This module interfaces OpenPathSampling (OPS) with PLUMED, an open-source
library with a rich catalogue of Collective Variables (CVs).
Special thanks to Gareth A. Tribello for facilitating the use of the
PLUMED Cython wrapper.
* G.A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni, G. Bussi,
PLUMED2: New feathers for an old bird, Comp. Phys. Comm. 185, 604 (2014);
https://doi.org/10.1016/j.cpc.2013.09.018
Purpose of Module
_________________
.. Give a brief overview of why the module is/was being created.
Transition path sampling simulations and analysis rely on accurate state
definitions. Such states are typically defined as volumes in a CV-space.
OPS already supports a number of CVs, including the ones defined in the
MDTraj Python library. PLUMED, an open-source C++ library, offers a wide
variety of extra CVs, which are enabled in OPS by this module.
Many of PLUMED's dozens of CVs have a biomolecular focus, but they are
also general enough for other applications. PLUMED's popularity (over
500 citations in 4 years after the release of PLUMED2) is greatly based
on the fact that it works with many MD codes. OPS is now added to that
list. The PLUMED code is well-maintained and documented for both users
and developers. Several tutorials and a mailing list are available to
address FAQs. For more information about the PLUMED code, visit:
http://www.plumed.org/home
In this module, the class ``PLUMEDInterface`` is a subclass of the
Cython wrapper class ``Plumed`` contained in the PLUMED installation.
For initialization, ``PLUMEDInterface`` requires an ``MDTrajTopology``
and accepts additional PLUMED settings:
* ``pathtoplumed=""`` is the path to the PLUMED installation, where the
``sourceme.sh`` script is run to set all relevant flags. By default,
the string is empty and the currently sourced PLUMED is used.
* ``timestep=1.`` is the time step size in PLUMED units (ps).
* ``kbt=1.`` is :math:`$k_BT$` in PLUMED units (kJ/mol).
* ``molinfo=""`` is a file to be used as ``STRUCTURE`` for the
``MOLINFO`` PLUMED command. It allows to provide extra information
about the molecules. Consult:
https://plumed.github.io/doc-v2.4/user-doc/html/_m_o_l_i_n_f_o.html
* ``logfile=plumed.log`` is the name of the log file written by the
``PLUMEDInterface``.
The initialized ``PLUMEDInterface`` can be subsequently used to make
functions that calculate CVs for a given ``Trajectory``. This is done
via the ``PLUMEDCV`` class, a subclass of ``CoordinateFunctionCV``.
In PLUMED input files, a common syntax is: ``label: keywords``. The
class ``PLUMEDCV`` takes ``name`` and ``definition`` as arguments,
which are respectively equivalent to PLUMED's ``label`` and
``keywords``. The ``PLUMEDCV`` class also takes the ``PLUMEDInterface``
as argument. This allows for a single ``PLUMEDInterface`` to contain
the ``MDTrajTopology``, additional PLUMED ``keywords`` and previously
defined CVs that can be reused for the same system. Both
``PLUMEDInterface`` and ``PLUMEDCV`` are storable.
This module supports (as listed in PLUMED documentation):
* Groups and Virtual Atoms: are directly set in the ``PLUMEDInterface``
via the ``PLUMEDInterface.set(name, definition)`` function. The
``PLUMEDInterface.get()`` function allows to consult the commands
that have been already set. Some commands do not need a ``name``,
while some others must be run before any other command (e.g.
``UNITS``).
* CV Documentation: all CVs are created by calling ``PLUMEDCV(name,
PLUMEDInterface, definition)``. The returned function can be applied
to a ``Trajectory``. CVs with components should specify the
``components=["c1", "c2", "c3", ...]`` keyword and the corresponding
PLUMED keywords in the ``definition``.
* Distances from reference configurations: also created by calling
``PLUMEDCV(name, PLUMEDInterface, definition)``. Most of them require
external files with reference configurations.
* Functions: also created by calling ``PLUMEDCV(name, PLUMEDInterface,
definition)``. They should be created using the same ``PLUMEDInterface``
that contains the previously defined CVs that are part of the
function.
* Multicolvar and Exploiting contact matrices are not tested.
For examples see the ``Examples`` section below.
For further PLUMED usage details see:
http://plumed.github.io/doc-master/user-doc/html/index.html
Background Information
______________________
This module builds on OpenPathSampling, a Python package for path sampling
simulations. To learn more about OpenPathSampling, you might be interested
in reading:
* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling
Testing
_______
Tests in OpenPathSampling use the `nose`_ package.
.. IF YOUR MODULE IS IN OPS CORE:
.. This module has been included in the OpenPathSampling core. Its tests can
.. be run by setting up a developer install of OpenPathSampling and running
.. the command ``nosetests`` from the root directory of the repository.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
The tests for this module can be run by downloading its source code (see the
``Source Code`` section below), installing its requirements, and running the
command ``nosetests`` from the root directory of the repository.
Examples
________
* Examples on how create and calculate PLUMED CVs can be found in
``plumed_wrapper_example.ipynb`` in the ``examples`` directory
(https://gitlab.e-cam2020.eu/apdealbao/plumed_wrapper/tree/master/plumed_wrapper/examples).
Open it using ``jupyter notebook plumed_wrapper_example.ipynb``
(see http://jupyter.org/ for more details).
Source Code
___________
.. link the source code
.. IF YOUR MODULE IS IN OPS CORE
.. This module has been merged into OpenPathSampling. It is composed of the
.. following pull requests:
.. * link PRs
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
The source code for this module can be found in:
https://gitlab.e-cam2020.eu/apdealbao/plumed_wrapper/tree/master
It can be installed by running ``pip install -e .`` from the root directory
of the package.
It requires to have the PLUMED development version (with the Cython wrapper)
installed from: https://github.com/plumed/plumed2; and to source the file
``/path/to/plumed2/sourceme.sh``
For details on PLUMED installation, see:
http://plumed.github.io/doc-master/user-doc/html/_installation.html
**Before using this module, please test the Cython PLUMED wrapper by attempting
to** ``import plumed`` **in Python.** If this is not successful, please refer to PLUMED
installation documentation (above), or to the mailing list:
https://groups.google.com/forum/#!forum/plumed-users
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _ost_s_shooting:
##############################
S-shooting in OpenPathSampling
##############################
.. sidebar:: Software Technical Information
The information in this section describes OpenPathSampling as a whole.
Information specific to the additions in this module are in subsequent
sections.
Language
Python (2.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later
.. contents:: :local:
Authors: Andreas Singraber
This module implements the S-shooting method [1]_ in OpenPathSampling.
Purpose of Module
_________________
S-shooting [1]_ is a recently developed method to determine rate constants of
rare events. It is similar in spirit to the reactive flux method but its
relaxed requirements help to overcome practical problems. The method is based
on a simple shooting algorithm where trajectories are propagated forward and
backward in time for a fixed number of timesteps. The starting points need to
be provided and must lie in the saddle point region. This so-called S region
(hence the name S-shooting) is defined via a suitable reaction coordinate and
must to separate the stable states A and B in such a way that no trajectory can
connect A with B without visiting S. In contrast to the reactive flux method
the time derivative of the reaction coordinate is not required, which makes
this approach applicable to systems exhibiting diffusive dynamics along the
reaction coordinate. The S-shooting method can also be applied if the initial
shooting points are taken from a biased simulation. Thus, it is a natural
follow-up to free energy calculations like umbrella sampling and, in
combination with free energy curves, allows the computation of rate constants.
The implementation of the S-shooting method in OpenPathSampling (OPS) is split
into two main parts:
- Forward and backward trajectories started from initial snapshots are
harvested and glued together calling the ``SShootingSimulation`` class. The
user needs to provide the initial snapshots, a suitable definition of the
S region and the desired trajectory length.
- The S-shooting analysis is performed upon calling the ``SShootingAnalysis``
class. Mandatory arguments include the definition of the stable states (A and
B) and of the S region. In case the initial snapshots are taken from a biased
simulation a bias function may be provided as an optional argument.
This module comes also with an IPython example notebook demonstrating the
method by applying it to a one-dimensional system (a brownian walker in a
double-well potential).
.. [1] Menzl, G., Singraber, A. & Dellago, C. S-shooting: a Bennett–Chandler-like method for the computation of rate constants from committor trajectories. Faraday Discuss. 195, 345–364 (2017), https://doi.org/10.1039/C6FD00124F
Background Information
______________________
This module builds on OpenPathSampling, a Python package for path sampling
simulations. To learn more about OpenPathSampling, you might be interested in
reading:
* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling
Testing
_______
Follow these steps to test the module:
1. Download and install OpenPathSampling (see http://openpathsampling.org/latest/install.html).
.. caution::
This module has been developed alongside a specific OPS version available at
that time. If incompatibilities arise as OPS is further enhanced, please use
version 0.9.5 available here:
https://github.com/openpathsampling/openpathsampling/releases/tag/v0.9.5 .
2. Install the `nose`_ package.
3. Download the source files of the module (see the `Source Code`_ section below).
4. Install the module: change to the ``S-Shooting`` directory and run ``python setup.py install``.
5. Run the tests: execute ``nosetests`` in the ``S-Shooting`` directory.
.. IF YOUR MODULE IS IN OPS CORE:
.. This module has been included in the OpenPathSampling core. Its tests can
.. be run by setting up a developer install of OpenPathSampling and running
.. the command ``nosetests`` from the root directory of the repository.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
.. The tests for this module can be run by downloading its source code,
.. installing its requirements, and running the command ``nosetests`` from the
.. root directory of the repository.
Examples
________
See the ``sshooting-example.ipynb`` IPython notebook in the source directory, here is the direct link: https://gitlab.e-cam2020.eu/singraber/S-Shooting/blob/master/ops_s_shooting/sshooting-example.ipynb
To run the example execute ``jupyter notebook sshooting-example.ipynb`` in your terminal.
Source Code
___________
.. link the source code
.. IF YOUR MODULE IS IN OPS CORE
.. This module has been merged into OpenPathSampling. It is composed of the
.. following pull requests:
.. * link PRs
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
.. The source code for this module can be found in: URL.
The source code for this module is located here:
https://gitlab.e-cam2020.eu/singraber/S-Shooting
.. tip::
Ultimately, this module will be merged into the official OPS code. Check
the status of the corresponding pull request here:
https://github.com/openpathsampling/openpathsampling/pull/787 .
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _ops_sr_shooter:
########################################
OPS-based module: Shooting range shooter
########################################
.. sidebar:: Software Technical Information
The information in this section describes OpenPathSampling as a whole.
Information specific to the additions in this module are in subsequent
sections.
Language
Python (2.7)
[+Python (3.6)]
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later
.. contents:: :local:
This module implements the "shooting from the top" algorithm as detailed in `the paper "Transition path sampling of rare events by shooting from the top" <http://dx.doi.org/10.1063/1.4997378>`_.
Purpose of Module
_________________
The purpose of this algorithm is to increase the number of generated transitions in a transition path sampling simulation by exclusively shooting from the transition state ensemble (TSE)/the top of the barrier (hence the name). Naturally this only works if the approximate location of the TSE is already known and can be given as a function of the atomic coordinates. In this module any `openpathsampling.Volume`_ object can be used by the user to define the shooting range volume. This enables the user to define the shooting range for example as a function of one or more collective variables. See also the :ref:`tse_module` for finding the TSE.
The implementation in this module includes:
* A ``ShootingRangeSelector`` subclass of ``openpathsampling.ShootingPointSelector`` to pick shooting points only in the predefined shooting range volume.
Background Information
______________________
This module builds on OpenPathSampling, a Python package for path sampling
simulations. To learn more about OpenPathSampling, you might be interested in
reading:
* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling
Testing
_______
Tests in OpenPathSampling and sr_shooter use the `nose`_ package.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
To test this module you need to first install OpenPathSampling, then download the source files for this package (see the ``Source Code`` section below) and install it using
``python setup.py install`` or ``pip install -e .`` from the root directory of the package.
In the root folder then type ``nosetests`` to test the module using the `nose`_ package.
Examples
________
| There are two `example jupyter notebooks <https://gitlab.e-cam2020.eu/hejung/sr_shooter/tree/master/examples>`_ in the example directory of the repository:
| One shows the `general setup of a two way shooting transition path sampling with a shooting range on a toy system <https://gitlab.e-cam2020.eu/hejung/sr_shooter/blob/master/examples/toy_example.ipynb>`_.
| The other is a `comparison between one way shooting and two way shooting from the shooting range <https://gitlab.e-cam2020.eu/hejung/sr_shooter/blob/master/examples/OneWayShooting_vs_TwoWayShooting.ipynb>`_ and shows that path space is explored faster with two way shooting when using a (well placed) shooting range. The reason being that the shots initiated at the barrier top have a high probability of success and two way shooting decorrelates faster (if using randomized velocities even faster).
Source Code
___________
The source code for this module can be found in https://gitlab.e-cam2020.eu/hejung/sr_shooter.
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _openpathsampling.Volume: http://openpathsampling.org/latest/volume.html
......@@ -49,7 +49,7 @@ This module tries to efficiently find a single transition state frame from each
trajectory. This is done by bisection of the trajectory, depending on the
current committor. For example, if the current committor is to high (to much
ends up in state B) the next index is selected halfway towards the left edge
and the current index is set as the new right edge. This is repeated untill a
and the current index is set as the new right edge. This is repeated until a
committor within a given range is reached or no new frame can be selected.
In the end this module returns a dictionary of shape ``{snapshot: comittor
......
.. _ops_web_throwing:
################################
Web Throwing in OpenPathSampling
################################
.. sidebar:: Software Technical Information
The information in this section describes OpenPathSampling as a whole.
Information specific to the additions in this module are in subsequent
sections.
Language
Python (2.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later
.. contents:: :local:
Authors: Sander Roet, Anders Lervik, Enrico Riccardi
This module implements the web throwing method in OpenPathSampling
Purpose of Module
_________________
.. Give a brief overview of why the module is/was being created.
Web throwing is a Monte Carlo move in path space designed to improve the