.. _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.