.. _examples-submoves-1d:

Subtrajectory moves in a 1D potential
=====================================

This example shows how to use the subtrajectory monte carlo moves
Stone Skipping (SS), Web Throwing (WT) [1]_ and Wire Fencing (WF) [2]_
in (Replica Exchange) Transition Interface Sampling simulations for
sampling trajectories of a particle in a 1D well. The three moves are
sketched out below:

.. _figsubtrajmoves:

.. figure:: /_static/img/examples/all3moves.png
    :alt: The three subtrajectory moves
    :width: 60%
    :align: center

    Cartoon representation of the three subtrajectory moves:
    stone skipping, web throwing and web throwing. The old 
    path is shown in blue. Four subtrajectories are shown 
    in orange. The final new path consists of the fourth 
    subtrajectory and its extensions in green.

Further details on the 1D potential, how to create the PyRETIS input
file and calculating reaction rates using TIS/RETIS are explained by
the previous 1D potential :ref:`TIS example <examples-tis-1d>` and
:ref:`RETIS example <examples-retis-1d>`.                                     

|

**Verification status:** passing -- see :ref:`example-tutorial-map`.

Tutorial quick start
--------------------

* **Best starting point:**
  :file:`examples/tutorials/path_sampling/1D-double-well/submoves/`.
* **Edit first:** the ``shooting_moves``, ``interface_sour``,
  ``interface_cap``, and ``n_jumps`` settings in the ``TIS`` section.
* **Run:** ``pyretisrun -i retis.toml -p`` from the tutorial folder,
  or ``pyretisrun -i retis.rst -p`` for the section-based input shown
  below.
* **Analyse:** ``pyretisanalyse -i out.rst`` after ``out.rst`` is
  created.
* **Expected output:** standard RETIS ensemble folders plus move labels
  for stone skipping, web throwing, and wire fencing in
  ``pathensemble.txt``.
* **Related check:** :file:`examples/tests/test-internal/retis-ss-wt-wf/`;
  see :ref:`example-test-status`.

Defining the shooting move 
--------------------------

To define the specific shooting moves performed in each of the
ensembles in i.e. a RETIS simulation, the number of ensembles
needs to be known. This information can be obtained from reading
the ``interfaces`` variable in the
:ref:`simulation section <user-section-simulation>` of the input file:

.. literalinclude:: /_static/examples/submoves1d/retis-1d.txt
   :language: rst
   :start-at: Simulation
   :end-before: System

Here we have one :math:`[0^{-}]` ensemble and seven :math:`[i^{+}]`
ensembles for a total of 8 ensembles. Then we can define the
specific shooting moves to be performed in each ensemble in the
:ref:`tis section <user-section-tis>`:

.. literalinclude:: /_static/examples/submoves1d/retis-1d.txt
   :language: rst
   :start-at: TIS settings
   :end-before: RETIS settings

The ``shooting_moves`` variable defines the list of shooting moves
to be used for all the ensembles. Here we see that :math:`[0^{-}]` and
:math:`[0^{+}]` performs the shooting move while the other
ensembles performs the SS, WT and WF moves. The ``interface_sour``
sets the SOUR interface for the WT, while
if defined, the ``interface_cap`` variable sets the upper value
limit of subtrajectories generated by the WF move. The variable
``n_jumps`` defines the number of subtrajectories to be generated
per move and the bool ``high_accept`` determines whether the
high acceptance protocol should be used or not.
See :ref:`user-guide-path-move-types` for the full list of move type
codes and :ref:`user-guide-path-status-codes` for all acceptance and
rejection status codes.

|

Running the RETIS simulation
----------------------------

Running a RETIS simulation with subtrajectory moves works the same way
as running without subtrajectory moves. Below is a complete input file 
(let's call it ``retis.rst``). 

.. pyretis-collapse-block::
   :heading: Show/hide the full input file

   .. literalinclude:: /_static/examples/submoves1d/retis-1d.txt
      :language: rst

The initial configuration
:download:`initial.xyz </_static/examples/submoves1d/initial.xyz>`
is included in the tutorial folder. The simulation can then be
executed using:

.. code-block:: pyretis

   pyretisrun -i retis.toml -p

The ``-p`` option will display a progress bar for your simulation.

|

Tested by
---------

The subtrajectory move settings are represented by
:file:`examples/tutorials/path_sampling/1D-double-well/submoves/` and
checked by :file:`examples/tests/test-internal/retis-ss-wt-wf/`. Use
the fixture as the short regression check and this page as the
user-facing guide to choosing and interpreting the move settings.

References
----------


.. [1] E. Riccardi, O. Dahlen and T. S. van Erp, *Fast decorrelating
   Monte Carlo moves for efficient path sampling*, J. Phys. Chem. Lett.
   **8**, 4456-4460 (2017), https://doi.org/10.1021/acs.jpclett.7b01617

.. [2] D. T. Zhang, E. Riccardi and T. S. van Erp, *Enhanced path
   sampling using subtrajectory Monte Carlo moves*, J. Chem. Phys.
   **158**, 024113 (2023), https://doi.org/10.1063/5.0127249