Getting the initial path¶

Before a TIS, RETIS or REPPTIS simulation can start, every path ensemble needs one valid initial path — a trajectory that already satisfies the ensemble’s interface conditions. Generating these starting paths is a step in its own right, and PyRETIS offers four routes, summarised here and configured through the initial-path section.

Which route to use:

No trajectory yet, simple system → kick.
No trajectory yet, hard-to-reach barrier → explore first to map the order parameter, then kick or load.
You already have a trajectory (MD or a previous run) → load (and its sparse variants).
Continuing an interrupted run → restart (see the reference).

Kick: MC + MD generation from a single configuration¶

The kick method builds initial paths from scratch, needing only a single starting configuration. For each ensemble it randomises the velocities (a Monte-Carlo kick), integrates the dynamics (MD) one step, and accepts the move when it gets closer to the ensemble’s middle interface — repeating until a crossing is found, then shooting forward and backward to complete the path.

[initial-path]
method = "kick"
kick-from = "previous"

The kick-from option controls how multi-ensemble runs are seeded:

kick-from = "initial" (default) — every ensemble is kicked from the same user configuration. Simple, but ensembles whose interface lies far from the start may need many iterations.
kick-from = "previous" (recommended for RETIS) — only the first ensemble starts from the user configuration; each later ensemble is kicked from the frame of the previously generated path closest to (and left of) the next interface, propagating the seed through interface space.

Every engine can kick-initiate a path, including ones with no usable single MD step (CP2K, LAMMPS streaming, ASE, TurtleMD): they search for the crossing by advancing propagate() one step at a time instead. With kick-from = "initial", setting kick-parallel = true kicks every ensemble in parallel (one job per worker) instead of sequentially in one process — validated for TurtleMD so far; internal engines should keep kick-parallel = false for now.

The full keyword list is in the kick reference. Every standard 1D tutorial uses kick, e.g. TIS in a 1D potential and RETIS in a 1D potential.

Explore: mapping the order parameter first¶

When a good order parameter or a sensible interface placement is not yet known, the explore task runs an exploratory simulation that wanders the order-parameter space without enforcing interface conditions. Its output (the visited order-parameter range and the trajectories) helps you place interfaces sensibly before committing to a TIS/RETIS run, and the generated trajectories can themselves be loaded as initial paths.

[simulation]
task = "explore"

[initial-path]
method = "kick"

See the explore tutorial for a runnable 1D double-well example.

Load: reusing an existing trajectory¶

The load method initialises the ensembles from trajectory data you already have — a molecular-dynamics run or a previous (P)RETIS simulation — instead of generating paths from scratch. PyRETIS distributes the frames across the ensemble subfolders, recomputes the order parameter from the atomic positions (so you can change the order parameter definition without regenerating trajectories), and validates / cleans each path.

[initial-path]
method = "load"
load_folder = "load"

Two folder layouts are supported — a single shared trajectory placed directly in load_folder, or per-ensemble 000/, 001/, … subfolders. With load_and_kick = True the loaded frames become a seed pool: if they cannot form a valid path, PyRETIS falls back to a kick from the nearest frame. The layouts and all keywords are documented in the load reference.

Load (sparse): loading only the frames you kept¶

You do not need the full, densely sampled trajectory on disk. A sparse load reconstructs each path from a small set of stored frames plus a traj.txt index, with PyRETIS recomputing the order parameter and filling in the path bookkeeping. This is the common case when reusing trajectories where only selected frames were saved. Two runnable references with the internal engine ship under the test suite:

load-traj — a shared trajectory referenced from traj.txt.
load-frames — individual per-ensemble frame files.

Both run with pyretis run -i retis.toml -p exactly like the load method above; they differ only in how the kept frames are laid out.

Restart: continue an interrupted run¶

restart does not construct new paths at all — it resumes a simulation from the pyretis.restart state file a previous run wrote, picking the sampling up exactly where it stopped (the same active paths, random-number state and cycle counter). Use it to extend a finished run to more cycles, or to recover one that was interrupted:

[initial-path]
method = "restart"

flexible_restart = True relaxes the consistency checks when the restart settings have changed (for example a different cycle target). The full keyword list is in the restart reference.

Adding collective variables when you restart¶

A simulation often runs for a while before you realise there is another quantity you would like recorded. You do not have to start over: add a collective-variable section to the input (its keywords are the same as an orderparameter section) and restart as usual.

[orderparameter]
class = "pyretis_position"      # unchanged -- see the warning below
dim = "x"
index = 0

[[collective-variable]]         # new
class = "pyretis_distance"
index = [0, 1]

[initial-path]
method = "restart"

The paths being resumed were sampled without the new column, so on startup PyRETIS re-reads their frames and computes the added collective variable for each one. The trajectories are still on disk and a collective variable is a deterministic function of a frame, so the values are recovered exactly rather than guessed, and from the first new cycle every ensemble writes one consistent set of columns. You will see a warning naming the old and new column counts.

Two things are worth knowing.

The history keeps its old width. order.txt is appended to, so the blocks written before the restart still have the old number of columns. Only frames sampled from the restart onwards carry the new collective variable. If you want a file with one uniform width, restart into a fresh directory.

The sampling is unaffected. Adding a collective variable is an observation, not a change to the simulation: the progress coordinate that the interfaces are defined on is kept exactly as it was sampled, so the continuation follows the very same trajectory it would have without the new column. (The one exception is a velocity-dependent collective variable, such as pyretis_velocity. It forces the order parameter to be re-evaluated whenever a path is time-reversed, which re-derives the values at full precision instead of the six decimals order.txt stores. The moves, acceptances and paths are identical; reported order values can differ in the ninth significant digit.)

Collective variables can be removed on a restart in the same way; the dropped columns simply stop being written.

Warning

The first order parameter is the progress coordinate: it defines the interfaces and drives the sampling. It must stay the one the loaded paths were sampled with. PyRETIS verifies this by recomputing it from the frames, and refuses to start if it has moved — continuing would mix two different reaction coordinates in a single data set. See the error description.