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.

With kick-from = "initial", kick-parallel = true makes the kick of each ensemble a job of its own, and up to [runner] workers of them run at the same time (one at a time with the default single worker). It is tested with TurtleMD and with the internal integrators Langevin and VelocityVerlet. OpenMM and the internal integrators kick each ensemble from the starting configuration in memory and store the initial paths as the sequential kick does (see kick-parallel). The kick of each ensemble draws from random streams of its own, spawned from [simulation] seed, with kick-parallel = true or without: both kicks store the same initial paths where they run the same engine section (the sequential kick runs [engine], the parallel kick the section of each ensemble’s ensemble_engines; an explore run excepted), and another [simulation] seed kicks other ones. With ASE the kick stops before a path is made, with kick-parallel or without.

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: it accepts every path it generates, also one that does not cross the middle interface of its ensemble. Its output (the visited order-parameter range and the trajectories) helps you place interfaces sensibly before committing to a TIS/RETIS run. The paths it keeps, in NNN/accepted/<n>/, can seed that run through method = "load" with load_and_kick = true, which kicks an ensemble whose path does not cross its middle interface from the frame nearest to that interface. Place the files of each path in the folder of its ensemble as for the paths of an earlier run (with an internal integrator, the frame files *.xyz only). An explore run keeps no [0^-] path: for a RETIS run, put the files of its [0^+] path into 000 as well.

[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, checks and, where needed, cleans each path with the order parameter values of its order.txt, or with values it computes from the frames when there is none, and recomputes the order parameter of every loaded path from its frames before the first cycle. After you change the order parameter, remove the order.txt files from the load folder: the trajectories need no change.

[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 builds each path from a small set of stored frames, with PyRETIS computing 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 traj.txt in each ensemble folder, 000/ to 003/, with the few frames (positions and velocities) of its path.
load-frames — single-frame .xyz files placed directly in the load folder, which PyRETIS distributes over the ensembles.

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 continues a simulation from the output.toml the run keeps in its run directory, 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 (raise [simulation] steps to the new total), or to recover one that was interrupted:

[initial-path]
method = "restart"

A restart refuses a change of the settings that fix what the run samples. To continue with changed settings, set [simulation] allow_setting_change = true; to move, add or remove interfaces, or to change the number of ensembles, start a new simulation from the saved paths with method = "load" (see starting from the paths of an earlier run). 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. A restart runs in the directory of the run it continues (elsewhere it stops, as it finds no output.toml), so for one uniform width give the collective variable from the first run on.

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. In our validation runs the moves, acceptances and paths were identical; in principle a borderline acceptance could flip, since the full-precision value may differ from the stored one exactly at an interface. 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, so it must stay the one the paths were sampled with; continuing would mix two reaction coordinates in a single data set. A restart compares the [orderparameter] section with the one of the run it continues and refuses a change with a ValueError that names the setting, such as [orderparameter]: class 'pyretis_position' -> 'pyretis_velocity'. [simulation] allow_setting_change = true lifts that check; the restart then stops on a changed order parameter only when it also adds or removes a collective variable (see the error description). To sample another reaction coordinate, start a new simulation.