.. _user-guide-tutorials:

.. role:: header
   :class: h4

Tutorials
=========

In addition to reading the documentation, we have prepared
several examples to highlight the usage and capabilities of |pyretis|.
The cards below point to the user-facing tutorial folders that ship
with the source tree. Larger published-result packages that regenerate
figures from validation studies are collected on the
:ref:`results page <our-results>`. The complete tutorial list is in the
:ref:`example section <examples-index>`.

The examples below are grouped by what you are most likely to change:
the potential, the sampling method, the external dynamics engine, or the
molecular dynamics workflow. Each card links to the rendered
documentation and to the matching source folder under
:file:`examples/tutorials/`.

Potentials
----------

.. container:: row

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/tis-1d-pot.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-tis-1d.html

      .. container:: caption

         :header:`1D double well`

         The smallest TIS/RETIS model: one particle in the van Erp
         double-well benchmark.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/retis-1d-pot.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-retis-triple-well.html

      .. container:: caption

         :header:`1D triple well`

         RETIS on a three-state landscape, including the ``zero_left``
         shortcut for the [0-] ensemble.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-triple-well>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/2dpot.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-2d-hysteresis.html

      .. container:: caption

         :header:`2D hysteresis`

         A two-dimensional internal potential where the best order
         parameter is deliberately less obvious.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/2D-hysteresis>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/retis-2d-wca.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-retis-wca.html

      .. container:: caption

         :header:`2D WCA bond`

         Bond breaking in the WCA model from van Erp, Moroni and
         Bolhuis (2003), with low- and high-barrier variants.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/2D-wca>`__

Sampling methods
----------------

.. container:: row

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/tis-1d-pot.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-tis-1d.html

      .. container:: caption

         :header:`TIS and flux`

         Initial flux plus TIS crossing probabilities for the 1D
         double-well system.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/tis>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/retis-1d-pot.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-retis-1d.html

      .. container:: caption

         :header:`RETIS`

         Replica exchange between path ensembles for the same
         double-well benchmark.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/retis>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/sub_wf.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-submoves-1d.html

      .. container:: caption

         :header:`Subtrajectory moves`

         Stone skipping, web throwing and wire fencing from Riccardi
         et al. (2017) and Zhang et al. (2023).

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/submoves>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/umbrella-sampling-thumb.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-umbrella.html

      .. container:: caption

         :header:`Umbrella sampling`

         Monte Carlo umbrella sampling for free-energy estimation
         alongside the rate-constant tutorials.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/umbrella_sampling>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/permeability-thumb.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-permeability.html

      .. container:: caption

         :header:`Permeability`

         A path-sampling setup using ``permeability = True`` for
         membrane-style transport calculations.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/permeability>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/particle-swarm-thumb.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-pso.html

      .. container:: caption

         :header:`Particle swarm`

         Particle-swarm optimisation for finding useful initial paths
         before path sampling.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/other/particle_swarm>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/repptis-400x400.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-repptis.html

      .. container:: caption

         :header:`REPPTIS`

         Replica-exchange partial-path TIS on the 1D double well, with the
         Markov-state-model kinetics analysis.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/repptis>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/explore-landscape-thumb.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-explore.html

      .. container:: caption

         :header:`Exploring the landscape`

         Free-energy landscape exploration to generate a first valid
         initial path before path sampling.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/1D-double-well/explore>`__

External engines
----------------

.. container:: row

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/hydrate.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-gromacs-hydrate.html

      .. container:: caption

         :header:`GROMACS`

         Methane transport in an sI hydrate structure with a custom
         Python order parameter.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/gromacs-hydrate>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/2d-lammps.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-lammps-wca.html

      .. container:: caption

         :header:`LAMMPS`

         The 2D WCA bond-breaking model driven by LAMMPS instead of
         the internal engine.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/2D-wca-lammps>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/hydrogen.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-cp2k-hydrogen.html

      .. container:: caption

         :header:`CP2K`

         A small hydrogen bond-breaking example using CP2K for the
         dynamics.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/cp2k-hydrogen>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: https://openmm.org/images/logo.svg
         :width: 94%
         :class: img-responsive
         :target: ../examples/examples-openmm.html

      .. container:: caption

         :header:`OpenMM`

         RETIS for an argon model with OpenMM providing the molecular
         dynamics.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/path_sampling/openmm-argon>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/pyretisrev.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-vvexternal.html

      .. container:: caption

         :header:`Compiled extensions`

         C and FORTRAN extensions for custom integrators, potentials
         and order parameters.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/extending>`__

Molecular dynamics
------------------

.. container:: row

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/md-nve.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-md.html

      .. container:: caption

         :header:`pyretisrun MD`

         Plain molecular dynamics from an input file and from the
         |pyretis| Python API.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/molecular_dynamics/md_nve>`__

   .. container:: col-lg-3 col-md-3 col-sm-3 col-xs-6 thumbnail thumbnail2

      .. image:: /_static/img/examples/thumbnails/pyretisrev.png
         :width: 100%
         :class: img-responsive
         :target: ../examples/examples-md-fb.html

      .. container:: caption

         :header:`Flux paths`

         Forward and backward MD utilities for generating path-sampling
         starting points.

         `Tutorial source <https://gitlab.com/pyretis/pyretis/-/tree/develop/examples/tutorials/molecular_dynamics/md_nve/forward_backward>`__