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.

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:

State the purpose of the simulation and the method/engine used.
Identify the files the user is expected to edit first.
Give the start command and the main files/directories created.
Explain what a short startup run should look like.
Add a small Tested by section to each example page. Link to the relevant heavy-test directory or explain the optional dependency.
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.
Link unusual input keywords to the relevant user-guide section, and link the page to PyRETIS quick guide for users and LLMs when adding new setup patterns.
Move tutorials out of tutorials/other/ once they have a stable docs page.
Keep generated outputs out of tutorial directories unless they are intentionally used as reference material.
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 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.