readme.rst 5.86 KB
Newer Older
1
.. _ops_maximumlikelihood:
Raffaela's avatar
Raffaela committed
2

3
4
5
#######################################################
Maximum likelihood optimization of reaction coordinates
#######################################################
Raffaela's avatar
Raffaela committed
6
7
8

.. sidebar:: Software Technical Information

Raffaela's avatar
Raffaela committed
9
This module is based on OpenPathSampling. This section includes information for the specific module and refers to the OpenPathSampling library. 
Raffaela's avatar
Raffaela committed
10
11
12
13
14
15
16
17
18
19
20
21
22

  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

23
24
  Licence
    LGPL v. 2.1 or later 
Raffaela's avatar
Raffaela committed
25

26
.. contents:: :local:
Raffaela's avatar
Raffaela committed
27

Raffaela's avatar
Raffaela committed
28
This module implements an OpenPathSampling library that provides a maximum 
29
30
likelihood analysis to obtain an optimal reaction coordinate by combining 
multiple collective variables. 
Raffaela's avatar
Raffaela committed
31
32
33
34

Purpose of Module
_________________

35
OpenPathSampling (OPS) is a software package that simulates complex processes 
Raffaela's avatar
Raffaela committed
36
using path sampling techniques and yields reactive trajectories between states 
37
38
39
40
41
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.

Raffaela's avatar
Raffaela committed
42
43
44
45
46
47
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.
48

Raffaela's avatar
Raffaela committed
49
50
51
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.
52

Raffaela's avatar
Raffaela committed
53
The reaction coordinate is constructed by optimizing the likelihood function 
Raffaela's avatar
Raffaela committed
54

Raffaela's avatar
Raffaela committed
55
:math:`L = \prod_{\mathrm{yes}} p(r(q_i)) ~ \prod_{\mathrm{no}} (1-p(r(q_i))),`
Raffaela's avatar
Raffaela committed
56

Raffaela's avatar
Raffaela committed
57
where r is a reaction coordinate model that combines several CVs, q_i, into a 
Clemens Moritz's avatar
Clemens Moritz committed
58
59
60
61
62
63
64
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`_.
Raffaela's avatar
Raffaela committed
65
66
67

Classes and objects implemented in this module: 

Raffaela's avatar
Raffaela committed
68
* ``TargetFunctionDescription`` class. Wrapper around functions that carries additional information such as the number of parameters which shall be varied during subsequent optimization. 
Raffaela's avatar
Raffaela committed
69

Raffaela's avatar
Raffaela committed
70
* ``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.
Raffaela's avatar
Raffaela committed
71

Raffaela's avatar
Raffaela committed
72
* ``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.
Raffaela's avatar
Raffaela committed
73

Raffaela's avatar
Raffaela committed
74
* ``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.
Raffaela's avatar
Raffaela committed
75
76
77
78

Background Information
______________________

Raffaela's avatar
Raffaela committed
79
This module is built on the OpenPathSampling library. More information about it are given in the following links: 
Raffaela's avatar
Raffaela committed
80
81
82
83

* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling

Raffaela's avatar
Raffaela committed
84
85
86
87
88
89
90
91
92
93
94
95
96
The following ``Testing`` and ``Examples`` section have been tested with the version
of OpenPathSampling at 24 Jul 2017. To retrieve this version

::

  conda uninstall openpathsampling
  conda install future
  conda install msmbuilder
  git clone git://github.com/openpathsampling/openpathsampling.git
  cd openpathsampling
  git checkout 494f365feea888bdd7da717855829006557ac907
  pip install -e .

Raffaela's avatar
Raffaela committed
97
98
99
100
101
102
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).

Raffaela's avatar
Raffaela committed
103
104
105
Testing
_______

Raffaela's avatar
Raffaela committed
106
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.
Raffaela's avatar
Raffaela committed
107
108
109
110

Examples
________

Raffaela's avatar
Raffaela committed
111
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).
Raffaela's avatar
Raffaela committed
112
113
114
115
116


Source Code
___________

Clemens Moritz's avatar
Clemens Moritz committed
117
Source code can be found at https://gitlab.e-cam2020.eu/Classical-MD_openpathsampling/MaxLikelihood
Raffaela's avatar
Raffaela committed
118
119
120
121

.. Here are the URL references used

.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html
Raffaela's avatar
Raffaela committed
122
.. _nose: http://nose.readthedocs.io/en/latest/