.. _examples-llm-quickstart:

#######################################
PyRETIS quick guide for users and LLMs
#######################################

This page is a compact orientation guide for anyone trying to set up a
|pyretis| simulation from the documentation. It is intentionally
procedural and repetitive so that both users and language-model
assistants can find the correct pattern quickly.

Start from the right folder
===========================

Use :file:`examples/tutorials/` when you want to learn or adapt a
simulation. Use :file:`examples/tests/` when you want a short,
validated consistency check.

The two folders have different jobs:

* :file:`examples/tutorials/` contains user-facing setups. These may be
  long and are allowed to be experience-building simulations.
* :file:`examples/tests/` contains heavy checks used by
  :file:`test-heavy.sh`. These are optimized for reproducible output
  comparisons, not for narrative readability.

Do not copy generated output folders such as ``000/``, ``001/``,
``report/``, ``traj/`` or ``energy/`` as if they were required source
files. Start from the input files, order-parameter modules, initial
configurations, and external-engine input folders listed by each
tutorial page.

Canonical command patterns
==========================

Most |pyretis| tutorials use one of these command patterns.

.. list-table::
   :header-rows: 1
   :widths: 24 38 38

   * - Task
     - Command
     - What to inspect
   * - Run one input file
     - ``pyretisrun -i input.rst -p``
     - ``pyretis.log``, ``out.rst``, ensemble folders, trajectory and
       energy files.
   * - Analyse one completed run
     - ``pyretisanalyse -i out.rst``
     - ``report/`` and the generated analysis figures/tables.
   * - Split a TIS setup into ensemble inputs
     - ``pyretisrun -i tis.rst``
     - Generated files such as ``tis-001.rst``, ``tis-002.rst``.
   * - Run one split TIS ensemble
     - ``pyretisrun -i tis-001.rst -p -f 001.log``
     - The numbered ensemble output and the renamed log file.
   * - Run all tutorial startup checks
     - ``examples/run-tutorials.sh``
     - Whether tutorial commands start without missing files, broken
       imports, PyRETIS errors, or tracebacks. Per-tutorial hard
       timeout (default ``2s`` standalone, ``2m`` when invoked via
       ``test-heavy``) is set via ``PYRETIS_TUTORIAL_TIMEOUT``. The
       ``path_sampling/1D-triple-well/retis-zero-left`` tutorial is
       the canonical default that finishes end-to-end under the 2 m
       budget (~15-20 s) and only smoke-starts under the 2 s budget.
   * - Run heavy checks
     - ``./test-heavy.sh`` (thin wrapper around
       ``examples/run-tests.sh``)
     - Whether bundled examples reproduce their reference output.
       Heavy checks finish with the tutorial smoke checks; set
       ``PYRETIS_RUN_TESTS_SKIP_TUTORIALS=1`` to skip them.

Choose the closest tutorial
===========================

The canonical mapping between tutorial folders, docs pages, and
heavy-test fixtures lives in :ref:`example-tutorial-map`. Always
read that table before recommending an example; it also carries the
verification-status column you should cite ("passing", "engine",
"smoke", "manual") rather than inventing one.

Quick pointers for the most common requests:

* First TIS simulation -- :ref:`examples-tis-1d`.
* First RETIS simulation -- :ref:`examples-retis-1d`.
* Initial flux calculation -- :ref:`examples-tis-1d-flux`.
* Sub-trajectory moves (SS / WT / WF) -- :ref:`examples-submoves-1d`.
* ``zero_left`` for a bounded reactant basin --
  :ref:`examples-retis-triple-well`.
* Plain molecular dynamics -- :ref:`examples-md`.
* External engines -- :ref:`examples-gromacs-hydrate`,
  :ref:`examples-retis-lammps`, :ref:`examples-cp2k-hydrogen`,
  :ref:`examples-openmm`.
* Custom order parameters / engines / potentials --
  :ref:`examples-vvexternal`, :ref:`examples-pso`.

Read input files by section
===========================

When adapting an example, keep the |pyretis| section structure intact.
The most common sections are:

* ``Simulation``: method, number of cycles, interfaces, and method-specific
  switches such as ``permeability`` or ``zero_left``.
* ``System`` and ``Box``: units, temperature, dimensions, and periodicity.
* ``Particles``: initial coordinates, masses, labels, and velocity setup.
* ``Engine``: internal engine or external program coupling.
* ``TIS`` and ``RETIS``: shooting, path-length limits, swap behavior, and
  move frequencies.
* ``Orderparameter``: built-in order parameters or a Python module/class.
* ``Forcefield`` and ``Potential``: potential-energy model for internal
  engines.
* ``Output`` and ``Analysis``: write frequency and post-processing options.

When an external engine is used, do not move its input files out of the
``input_path`` directory named in the ``Engine`` section. The executable
name in the input file must match the local installation, for example
``gmx``, ``lmp``, ``cp2k`` or a site-specific wrapper.

Minimal adaptation workflow
===========================

1. Pick the tutorial with the closest method and engine.
2. Copy only the listed input files and support modules to a new working
   directory.
3. Run the tutorial unchanged for a few cycles or with the smoke runner.
4. Change one category at a time: system, order parameter, engine, then
   interface positions.
5. Re-run with ``pyretisrun -i ... -p`` and inspect ``pyretis.log`` and
   ``out.rst`` before doing a long run.
6. Analyse only after a run has produced the expected output files.
7. Use :ref:`example-test-status` to find a representative check if
   the adapted setup starts failing.

Rules for LLM assistants
========================

When producing PyRETIS instructions or code:

* Prefer an existing tutorial input file over inventing a new one.
* Link to the relevant user-guide section for every non-obvious input
  section or engine setting.
* State whether a command is a short startup check or a convergence run.
* Keep external-engine examples explicit about required programs and
  file names.
* Do not claim an example is fully verified unless it is listed as
  passing in :ref:`example-test-status`.
* If a setup is based on :file:`examples/tests/`, say that it is a
  regression fixture and explain how to adapt it for a tutorial.

This guide is deliberately conservative: it should help assistants give
correct first steps before trying to optimize or automate a full
simulation campaign.