The initial-path section¶

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

The whole section is optional: an input that leaves it out generates its initial paths with kick, which needs nothing beyond the starting configuration the input already supplies. The chosen initiation is always written to the log, so a run records how its first paths were made. Give the section when you want load or restart instead, or to tune the kick.

Example initial-path section:

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

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

Table 38 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 to continue a run in its run directory, whose output.toml holds the state of the run — 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 output.toml is unavailable or whose interfaces or ensembles need to change; 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.

A kicked path that starts at state B and ends at state A is reversed. A path that starts and ends at state B is repaired by Monte Carlo moves: a time reversal and, when that is rejected, an aimless shot from the frame of the path closest to the middle interface; a move that brings the path closer to a valid one replaces it, for at most [tis] initial_path_fix_maxtries attempts.

Random numbers. The kick of each ensemble draws from random streams of its own, spawned from [simulation] seed: the velocities of its kicks and of the shots of a repair, the random forces of a Langevin integrator and the seeds of the runs of an external engine. An ensemble draws the same numbers whether the ensembles are kicked one after the other or with kick-parallel = true, so both kicks store the same initial paths where they run the same engine section (an explore run excepted), and another [simulation] seed kicks other initial paths.

TurtleMD. A TurtleMD input gives its particles in [engine.particles], and the engine reads its starting configuration from a file. The run writes the starting positions, those of [particles.position] when the input has that section and those of [engine.particles] pos otherwise, to turtlemd_initial_NNN.xyz in the run directory, one file for each ensemble NNN (turtlemd_initial.xyz for the parallel kick), and refuses a [particles.position] input_file of the same name: give the file of the positions another name.

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 39 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.
kick-parallel	Kick the ensembles at the same time, on the workers of `[runner] workers`.

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.

Keyword kick-parallel¶

kick-parallel = boolean

With kick-parallel = true and kick-from = initial (the default), the kick of each ensemble is a job of its own, and up to [runner] workers of them run at the same time; with one worker, the default, they run one after the other. It changes only how the kicks are run, not the search itself or what makes a path valid: the kick of each ensemble draws from the same random streams, spawned from [simulation] seed, with kick-parallel = true or without, so both store the same initial paths where they run the same engine section (an explore run excepted: its two kicks store different ones).

kick-from = previous kicks each ensemble from the path just made for the one before, so the ensembles are kicked one after the other: with it, kick-parallel = true takes no effect, and the run does not say so.

kick-parallel = true is tested with TurtleMD and with the internal integrators Langevin and VelocityVerlet. With ASE the kick stops before a path is made, with kick-parallel or without.

With an internal integrator, each job kicks from the starting configuration held in memory, as the sequential kick does, and stores its initial path as the sequential kick stores it: the positions and the velocities of its frames in the traj.xyz of the path, whose energies the run computes from the frames. A job draws the velocities of its kicks, and a Langevin integrator its random forces, from the random streams of its ensemble: the initial paths do not depend on the number of workers or on the worker that runs a job.

With TurtleMD, each job kicks from the starting configuration of the sequential kick, in the box of the input, and stores its initial path as the sequential kick stores it: the velocity direction of each frame in its traj.txt and the energies TurtleMD gives in its energy.txt.

With OpenMM, each job kicks from the starting configuration held in memory, as the sequential kick does, and stores its initial path as the sequential kick stores it: each frame with its own periodic box in the traj.xyz of the path, and the potential and kinetic energies of the frames in its energy.txt. A stochastic OpenMM integrator, thermostat or barostat is seeded from the job’s random stream before each kick, so the initial paths do not depend on the number of workers or on the worker that runs a job either.

With GROMACS, LAMMPS or CP2K, each job kicks from the configuration file the sequential kick starts from, the conf of the input_path of [engine], and draws the velocities of its kicks and the seeds of the engine from the random streams of its ensemble.

Default:: The default value is kick-parallel = false.

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, …, the names of the ensemble directories of the run, see What a run writes). A pptis run without zero_left or flux numbers only the windows it builds, so it reads its first window, the [0^+] or the [1^+], from 000. The load folder is input and is only read: its files are linked or copied into a directory pyretis-load-* in the directory PyRETIS runs in, the files a load prepares (traj.txt, order.txt and the frames of each ensemble in NNN/accepted/) are written there, and the paths are read from there. The directory is removed when the load ends. A run that stops during the load leaves it in the run directory; remove that pyretis-load-* directory by hand. In pyretis-load-* the .txt files of the load folder are copies, and its other files, the frames, are hard links where the filesystem allows, which take no disk space of their own, and copies elsewhere. A run that reads initial paths staged flat, in <load_dir>/<path number>, keeps a copy of their files that takes as much disk space as the staged files (see load_dir). Messages about the files of the load name them in the load folder, and pyretis tools clean leaves the load folder a TOML input names in place. 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).
Order parameter. When the folder of an ensemble holds an order.txt, the load checks and, where needed, cleans the path with the values it holds; without one, it computes them from the frames with the order parameter of the simulation input. The run then recomputes the order parameter of every loaded path from its frames, warns where the values differ, and stops when a path is not valid for its ensemble with the recomputed values. An .xyz frame is evaluated in the box of its box line. A frame without a box line, or with a box line of zeros, is evaluated with CP2K in the cell of the CP2K input template, and with OpenMM in the periodic box of the OpenMM simulation. OpenMM propagates a periodic cell only: a frame whose box line has a length of inf or 0 stops the run with a ValueError when the frame is set in the OpenMM context.
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.

The potential and kinetic energies of the loaded frames are read from the energy.txt of the ensemble folder. Without one, as in every unformatted load, OpenMM computes them from each frame: the potential energy of the OpenMM System at the positions of the frame and in the box it is evaluated in (step 2), and the kinetic energy of its velocities, both in kJ/mol as the frames of its MD record them. It computes them in the same way for a path staged without energy.txt in the load_dir of the run, with the engine section ensemble_engines gives the ensemble of the path. The internal integrators recompute the energies of the stored frames in the run, with the engine section of the ensemble of the path, and the energies of the frames of the other engines are written as nan.

Path validation and cleaning¶

After collecting frames PyRETIS checks whether the assembled sequence constitutes a formally valid path for the target ensemble. In the [0^-] of a rate calculation with zero_left, a valid path starts and ends at the first interface, so a loaded path that reaches zero_left is recovered like any other. A recovered path is a seed: its interior frames are the shooting points of the first moves, and the analysis leaves it out. If the sequence is not a valid path, 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, .lammpstrj, plain-text .txt). PyRETIS will, in the directory where it prepares the load:

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

The frames of a LAMMPS dump (.lammpstrj) are listed by their time steps (see the index column of traj.txt below), and a dump whose time steps do not increase from frame to frame is refused. A file of one of these formats that is a LAMMPS restart file stops the load with an error that names it, before any frame is read, whatever the engine: PyRETIS does not start from a LAMMPS restart file (see Configurations held in LAMMPS restart files).

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`	Optional. Full path (positions and velocities). Without it, the frames of the trajectory files of the folder are read in the order of their names, from its `accepted/` when the folder holds an `order.txt`.
`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`	Optional. Frame index file referencing MD files. Without it, the frames of the MD files are read in the order of their names.
`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. If absent, OpenMM computes the energies of the frames, and those of the other external engines are written as `nan` (see above).

The index column of an external traj.txt names each frame by its frame number in its file, counted from 0, and a frame of a LAMMPS dump (.lammpstrj) by its time step, the number below its ITEM: TIMESTEP line. Both LAMMPS engines dump frame k of a path at the time step k * subcycles, and the traj.txt of their paths lists these time steps. A time step that no frame of the dump has stops the load with a ValueError, except a time step past the last frame of its dump, which names a frame past the end of the file (see below). The rows may list the frames of a file in any order, skip frames or name a frame more than once; without order.txt, each row receives the order parameter of the frame it names, evaluated with the velocity direction of its vel column. Rows at the end of traj.txt that name frames past the end of their files, the frames an interrupted run did not write, are cut from the path with a warning; a row naming a frame past the end of its file that rows naming written frames follow stops the load with a ValueError.

Use Layout 2 when different ensembles should start from different trajectories, such as the paths of an earlier run.

Starting from the paths of an earlier run. A run directory is not a load folder: a load_folder that names one stops with ValueError: zip() argument 2 is longer than argument 1. A run keeps the files of its live paths in NNN/accepted/<n>/, <n> the path number, and of older paths in NNN/archive/<n>/, each with the order parameter along the path in its order.txt (see What a run writes). For each ensemble NNN of the new simulation, pick a path of the earlier run that crosses the ensemble’s middle interface: the largest value in the order.txt of the path lies right of that interface. Check it for each path: a path is kept in the folder of the path it was shot from, so the folder of an ensemble can hold paths that do not cross its middle interface. Copy the files of the path into <load_folder>/NNN/:

for an external engine such as GROMACS, LAMMPS or OpenMM, traj.txt, order.txt and energy.txt into <load_folder>/NNN/ and the trajectory files into <load_folder>/NNN/accepted/;
for an internal integrator (Langevin, VelocityVerlet, Verlet) or TurtleMD, the frame files (*.xyz) alone: the traj.txt of a run lists frame files, which this layout does not read, and the load writes its own.

One path may serve several ensembles, for example when an interface is added. When no path of the earlier run crosses the middle interface of an ensemble, give it the path that comes closest and set load_and_kick = true: the load then kicks from the frame nearest that interface.

Note

Remove an outdated order.txt. An order.txt in the load folder is not required: the load computes the order parameter from the frames when it is absent. When it is present, the load checks and, where needed, cleans the path with the values it holds, so remove it when it no longer matches the order parameter of the input, for example after you changed its definition; the trajectory files need no change.

Keywords for the load method¶

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

Table 40 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 an existing simulation. It is not a vehicle for changing the simulation itself — for that, use load.

A path-sampling run (tis, retis, biretis, explore, pptis, repptis) started with pyretis run keeps its state in the run directory’s output.toml, and a restart continues from there. The settings of the continuation are taken from the new input file; only the running state — the cycle counter, the random-generator state, the occupancy weights and the paths each ensemble holds — comes from output.toml.

output.toml records the input of the run: its sections under the names of the input, with its defaults written out (the zero-swap probability as [retis] swapfreq), and the [current] state. It leaves out what PyRETIS works out from the input as it reads it (the engine type, the input_files it finds for GROMACS and CP2K, the run directory, the copies of the sections for each ensemble), and every key that takes no effect on the run (the keywords that take no effect), which a path-sampling run refuses in its input, also where PyRETIS sets such a key itself, as method = "restart" sets [simulation] restart. So it holds no [simulation] rgen, and holds the rgen of [tis], [engine] and [system] only for a run that kicks its initial paths one ensemble after the other (method = "kick", unless kick-parallel = true with kick-from = initial, or load with load_and_kick = true). It records [output] screen, the cycles between two progress reports. pyretis run -i output.toml resumes the run with the settings it records, and pyretis analyse -i output.toml analyses it as its input would.

An output.toml written by an earlier PyRETIS can hold keys that took no effect on its run, such as [retis] nullmoves or [output] trajectory-file. The run file still continues and analyses: such a key is left out when the file is read, silently when its value is the one this version gives it, and named in a warning otherwise. A value that earlier PyRETIS took as another input key is read under that key: [simulation] zeroswap as [retis] swapfreq, which it won over, and [tis] relative_shoots as [retis] relative_shoots when the file sets none there. pyretis run -i output.toml then writes the record of this version, with the defaults the file does not hold, such as [output] screen.

An output.toml or restart.toml written by an earlier PyRETIS holds the configuration of the scheduler instead, with its [simulation.tis_set] table. A restart continues from it as from the output.toml of this version: the continuation compares its settings with the ones that state file records, and names each setting by its input key. pyretis run -i refuses such a state file, and the message names this route: set method = "restart" in the input of the run and run it in the run directory. pyretis analyse -i reads the settings of such a state file under the names of the input, except for the state file of a tis run of one ensemble, whose analysis counts a crossing at [tis] detect when its input gives [tis] ensemble_number, which the state file does not say (see Calculating the rate). The continuation writes output.toml in the form of this version.

kick and load start a new simulation, which writes the output files of its ensemble directories afresh. When one of those directories holds a pathensemble.txt with data rows, the record of cycles a simulation has sampled, pyretis run stops with a ValueError before initiation and leaves the ensemble directories and output.toml as they were. A path-sampling run refuses [output] backup, so no setting lets it write over that record. To add cycles to that simulation, set method = "restart" and raise [simulation] steps to the new total. To start a new simulation, use a new directory, or first clean the run directory with pyretis tools clean or remove the ensemble directories the message names. A run that starts a new simulation from initial paths already in the run directory, such as a run of a legacy-runner input, stops before its load in the same case, and when a pathensemble.txt holds the header alone, with a FileExistsError that names the ensemble directories. A run of a legacy-runner input stops before it writes anything, with a ValueError, when the run directory holds the state file of a simulation, an output.toml or the legacy restart.toml with a [current] section. pyretis run -i output.toml continues the simulation of an output.toml that records the input of the run; a state file of an earlier PyRETIS is continued by the input converted to the canonical schema (python -m pyretis.tools.convert_legacy_schema) with method = "restart" (see load_dir).

The legacy-runner schema ([runner], [simulation.tis_set], no [simulation] task) is deprecated: PyRETIS 4 converts such an input to its canonical form when it reads it, with a deprecation notice, and PyRETIS 5 will not read it (see the migration guide). The schema has no [initial-path] section: a run of a legacy-runner input starts from the initial paths staged in the run directory, and records its canonical form, its defaults resolved, in output.toml, as a run of a canonical input does, the pool of ensemble_engines and the engine sections it names among them. pyretis run -i output.toml resumes that run, and the canonical form with method = "restart" continues it. The canonical form takes the initiation of the canonical input, method = "kick", which the record names: a new run of the canonical form generates its initial paths, and stops before it writes a file when the run directory holds initial paths staged flat.

Before continuing, the restart compares the new input with the one that wrote output.toml and refuses, with a ValueError and without touching the saved state, when:

the number of ensembles differs;
any interface position differs;
the ensemble layout differs: the ensembles [simulation] task builds, the [0^-] window that zero_left bounds, a permeability run, for task = "pptis", whether zero_left or flux adds a [0^-] window and zero_ensemble a [0^+] window, and, for task = "pptis" and "repptis", the ensemble windows that [pptis] memory and [repptis] memory set, and, for task = "biretis", the interfaces of state B that interfaces_b gives and the number of shared ensembles that shared sets;
any of these settings differs: [tis] maxlength, [tis] allowmaxlength, [tis] enforce_must_cross_m, [system] temperature, the engine temperature, timestep and subcycles, any setting of the orderparameter section (its class, every setting the class reads, the module it is read from and its name), and the GROMACS exchange format gmx_format;
the continuation draws the shooting velocities from another distribution (see below).

The refusal names each setting by its input key, e.g. [simulation] zero_left, and says what it fixes and the value of each run.

maxlength and allowmaxlength enter the acceptance probability of the shooting move, and enforce_must_cross_m decides which paths are members of an ensemble, so changing one of them would continue the chain under a different acceptance rule. The ensemble layout decides which ensembles exist and which paths each of them accepts, so the paths the ensembles hold were accepted in the recorded layout. flux and zero_ensemble change the ensembles of a pptis run only, so the restart compares them for that task. The memory sets the window [lambda_{i-memory}, lambda_i, lambda_{i+memory}] of each ensemble of a pptis or repptis run. The time grid and the order parameter fix what the saved paths mean: a particle index, a dimension or a periodicity that differs defines another reaction coordinate, as a different class does.

The temperature sets the distribution the ensembles sample. [system] temperature is compared for every run, within a relative \(10^{-9}\). The internal integrators, TurtleMD, ASE and the user-defined engines that are built on none of the engines below run at it. GROMACS, LAMMPS, CP2K, OpenMM and AMS run at the temperature their own input states, and the run sets [system] temperature to it when the input leaves it out (see the temperature keyword), so a continuation whose engine input states another temperature than the run it continues is refused on [system] temperature. The engine temperature of a section is compared on the temperature the engine of the section runs at: the temperature the section records, which an engine section gives or a pool whose engines run at different temperatures records for each engine, and else the temperature of the run. pyretis run -i output.toml compares the temperatures the run file records with the engine inputs in the same way, before any engine runs.

A run file whose state marks its record of the temperatures (temperature_rule in [current.provenance]) and that records no temperature for an engine, neither [system] temperature nor the engine temperature, is refused by pyretis run -i and by a continuation: the temperature its paths were sampled at is not known. The resume does not give such a file the default [system] temperature 1 of the internal integrators.

A run file written by an earlier PyRETIS, whose state does not mark its record of the temperatures, is read as that PyRETIS ran its engines: the internal integrators at [system] temperature, TurtleMD and ASE at the engine temperature, GROMACS and CP2K at the engine temperature when the section gives one, CP2K of [engine] also at [system] temperature, and every other engine at the temperature of its own input, which the run file does not record. The [system] temperature such a file records for CP2K of [engine] is compared with its CP2K input, in a run file and in the state file of the scheduler shape alike, and a difference is refused. A LAMMPS engine took the beta of its acceptance from the engine temperature when the section gives one, and its velocity draws too, except lammps_steps with velocity_generation = "engine", for which LAMMPS drew them at the SET_TEMP of lammps.in; it ran its dynamics at the thermostat fixes of the lammps.in of that run, which the run file does not record either. The engines that run at [system] temperature must have run at one temperature, which is the temperature of the run that continues; a run file whose such engines ran at different temperatures, a TurtleMD pool at 0.07 and 0.08 or an internal integrator and a TurtleMD engine at different temperatures, is refused before any engine runs, by pyretis run -i and by a continuation: a new run is needed. A temperature the run file records for an engine is compared with the continuation; one it does not record, or records in part (LAMMPS), is reported as UNKNOWN, also when the temperatures happen to be equal, and the resume runs the engine at the temperature of its input. An engine temperature the run file gives for such an engine is still compared as it is given, so a continuation that changes it, or leaves it out at another temperature, is refused. A [particles.velocity] temperature that such a run file, or the state file of the scheduler shape of such a run, records is left out, with a warning, when it equals the temperature the engines of the run ran at within a relative \(10^{-9}\) (the engine temperature of TurtleMD and ASE, the [system] temperature of the internal integrators, the one temperature the file records for engines that read their own input, and else the [system] temperature it records), and refused otherwise; an input that starts a run is refused when it sets one.

pyretis analyse -i reads such a run file or state file in the same way, from the file alone, and refuses no run for its temperatures. It analyses the run at the one temperature its engines that run at [system] temperature ran at (a TurtleMD or ASE engine at its engine temperature). For a run whose engines all read their temperature from their own input it takes the temperatures the file records for them (GROMACS and LAMMPS at the engine temperature, CP2K of [engine] at [system] temperature): one temperature is the temperature of the run, and different ones leave [system] temperature out, as this PyRETIS records a pool whose engines run at different temperatures; when the file records none of them, the analysis reads the [system] temperature it records. A run with an engine the analysis does not know is read at the [system] temperature the file records; the analysis does not know a module engine, whose temperature it does not read from its module, an engine class that PyRETIS does not hold, and a TurtleMD or ASE engine section without a temperature. Where the record gives no one temperature, the analysis reads no [system] temperature, with a warning that says why, as for a run that states none: engines that run at [system] temperature at different temperatures (a TurtleMD pool at 0.07 and 0.08, an internal integrator and a TurtleMD engine), a TurtleMD integrator beta other than 1 / (boltzmann * temperature) of its engine temperature, an engine that reads its temperature from its own input at another recorded temperature than those, an engine the analysis does not know beside an engine that reads its own input at another recorded temperature than the [system] temperature of the file, or a [particles.velocity] temperature other than the temperature of the run (the velocities were drawn at one temperature, and the run held at another). The path-sampling analyses do not use the temperature; an analysis that needs it (the energy analysis of an md-flux run) does not run, with its own message, which says what the record shows. Only that analysis stops: the other analyses of the task (the flux and order parameter analyses of md-flux) complete and their reports are written, and pyretis analyse then exits with status 1. Where the file does not record in full the temperature an engine ran at (LAMMPS, an engine section without a temperature, OpenMM, AMS, a module engine), a warning says that the temperature the analysis reads is not verified. The analysis does not compare the run file with the engine inputs: a CP2K input in the run directory that now states another temperature is not read, as the run file records the temperature the run ran at; running and resuming the run compare them. Each warning appears once per analysis: the analysis reads the run file of a path-sampling run again for its interfaces and ensembles, quietly. A run file of this PyRETIS that records a [particles.velocity] temperature is read in the same way, with its [system] temperature.

The out.toml that an in-process task of this PyRETIS (md, md-flux, …) stores carries the table [provenance] with temperature_rule = 1, the mark the [current] state of a run file carries: its [system] temperature is the temperature the run ran at. pyretis analyse -i out.toml reads it as the record of its run, as a run file with the mark: at that temperature, compared with no engine input and no Python module of an engine. The settings parse leaves the table out, so the file still parses as an input, and refuses a [provenance] table other than the one PyRETIS writes. The out.rst of an .rst input carries no mark.

pyretis analyse -i reads a file without a [current] state and without that mark (an input, or the out.toml an earlier PyRETIS stored) as the input of a run of this PyRETIS, unless the file records a setting that this PyRETIS refuses in an input for its temperature and that only an earlier PyRETIS ran: a [particles.velocity] temperature, a TurtleMD integrator beta, an engine temperature of TurtleMD or ASE without [system] temperature, or an engine temperature other than the [system] temperature of the file. Such a file is read as the record of a run of an earlier PyRETIS, with a warning that names the setting, by the rules above: an earlier md-flux run whose out.toml records a [particles.velocity] temperature equal to its [system] temperature is analysed at that temperature, and one with another value without a temperature. An input of the legacy-runner schema is read by these rules too: a TurtleMD pool at 0.07 and 0.08 is analysed without [system] temperature, with the warning, while pyretis run refuses it.

A file without a state records no temperature its engines ran at, so the analysis compares the [system] temperature it reads from such a file, a legacy-runner input among them, with the inputs of its engines that read their temperature from their own input (cp2k.inp, the mdp file, lammps.in, …), read where the file names them, as a run of the file compares them: the temperature within a relative \(10^{-9}\), and the unit system lammps.in declares against [system] units. A difference, or an engine input that cannot be read, leaves the file without [system] temperature, with a warning that names both values, or the input and why it cannot be read: the analysis refuses no such file, and reads no temperature its run may not have run at. A run file or state file, and the marked out.toml, is the record of its run, and is not compared. The analysis does not read the temperature of an engine from a Python module: a module engine (an engine section that names a module), whose class only its module defines, and OpenMM, whose simulation module states its temperature. A file without a state with such an engine and a [system] temperature is read without [system] temperature, with a warning that the temperature of that engine is read only by a run; one without [system] temperature is read without it, and without a warning. The record of the run holds the temperature the run ran at: the run file a path-sampling run writes, with its [current] state, and the marked out.toml of an in-process task. The analysis runs no simulation module; the settings parse imports a module engine, as a run does, to give [system] units its default when the file sets none.

A temperature that is not a finite, positive number (a string, a boolean, a list, a table, nan, inf, zero or a negative number) in [system], in an engine section or in [particles.velocity] is refused as an invalid input on every route, the analysis included, before it is compared with anything: [system] temperature with [system] temperature = 'hot' is not a number or [system] temperature = nan is not a finite number, and an engine section, when a file is read, with [engine] temperature = nan is not a finite number: a temperature is a finite, positive number (a run that checks the section also names the temperature its engine runs at), and [particles.velocity], when a resume or the analysis reads a run file, with [particles.velocity] temperature = 'hot' is not a number. It is compared with the temperature of the run. A state file of the scheduler shape is checked in the same way, with the mark or without it. A boolean is never read as a temperature. A restart file that records such a temperature of its system is refused by the continuation.

The engine timestep and subcycles apply to every engine: each engine stores a frame every subcycles integration steps. The gmx_format applies to the GROMACS engines and to a module-provided engine, whose class is imported only when the run starts. A setting that applies to neither run’s engine is skipped. The internal integrators (Langevin, VelocityVerlet, Verlet) and OpenMM run with subcycles = 1 when the input leaves it out, and the restart compares it as 1; the GROMACS, LAMMPS, CP2K, AMS, ASE and TurtleMD engines require it. A setting that applies and cannot be compared is reported as UNKNOWN in a WARNING, with the reason, and the restart proceeds: the previous run did not record it (an archive written before the setting was persisted, or a value its engine took from its own input), the continuation does not record it, neither run records it, or it applies to the engine of one run only. LAMMPS and OpenMM take the time step from their own input (the LAMMPS input file and the restart file it reads, see the time step of LAMMPS, and the OpenMM integrator); it is recorded, and cross-checked by the engine, when [engine] timestep states it as well, and the warning about a continuation that leaves it out says so. For any other setting that neither run records, the warning asks for the two inputs to be compared by hand.

[tis] zero_momentum and [tis] rescale_energy select the distribution of the shooting velocities, and the paths the ensembles hold were shot with the draws of the run that wrote output.toml. The restart compares those draws with the draws of the continuation: whether every draw has zero total linear momentum, and the energy the drawn velocities are re-scaled to. The continuation draws as its input selects, and so does the run that wrote an output.toml whose [current.provenance] holds velocity_draw_rule = 1. An output.toml without that key records the draws of the engine the run used:

the internal integrators, OpenMM and cp2k_steps keep the linear momentum of every draw;
GROMACS and lammps_steps with velocity_generation = "engine" (gen_vel, and velocity create with the LAMMPS default mom yes) draw with zero total linear momentum;
the streaming cp2k engine draws with zero total linear momentum unless the recorded zero_momentum is false;
AMS draws with zero total linear momentum (GenerateVelocities removes the net linear momentum with RandomVelocitiesMethod Gromacs and Exact, the AMS default; Boltzmann is not checked);
TurtleMD, ASE, the streaming LAMMPS engines, and GROMACS and lammps_steps with velocity_generation = "maxwell" follow the recorded zero_momentum, a missing key being false;
no engine of PyRETIS re-scales the energy of a shooting draw;
for an engine imported from a module, the momentum reset, and a positive recorded rescale_energy, are reported as UNKNOWN in a WARNING and the restart proceeds: a module engine can inherit the modify_velocities of an engine of PyRETIS, whose momentum reset depends on the PyRETIS version that wrote the output.toml.

A continuation that draws differently is refused with a ValueError that names the engine, how each of the two runs draws, and, where one exists, the zero_momentum and rescale_energy that draw as the run being continued did. For example, the output.toml of a GROMACS run with velocity_generation = "engine" without the key continues with zero_momentum = true, the draw of gen_vel, and is refused with zero_momentum = false.

pyretis run -i output.toml resumes with the settings output.toml records. For an output.toml without velocity_draw_rule it compares the draws those settings select with the draws of the engine the run used, as listed above, and refuses a resume that draws differently with a ValueError that names the [tis] zero_momentum and rescale_energy that draw as that run did; setting them in the [tis] section of output.toml lets the resume proceed. Every run records velocity_draw_rule in the output.toml it writes.

Every other setting is taken from the new input file as written, and applies from the resumed cycle on.

[tis] high_accept may change on a restart too, but it selects the acceptance rule of stone skipping, and the paths the ensembles hold at that point were accepted under the other rule. They are therefore left out of the statistics: each is marked with the initialisation code hc, the change is recorded under [current] high_accept_changes in output.toml, and each ensemble counts again from its first path accepted after the restart. A WARNING reports how many paths were set aside.

A restart also records, as [current] ss_weight_from_cycle in output.toml, the first cycle it writes, unless the state already holds one, and with it, under [current] ss_weight_before, the move list and layout of the run being continued and the paths it holds. The analysis reads them to tell which rows carry the stone-skipping weight of the rule each path was sampled with; see the analysis guide.

[simulation] priority_shooting may change on a restart as well: turn it on when some ensembles have received fewer moves than the others, and the moves go to them more often until all have received the same number. While it is on, the moves submitted to each ensemble are recorded as [current] moves_submitted in output.toml and continue over the restart; a restart that turns it on without that record starts from the attempted moves in each ensemble’s moves.txt. See priority_shooting.

To continue although one of the checked settings changed, or the draws differ, set allow_setting_change = true in the [simulation] section (of the input, or of output.toml for pyretis run -i output.toml). The check is then skipped and a WARNING says that the samples before and after the restart were not drawn under the same settings. It does not lift the checks of the number of ensembles and of the interface positions: to move, add or remove interfaces, or to change the number of ensembles, start a new simulation from the saved paths with load (see starting from the paths of an earlier run).

Keywords for the restart method¶

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

Table 41 Keywords for the restart method.¶
Keyword	Description
method	Selects the restart method.
flexible_restart	md tasks: restart with changed settings (see below). Path-sampling runs and make-tis-files refuse true and name what to set instead.

Keyword method¶

method = restart

The method keyword selects the restart initialization. The continuation of a path-sampling run reads the run directory’s output.toml (or the legacy restart.toml), whichever PyRETIS version wrote it, so run it in the directory of the run it continues. An md, md-nve or md-flux task continues from its restart file instead (see below).

Restarting an md task¶

An md, md-nve or md-flux task continues from the restart file that [simulation] restart names; method = "restart" sets that key to pyretis.restart when the input gives none. Set [simulation] steps to the total number of steps. The restart takes its settings from the restart file, so that it continues the same simulation, and from the new input the settings listed below and the whole [output] section, prefix included: an [output] key the new input leaves out takes its default, not the value of the restart file. A changed value of any other setting, such as [engine] timestep or gamma, is not used, and the run does not say so; the out.toml it writes shows the new value.

An umbrellawindow task takes method = "restart" as well, but its restart does not continue the window: it stops with KeyError: 'steps' unless the input sets [simulation] steps, which the task otherwise does not use; it keeps the mincycle of the restart file unless flexible_restart = true; and it draws its trial moves anew from the [simulation] seed of the new input, so the window differs from the one a run without the stop gives. To run a window for more cycles, run it again with the larger mincycle.

Settings the new input may change¶

When one of these settings differs from the restart file, PyRETIS logs a WARNING and takes the value of the new input:

simulation: steps
output: screen, backup, trajectory-file, energy-file, order-file, cross-file, restart-file, pathensemble-file, log_file, log_mode, engine_log

A changed [simulation] seed is named in a WARNING too, but takes no effect on an md task. An md-nve or md-flux task continues the random numbers of the restart file, so its continuation is the run it would have been without the stop; an md task with a stochastic integrator (Langevin) draws them anew from the seed of its engine section, so its continuation differs from a run without the stop (an umbrellawindow task draws from the new seed, see above).

The keys of the moves of a path-sampling run take no effect on an md task either (see the keywords that take no effect). With a changed value of [simulation] priority_shooting, of [tis] freq, sigma_v, shooting_move, shooting_moves, high_accept, n_jumps, mirror_freq, target_freq and target_indices, or of [retis] swapfreq, the run continues as it does with the value of the restart file, and a WARNING can name the change (Restart override: "tis.freq" changed from None to 0.3.).

Settings a restart refuses to change¶

The restart stops with a ValueError, before it continues, when the new input changes [simulation] interfaces or task, or sets a [system] temperature that differs from the one of the restart file by more than a relative \(10^{-9}\) (see below). It also refuses a change of [tis] maxlength, allowmaxlength and enforce_must_cross_m and of [simulation] zero_left, zero_ensemble, flux and permeability, which take no effect on an md task, with a message that names load: keep them as they were.

To restart an md-flux task with other interfaces, set flexible_restart = true (below); to change any other of these settings, start a new simulation.

The system the restart file holds was propagated, and its velocities drawn, at the temperature the restart records, so the continuation runs at it: an input that leaves [system] temperature out runs at the temperature of the restart file, which the stored settings (out.toml) record (an input with a TurtleMD or ASE engine, or with another engine that has no default temperature, such as an engine of your own built on EngineBase, must still set it, as for a new run; see the temperature of a user-defined engine), and a [system] temperature the input sets, or the temperature the input of an engine that reads its own states, must equal it within a relative \(10^{-9}\), and the stored settings then record the temperature of the restart file; else the restart is refused, naming the value. A restart file written by an earlier PyRETIS, without the temperature_rule mark, records for an engine that reads its temperature from its own input the [system] temperature of its settings, which the engine did not run at: the continuation runs at the temperature of the engine input, with a warning that it is not verified, also when the two are equal. The engine temperature such a restart file records for a LAMMPS engine, which took the beta and its draws from it and ran its dynamics at its lammps.in, is compared with the continuation, and an equal value is warned about as not verified too. A continuation of an umbrellawindow restart file written by an earlier PyRETIS runs at the [system] temperature that the settings in the file record, as for a restart file of this PyRETIS: an input that sets another [system] temperature is refused, and so is a restart file whose system records another temperature than its settings.

pyretis analyse of an md-flux continuation (with its input or its out.toml) reads the number of particles of the run and the degrees of freedom of its temperature, for the Boltzmann distributions of the energy analysis, from the restart file that [simulation] restart names: the input of the continuation need not hold a [particles] section. It reads there the engine of the run as well, which decides whether the distributions are drawn (see npart): the continuation runs the engine of the restart file, whatever [engine] its input names. With flexible_restart = true the continuation runs the engine its input names, and the distributions are drawn only when that is the engine of the restart file.

When that restart file is not found, or cannot be read (the message names the error of the reading), the energy analysis draws no Boltzmann distribution: it writes its histograms, block analyses and figures without them, a warning and the report say why, and pyretis analyse exits with status 0. [particles] npart does not replace the restart file; analyse the continuation in a directory where the restart file it continues is found and can be read, to draw them.

The energy analysis does not run, with a message that says why, when the restart file records another number of particles than the [particles] npart the input sets (leave [particles] npart out, or set it to that number), or records particles without a type, or particles of an internal engine without a whole record of their number, masses and velocities and of the degrees of freedom of the temperature of the run. The flux and order parameter analyses complete and their reports are written, the report says why the energy analysis did not run, and pyretis analyse exits with status 1. See npart, which lists the cases where the energy analysis does not run or draws no Boltzmann distribution, such as a run on an external engine (CP2K, GROMACS or LAMMPS).

Keyword flexible_restart¶

flexible_restart = boolean

For an md, md-nve or md-flux task, flexible_restart = true skips the check of the settings: the restart takes the settings of the new input, the interfaces of an md-flux task included, and logs no WARNING for a changed value. Keep [simulation] task as it was: a restart that turns an md or md-nve task into md-flux stops with KeyError: 'leftside_prev', and one that turns an md task into md-nve with KeyError: 'engine'; to change the task, start a new run.

The restart file still gives the state the run continues from, and with it the [system] temperature and, for an md-nve or md-flux task with an internal integrator, [engine] timestep, gamma and high_friction. A [system] temperature the new input sets must equal the temperature of the restart file, within a relative \(10^{-9}\), and the continuation is given it when the input leaves it out (see Settings a restart refuses to change). Of the other three the run keeps the values of the restart file without a message, although the out.toml it writes shows the new ones. To change these, start a new run.

A path-sampling run (tis, retis, explore, pptis, repptis) and make-tis-files refuse flexible_restart = true, the PyRETIS 3 way to restart a run with changed settings or interfaces, and name what to set instead:

To continue the run with changed settings, such as [tis] maxlength or [system] temperature, keep method = "restart" and set [simulation] allow_setting_change = true (see the restart method). The run continues with a WARNING: the samples before and after the restart were not drawn under the same settings, so analyse the two stretches separately (with the default [analysis] method, pyretis analyse -skipb N leaves out the first N cycles and -skipe N the last N; the WHAM analysis counts -skipb in paths and ignores -skipe, although the log says it discards those cycles, see The PyRETIS analysis application).
To move, add or remove interfaces, or to change the number of ensembles, start a new simulation from the saved paths with load (see starting from the paths of an earlier run).

Default:: The default value is flexible_restart = false.