.. _examples-index:

########
Examples
########

Welcome to the |pyretis| examples library. The source distribution keeps
user-facing material under :file:`examples/tutorials/` and consistency
checks under :file:`examples/tests/`.

The pages are grouped by topic, with a short note on what each
tutorial covers so you can pick the one that matches the question you
have. If you are new to |pyretis|, we recommend the "Getting started"
tutorials first. If you are adapting the examples with help from an
LLM, start with :ref:`examples-llm-quickstart` so the assistant follows
the same folder, command, and verification conventions as the website.
The runnable checks behind these tutorials are tracked in
:ref:`example-test-status`.

Potentials
==========

These examples are a good place to start when the main question is
which model system to use. They run with the internal |pyretis| engine
unless noted otherwise, and each entry links to the matching tutorial
source folder in the repository.

.. toctree::
    :maxdepth: 1

    examples-tis-1d.rst
    examples-retis-triple-well.rst
    examples-2d-hysteresis.rst
    examples-retis-wca.rst

* :ref:`TIS in a 1D double-well potential <examples-tis-1d>` -- the
  van Erp double-well benchmark and the initial-flux workflow.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/tis>`__.
* :ref:`Triple-well RETIS with zero_left <examples-retis-triple-well>`
  -- a three-state potential showing how ``zero_left`` avoids wasted
  ``[0^-]`` trajectories.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-triple-well>`__.
* :ref:`Hysteresis on a 2D potential <examples-retis-2d>` -- a richer
  internal landscape where order-parameter choice matters.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/2D-hysteresis>`__.
* :ref:`Breaking a bond with RETIS <examples-retis-wca>` -- the WCA
  bond-breaking model from van Erp, Moroni and Bolhuis (2003).
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/2D-wca>`__.

Sampling methods
================

These examples focus on the sampling algorithm or the way initial paths
are generated.

.. toctree::
    :maxdepth: 1

    examples-retis-1d.rst
    examples-submoves-1d.rst
    examples-repptis.rst
    examples-explore.rst
    examples-umbrella.rst
    examples-permeability.rst
    examples-pso.rst

* :ref:`RETIS in a 1D potential <examples-retis-1d>` -- replica
  exchange between path ensembles for the double-well benchmark.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/retis>`__.
* :ref:`Subtrajectory moves on a 1D potential <examples-submoves-1d>`
  -- stone skipping, web throwing and wire fencing from Riccardi,
  Dahlen and van Erp (2017) and Zhang, Riccardi and van Erp (2023).
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/submoves>`__.
* :ref:`Partial path TIS (REPPTIS) <examples-repptis>` -- replica
  exchange partial path TIS for long permeation timescales, from
  Vervust, Zhang, van Erp and Ghysels (2023).
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/repptis>`__.
* :ref:`Exploring the order parameter <examples-explore>` -- the
  ``explore`` task for scouting the order-parameter space and seeding
  initial paths (see :ref:`Getting the initial path
  <user-guide-initial-paths>`).
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/explore>`__.
* :ref:`Umbrella sampling <examples-mc-umbrella-sampling>` --
  free-energy estimation alongside the rate-constant workflows.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/umbrella_sampling>`__.
* :ref:`Permeability calculation <examples-permeability>` -- using
  ``permeability = True`` instead of, or together with, TIS.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/permeability>`__.
* :ref:`PSO-based initial path optimisation <examples-pso>` --
  particle-swarm assisted initialisation.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/other/particle_swarm>`__.

External engines
================

These tutorials replace the internal Langevin engine with one of
the standard MD codes, or with compiled extension modules. They require
the corresponding engine or compiler to be installed and reachable on
your ``PATH``.

.. toctree::
    :maxdepth: 1

    examples-gromacs-hydrate.rst
    examples-cp2k-hydrogen.rst
    examples-lammps-wca.rst
    examples-openmm.rst
    examples-vvexternal.rst

* :ref:`GROMACS hydrate <examples-gromacs-hydrate>` -- methane
  transport in an sI hydrate with a custom Python order parameter.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/gromacs-hydrate>`__.
* :ref:`CP2K hydrogen <examples-cp2k-hydrogen>` -- a small
  *ab initio* hydrogen bond-breaking setup.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/cp2k-hydrogen>`__.
* :ref:`LAMMPS WCA <examples-retis-lammps>` -- the 2D WCA
  bond-breaking model driven by LAMMPS.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/2D-wca-lammps>`__.
* :ref:`OpenMM argon <examples-openmm>` -- RETIS with OpenMM handling
  the molecular dynamics.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/openmm-argon>`__.
* :ref:`Compiled external components <examples-vvexternal>` -- C and
  FORTRAN extensions for custom integrators, potentials and order
  parameters.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/extending>`__.

Analysis
========

These examples show how to start, seed, analyse and visualise runs with
``pyretisrun``, ``pyretisanalyse`` and |pyvisa|.

.. toctree::
    :maxdepth: 1

    examples-md.rst
    examples-md-fb.rst
    examples-pyvisa.rst
    examples-pyvisa-analysis.rst

* :ref:`Plain MD <examples-md>` -- input-file
  (:ref:`examples-md-nve`) and library-based
  (:ref:`examples-md-nve-lib`) ways to run a Lennard-Jones
  simulation.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/molecular_dynamics/md_nve>`__.
* :ref:`Forward/backward MD <examples-for-back-md>` and
  :ref:`initial flux <examples-tis-1d-flux>` -- handy when
  you need to seed initial paths for TIS.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/molecular_dynamics/md_nve/forward_backward>`__.
* :ref:`pyvisa GUI <examples-pyvisa>` and
  :ref:`pyvisa analysis <examples-pyvisa-analysis>` -- visualise
  and post-process your trajectories.
  `Source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/gromacs-hydrate>`__.

How the examples are organised
==============================

The pages below describe the contract between tutorial pages and
heavy checks, the rules for adding new examples, the current
verification status, and the LLM-oriented quick reference.

.. toctree::
    :maxdepth: 1

    llm-quickstart.rst
    example-organization.rst
    examples-from-tests.rst
    example-test-status.rst
    interactive-examples.rst

* :ref:`PyRETIS quick guide for users and LLMs <examples-llm-quickstart>`
  -- compact rules for choosing examples, running commands, and
  avoiding common setup mistakes.
* :ref:`Example organization <example-organization>` -- folder
  contract, tutorial authoring rules, and how tutorials link to the
  heavy suite.
* :ref:`Using heavy checks as tutorials <examples-from-tests>` --
  one-shot table of which test fixture to copy when starting a new
  setup.
* :ref:`Example test status <example-test-status>` -- the current
  verification matrix and per-suite refresh dates.
* :ref:`Interactive examples <interactive-examples>` -- planned
  notebook front ends for the lightweight tutorials.

The :file:`examples/` folder has two subfolders:

* :file:`examples/tutorials/` for user-facing setup guides;
* :file:`examples/tests/` for heavy consistency checks.

To run all heavy example checks from the repository root:

.. code-block:: bash

   ./test-heavy.sh

To run a single check, ``cd`` into its directory and execute its
``run.sh``::

   cd examples/tests/test-internal/retis
   ./run.sh

``run.sh`` cleans the directory, calls ``pyretisrun`` and
``pyretisanalyse``, then runs ``compare.py`` to validate the
output against the reference data in :file:`results/`.