Enhanced path sampling using subtrajectory Monte Carlo moves (2022)
==================================================================

Ready-to-run inputs for the study of the subtrajectory Monte Carlo
shooting moves -- Stone Skipping (SS), Web Throwing (WT) and Wire
Fencing (WF) -- for (replica-exchange) transition interface sampling.

Paper:
  D. T. Zhang, E. Riccardi and T. S. van Erp, "Enhanced path sampling
  using subtrajectory Monte Carlo moves", J. Chem. Phys. 158, 024113
  (2023).  https://doi.org/10.1063/5.0127249

Each sub-case ships, where applicable:
  retis.rst         legacy input for PyRETIS 3   (pyretisrun -i retis.rst)
  retis.toml        canonical input for PyRETIS 4 (pyretisrun -i retis.toml)
  orderparameter.py the order parameter (when not a built-in one)
  <engine>_input/   the engine-specific system files
  avatar.png        the small render used on www.pyretis.org

The retis.toml files were generated from the retis.rst with
  python -m pyretis.tools.convert_settings


The three sub-cases
-------------------

internal/   1D double-well, internal Langevin engine, Wire Fencing TIS.
            The benchmark case from the paper; the order parameter is the
            built-in Position, so no orderparameter.py is needed.
            RUNS OUT OF THE BOX on a normal machine:
                PyRETIS 3:  pyretisrun -i retis.rst
                PyRETIS 4:  pyretisrun -i retis.toml
            On www.pyretis.org this case is featured under
            "Getting started with PyRETIS" -> "Scientific results to
            reproduce".

hole/       GROMACS dodecane thin film in water; the sampled reaction is
            the rupture (hole formation) of the film. Stone Skipping /
            committor moves.
            - orderparameter.py (class H20Hole) measures the largest
              empty patch in the 2D map of the dodecane carbons. It reads
              gromacs_input/conf.gro, which the GROMACS engine regenerates
              from conf.g96 (via editconf) at run time; it is therefore
              not shipped here.
            - method = load: needs an initial-path "load/" folder of
              trajectories that is NOT part of these source files. The
              input parses and the engine sets up correctly; only the
              initial-path data is missing (or switch to method = kick).

ruru/       CP2K (ab initio) di-ruthenium aqua complex; the sampled
            reaction is a ruthenium redox / charge-transfer event.
            Committor / Stone Skipping moves.
            - orderparameter.py (class OrderX) requires the MDAnalysis
              package. It is advanced research code: it reads ./retis.rst
              for the engine settings and inspects CP2K HOMO / Wannier
              centre files to assign the excess charge, so it assumes the
              PyRETIS 3 CP2K workflow.
            - method = load: like hole/, it needs a "load/" folder that is
              NOT part of these source files.


Notes
-----
- hole/ uses the streaming "gromacs2" engine; in PyRETIS 4 that name is
  deprecated (it still runs, with a warning) -- use "gromacs" going
  forward.
- avatar.png in each sub-case (and the matching thumbnails on the
  website) are produced from the case data by make_avatars.py:
      python make_avatars.py . avatars
  (requires numpy, matplotlib and ASE.)