===========================================================================
 PyRETIS source files - reproducing the published examples
===========================================================================

This directory collects input files for several published studies that used
PyRETIS. They let you re-run (and build on) the simulations behind the papers.
The files were cleaned up and re-tested in 2026 against current PyRETIS.

NOTE ON SCOPE: some of these are production studies (large solvated systems
or ab-initio DFT) whose full convergence requires HPC resources and long
wall-clock times. The inputs here are functional and have been verified to
start and run on a normal workstation; reproducing the published statistics
(error bars included) is a separate, much larger compute effort.


TWO INPUT FORMATS (pick the one matching your PyRETIS)
-----------------------------------------------------
Each case ships the same simulation in two formats:

  * retis.rst   - PyRETIS 3 (the master release line, 3.0.x)
                    run with:  pyretisrun -i retis.rst
  * retis.toml  - PyRETIS 4 (the develop line, 4.x) - canonical TOML format
                    run with:  pyretisrun -i retis.toml

The .toml files were produced from the .rst files with
    python -m pyretis.tools.convert_settings retis.rst
In PyRETIS 4 the legacy .rst format still works but is deprecated; prefer the
.toml. In PyRETIS 3 use the .rst.

Cluster-specific launch commands (srun/mpiexec, -np ..., gmx_mpi) have been
replaced by simple single-machine commands (e.g. "cp2k = cp2k.popt",
"mdrun = gmx mdrun"). Adapt these to your own machine/queue as needed.


THE CASES
---------
  Water_trimer_2020/  1D double-well Langevin model (internal engine).
                      Runs to completion on a normal machine.
  Submoves_2022/      Sub-trajectory moves (stone-skipping / wire fencing).
                      internal/ runs out of the box; ruru/ and hole/ need
                      extra data - see that folder's README.
  Formic_acid_2020/   CP2K (BLYP DFT). Runs; a DFT step is expensive.
  H-NS_2019/          GROMACS, solvated protein-DNA. Engine verified;
                      production needs HPC. See its README.
  CyP-A_2019/         GROMACS protein. Engine verified; mdp modernised.
  Water_2019/         CP2K. Reconstructed port of a retired-TISMOL study;
                      see its README before quantitative use.


DEPENDENCIES
------------
Beyond PyRETIS and the relevant engine (GROMACS / CP2K), some custom order
parameters need extra Python packages:
  * mdtraj      - H-NS_2019, CyP-A_2019, Formic_acid_2020
  * MDAnalysis  - Submoves_2022/ruru


CITATION
--------
These files are free to download and use. If they help your research, please
cite the corresponding paper (listed in each sub-folder's README) and PyRETIS:
  A. Lervik, E. Riccardi and T. S. van Erp, J. Comput. Chem. 38, 2439 (2017).
  E. Riccardi, A. Lervik, S. Roet, O. Aaroen and T. S. van Erp,
  J. Comput. Chem. 41, 370 (2020).