.. _examples-from-tests:

#################################
Using heavy checks as tutorials
#################################

The directories under :file:`examples/tests/` are consistency checks,
but they are also useful minimal setups. This page translates them
into user-facing recipes. The difference is intent:

* In :file:`examples/tests/`, the goal is to **reproduce** reference
  output.
* In :file:`examples/tutorials/`, the goal is to **understand** the
  input files well enough to adapt them to a new simulation.

The same recipes are shipped next to the code in
:file:`examples/tutorials/from_tests/README.rst` so they stay in sync
with the heavy-test folder layout.

Internal engine
===============

Start from :file:`examples/tests/test-internal/` when you want a small,
dependency-free template.

.. list-table::
   :header-rows: 1
   :widths: 24 36 40

   * - Test fixture
     - What it is useful for
     - How to turn it into a tutorial setup
   * - ``retis``
     - Minimal RETIS with the internal Langevin engine.
     - Copy ``retis.rst`` and ``initial.xyz``; then change
       interfaces, ``steps``, and potential parameters.
   * - ``tis-multiple``
     - Splitting a multi-ensemble TIS setup into per-ensemble input
       files.
     - Start from ``tis-multiple.rst`` and inspect the generated
       ``tis-001.rst``-style files.
   * - ``md-restart``
     - Restarting MD with Langevin or Velocity Verlet.
     - Use it to learn which restart files are created and which
       settings can be overridden.
   * - ``mdflux-restart``
     - Initial flux and flux restarts.
     - Use it before designing a TIS/RETIS workflow that needs a
       flux estimate.
   * - ``retis-load-sparse``
     - Loading paths from sparse trajectory data.
     - Use it when your starting trajectories come from another
       tool.
   * - ``retis-ss-wt-wf``
     - Stone skipping, web throwing, and wire fencing.
     - Use it after the 1D RETIS tutorial to understand sub-move
       choices.
   * - ``retis-zero-left``
     - Zero-left bounded reactant basin.
     - Pair it with :ref:`examples-retis-triple-well` to see the
       ``zero_left`` shortcut.
   * - ``compare-internal-with-lammps``
     - Internal Lennard-Jones MD agreement with LAMMPS reference
       output.
     - Use it as a unit-conversion sanity check before swapping
       engines.
   * - ``explorer``
     - Loading frames for free-energy landscape exploration.
     - Use it after the 2D-hysteresis tutorial.
   * - ``partial-path``
     - REPPTIS-style partial paths.
     - Use it once you have a working REPPTIS input.

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

External-engine checks are best used as dependency-specific
templates. First verify that the external program works in your
environment, then copy the input folder and adapt one setting at a
time.

.. list-table::
   :header-rows: 1
   :widths: 22 38 40

   * - Suite
     - Use it for
     - First adaptation
   * - ``test-gromacs``
     - GROMACS command execution, file staging, sparse loading,
       restart, RETIS, and REPPTIS.
     - Replace the GROMACS coordinate/topology files, then update
       the order parameter.
   * - ``test-lammps``
     - LAMMPS propagation, velocity modification, phase-point
       dumping, and RETIS.
     - Replace ``system.data`` and ``lammps.in`` while keeping
       ``order.in`` simple until propagation works.
   * - ``test-cp2k``
     - CP2K execution, integration, and loading RETIS results.
     - Start with the hydrogen input and change only the CP2K
       input file once the runner is configured.
   * - ``test-openmm``
     - OpenMM RETIS through the Python engine.
     - Confirm that ``openmm`` imports, then adapt the two-particle
       setup to your force field.
   * - ``test-pyvisa``
     - PyVisA post-processing for the GROMACS sparse-load output.
     - Use after a path-sampling run has produced order, energy,
       and path ensemble files.

Running a fixture briefly
=========================

For exploration, run a fixture in a temporary copy and stop early
once the setup has passed initialization and produced a few cycles.
For example:

.. code-block:: bash

   cd examples/tests/test-internal/retis
   timeout 30s pyretisrun -i retis.rst -p

For a real tutorial run, remove the timeout and increase the number
of cycles only after you have checked the first log and the
``out.rst`` file.