The initial-path section¶

The initial-path section specifies how the initial path for a TIS/RETIS simulation should be generated.

Example initial-path section:

Initial-path settings
---------------------
method = kick
kick-from = previous

The different methods may require different keywords and this is described below for the following supported methods:

Table 31 Supported initiation methods in PyRETIS¶
Method name	Description
kick	For initiating new trajectories from given initial configuration(s).
load	For loading previously generated frames/trajectories
restart	For restarting PyRETIS simulations.

Choosing a method. Use restart whenever a pyretis.restart file is available — it is the most faithful continuation and requires no extra setup. Use load when you have a molecular dynamics trajectory or a previous run whose restart files are unavailable or whose settings need to change beyond what a restart allows; PyRETIS handles the distribution of frames across ensembles automatically. Use kick when no prior trajectory exists and paths must be generated from scratch.

The kick method¶

The kick method generates initial paths for all path ensembles from scratch, requiring only a single starting configuration from the user. It is recommended when no prior trajectory is available.

For each ensemble, the method searches for a crossing of the ensemble’s middle interface \(\lambda_i\) starting from a given phase point \(x\):

Velocities are randomised (e.g. drawn from a Maxwell–Boltzmann distribution).
The equations of motion are integrated one step forward. This gives a new phase point \(y\).
If \(y\) is closer to \(\lambda_i\) than \(x\), the update \(x \leftarrow y\) is accepted and the steps are repeated. Otherwise, the steps are repeated from \(x\) unchanged.

When a crossing is found, two phase points are available: one immediately before the interface and one immediately after. A full path is then generated by integrating forward from the point after the interface and backward from the point before it.

Efficient ensemble population with kick-from = previous. With kick-from = initial every ensemble is kicked from the same user-provided configuration, which may require many iterations for ensembles whose interface lies far from the starting point. With kick-from = previous (recommended for RETIS) only the first ensemble is kicked from the provided configuration. For each subsequent ensemble PyRETIS automatically selects the frame from the just-generated path that lies closest to the next interface and is still to the left of it, then kicks from that frame. This propagates the starting point progressively through interface space so that the kicking algorithm is always seeded close to the target interface, greatly reducing the number of iterations needed per ensemble and requiring no additional input from the user.

Keywords for the kick method¶

For the kick method, the following keywords can be set:

Table 32 Keywords for the kick method.¶
Keyword	Description
method	Selects the kick method.
kick-from	Modify how the initial point for the kick method is picked.

Keyword method¶

method = kick

The method keyword selects the kick initialization.

Keyword kick-from¶

kick-from = string

The kick-from keyword specifies what initial point we use for the kick method. This setting is used when several path ensembles are initiated at the same time. It can be set to:

kick-from = initial: In which we will kick from the initial configuration provided. That is, all path ensembles are initiated from the same starting point.
kick-from = previous: In which we kick from the point on the previous path which is closest to the next interface and still left of this interface. The first path ensemble will be initiated using the provided initial configuration for the particles.

Default:: The default value is kick-from = initial.

The load method¶

The load method initialises path ensembles from existing trajectory data, avoiding the need to generate paths from scratch via kicking. It is the recommended starting point whenever a prior molecular dynamics trajectory or a previous (P)RETIS run is available.

How ensembles are populated¶

PyRETIS maps each path ensemble to a numbered subfolder inside load_folder (000, 001, 002, …, matching the ensemble numbering used during the simulation). For each ensemble in turn the following steps are applied:

Collect frames. Trajectory or configuration files are read from the load folder (see Load folder layouts below for the two supported layouts).
Recompute the order parameter. The order parameter is always recomputed from atomic positions using the order parameter function defined in the simulation input. If an order.txt file is present it is used as-is; if it is absent it is generated and written to disk. This design means users can change the order parameter definition without regenerating their trajectory files.
Validate and clean the path. Only frames relevant to the ensemble are kept; the rest are discarded (see Path validation and cleaning below).
Fall back to kick if needed. If no valid path can be assembled from the loaded data and load_and_kick = True, PyRETIS automatically kicks from the frame nearest to the ensemble’s middle interface.

Path validation and cleaning¶

After collecting frames PyRETIS checks whether the assembled sequence constitutes a formally valid path for the target ensemble. If it does not, the following recovery steps are attempted in order:

Frames are sorted by order parameter and the validation is repeated.
If sorting alone is insufficient, the sequence is mirrored to produce an L-to-L or R-to-R path — a valid bookkeeping form that satisfies the ensemble definition.
Frames outside the ensemble’s relevant region are discarded, keeping:
- the two frames immediately before and after the first interface, and
- all frames between the interface defining the ensemble and the last interface.
If this second group is empty, the frame with the highest order parameter is retained so that the load_and_kick fallback has a useful seed.

If all three steps fail and load_and_kick = False, PyRETIS raises an error.

Load folder layouts¶

Two layouts are supported.

Layout 1 — unformatted (single shared trajectory). Place one or more trajectory or configuration files directly in load_folder (accepted formats: .xyz, .gro, .trr, .g96, plain-text .txt). PyRETIS will:

distribute the files to each ensemble subfolder,
generate traj.txt (frame index list) automatically,
recompute and write order.txt using the order parameter function.

Only the frames relevant to each ensemble survive path cleaning. Use this layout when you have a single long trajectory and want PyRETIS to handle the per-ensemble distribution automatically with minimal user effort.

Layout 2 — formatted (per-ensemble subfolders). Create subfolders 000, 001, 002, … inside load_folder and place the relevant files for each ensemble there. If traj.txt or order.txt are absent they are regenerated automatically.

For internal engines (positions and velocities stored in PyRETIS format):

File	Notes
`traj.txt`	Required. Full path (positions and velocities).
`order.txt`	Optional. Recomputed from atomic positions if absent.
`energy.txt`	Optional. Energies are silently ignored if absent.

For external engines (GROMACS, CP2K, …):

File / folder	Notes
`traj.txt`	Required. Frame index file referencing MD files.
`accepted/`	Required. Actual MD trajectory files (`.trr`, `.gro`, `.xtc`, `.g96`, `.xyz`, …) referenced in `traj.txt`.
`order.txt`	Optional. Recomputed from atomic positions if absent.
`energy.txt`	Optional. Energies are silently ignored if absent.

Use Layout 2 when different ensembles should start from different trajectories, or when you want to resume from formatted output of a previous (P)RETIS run with changed settings (and no restart file is available).

Note

Order parameters are always recomputed from atomic positions using the order parameter function defined in the simulation input. Placing an order.txt file in the load folder is a performance shortcut, not a requirement. If it is absent or outdated, PyRETIS regenerates it automatically. This allows users to change the order parameter definition without regenerating trajectory files.

Keywords for the load method¶

For the load method, the following keywords can be set:

Table 33 Keywords for the load method.¶
Keyword	Description
method	Selects the load method.
load_and_kick	Fall back to kick initialisation when loaded data cannot form a valid path.
load_folder	Directory containing the trajectory data to load.

Keyword method¶

method = load

The method keyword selects the load initialization.

Keyword load_and_kick¶

load_and_kick = boolean

When load_and_kick = True, the loaded trajectory data is used as a pool of candidate frames rather than as a ready-made path. If the loaded frames cannot be assembled into a valid path for the target ensemble — even after sorting and mirroring — PyRETIS:

Selects the frame from the loaded data that is closest to the ensemble’s middle interface.
Uses this frame as the starting configuration for a standard kick initialisation (two-way shooting).
The resulting kicked path fully replaces the loaded frames; no loaded frames are retained in the final path.

This option is particularly useful when the available trajectory does not cross the relevant interface, or when you want a freshly generated, unbiased initial path seeded from a physically relevant region of phase space.

If load_and_kick = False (the default) and no valid path can be assembled from the loaded data, PyRETIS raises an error.

Default:: The default value is load_and_kick = False.

Keyword load_folder¶

load_folder = string

The load_folder keyword specifies the directory containing trajectory data for load initialisation. See Load folder layouts for the two supported layouts (unformatted single trajectory or formatted per-ensemble subfolders).

Default:: The default value is load_folder = load.

The restart method¶

The restart method is used to continue simulations.

By default, a restart is a strict continuation: all settings are taken from the restart file, so the simulation proceeds exactly as if it had never been interrupted. Two mechanisms allow controlled deviations from this behaviour:

Implicit overrides — a fixed set of parameters (step count, random seed, output settings, move frequencies, etc.) can always be changed in the new input file without any extra flag. PyRETIS detects the change, emits a WARNING for each modified value, and applies it. Everything else in the new input is silently ignored. See Implicit parameter overrides for the full list.
Flexible restart — set flexible_restart = True to take the entire new input file as the settings. This is needed for structural changes such as adding or removing interfaces or ensembles. The user is then responsible for ensuring that the modified setup remains consistent with detailed balance. See Keyword flexible_restart.

Keywords for the restart method¶

For the restart method, the following keywords can be set:

Table 34 Keywords for the restart method.¶
Keyword	Description
method	Selects the restart method.
flexible-restart	Use the new input file for structural changes on restart.

Keyword method¶

method = restart

The method keyword selects the restart initialization. The general simulation information is stored in the file pyretis.restart. The restart file can be specified in the simulation section with the keyword restart in the simulation input file. Thereafter, path and ensemble data from restart files for each ensemble are loaded. These restart files are named ensemble.restart and there is one of such file for each path ensemble, e.g. 001/ensemble.restart. Note that when doing a restart, the ensemble.restart files will be overwritten with new data from the continued simulation. Note: if an ensemble has a lower number of cycles, it is possible to temporaneously prioritize it until it gets the same number of cycles by adding the keyword priority_shooting = True in the retis section.

Implicit parameter overrides¶

Even without flexible_restart, a curated set of parameters can be changed in the new input file. Whenever a value differs from the one stored in the restart file, PyRETIS logs a WARNING and applies the new value; all other settings from the restart file are preserved unchanged.

The parameters that can be overridden in this way are:

simulation: steps, interfaces, seed, priority_shooting
output: screen, backup, trajectory-file, energy-file, order-file, cross-file, restart-file, pathensemble-file
tis: freq, sigma_v, aimless, allowmaxlength, maxlength, shooting_move, shooting_moves, high_accept, n_jumps, mirror_freq, target_freq, target_indices, nullmoves
retis: swapfreq, swapsimul, nullmoves

These cover parameter tuning (step count, random seed, move frequencies, output paths) that does not alter the statistical validity of the accumulated data. For anything beyond this list — in particular adding or removing ensembles or changing the number of interfaces — use flexible_restart = True.

Note

Changing interfaces via an implicit override adjusts interface positions for the existing set of ensembles. To change the number of interfaces (and therefore the number of ensembles) you must use flexible_restart = True.

Keyword flexible_restart¶

flexible_restart = boolean

If True, all settings are taken from the new input file instead of from the restart file. Use this when structural changes to the simulation are needed, for example:

changing interface positions or their number,
adding or removing path ensembles.

In this mode no WARNING is emitted for changed values, and no whitelist is enforced — the new input is used as-is.

Warning

When settings are changed under flexible_restart, the user is responsible for ensuring that the new setup is consistent with detailed balance. If it is not, the pathensemble.txt files should be discarded before continuing.

If some interfaces are removed, the ensemble folders must be relabeled manually. PyRETIS expects a continuous numbering scheme, e.g. 000/, 001/, 002/, …

If new ensembles are added, consider setting priority_shooting = True in the retis section to focus sampling on the new ensembles until they reach a comparable number of cycles.

Default:: The default value is flexible_restart = False.