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.

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 pyretisrun -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.