Commit 64ed813a authored by Alan O'Cais's avatar Alan O'Cais

Major update to this documentation, merging 4 other repositories

parent 2281117d
_build
_templates
_static
\ No newline at end of file
_static
*.pyc
image: plaindocs/docker-sphinx
pages:
script:
- sudo apt-get -y install dvipng
- make html
- mv _build/html/ public/
artifacts:
paths:
- public
only:
- master
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)
- [ ] 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 the Copyright year up to date?
This diff is collapsed.
.. _ost_committor:
######################################
Committor Analysis 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: David W.H. Swenson
This module adds a simulator to perform committor analysis in
OpenPathSampling, given a set of initial points to shoot from.
Purpose of Module
_________________
.. Give a brief overview of why the module is/was being created.
Frequently, we try to launch several trajectories from a point that
is not in any state, to see which state they land in. In a transition
A->B, the fraction that land in B is called the "committor" at that
point. Configurations which lead to a committor of approximately 50%
are said to make up the "transition state ensemble." This code
provides a straightforward way of calculating the committor for a
given set of initial conditions.
While this direct approach is not necessarily the best way to
calculate the committor, it is still a very useful tool for
obtaining initial trajectories for path sampling simulations.
The implementation in this module includes:
* ``SnapshotModifier`` abstract class to change a snapshot, along with
concrete subclasses ``NoModification`` (used in testing) and
``RandomVelocities`` (used for committor analysis). This same class of
object will be reused for two-way shooting.
* A ``CommittorSimulation`` subclass of ``PathSimulator`` to run the
committor simulation.
* A generic ``TransformedDict`` object which acts as a dictionary, but
applies an arbitrary key-altering function before accessing the keys.
* ``SnapshotByCoordinateDict``, a subclass of ``TransformedDict``, which
uses the coordinates of a snapshot as the internal keys. Thus multiple
snapshots with the same coordinates can map to the same values, regardless
of their velocities.
* ``ShootingPointAnalysis``, a subclass of ``SnapshotByCoordinateDict``,
which performs the analysis of shooting points. This includes calculating
the committor and making 1D and 2D histograms of the committor (mapped
with arbitrary axes).
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,
.. installing its requirements, and running the command ``nosetests`` from the
.. root directory of the repository.
Examples
________
* OPS docs committor example [`GitHub
<https://github.com/openpathsampling/openpathsampling/blob/master/examples/misc/committors.ipynb>`_ | `Docs
<http://openpathsampling.org/latest/examples/miscellaneous/committors.html>`_]
* Alanine dipeptide committor example [`GitHub
<https://github.com/openpathsampling/openpathsampling/tree/master/examples/misc/alanine_dipeptide_committor>`_
| `Docs
<http://openpathsampling.org/latest/examples/miscellaneous/committors_alanine_dipeptide.html>`_]
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
* https://github.com/openpathsampling/openpathsampling/pull/450
* https://github.com/openpathsampling/openpathsampling/pull/454
* https://github.com/openpathsampling/openpathsampling/pull/466
* https://github.com/openpathsampling/openpathsampling/pull/601
* https://github.com/openpathsampling/openpathsampling/pull/618
* https://github.com/openpathsampling/openpathsampling/pull/647
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
.. The source code for this module can be found in: URL.
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _ops_direct_rate_flux:
####################################################
Direct MD (on-the-fly) flux/rate 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: David W.H. Swenson
This module contains code to implement the direct (on-the-fly) calculation
of flux and rate in OpenPathSampling.
Purpose of Module
_________________
.. Give a brief overview of why the module is/was being created.
This calculates the flux out of a state and through an interface, or the
rate of the transition between two states, while running a
trajectory. This means that you don't have to save all the frames of the
trajectory. This is especially useful for small (toy) systems, where you can
easily run very long trajectories to get very accurate results, and would
rather re-run than save the full trajectory.
A separate module calculates the rate and flux from an existing trajectory.
The primary object implemented in this module is the ``DirectSimulation``
subclass of ``PathSimulator``, which performs on-the-fly analysis of flux
and rate.
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,
.. installing its requirements, and running the command ``nosetests`` from the
.. root directory of the repository.
Examples
________
Flux for MISTIS: [`GitHub
<https://github.com/openpathsampling/openpathsampling/blob/master/examples/toy_model_mistis/toy_mistis_2_flux.ipynb>`_ | `Docs
<http://openpathsampling.org/latest/examples/mistis.html>`_]
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
* https://github.com/openpathsampling/openpathsampling/pull/495
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
.. The source code for this module can be found in: URL.
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _ops_flux_rate_analysis:
######################################
Flux/Rate Analysis 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: David W.H. Swenson
This module adds the ability to use existing trajectories to calculate the
flux through an interface or the rate of a transition in OpenPathSampling.
Purpose of Module
_________________
.. Give a brief overview of why the module is/was being created.
After defining volumes with OpenPathSampling, we can use those definitions
to analyze existing trajectories. In particular, we can calculate the flux
out of a given volume and through a dividing surface, or we can calculate
the rate.
The flux calculation is used as part of obtaining the rate in transition
interface sampling (TIS). While some variants of TIS calculate the flux as
part of their primary sampling, others need an auxiliary calculation. In
addition, the flux calculation is always useful for confirming a good
definition of the innermost interface in TIS.
The rate calculation will probably not be used very much, because it
requires long trajectories. Both flux and rate are included as a single
"module" because the code is very closely related.
This module analyses previously existing trajectories. Another module will
calculate these things on-the-fly with an OPS engine.
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,
.. installing its requirements, and running the command ``nosetests`` from the
.. root directory of the repository.
Examples
________
Examples for this have been provided in the ``ops_additional_examples``
repository. In particular, the Jupyter notebooks:
* https://gitlab.e-cam2020.eu/dwhswenson/ops_additional_examples/blob/master/transition_analysis_Abl.ipynb
* https://gitlab.e-cam2020.eu/dwhswenson/ops_additional_examples/blob/master/DNA_flux_example.ipynb
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:
* https://github.com/openpathsampling/openpathsampling/pull/435
* https://github.com/openpathsampling/openpathsampling/pull/448
* https://github.com/openpathsampling/openpathsampling/pull/451
* https://github.com/openpathsampling/openpathsampling/pull/654
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
.. The source code for this module can be found in: URL.
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _ops_maximumlikelihood:
#######################################################
Maximum likelihood optimization of reaction coordinates
#######################################################
.. 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
https://gitlab.e-cam2020.eu/Classical-MD_openpathsampling/MaxLikelihood/tree/master/examples
Licence
LGPL v. 2.1 or later
.. contents:: :local:
Authors: Clemens Moritz and Raffaela Cabriolu
This module implements an OpenPathSampling library that provides a maximum
likelihood analysis to obtain an optimal reaction coordinate by combining
multiple collective variables.
Purpose of Module
_________________
OpenPathSampling (OPS) is a software package that simulates complex processes
using path sampling techniques and yields reactive trajectories between states
of interest in a given system. However, such trajectories do not automatically
lead to a physical understanding of the reaction mechanism.
To gain such an understanding it is desirable to find a set of collective
variables (CVs) that carry physically important information about the process.
The size and the shape of a crystalline cluster in a freezing liquid, the number
of native contacts in a folding protein or bond length and bond angles in
chemical reactions are examples of such CVs. The aim of this module is to find
an optimized combination of multiple CVs into a single coordinate, that monitors
the progress of the reaction. Such a coordinate is commonly called a reaction
coordinate.
In methods used to study complex processes, having a good reaction coordinate
either significantly improves their efficiency or it is a prerequisite for the
reliability of their results.
The reaction coordinate is constructed by optimizing the likelihood function
:math:`L = \prod_{\mathrm{yes}} p(r(q_i)) ~ \prod_{\mathrm{no}} (1-p(r(q_i))),`
where r is a reaction coordinate model that combines several CVs, q_i, into a
reaction coordinate and p is the probability model that maps this coordinate to
a probability of having a successful outcome (yes). The definition of a
successful outcome depends on the chosen probability model. Both r and p depend
on a set of coefficients that are used to maximize L.
For more details on the method, please refer to the references given in
`Background Information`_.
Classes and objects implemented in this module:
* ``TargetFunctionDescription`` class. Wrapper around functions that carries additional information such as the number of parameters which shall be varied during subsequent optimization.
* ``REACTION_COORDINATE_MODELS`` dictionary of objects of the class ``TargetFunctionDescription``. Collection of commonly used reaction coordinate models. At the moment two combinations of collective variables are available: a linear function, and a quadratic function. Additionally the user can define custom functions.
* ``PROBABILITY_MODELS`` dictionary of objects of the class ``TargetFunctionDescription``. Collection of commonly used probability models. At the moment two functions are available: a sigmoidal function as a model for committor probabilities and a symmetric peaked function as a model for the probability of finding a transition path starting from the configuration r.
* ``MaxLikelihoodCVAnalysis`` class. It implements the maximum likelihood analysis. There are two methods implemented: one for optimization based on committor probabilities, using an ``openpathsampling.ShootingPointAnalysis`` object (``optimize_from_spa``), and an other one where the user can perform optimizations for custom problems, using the ``optimize`` method.
Background Information
______________________
This module is built on the OpenPathSampling library. More information about it are given in the following links:
* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling
Information about the method can be found in these publications:
* Peters, B. & Trout, B. L. "Obtaining reaction coordinates by likelihood maximization." J. Chem. Phys. 125, 54108 (2006).
* Peters, B., Beckham, G. T. & Trout, B. L. "Extensions to the likelihood maximization approach for finding reaction coordinates." J. Chem. Phys. 127, 34109 (2007).
* Peters, B. "Reaction Coordinates and Mechanistic Hypothesis Tests." Annu. Rev. Phys. Chem. 67, annurev-physchem-040215-112215 (2016).
Testing
_______
To test this module you need to download the source files package (see the ``Source Code`` section below) and install it using ``python setup.py install`` from the root directory of the package. In the ``ops_maxlikelihood/tests`` folder type ``nosetests`` to test the module using the `nose`_ package.
Examples
________
The example of the Maximum Likelihood module on the 2D toy model implemented in OPS is given in the directory examples. Open it using ``jupyter notebook ExampleMaximumLikelihood2DToyModel.ipynb`` (see Jupyter notebook documentation at http://jupyter.org/ for more details).
Source Code
___________
Source code can be found at https://gitlab.e-cam2020.eu/Classical-MD_openpathsampling/MaxLikelihood
.. Here are the URL references used
.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _nose: http://nose.readthedocs.io/en/latest/
.. _ost_example:
#################
OPS-based modules
#################
.. 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: Alan O'Cais
This is the template for an E-CAM *module* based on OpenPathSampling (OPS). Several
sections are already pre-filled with the details of OPS. Please fill out the
rest in order to make your module. Feel free to add additional information as
well. This section should provide a very brief description of your module.
To add your module, please follow the instructions in ":ref:`contributing`" but create your module
in a subdirectory of ``modules/OpenPathSampling`` and use a copy of
:download:`this file <./ops_module_template.rst>` as a starting point.
Push your changes
back to GitLab and immediately open a merge request from your feature branch
against our repository. We can discuss your module in the merge request and
help you get it accepted.
For more details and the syntax for further functionality, see the generic example module in the
``modules/example_module/`` directory (:ref:`example`).
Purpose of Module
_________________
.. Give a brief overview of why the module is/was being created.
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,
.. installing its requirements, and running the command ``nosetests`` from the
.. root directory of the repository.
Examples
________
Link to examples, if you have one. May be a file within your source code.
Source Code