readme.rst 5.86 KB
Newer Older
 Raffaela committed Apr 04, 2017 1 .. _ops_maximumlikelihood:  Raffaela committed Apr 02, 2017 2   Raffaela committed Apr 04, 2017 3 4 5 ####################################################### Maximum likelihood optimization of reaction coordinates #######################################################  Raffaela committed Apr 02, 2017 6 7 8  .. sidebar:: Software Technical Information  Raffaela committed Apr 04, 2017 9 This module is based on OpenPathSampling. This section includes information for the specific module and refers to the OpenPathSampling library.  Raffaela committed Apr 02, 2017 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  Raffaela committed Apr 04, 2017 23 24  Licence LGPL v. 2.1 or later  Raffaela committed Apr 02, 2017 25   Raffaela committed Apr 04, 2017 26 .. contents:: :local:  Raffaela committed Apr 02, 2017 27   Raffaela committed Apr 04, 2017 28 This module implements an OpenPathSampling library that provides a maximum  Raffaela committed Apr 04, 2017 29 30 likelihood analysis to obtain an optimal reaction coordinate by combining multiple collective variables.  Raffaela committed Apr 02, 2017 31 32 33 34  Purpose of Module _________________  Raffaela committed Apr 04, 2017 35 OpenPathSampling (OPS) is a software package that simulates complex processes  Raffaela committed Apr 04, 2017 36 using path sampling techniques and yields reactive trajectories between states  Raffaela committed Apr 04, 2017 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 committed Apr 04, 2017 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.  Raffaela committed Apr 04, 2017 48   Raffaela committed Apr 04, 2017 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.  Raffaela committed Apr 04, 2017 52   Raffaela committed Apr 04, 2017 53 The reaction coordinate is constructed by optimizing the likelihood function  Raffaela committed Apr 02, 2017 54   Raffaela committed Apr 04, 2017 55 :math:L = \prod_{\mathrm{yes}} p(r(q_i)) ~ \prod_{\mathrm{no}} (1-p(r(q_i))),  Raffaela committed Apr 02, 2017 56   Raffaela committed Apr 04, 2017 57 where r is a reaction coordinate model that combines several CVs, q_i, into a  Clemens Moritz committed Apr 04, 2017 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 committed Apr 02, 2017 65 66 67  Classes and objects implemented in this module:  Raffaela committed Aug 21, 2017 68 * TargetFunctionDescription class. Wrapper around functions that carries additional information such as the number of parameters which shall be varied during subsequent optimization.  Raffaela committed Apr 04, 2017 69   Raffaela committed Aug 21, 2017 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 committed Apr 02, 2017 71   Raffaela committed Aug 21, 2017 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 committed Apr 02, 2017 73   Raffaela committed Aug 21, 2017 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 committed Apr 02, 2017 75 76 77 78  Background Information ______________________  Raffaela committed Apr 04, 2017 79 This module is built on the OpenPathSampling library. More information about it are given in the following links:  Raffaela committed Apr 02, 2017 80 81 82 83  * OPS documentation: http://openpathsampling.org * OPS source code: http://github.com/openpathsampling/openpathsampling  Raffaela committed Aug 21, 2017 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 committed Apr 04, 2017 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 committed Apr 02, 2017 103 104 105 Testing _______  Raffaela committed Aug 21, 2017 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 committed Apr 02, 2017 107 108 109 110  Examples ________  Raffaela committed Aug 21, 2017 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 committed Apr 02, 2017 112 113 114 115 116  Source Code ___________  Clemens Moritz committed Apr 04, 2017 117 Source code can be found at https://gitlab.e-cam2020.eu/Classical-MD_openpathsampling/MaxLikelihood  Raffaela committed Apr 02, 2017 118 119 120 121  .. Here are the URL references used .. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html  Raffaela committed Aug 21, 2017 122 .. _nose: http://nose.readthedocs.io/en/latest/