.. _common-setups:
=============
Common setups
=============
OpenPathSampling is very flexible and simplifies many different approaches
to path sampling. Since it is easy to get lost under all those options, here
we summarize the most common setups of networks and move schemes for
transition path sampling and transition interface sampling.
Throughout the following, we assume that ``A``, ``B``, and ``C`` are
volumes that represent states. We assume that ``interfacesA`` is a list of
interfaces leaving state ``A``, and that ``interfacesAB`` is a list of
interfaces leaving state ``A`` in the expected direction of ``B``.
Similarly, we expect ``orderparameterA`` is a collective variable describing
the process of leaving ``A``, and ``orderparameterAB`` is a CV for leaving
``A`` toward ``B``.
------------------------
Transition Path Sampling
------------------------
Transition networks for TPS
===========================
For all transition path sampling setups, you can use either fixed path
length ensembles or flexible path length ensembles. The fixed path length
ensembles are created with the :class:`.FixedLengthTPSNetwork`, while the
flexible path length ensembles are created with the :class:`.TPSNetwork`.
The interfaces to these classes are the same, except that any method to
create a :class:`.FixedLengthTPSNetwork` requires an extra ``length``
parameter. The same network classes are used for both multiple state TPS
and 2-state TPS.
Unidirectional two-state TPS
----------------------------
The standard initialization of the TPS network objects takes the parameters
``initial_states`` and ``final_states``. If you want a :class:`.TPSNetwork`
from state ``A`` to state ``B``, that can be created with:
.. code-block:: python
network = paths.TPSNetwork(initial_states=A, final_states=B)
This will only sample the :math:`A\to B` transitions. The TPS examples for
alanine dipeptide give practical illustrations of this for both fixed-length
and flexible-length ensembles.
Bidirectional two-state TPS
---------------------------
If you want to sample both the :math:`A\to B` transitions and the
:math:`B\to A` transitions in one TPS simulation, then you can achieve the
desired sampling ensemble in several ways.
First, you could use the approach as above, but using
``initial_states=[A,B]`` and ``final_states=[A,B]``. But there is a shortcut
for this (particularly useful when there are many states) with
.. code-block:: python
network = paths.TPSNetwork.from_states_all_to_all([A,B])
Both of these approaches ignore the self-transitions (:math:`A\to A` and
:math:`B\to B`). You can also explicitly create the transitions with the
:meth:`.TPSNetwork.from_state_pairs` method:
.. code-block:: python
network = paths.TPSNetwork.from_state_pairs([(A,B), (B,A)])
Multiple-state TPS
------------------
The approaches for bidirectional 2-state TPS can be directly generalized to
multiple states. By default, the multiple state ensemble ignores
self-transitions (:math:`A\to A`) if created with either the standard
initialization or with :meth:`from_states_all_to_all
<.TPSNetwork.from_states_all_to_all>`. If you would
like to include the self-transitions (not likely), then add the parameter
``allow_self_transitions=True`` to either the standard initialization or to
``from_states_all_to_all``.
The method :meth:`.from_state_pairs` *will* allow self-transitions if you
explicitly include them. In practice, :meth:`.from_state_pairs` is most
useful when you only want to include certain transitions. For example, if
you have states ``A``, ``B``, and ``C``, but only want to include the
transitions :math:`A\to B`, :math:`A\to C`, and :math:`B\to C`, this is the
method to use. You'd create the network with
.. code-block:: python
network = paths.TPSNetwork.from_state_pairs([(A,B), (A,C), (B,C)])
Move schemes for TPS
====================
Often, when using TPS (and especially when using flexible-length TPS), the
entire move scheme consists of a single shooting mover. A move scheme
consisting of a single one-way shooting move can be created with the
:class:`.OneWayShootingMoveScheme`. The common way to set this up is:
.. code-block:: python
scheme = paths.OneWayShootingScheme(network, selector, engine)
where ``network`` would be the (TPS) network, ``selector`` is a shooting point
selector (usually an instance of :class:`.UniformSelector`), and ``engine``
is the desired dynamics engine.
*****
-----------------------------
Transition Interface Sampling
-----------------------------
Transition networks for TIS
===========================
As with TPS, the 2-state system in TIS is just a special case of the
multiple-state approach, so we use the same network classes to create
2-state systems as multiple-state systems.
.. _unidirectional-TIS:
Unidirectional two-state TIS
----------------------------
For unidirectional 2-state TIS (only studying the transition :math:`A\to B`,
not :math:`B\to A`), we use the :class:`.MISTISNetwork` with only one
transition listed:
.. code-block:: python
network = paths.MISTISNetwork([(A, interfacesAB, B)])
This will sample the transition from ``A`` to ``B`` using the
:class:`.InterfaceSet` ``interfaces``.
.. _bidirectional-TIS:
Bidirectional two-state TIS
---------------------------
For bidirectional 2-state TIS (simultaneously studying both the :math:`A\to
B` transition and the :math:`B\to A` transition), you could use a
:class:`.MISTISNetwork` as in the unidirectional case, but giving both
transitions instead. However, using the :class:`.MSTISNetwork` is a little
simpler, and gives completely equivalent results:
.. code-block:: python
network = paths.MSTISNetwork([(A, interfacesA),
(B, interfacesB)])
Multiple-state TIS
------------------
The network for the standard multiple state TIS, where there is one set of
interfaces for each state, is given by straightforward extension of the
bidirectional 2-state case to more states. Illustrations of this are in the
toy model MSTIS example, and in the alanine dipeptide MSTIS example.
If you wish to only focus on certain final states from a particular initial
states, or if you want to use more than one interface set per initial state,
then you need to use the multiple interface set variant of multiple state
TIS. This is given by straightforward extension of the unidirectional case
to more transitions. An illustration of this is in the toy model MISTIS
example.
More details on the distinctions between the MSTIS network and the MISTIS
networks are in the :ref:`"Which network should I use" `
section.
Move schemes for TIS
====================
Here we'll discuss some standard and simple move schemes for TIS, which tend
to be significantly more complicated than for TPS. If you want a much more
complicated move scheme, it is usually good to start with one of these basic
move schemes, and then to use the :class:`.MoveStrategy` objects to modify
the scheme.
Standard TIS scheme
-------------------
The default TIS scheme includes one-way shooting (uniform shooting point
selection) for each TIS and multiple state ensemble, path reversal movers on
those same ensembles, a minus mover for each state, and nearest-neighbor
replica exchange. The probabilities of choosing each move type are designed
such that, for each ensemble, path reversal and replica exchange are tried
half as frequently as shooting. The minus move is tried 1/5 as frequently as
shooting.
This move scheme is generated with
.. code-block:: python
scheme = paths.DefaultScheme(network, engine)
.. TODO: SRTIS