.. _examples-repptis: Partial path TIS (REPPTIS) in a 1D potential ============================================ This example shows how to run **REPPTIS** -- Replica Exchange Partial Path Transition Interface Sampling -- on the 1D double-well benchmark. REPPTIS cuts the sampled trajectories short: instead of requiring a path to connect the two stable states, each path only has to cross from one interface neighbourhood to the next. The short partial paths are then combined with replica exchange between the partial-path ensembles, which makes it possible to reach permeation timescales that ordinary RETIS cannot. The method and its memory-reduction / replica-exchange scheme are described by Vervust, Zhang, van Erp and Ghysels [1]_. The closed-form kinetics (mean first passage time, flux and rate) that can be recovered from the short partial paths via a Markov-state-model analysis are derived by Vervust, Wils, Safaei, Zhang and Ghysels [2]_; REPPTIS for permeation builds on the permeability-from-(RE)TIS formalism of Ghysels, Roet, Davoudi and van Erp [3]_. **Verification status:** smoke -- see :ref:`example-test-status`. Tutorial quick start -------------------- * **Best starting point:** :file:`examples/tutorials/path_sampling/1D-double-well/repptis/`. * **Edit first:** ``task = "repptis"`` and the ``interfaces`` list in the ``[simulation]`` section; the ``[retis]`` ``swapfreq`` / ``swapsimul`` options control the partial-path replica exchange. * **Run:** ``pyretisrun -i repptis.toml -p`` from the tutorial folder. * **Analyse:** ``pyretisanalyse -i repptis.toml`` after the run has created its output. * **Expected output:** the standard per-ensemble folders (``000`` ... ``00N``) with ``pathensemble.txt`` / ``order.txt``, where the partial paths are shorter than the full RETIS paths. * **Related checks:** :file:`examples/tests/test-internal/partial-path/` (internal Langevin engine) and :file:`examples/tests/test-gromacs/test-repptis/` (real GROMACS); see :ref:`example-test-status`. Selecting the partial-path task ------------------------------- REPPTIS is requested by setting ``task = "repptis"`` in the :ref:`simulation section `. Apart from the task name, the input file is structured exactly like a RETIS input -- the same ``interfaces``, ``[engine]``, ``[orderparameter]`` and ``[retis]`` sections apply: .. literalinclude:: /_static/examples/repptis1d/repptis.toml :language: toml :start-at: [simulation] :end-before: [system] The ``interfaces`` list defines the partial-path ensembles in the same way as for RETIS: one :math:`[0^{-}]` ensemble and one :math:`[i^{+}]` ensemble per intermediate interface. The difference is in how far each trajectory is propagated -- a REPPTIS path is terminated as soon as it reaches a neighbouring interface, rather than being extended all the way to a stable state. For a permeation setup, combine ``task = "repptis"`` with ``permeability = True`` and ``zero_left`` as shown in the :ref:`permeability example `; the :file:`examples/tests/test-internal/partial-path/` fixture runs exactly this combination on a flat 1D potential. Running the simulation ---------------------- Running REPPTIS works the same way as RETIS. Below is the complete input file for the 1D double-well: .. pyretis-collapse-block:: :heading: Show/hide the full input file .. literalinclude:: /_static/examples/repptis1d/repptis.toml :language: toml The initial configuration :download:`initial.xyz ` is included in the tutorial folder. The simulation is executed with: .. code-block:: pyretis pyretisrun -i repptis.toml -p The ``-p`` option displays a progress bar. Recovering kinetics from partial paths -------------------------------------- Because REPPTIS paths are cut short, the crossing probability, mean first passage time, flux and rate cannot be read off directly the way they are for full RETIS paths. They are instead reconstructed with a Markov-state-model (MSM) analysis of the partial-path ensembles, using the closed formulas of Vervust, Wils, Safaei, Zhang and Ghysels [2]_. PyRETIS provides that analysis in :py:mod:`pyretis.analysis.repptis_msm`: the per-ensemble *local* crossing probabilities (the LML / LMR / RML / RMR path-type fractions) are assembled into a transition matrix with :py:func:`~pyretis.analysis.repptis_msm.construct_M`, the overall crossing probability follows from :py:func:`~pyretis.analysis.repptis_msm.global_pcross_msm`, and the mean first passage time -- hence the flux and rate -- from :py:func:`~pyretis.analysis.repptis_msm.mfpt_to_first_last_state`. The runnable tutorial :file:`msm_kinetics.py` in this folder walks through the whole reconstruction. It verifies the exact symmetric limit ``pcross = 1 / (2 * (N - 1))`` and then computes the crossing probability, MFPT and rate for a representative asymmetric model: .. code-block:: pyretis python msm_kinetics.py .. pyretis-collapse-block:: :heading: Show/hide the MSM tutorial script .. literalinclude:: /_static/examples/repptis1d/msm_kinetics.py :language: python From a run to the rate (end to end) ----------------------------------- :file:`repptis_to_kinetics.py` closes the loop from *sampling* to *theory*: it analyses an actual REPPTIS run for the per-ensemble local crossing probabilities (``LML`` / ``LMR`` / ``RML`` / ``RMR``, via :py:func:`~pyretis.analysis.path_analysis.analyse_repptis_ensemble` and :py:func:`~pyretis.analysis.repptis_analysis.local_crossing_probabilities`) and combines them into the overall crossing probability **two independent ways** -- the closed-form REPPTIS recursion (:py:func:`~pyretis.analysis.repptis_analysis.global_crossing_probabilities_from_local`) and the Markov state model (:py:func:`~pyretis.analysis.repptis_msm.construct_M` + :py:func:`~pyretis.analysis.repptis_msm.global_pcross_msm`) -- which agree. The full workflow is: .. code-block:: pyretis pyretisrun -i repptis.toml -p # sample the partial paths python repptis_to_kinetics.py # reconstruct the kinetics If run without simulation output present, the script falls back to a small set of illustrative local probabilities so it still demonstrates the analysis. .. pyretis-collapse-block:: :heading: Show/hide the end-to-end script .. literalinclude:: /_static/examples/repptis1d/repptis_to_kinetics.py :language: python Tested by --------- The REPPTIS task is represented by :file:`examples/tutorials/path_sampling/1D-double-well/repptis/` and checked by :file:`examples/tests/test-internal/partial-path/` (internal engine) and :file:`examples/tests/test-gromacs/test-repptis/` (GROMACS). The MSM kinetics tutorial :file:`msm_kinetics.py` runs in the tutorial smoke suite (``examples/run-tutorials.sh``, exercised by ``test-heavy``) and the underlying analysis is unit-tested in :file:`test/analysis/test_repptis_msm.py`. Use the fixtures as the short regression checks and this page as the user-facing guide. References ---------- .. [1] W. Vervust, D. T. Zhang, T. S. van Erp and A. Ghysels, *Path sampling with memory reduction and replica exchange to reach long permeation timescales*, Biophys. J. **122**, 2960-2972 (2023), https://doi.org/10.1016/j.bpj.2023.02.021 .. [2] W. Vervust, E. Wils, S. Safaei, D. T. Zhang and A. Ghysels, *Estimating full path lengths and kinetics from partial path transition interface sampling simulations*, J. Chem. Theory Comput. (2026), https://doi.org/10.1021/acs.jctc.5c01498 (arXiv:2602.12835). .. [3] A. Ghysels, S. Roet, S. Davoudi and T. S. van Erp, *Exact non-Markovian permeability from rare event simulations*, Phys. Rev. Research **3**, 033068 (2021), https://doi.org/10.1103/PhysRevResearch.3.033068