Merge pull request #471 from dwhswenson/documentation

Docs on Networks

devtools/ci/after_sucess.sh

@@ -33,7 +33,7 @@ conda list -e
 # Install pandoc for markdown support
 sudo apt-get install pandoc
 
-(cd docs && make html && cd -)
+(cd docs && python premake.py && make html && cd -)
 ls -lt docs/_build
 pwd
 echo travis_fold:end:build.docs

docs/.gitignore

@@ -1,2 +1,7 @@
 # ignore _build/, which is where the generated docs go
 _build
+guides/absolute_beginners.rst
+guides/power_users.rst
+guides/user_levels.rst
+api
+netcdfplus/api

docs/conf.py

@@ -89,7 +89,7 @@
 
 # General information about the project.
 project = u'OpenPathSampling'
-copyright = u'2014, Jan-Hendrik Prinz, John Chodera, David W.H. Swenson, Peter Bolhuis'
+copyright = u'2016, Jan-Hendrik Prinz, David W.H. Swenson, John Chodera, Peter Bolhuis'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/guides/index.rst

@@ -3,29 +3,19 @@
 Guides to OpenPathSampling
 ==========================
 
-This section contains larger texts that discuss more detailed the works of OpenPathSampling.
-
-.. markdown:: docs/guides/user_levels.md
-
-
-For Beginners
--------------
-
-.. markdown:: docs/guides/absolute_beginners.md
-
-
-For advanced users
-------------------
-
-.. markdown:: docs/guides/power_users.md
+This section contains larger texts that discuss more detailed the works of
+OpenPathSampling.
 
+.. toctree::
+    user_levels
+    absolute_beginners
+    power_users
 
 Topics
 ======
 
 This part covers discussions about various topics.
 
-
-Ensembles vs Volumes
---------------------
+.. toctree::
+   transitions_and_networks
 

docs/guides/transitions_and_networks.rst

@@ -0,0 +1,200 @@
+.. _transitions-and-networks:
+
+========================
+Transitions and Networks
+========================
+
+Different path sampling approaches use different kinds of ensembles. But
+what they all share in common is that those ensembles represent some network
+of transitions.
+
+Under most circumstances, the user can directly work with
+:class:`TransitionNetworks <.TransitionNetwork>`, and never needs to work
+directly with :class:`Ensembles <.Ensemble>`.  This document describes the
+internal structure of :class:`TransitionsNetworks <.TransitionNetwork>`, and
+explains how to customize that structure with different ensembles if so
+desired.
+
+This also covers some of the interface between :class:`TransitionNetworks
+<.TransitionNetwork>` and :py:class:`.MoveStrategy` objects. When developing
+new methodologies, this interface allows for high levels of flexibility. A
+new :class:`.TransitionNetwork` could be combined with a customized
+:class:`.MoveStrategy` to develop all sorts of path-sampling-like
+approaches.
+
+:class:`Networks <.TransitionNetwork>` are made of :class:`Transitions <.Transition>`
+=====================================================================================
+
+A transition describes a set of paths with certain allowed initial and final
+conditions. There are two groups of transitions that are important when
+working with networks. First, there are the
+:attr:`~.TransitionNetwork.sampling_transitions`, which are what are
+actually sampled by the dynamics. Then there are
+:attr:`~.TransitionNetwork.analysis_transitions` (or just
+:attr:`~.TransitionNetwork.transitions`) which are the subjects of analysis.
+
+The difference between these is easily described in the context of MSTIS.
+With MSTIS, you use one set of ensembles to sample the transitions from a
+given state to all other states. So you would sample :math:`A\to (B \text{ or }
+C)`, but the analysis transitions would include separate studies of
+:math:`A\to B` and :math:`A\to C`.
+
+The network is defined by the combination of what the underlying transitions
+to study are, and the approach used to study them. It defines a set of path
+ensembles which are sampled during the dynamics, and the way to combine
+those afterward into results that connect to physical meaning.
+
+Handcrafting :class:`Networks <.TransitionNetwork>`
+---------------------------------------------------
+
+Beyond the simple tools to customize the networks you study, you can
+manually create them with whatever complexity you desire. The
+:class:`Network <.TransitionNetwork>` level of code is designed to interact
+with the :class:`.MoveScheme` and :class:`.MoveStrategy` code, as well as
+with some of the analysis tools. As long as
+you implement a few items, your custom :class:`Network <.TransitionNetwork>`
+will work seamlessly with those.
+
+The main point is that there are two aspects of the network: there's the
+sampling network, which is organizes the ensembles as used in sampling, and
+the analysis network, which actually consists of the specific transitions
+you're interested in studying.
+
+Handcrafting the sampling network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The sampling network consists of three objects:
+
+* :attr:`network._sampling_transitions
+  <.TransitionNetwork._sampling_transitions>`: a list of transitions;
+  contains all the normal ensembles (accessible as
+  :attr:`network.sampling_transitions
+  <.TransitionNetwork.sampling_transitions>`)
+* :attr:`network.special_ensembles <.TransitionNetwork.special_ensembles>`:
+  a dictionary with strings for keys, describing
+  the type of ensemble, and dictionaries for values. Those value dictionaries
+  have the ensembles themselves as keys, and a list of associated transitions as
+  values.
+* :attr:`network.hidden_ensembles <.TransitionNetwork.hidden_ensembles>`:
+  this list is empty when built by the network, and is set by the MoveScheme
+  if necessary. This consists of ensembles that aren't part of the network,
+  but are part of the move scheme.
+
+The special ensembles need to have the correct key names to work with the
+:class:`.MoveScheme` and :class:`.MoveStrategy` subsystem. These are
+``'minus'`` for the minus interfaces, and ``'ms_outer'`` for the multiple
+state outer interfaces.
+
+If you do that, then :class:`.MoveStrategy` and :class:`.MoveScheme` will
+work with your networks.
+
+Handcrafting the analysis network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The analysis network is determined by the list of all state pairs that
+represent the transitions you're studying. It is contained in the
+:class:`network.transitions <.TransitionNetwork.transitions>` dictionary,
+which has keys of tuples in the form ``(stateA, stateB)`` with values of the
+:class:`.Transition` object that describes the :math:`A\to B` transition.
+During analysis calculations, you will often perform the analysis on the
+sampling network, but copy the results of that analysis to the transition
+network using
+:meth:`analysis_transition.copy_analysis_from(sampling_transition)
+<.Transition.copy_analysis_from>`.  For example, in MSTIS, you only run one
+crossing probability analysis per state (per sampling transition), but this
+is used to link to all the specific state-to-state transitions in the
+analysis network.
+
+Examples of Networks and Transitions
+====================================
+
+Two-state network
+-----------------
+
+It is perhaps easiest to understand the idea of networks and transitions if
+we visualize them for the case of transition interface sampling. Let's take
+one of the commonly-used illustrations of TIS as a starting point:
+
+.. image:: two_state_tis.png
+
+Here we see two transitions: :math:`A\to B` and :math:`B\to A`. In this
+simple example, there is no distinction between sampling transitions and
+analysis transitions. Each transition consists of several ensembles. The
+ensembles define the paths that will actually be sampled during the path
+sampling simulation. The transitions provide a context for analyzing those
+results: in TIS, we combine results from sampling multiple ensembles in a
+specific way in order to determine rates. The :class:`Transition` object
+keeps the information on how to combine information from its various
+ensembles.
+
+In practice, this network can be created as either an :class:`.MSTISNetwork`
+or a :class:`.MISTISNetwork`:
+
+.. code-block:: python
+
+   # mstis version 
+   mstis = paths.MSTISNetwork([
+       (stateA, interfacesAB, orderparameterAB),
+       (stateB, interfacesBA, orderparameterBA)
+   ])
+
+   # mistis version
+   mistis = paths.MISTISNetwork([
+       (stateA, interfacesAB, orderparameterAB, stateB),
+       (stateB, interfacesBA, orderparameterBA, stateA)
+   ])
+
+Both of these would give the same behavior.
+
+Note that there are other approaches that could give different networks. By
+default, both :class:`.MSTISNetwork` and :class:`.MISTISNetwork` create a
+"multiple state outer interface," which links the two transitions. Whether
+this interface is actually used depends on the :class:`.MoveScheme`:
+however, another network type might not even make it. Similarly, the
+transitions in both of these create a :class:`.MinusInterfaceEnsemble`,
+which could be removed.
+
+For simplicity, we recommend that users who wish to avoid making use of
+these ensembles adjust the :class:`.MoveStrategy` and :class:`.MoveScheme`
+to manage that, rather than creating a new :class:`.TransitionNetwork`.
+
+Three-state networks
+--------------------
+
+Now let's consider a 3-state system. In the image below, we illustrate the
+sampling network for an :class:`.MSTISNetwork` for a 3-state system.
+
+.. image:: three_state_tis.png
+
+In this example, there are 3 sampling transitions: 
+
+* from state A, through the interfaces associated with A, and to either
+  state B or state C
+* from state B, through the interfaces associated with B, and to either
+  state A or state C
+* from state C, through the interfaces associated with C, and to either
+  state A or state B
+
+However, there are 6 analysis transitions: :math:`A\to B`, :math:`A\to C`,
+:math:`B\to A`, :math:`B\to C`, :math:`C\to A`, and :math:`C\to B`. Each
+sampling transition samples for two analysis transitions.
+
+When you want a rate, you want the rate for the analysis transition. For
+example, you would typically want a rate for the :math:`A\to B` process, not
+the :math:`A\to (B \text{ or } C)` process, which is what the sampling
+transition would give you. However, the sampling transitions can be much
+more efficient to sampling: the number of analysis transitions scales as the
+square of the number of states, while, in MSTIS, the number of sampling
+transitions scales linearly with (actually, is equal to) the number of
+states.
+
+:class:`MISTISNetworks <.MISTISNetwork>`, on the other hand, have a sampling
+transition for each analysis transition. This can give the advantage of
+allowing a better order parameter to be used as an approximation to very
+different reaction coordinates coming from the same state. It also allows
+you to focus on only a subset of the :math:`N^2` possible transitions.
+
+By distinguishing between sampling transitions and analysis transitions,
+OpenPathSampling makes it easy to allow this kind of flexibility in the
+underlying sampling style, while still making it very easy to set up a given
+kind of network with minimal code.

docs/index.rst

@@ -35,6 +35,7 @@ API Reference
     pathsimulator
     storage
     treemixin
+    network
     engines/openmm
 
 Developing
@@ -61,4 +62,4 @@ README
 
 License
 -------
-OpenPathSampling is licensed under ???
+OpenPathSampling is licensed under the LGPL, v. 2.1 or later.

docs/network.rst

@@ -0,0 +1,50 @@
+.. _network:
+
+.. currentmodule:: openpathsampling.analysis.network
+
+Networks
+========
+
+Networks are an easy way to set up ensembles for path sampling calculations,
+and to retain a context for those ensembles when analyzing the results of a
+simulation.
+
+Many path sampling methods (transition interface sampling as one example)
+require sampling multiple path ensembles, and then results from those path
+ensembles are combined in analysis. As such, the path ensemble itself is not
+enough: you need both the path ensemble and its context. Networks provide
+that context.
+
+Networks are so named because they allow the study of complicated transition
+networks, instead of just single transitions. It is at this level that we
+encounted ideas like multiple state path sampling methods and multiple
+interface set transition interface sampling.
+
+A longer discussion of networks, and the associated concept of transitions,
+can be found in the file `Transitions and Networks
+<guides/transitions_and_networks.html>`_.
+
+
+
+Abstract class
+--------------
+.. autosummary::
+   :toctree: api/generated
+
+   TransitionNetwork
+
+TPS networks
+------------
+.. autosummary::
+   :toctree: api/generated
+
+   TPSNetwork
+   FixedLengthTPSNetwork
+
+TIS networks
+------------
+.. autosummary::
+   :toctree: api/generated
+
+   MSTISNetwork
+   MISTISNetwork

docs/premake.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python
+
+import os
+import re
+
+docs_prefix = "docs"
+
+# We should have thing_to_wrap.md, wrap it in rst
+things_to_wrap = [
+    "guides/absolute_beginners", "guides/power_users", "guides/user_levels"
+]
+
+def clean_filename(fname, strip_path=True):
+    fname = re.sub('\_', '-', fname)
+    if strip_path:
+        fname = re.sub('.*\/', '', fname)
+    return fname
+
+def wrap_file(basename):
+    md_file = basename + ".md"
+    assert(os.path.isfile(md_file))
+    clean_name = clean_filename(basename, strip_path=True)
+    rst_file = basename + ".rst"
+    lines = [".. _"+clean_name+":\n", 
+             ".. markdown:: " + docs_prefix + "/" + md_file]
+    rst = open(rst_file, "w")
+    for line in lines:
+        rst.write(line)
+
+if __name__ == "__main__":
+    for thing in things_to_wrap:
+        wrap_file(thing)