Interactive examples

Interactive examples are a good fit for PyRETIS, but they should be introduced in a way that does not make the normal documentation build fragile. The easiest path is to start with the pure-Python internal examples and keep the external-engine examples as downloadable input sets.

Recommended first step

Create one notebook for each lightweight internal tutorial:

• TIS in a 1D potential.
• RETIS in a 1D potential.
• Sub-moves on a 1D potential.
• Plain MD and MD-flux setup.

Each notebook should run in a few minutes, generate one or two plots, and link back to the corresponding full documentation page. The source of truth should remain the same input files used by the examples and the regression tests, so the notebook is a guided front end rather than a separate example that can drift.

Documentation integration

There are two low-maintenance ways to publish these notebooks:

• Notebook links in the examples pages. Store notebooks under examples/notebooks/ and link to them from the relevant pages. This is the smallest change and works immediately.
• Rendered notebooks in Sphinx. Add nbsphinx or myst-nb later and render selected notebooks into the website. This gives a richer website, but the docs build must then decide whether notebooks are executed during CI or rendered from saved outputs.

For a hosted interactive session, Binder is the practical first target: it can install the Python dependencies and run the pure-Python examples without requiring users to install PyRETIS locally. JupyterLite can be considered later for tiny browser-only demos, but it is a tighter fit because PyRETIS uses scientific Python dependencies and some examples need file-system output.

Suggested implementation plan

1. Add examples/notebooks/tis-1d.ipynb and keep it under five visible cells: import, load settings, run, analyse, plot.
2. Add a small environment.yml or requirements-notebooks.txt for Binder.
3. Add a notebook smoke test that runs the notebook with jupyter nbconvert --execute or pytest --nbmake.
4. Link the notebook from TIS in a 1D potential and this page.
5. Repeat for RETIS and sub-moves once the first notebook is stable.

This keeps the interactive work incremental: the website can advertise the direction now, while the normal examples and regression checks stay fully usable without a notebook stack.