.. _example-organization:

####################
Example organization
####################

The examples tree has exactly two top-level subfolders:
``examples/tutorials`` and ``examples/tests``. Tutorials are for users
who want to learn how to set up simulations. Tests are for developers
who want to check that generated output still matches reference data.
Those goals are related, but the folder layouts inside each branch are
allowed to differ.

.. list-table::
   :header-rows: 1
   :widths: 24 34 42

   * - Area
     - Purpose
     - Rule of thumb
   * - ``tutorials/path_sampling/``
     - TIS, RETIS, REPPTIS, and engine-coupling tutorials.
     - Each directory should have a short ``README.rst``, one primary
       input file, and a matching page under ``docs/examples/``.
   * - ``tutorials/molecular_dynamics/``
     - MD and flux tutorials used to prepare path sampling.
     - Keep these small and make clear whether they are library-based
       scripts or ``pyretisrun`` input-file examples.
   * - ``tutorials/umbrella_sampling/``
     - Sampling tutorials outside the path-sampling path.
     - Keep the current topic grouping, but add a README when a folder
       contains more than one runnable script.
   * - ``tutorials/extending/``
     - Advanced tutorials for custom engines, force fields, and
       order parameters.
     - Treat these as advanced examples and link them from both the
       examples pages and the developer guide where relevant.
   * - ``tutorials/from_tests/``
     - User-facing recipes derived from ``examples/tests`` fixtures.
     - Explain how to adapt a tested setup to a new simulation, without
       requiring users to reproduce reference output.
   * - ``tutorials/other/``
     - Incubator for examples that do not yet fit a stable topic.
     - New examples should not stay here once they are documented.
   * - ``test/``
     - Heavy consistency checks driven by ``test-heavy.sh``.
     - This folder is special: optimize it for reproducible comparison
       against reference output, not for narrative readability.

How tutorials connect to tests
==============================

A tutorial does not need to duplicate the exact heavy-test directory.
Instead, each documented tutorial should have one of these links to the
heavy suite:

* **Direct check:** the documentation page points to a heavy-test case
  that runs the same input file or an intentionally shortened version.
* **Representative check:** the page points to a heavy-test case that
  exercises the same engine, method, and analysis path.
* **Manual / optional check:** the page explains which external program
  or GUI dependency is required and why the example is not part of the
  default smoke scope.

This avoids turning tutorial folders into brittle CI fixtures while
still making every tutorial accountable.

Tutorial requirements
=====================

Every tutorial should contain enough information for a user to adapt the
setup:

1. State the purpose of the simulation and the method/engine used.
2. Identify the files the user is expected to edit first.
3. Give the start command and the main files/directories created.
4. Explain what a short startup run should look like.
5. Add a small ``Tested by`` section to each example page. Link to the
   relevant heavy-test directory or explain the optional dependency.
6. Use the heading ``Tutorial quick start`` for the command-and-file
   checklist. This makes the page easy to scan for users and for LLM
   assistants using the documentation as context.
7. Link unusual input keywords to the relevant user-guide section, and
   link the page to :ref:`examples-llm-quickstart` when adding new
   setup patterns.
8. Move tutorials out of ``tutorials/other/`` once they have a stable
   docs page.
9. Keep generated outputs out of tutorial directories unless they
   are intentionally used as reference material.
10. Add new tutorials to ``test-heavy.sh`` by creating a shortened
    heavy-test fixture under ``examples/tests/``.

Adding a new example
====================

For a new user-facing tutorial, include:

* a short ``README.rst`` with the purpose, requirements, run command,
  and expected output files;
* a documentation page under ``docs/examples/`` that explains the input
  choices and links to the runnable files;
* a heavy-test fixture under ``examples/tests/`` or a note explaining why
  the example is optional/manual;
* a line in :ref:`example-test-status` so the website reports how the
  example is checked.

This gives contributors a simple contract: if an example is visible in
the website, the website also says how it is verified.