The simulation section¶

The simulation section defines and selects the simulation PyRETIS will run.

Example Simulation section:

[simulation]
task = "retis"
steps = 20000
interfaces = [
    -0.9,
    -0.8,
    -0.7,
    -0.6,
    -0.5,
    -0.4,
    -0.3,
    1.0,
]

For this section, the keyword task specifies the type of simulation to run and this will also determine the keyword that can be set in this section. Further, a specific task might also require additional sections to be defined as detailed in the table below:

Table 1 Possible values for the task keyword¶
Task	Description	Keywords	Required sections
`retis`	A replica exchange transition interface sampling simulation.	`task`, `steps`, `interfaces`
`tis`	A transition interface sampling simulation.	`task`, `steps`, `interfaces`
`biretis`	A bidirectional RETIS simulation: the rates of A -> B and B -> A in one run.	`task`, `steps`, `interfaces`, `interfaces_b`, `shared`
`repptis`	A replica exchange partial path transition interface sampling simulation.	`task`, `steps`, `interfaces`	`retis`
`pptis`	A partial path transition interface sampling simulation.	`task`, `steps`, `interfaces`
`explore`	A free energy surface exploration simulation.	`task`, `steps`, `interfaces`
`md-flux`	A MD FLUX simulation.	`task`, `steps`, `interfaces`
`md-nve`	A MD NVE simulation.	`task`, `steps`

Three further values are accepted. md runs a molecular dynamics simulation and takes task and steps. make-tis-files takes task, steps and interfaces, writes the input of a single TIS simulation for each [i^+] ensemble of the interfaces (tis-002.toml for the [1^+], tis-003.toml for the [2^+], …) and exits; with zero_ensemble = true it writes the input of the [0^+] (tis-001.toml) as well. It needs three interfaces or more, or two or more with zero_ensemble = true. Each input holds the seed of this section plus the number of its ensemble (seed = 18 in tis-002.toml of an input with seed = 16), so the TIS runs draw independent random numbers in their kicks and moves. umbrellawindow runs one window of an umbrella sampling simulation; its keywords are given in its own section.

Since the different tasks may require different keywords, these are described below individually. In addition, there are some settings which typically are used in relation to the analysis, or when extending simulations. These are described in the section on common keywords.

The retis task ¶

The retis task defines a replica exchange transition interface sampling simulation.

Example Simulation section for task retis:

[simulation]
task = "retis"
steps = 20000
interfaces = [
    -0.9,
    -0.8,
    -0.7,
    -0.6,
    -0.5,
    -0.4,
    -0.3,
    1.0,
]

Keywords for the retis task ¶

For the retis task, the following keywords can be set:

Table 2 Keywords for the retis task.¶
Keyword	Description
steps	The number of total retis steps (cycles)
interfaces	The location of the interfaces to consider.
priority_shooting	Prioritize the ensembles with fewer moves.

The sections TIS and RETIS set the moves and the swaps of this task; an input that leaves one out takes the defaults of its keywords.

Keyword steps ¶

steps = integer

The steps keyword defines the number of RETIS cycles to perform. Note that it indicates the goal/final number of the simulation cycles.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces to use in the path simulation.

Default: Not any, this keyword must be specified.

Note

interfaces is topology-defining: it is locked once the simulation is started. A restart that supplies a different list aborts with a ValueError. To change the interface set, start a new simulation, in a new run directory, with [initial-path] method = “load” and load_and_kick = true. For each ensemble of the new run, copy the files of a path of the run that crosses its middle interface, from <ensemble>/accepted/<path number>/ of the run directory, into the subfolder of the load folder that has the name of its ensemble directory (000, 001, …), as starting from the paths of an earlier run describes for each engine (with an internal integrator or TurtleMD, the frame files *.xyz only). Every ensemble needs its subfolder. An ensemble whose frames form no valid path gets a path generated by a kick from the frame nearest its middle interface.

Keyword priority_shooting ¶

priority_shooting = boolean

If true, the scheduler weights the choice of each move’s ensemble toward the ensembles that have received fewer moves. A move is a pair: the ensemble whose rules it follows (its interfaces and its acceptance) and one of the paths that ensemble holds, drawn by its infinite-swap occupancy. priority_shooting changes only the first choice: an ensemble that has received n moves, while the most-sampled ensemble has received n_max, is chosen with weight n_max - n + 1. The ensembles that lag are shot more often until all have received the same number of moves; level ensembles are equally likely. The path is then drawn from the chosen ensemble as usual.

A move counts when it is submitted, accepted or not, and a zero swap counts for both of its ensembles. The weights therefore depend on the moves made so far, and not on the current paths or on how long the moves take to finish with several workers, so every move still leaves the sampled distribution unchanged: only the allocation of moves, and with it the statistical error of each ensemble, changes.

The counts are kept in output.toml as [current] moves_submitted, so the ensembles stay level over a series of short jobs, each one a restart of the previous one. A restart of a run that did not record them starts from the attempted moves in each ensemble’s moves.txt. priority_shooting cannot be combined with relative_shoots or pick_scheme.

Default: The default value is priority_shooting = false.

The biretis task ¶

The biretis task computes the rate constants of both directions, \(k_{AB}\) and \(k_{BA}\), and their ratio, the equilibrium constant \(K = k_{AB}/k_{BA}\), in one simulation, instead of a retis run for each direction.

It samples two ladders of ensembles:

the ensembles of state A, whose paths start in A and cross the interfaces of interfaces on their way to B, with the [0^-] ensemble of A, which gives the flux out of A;
the ensembles of state B, whose paths start in B and cross the interfaces of interfaces_b on their way to A, with the [0^-] ensemble of B.

Where the two ladders meet, shared ensembles hold the paths of both states: a shared ensemble holds the paths that start in A and cross its interface of interfaces, and the paths that start in B and cross its interface of interfaces_b. A path from A to B is, run backwards, a path from B to A: a reactive path that the run samples once counts for both directions, and a time reversal in a shared ensemble ([tis] freq) turns the one into the other. One run gives both rates for about the MD of one retis run; how its precision compares with two retis runs depends on the system (see the example).

Example Simulation section for task biretis:

[simulation]
task = "biretis"
steps = 20000
interfaces = [-0.9, -0.8, -0.7, -0.57, -0.44, -0.29, -0.12, 0.03, 0.9]
interfaces_b = [0.9, 0.8, 0.7, 0.57, 0.44, 0.29, 0.12, 0.03, -0.9]
shared = 1

The example runs examples/tutorials/path_sampling/internal/1D-double-well/biretis, an asymmetric double well whose two ladders meet in one shared ensemble at the top of the barrier, 0.03.

Keywords for the biretis task ¶

Table 3 Keywords for the biretis task.¶
Keyword	Description
`steps`	The number of cycles, as for `retis`.
`interfaces`	The interfaces of state A, ascending from lambda_A to lambda_B.
`interfaces_b`	The interfaces of state B, descending from lambda_B to lambda_A.
`shared`	The number of shared ensembles.

interfaces = list of floats

The interfaces of state A, in ascending order. The first is lambda_A, the boundary of state A (the paths of A start at or below it), and the last is lambda_B, the boundary of state B.

Default: Not any, this keyword must be specified.

interfaces_b = list of floats

The interfaces of state B, in descending order. The first is lambda_B and the last lambda_A: they are the last and the first interface of interfaces. The paths of B start at or above lambda_B and cross these interfaces going down.

Default: Not any, this keyword must be specified.

shared = integer

The number of shared ensembles. The shared ensemble k pairs the k-th of the last shared interfaces of interfaces before lambda_B with the k-th of the last shared interfaces of interfaces_b before lambda_A. With shared = 0 the two ladders are sampled side by side and exchange no paths. More than one shared ensemble logs a warning (see the placement of the shared ensembles below).

Default: Not any, this keyword must be specified.

Placing the shared ensembles ¶

Each ladder is placed as for retis, with a local crossing probability of about 0.2 to 0.5 between neighbouring interfaces. The interfaces of a shared ensemble are best paired so that a path that has come from A and crossed its A interface and a path that has come from B and crossed its B interface are equally likely to go on to the other state:

one shared ensemble on a single interface (the same value at the end of both lists): at the top of the barrier, where the committor is one half;
a symmetric system: mirror pairs, such as -0.7 with 0.7;
a long intermediate region, such as a shallow well between A and B: several shared ensembles across it, a layout that this version does not validate yet (see below).

A run with more than one shared ensemble logs a warning. The rates of a run with one shared ensemble are validated against brute-force rates on the double well of the example, with overdamped (Brownian) dynamics, and on the symmetric double well, whose mirror symmetry gives \(K = 1\), equal fluxes and equal local crossing probabilities of the two states: with underdamped Langevin dynamics, with the shared ensemble on a mirror pair of interfaces, and with no shared ensemble. Those of a run with more than one shared ensemble are not validated yet: on the double well of the example, runs with two shared ensembles gave \(K\) above its brute-force value. Compare the rates of such a run with those of a run with shared = 1.

The analysis prints the fraction of the paths of each shared ensemble that start in A. A fraction far from one half (as a rule of thumb, below 0.2 or above 0.8) means that the shared ensemble sits too close to one state: the crossing probability of the other state is then estimated from few paths, and that state needs more interfaces of its own. A fraction near one half does not show that the rates are right: the runs with two shared ensembles that gave \(K\) too high had fractions of 0.49 and 0.57.

The output ¶

The run writes one directory per ensemble: 000 is the [0^-] of A and 001 the [0^-] of B, then come the ensembles of A (its [0^+] first), the ensembles of B (its [0^+] first) and the shared ensembles. pyretis analyse -i <input> writes report/biretis_report.txt with the fluxes \(f_A\) and \(f_B\), the crossing probabilities \(P_A\) and \(P_B\), the rates \(k_{AB} = f_A P_A\) and \(k_{BA} = f_B P_B\), \(K\), their errors over five blocks of cycles, and the local crossing probability of each ensemble. [analysis] skip_initial_cycles and skip_final_cycles (-skipb and -skipe of pyretis analyse) leave out cycles at the start and at the end, as for retis. Leave out the first cycles of a run, which still depend on its kicked initial paths: in the example, the first 2000 of 20 000 cycles raise both rates by a few per cent. The report gives undefined for a value the cycles do not give, and for an error when one of the blocks gives no value or a value of zero (no path of the block crosses one of the interfaces): run more cycles. The WHAM analysis and the tools that read the path data of a run (the training set, the interface optimiser, the merge of several runs) take one-way runs and refuse a biretis run (see The PyRETIS analysis application).

A shared ensemble holds each reactive path in both directions, with equal weight. Its crossing probability for A is

\[\frac{c_{AA} + h}{n_{AA} + h}\]

where \(n_{AA}\) counts the paths of the ensemble that start and end in A, \(c_{AA}\) those of them that cross the next interface of A, and \(h\) is half the number of its reactive paths of both directions, which all cross that interface. Each path counts with its weight in the ensemble. The same holds for B, with the paths that start and end in B.

The biretis task requires dynamics that are reversible in time at equilibrium, as the time reversal move of retis does. In this version every ensemble shoots with sh (and the time reversal of [tis] freq) and runs with [engine], and the [0^-] of A has no left boundary. The run refuses an input that sets [tis] quantis, [simulation] permeability, [tis] mirror_freq, [tis] target_freq, [simulation] zero_left, a [tis] shooting_move or [tis] move other than sh, or one of the keys with one entry per interface, [tis] shooting_moves and [simulation] ensemble_engines: a biretis run has more ensembles than interfaces. It runs with one worker and refuses a [runner] workers other than 1: its rates with several workers are not validated in this version. It starts from kicked paths ([initial-path] method = "kick", the default, sequential or with kick-parallel = true) and refuses method = "load"; method = "restart" continues it. [retis] swapfreq is, as for retis, the probability that a move picked in a [0^-] or a [0^+] is the zero swap of its state, and [retis] relative_shoots, when given, has one weight per ensemble, in the order of the directories.

The tis task ¶

The tis task defines a transition interface sampling simulation.

Example Simulation section for task tis (multiple path ensembles):

[simulation]
task = "tis"
steps = 20000
interfaces = [
    -0.9,
    -0.8,
    -0.7,
    -0.6,
    -0.5,
    -0.4,
    -0.3,
    1.0,
]

Example Simulation section for task tis (a single path ensemble):

[simulation]
task = "tis"
steps = 20000
interfaces = [
    -0.9,
    -0.9,
    1.0,
]

[tis]
detect = -0.8
ensemble_number = 1

Keywords for the tis task ¶

For the tis task, the following keywords can be set; ensemble_number, detect and maxlength are keywords of the [tis] section:

Table 4 Keywords for the tis task.¶
Keyword	Description
steps	The total number of steps to perform.
interfaces	The interfaces defining the TIS ensemble.
priority_shooting	Prioritize the ensembles with fewer moves.
ensemble_number	For defining the ensemble number considered.
detect	The interface used for detecting successful paths.
maxlength	The maximum number of steps allowed for a path.

The section TIS sets the moves of this task; an input that leaves it out takes the defaults of its keywords.

Keyword steps ¶

steps = integer

The steps keyword defines the total number of TIS cycles of the simulation: a restart continues it up to this number, so raise it above the cycles done to sample more.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces to use in the path simulation. Three interfaces are the left, middle and right interfaces of one ensemble, which a single TIS simulation samples. Two, or four or more interfaces define the RETIS ensembles [0^-], [0^+], [1^+], … of the interfaces, which are sampled without swaps; pyretis run refuses such an input with ensemble_number, which names one ensemble. For such a run, pyretis analyse with the default [analysis] method (matched) runs the RETIS analysis and writes the RETIS report (retis_report), as for a retis run: the crossing probability of each [i^+] ensemble, the matched crossing probability, the initial flux from the path lengths of the [0^-] and the [0^+], and the rate constant. The run attempts no swaps, so the report gives no swap acceptance ratio (n/a). With method = "wham" it writes wham_analysis.txt, with the point-matching and WHAM crossing probabilities, the initial flux and the point-matching and WHAM rate constants, and with method = "both" it writes the two.

Default: Not any, this keyword must be specified.

Note

Keyword priority_shooting ¶

priority_shooting = boolean

A single TIS run (a tis task with three interfaces), and each input make-tis-files writes, samples one ensemble: priority_shooting takes no effect on it, so leave it out there.

Default: The default value is priority_shooting = false.

Keyword ensemble_number ¶

ensemble_number = integer

A keyword of the [tis] section: the number of the one ensemble a single TIS simulation (a tis task with three interfaces) samples: ensemble_number = 1 names the [0^+], 2 the [1^+] and so on. The number names the ensemble and its directory, and the three interfaces set its window. pyretis run refuses a number below 1: 0 names the [0^-], whose paths start on the right, and a negative number names no ensemble.

A tis input with two, or four or more interfaces and this keyword, as PyRETIS 3 wrote a single TIS input, is read as the one ensemble of that number, and pyretis analyse reads the output in its directory as that ensemble. pyretis run refuses such an input, because it samples every ensemble of those interfaces (interfaces): to sample one [i^+] ensemble, give its three interfaces, as make-tis-files writes them, and sample the [0^-] with task = "retis".

make-tis-files writes the number of each ensemble into the single TIS input it writes for it. The retis, biretis, repptis, pptis and explore tasks sample every ensemble they build from their interfaces, and make-tis-files writes an input for each: these tasks refuse the keyword, which takes no effect on them (see the keywords that take no effect). A value that is not an integer, such as true or 1.0, is refused for every task.

Default: The default value is ensemble_number = 2.

Keyword detect ¶

detect = float

A keyword of the [tis] section: the interface at which the analysis of the one ensemble of a tis run with ensemble_number counts a crossing. Every other path-sampling run, and make-tis-files, refuses the keyword: the analysis of each of its ensembles counts a crossing at the interface after the middle one of the ensemble, and make-tis-files writes that interface into the input of each ensemble.

Default: The last interface of interfaces.

The repptis task ¶

The repptis task defines a replica exchange partial path transition interface sampling simulation. Paths between adjacent pptis ensembles can be swapped using the replica exchange move.

Example Simulation section for task repptis:

[simulation]
task = "repptis"
steps = 20000
interfaces = [
    -0.5,
    -0.3,
    0,
    0.3,
    0.5,
]

Keywords for the repptis task ¶

For the repptis task, the following keywords can be set:

Table 5 Keywords for the repptis task.¶
Keyword	Description
steps	The number of total repptis steps (cycles)
interfaces	The location of the interfaces to consider.
priority_shooting	Prioritize the ensembles with fewer moves.

In addition, this task needs [retis] swapfreq, without which the run stops before its first move; an input that leaves out the section TIS takes the defaults of its keywords.

(RE)PPTIS simulations take almost all of their keywords from the TIS and RETIS sections, because almost all of the keywords are the same. The repptis section carries the one keyword of its own, memory.

Keyword steps ¶

steps = integer

The steps keyword defines the number of REPPTIS cycles to perform. Note that it indicates the goal/final number of the simulation cycles.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces to use in the path simulation.

Default: Not any, this keyword must be specified.

Keyword priority_shooting ¶

priority_shooting = boolean

Default: The default value is priority_shooting = false.

The pptis task ¶

The pptis task defines a partial path transition interface sampling simulation. PPTIS ensembles are shorter than TIS ensembles, cutting the paths’ memory requirements. While for (RE)TIS the paths of [i^+] need to start from state A, cross interface i, and either commit to state B or return to state A, PPTIS paths of [i^+-] only need to start and end at interfaces i-1 or i+1, having crossed interface i.

Example Simulation section for task pptis:

[simulation]
task = "pptis"
steps = 20000
interfaces = [
    -0.5,
    -0.3,
    0,
    0.3,
    0.5,
]

Keywords for the pptis task ¶

For the pptis task, the following keywords can be set:

Table 6 Keywords for the pptis task.¶
Keyword	Description
steps	The total number of steps to perform.
interfaces	The interfaces defining the PPTIS ensemble.
priority_shooting	Prioritize the ensembles with fewer moves.

The section TIS sets the moves of this task; an input that leaves it out takes the defaults of its keywords.

PPTIS simulations take their other keywords from the TIS section. The pptis section carries memory.

Keyword steps ¶

steps = integer

The steps keyword defines the total number of PPTIS cycles of the simulation: a restart continues it up to this number, so raise it above the cycles done to sample more.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces to use in the path simulation. One run samples the ensemble [i^+-] of each interface i between the first and the last, whose paths start and end at the interfaces next to it (with the default memory): N interfaces give N - 2 ensembles, so a pptis task needs three interfaces or more. zero_ensemble adds the [0^+] and, with flux or zero_left, the [0^-].

Default: Not any, this keyword must be specified.

Keyword priority_shooting ¶

priority_shooting = boolean

A pptis task with three interfaces and without zero_ensemble = true samples one ensemble: priority_shooting takes no effect on it, so leave it out there.

Default: The default value is priority_shooting = false.

The explore task ¶

The explore task is a path sampling simulation designed to map the free energy landscape of a transition without computing rates. It is most useful before a production TIS/RETIS run, to locate local minima, check that paths can cross all interfaces, and generate a pool of initial paths to seed those simulations.

During an explore run every generated trajectory longer than two frames is accepted, whether or not it crosses the interfaces of its ensemble, and it is recorded with the status ACC. This means the simulation does not satisfy detailed balance and must not be used to compute crossing probabilities or rate constants.

Two tis-section settings shape an explore run as they shape a tis run:

freq is the probability of a time-reversal move, which reverses the current path and generates no new trajectory. Leave it out, or set freq = 0, to perform no time-reversal moves.
With allowmaxlength = false (the default), the length of each trial path is capped at a length drawn from the length of the path it is shot from, and at maxlength, as in a tis run; with allowmaxlength = true the cap is maxlength. A trial that reaches its cap is cut there, and accepted as well.

PyRETIS 3 set freq = 0 and allowmaxlength = true for every explore run, whatever its input gave; set them to these values to explore as it did.

A short maxlength in the tis section caps every trial path, and so controls how quickly the simulation restarts from a new shooting point and hence how densely the landscape is sampled.

Example Simulation section for task explore:

[simulation]
task = "explore"
steps = 5000
interfaces = [
    -1.9,
    -0.7,
    -0.5,
    0.3,
]

[tis]
freq = 0.0
maxlength = 100
allowmaxlength = true

Keywords for the explore task ¶

For the explore task, the following keywords can be set:

Table 7 Keywords for the explore task.¶
Keyword	Description
steps	The total number of shooting steps to perform.
interfaces	The interfaces defining the exploration region.
maxlength	Maximum path length; shorter values restart the trajectory more often and improve landscape coverage.

The section TIS sets the moves of this task; an input that leaves it out takes the defaults of its keywords.

Keyword steps ¶

steps = integer

The steps keyword defines the total number of cycles of the simulation: a restart continues it up to this number, so raise it above the cycles done to sample more.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces that define the exploration region. The first interface acts as the left boundary and the last interface as the right boundary. The path sampler will attempt to generate trajectories that span this region.

The number of interfaces determines the number of path ensembles created: N interfaces yield N - 1 ensembles, analogous to a TIS setup, so an explore task needs two interfaces or more. A larger number of intermediate interfaces gives finer spatial resolution but requires more initial paths.

Default: Not any, this keyword must be specified.

Note

explore is intended as a preparatory step. Once a satisfactory set of paths has been collected, start the production run (task tis, retis, pptis or repptis) as a new simulation, in a new run directory, with [initial-path] method = “load” and load_and_kick = true: [initial-path] method = "restart" continues the explore run itself, and refuses an input of another task. For each ensemble of the production run, copy the files of an explore path that crosses its middle interface, from <ensemble>/accepted/<path number>/ of the explore run directory, into the subfolder of the load folder that has the name of its ensemble directory (000, 001, …), as starting from the paths of an earlier run describes for each engine (with an internal integrator or TurtleMD, the frame files *.xyz only). For the [0^-], whose middle interface is the first interface, take a path of the [0^+] of the explore run that crosses that interface. Every ensemble needs its subfolder. An ensemble whose frames form no valid path gets a path generated by a kick from the frame nearest its middle interface.

The md-flux task ¶

The md-flux task is a molecular dynamics simulation for determining the initial flux for a TIS path simulation.

Example Simulation section for task md-flux:

[simulation]
task = "md-flux"
steps = 10000000
interfaces = [
    -0.9,
]

Keywords for the md-flux task ¶

For the md-flux task, the following keywords can be specified:

Table 8 Keywords for the md-flux task¶
Keyword	Description
steps	Defines the number of steps to carry out.
interfaces	Defines the interfaces to consider for the flux simulation.

Keyword steps ¶

steps = integer

The steps keyword specifies the step number the simulation ends at: the number of MD steps to perform when it starts at step 0. A simulation that starts at startcycle, or that restarts from a restart file, runs up to this step.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies for which interfaces the initial flux should be obtained. This can be given as a list of floats.

Default: Not any, this keyword must be specified.

The md-nve task ¶

The md-nve task is a NVE molecular dynamics simulation.

Example Simulation section for task md-nve:

[simulation]
task = "md-nve"
steps = 10000000

Keywords for the md-nve task ¶

The following keywords can be specified for the md-nve task:

Table 9 Keywords for the md-nve task¶
Keyword	Description
steps	The number of overall steps to consider for the simulation.

Keyword steps ¶

steps = integer

Default: Not any, this keyword must be specified.

The umbrellawindow task ¶

The umbrellawindow task runs one window of an umbrella sampling simulation as a Monte Carlo walk: each step displaces one particle, chosen at random, by at most maxdx along each dimension, and accepts or rejects the move by the Metropolis rule on the change of the potential energy at the temperature of the [system] section. The input of a new window must set [system] temperature: a run whose input sets none does not start; a window that continues a restart file ([simulation] restart) and leaves it out runs at the temperature of the window it continues. The force field holds the walk in the window: add a RectangularWell potential whose left and right are the two values of umbrella, which the run only records. The window finishes at the first step after mincycle steps at which every coordinate of every particle is above overlap, so the next window can start from that configuration, and several windows joined together cover the whole range. pyretis run writes no trajectory, energy or order file for this task, only the processed input out.toml, the log pyretis.log and the final configuration in the restart file pyretis.restart; the umbrella sampling example runs the windows from Python and builds the histograms of the positions.

potential = [
    { class = "DoubleWell", a = 1.0, b = 2.0, c = 0.0 },
    { class = "RectangularWell", left = -1.0, right = -0.4 },
]

[simulation]
task = "umbrellawindow"
umbrella = [-1.0, -0.4]
overlap = -0.5
maxdx = 0.1
mincycle = 10000

Keywords for the umbrellawindow task ¶

All four keywords have to be set for this task. An md, md-nve or md-flux task takes no effect from them, so leave them out of its input.

Keyword umbrella ¶

umbrella = list of floats

The two values of the window this simulation covers, which the run records in out.toml and in the restart file. It does not hold the walk in the window: a RectangularWell potential with left and right at these values does (see the umbrellawindow task). A path-sampling run refuses it, as it does overlap, maxdx and mincycle: they take no effect on it.

Default: Not any, this keyword must be specified.

Keyword overlap ¶

overlap = float

The window is allowed to finish only when every coordinate of every particle is above this value, after mincycle steps. It is compared with the positions of the particles, not with an order parameter. Set it to the left boundary of the next window, inside this one, so that consecutive windows overlap.

Default: Not any, this keyword must be specified.

Keyword maxdx ¶

maxdx = float

The largest displacement one Monte Carlo trial move may make.

Default: Not any, this keyword must be specified.

Keyword mincycle ¶

mincycle = integer

The number of cycles the window runs before it is allowed to finish.

Default: Not any, this keyword must be specified.

Common keywords ¶

The following keywords are common to the tasks. A path-sampling run (retis, biretis, repptis, tis, pptis, explore) and make-tis-files refuse endcycle, restart and startcycle.

Table 10 Common keywords¶
Keyword	Description
task	Selects the simulation to run.
endcycle	Written by PyRETIS into `out.toml`: the step the run ended at. Leave it out of an input.
exe_path	Written by PyRETIS into `out.toml`: the directory the run ran in. Leave it out of an input.
restart	The restart file an `md`, `md-nve` or `md-flux` task continues from.
seed	The seed of the random numbers of a path-sampling or `umbrellawindow` run, and of the LAMMPS runs of an `md`, `md-nve` or `md-flux` task.
allow_setting_change	Let a restart continue with changed settings.
startcycle	The step number the run starts at.

Keyword task ¶

task = string

Selects the simulation to run. The table of possible values at the top of this page lists the tasks, the keywords each one takes and the sections each one requires.

Default: The default value is "md".

Keyword endcycle ¶

endcycle = integer

The endcycle keyword is the cycle number at which the simulation ended. If the simulation was stopped before the specified number of steps were reached, the endcycle will be different from the steps keyword. PyRETIS sets it, whatever the input gives, and writes it to the processed input file out.toml of an md, md-nve, md-flux or umbrellawindow task, so leave it out of an input. A path-sampling run refuses it, as it does startcycle: it counts its cycles in the [current] section of output.toml.

Default: Not any, note that this keyword will be updated and modified by PyRETIS as part of the output process. This keyword is only used by the analysis program.

Keyword exe_path ¶

exe_path = string

The directory the simulation ran in, which PyRETIS writes into the processed input file out.toml of an md, md-nve, md-flux or umbrellawindow task. pyretis run runs the simulation in its run directory, whatever the input gives, so leave it out of an input.

Default: The directory pyretis run runs in.

Keyword restart ¶

restart = string

The restart keyword names the restart file an md, md-nve or md-flux task continues from: when it is set, the task restarts from that file (see restarting an md task). A path-sampling run reads no restart file: [initial-path] method = "restart" continues it from the output.toml of its run directory, so it refuses this keyword, with a message that names that method.

Default: Not set: the task starts anew. [initial-path] method = "restart" sets it to pyretis.restart.

Keyword startcycle ¶

startcycle = integer

The startcycle keyword specifies the step number an md, md-nve, md-flux or umbrellawindow task starts at; an md, md-nve or md-flux task runs from it up to steps. This can be used, for instance, when extending a simulation to tell PyRETIS that the simulation should start at a specified step number. A path-sampling run refuses it: it counts its cycles in the [current] section of output.toml, and [initial-path] method = "restart" continues it from the cycle it reached.

Default: The default value is 0.

Keyword seed ¶

seed = integer

The seed of the random numbers of a path-sampling run, of an umbrellawindow task and of the LAMMPS runs of an md, md-nve or md-flux task. A path-sampling run draws every random number from streams of numpy’s PCG64 generator spawned from it. The kick initiation ([initial-path] method = "kick", and a loaded path kicked with load_and_kick = true) draws from them the velocities of its kicks and of the shots that repair an initial path, the noise of a Langevin engine and the seeds of the runs of an external engine; the moves draw from them too. Each ensemble kicks with streams of its own, the same whether the ensembles are kicked one after the other or in parallel (kick-parallel = true), so both kicks store the same initial paths where they run the same engine section (an explore run excepted). A run with one worker repeats its paths for the same input and seed, and another seed kicks other initial paths. An umbrellawindow task draws its Monte Carlo moves from it.

A path-sampling run and make-tis-files refuse a [tis] seed other than 0 that differs from seed, a seed of [engine], [engine0] or a numbered engine section that differs from seed, a [retis] seed, and an rgen of [simulation], [retis], [tis], [system] or an engine section other than "pcg64" (see the keywords that take no effect).

An md, md-nve or md-flux task with a LAMMPS engine (class = "lammps_steps") draws the pyretis_seed of each LAMMPS run from a generator seeded with seed, so a stochastic fix of lammps.in draws other random numbers for another seed, and a restart continues the seeds of the run (see the LAMMPS guide). With another engine the task takes no effect from seed: a Langevin engine draws its noise from the seed and rgen of [engine].

Default: The default value is 0.

Keyword allow_setting_change ¶

allow_setting_change = boolean

With true, a continuation with [initial-path] method = "restart" continues although its input changes a setting the restart compares with the run it continues, such as [tis] maxlength, with a WARNING that the samples before and after the restart were not drawn under the same settings: analyse the two stretches separately. It does not lift the checks of the number of ensembles and of the interface positions. See the restart method.

Default: false.

Path sampling keywords ¶

These keywords shape the ensembles a path sampling task samples, and what the analysis reports for them. An md, md-nve, md-flux or umbrellawindow task samples no ensemble: these keywords take no effect on it, so leave them out of its input.

Table 11 Path sampling keywords¶
Keyword	Description
flux	A `pptis` task: build the `[0^-]`, for the flux and the rate.
zero_left	Place the left boundary of the minus ensemble.
zero_ensemble	A `pptis` task or `make-tis-files`: build the `[0^+]`.
permeability	Measure the permeability; set zero_left with it.
zeroswap	Refused: `[retis] swapfreq` sets the swap probability.
pick_scheme	Weight the scheduler’s choice of ensemble.
load_dir	Name the directory initial paths are loaded from.
ensemble_engines	Name the engine sections each ensemble runs with.

Keyword flux ¶

flux = boolean

With zero_ensemble = true, builds the [0^-] ensemble of a pptis task, as zero_left does, and pyretis analyse reports the flux through the first interface and the rate (see zero_ensemble). A retis or repptis task always samples the [0^-] and the [0^+], whose path lengths give the flux, and a biretis task those of each of its two states. A tis task with two, or four or more interfaces samples them as well, and pyretis analyse reports its flux and its rate as for a retis task (interfaces). A single TIS run (a tis task with three interfaces) and an explore task sample no [0^-]. For all of these, and make-tis-files, whose single TIS inputs sample no [0^-], flux takes no effect on the ensembles, and they refuse it, whatever its value (see the keywords that take no effect).

Default: The default value is false for pptis.

Keyword zero_left ¶

zero_left = float

The order-parameter value bounding the [0^-] ensemble on the left: the interfaces of the ensemble then run from this value to the first interface. Without it the ensemble reaches to minus infinity on the left. In a pptis task, setting it, with zero_ensemble = true, builds the [0^-] (see zero_ensemble). A retis or repptis task, and a tis task with two, or four or more interfaces, build the [0^-] in any case, and zero_left bounds it. A single TIS run and an explore task sample no [0^-]: zero_left takes no effect on them, so leave it out there. A make-tis-files task refuses it, and so does a biretis task: its flux is the one of a [0^-] that reaches to minus infinity.

In a run that measures the permeability (permeability), the [0^-] is the [0^-'] ensemble, whose paths start and end at either interface, and the analysis corrects the flux for the paths that end at zero_left (the factor \(\xi\)). In a rate calculation, the [0^-] takes its paths from the first interface only: a trial path that reaches zero_left is rejected (0-L, or BWI when it starts there, as a shooting move’s backward part that reaches it does), and the flux is computed from the paths that turn back before it. Those are the shorter excursions into state A, so the flux comes out too high when many trials reach zero_left; pyretis analyse warns when more than 1 % of the [0^-] trials were rejected there. Place zero_left where the [0^-] paths seldom reach it, or measure the permeability.

Default: No default.

Keyword zero_ensemble ¶

zero_ensemble = boolean

Selects whether a pptis task builds the [0^+] ensemble, and whether make-tis-files writes an input for it. Setting it to false there leaves that ensemble out, and the sampling starts at [1^+]. A retis or repptis task, a tis task with two, or four or more interfaces and an explore task always sample the [0^+], and a biretis task the [0^+] of each of its two states. A single TIS run samples the one ensemble of its three interfaces. For all of these, zero_ensemble takes no effect on the ensembles, and they refuse it, whatever its value.

A pptis task with a [0^-] ensemble (zero_left or flux) needs the [0^+] as well, because the flux combines the two, so such an input without zero_ensemble = true is refused. With zero_ensemble = true it measures the flux and the rate, and a zero_left sets the left interface of its [0^-]. A pptis task without either ensemble reports the crossing probability \(P(\lambda_N \mid \lambda_1)\) of its body ensembles, and no flux or rate.

Default: The default value is false for pptis and make-tis-files; the windows of a pptis task are then all body windows unless this keyword asks for the zero ensemble.

Keyword permeability ¶

permeability = boolean

Measures the permeability in a run with a [0^-] ensemble that zero_left bounds: a retis or repptis task, a tis task with two, or four or more interfaces, or a pptis task with zero_ensemble = true, each with zero_left set. The [0^-] is then the [0^-'] ensemble, whose paths start and end at either of its interfaces, its middle interface is placed midway between zero_left and the first interface, and pyretis analyse also computes \(\xi\), \(\frac{\tau}{dz}\) and the permeability. Set zero_left with it: without it, pyretis analyse of the run stops with an IndexError. A single TIS run, an explore task and a pptis task without a [0^-] sample no [0^-]: permeability takes no effect on them, so leave it out there. A biretis task refuses it.

Default: false.

Keyword zeroswap ¶

zeroswap = float

[retis] swapfreq is the one keyword of the swap probability, so every task refuses [simulation] zeroswap, with a message that names [retis] swapfreq. An earlier PyRETIS took the probability of a swap move from zeroswap, and from [retis] swapfreq when zeroswap was absent. A run file output.toml of such a version that holds zeroswap is therefore read with its value as [retis] swapfreq; a [retis] swapfreq the file holds as well took no effect there, and a warning names both values.

Keyword pick_scheme ¶

pick_scheme = integer

An exponent that weights the choice of the ensemble of each move: the ensembles, in the order of their interfaces, get the weights 1, 2, 3, … raised to the power pick_scheme (an ensemble that a running move holds is skipped), so a positive value biases the choice towards the outer ensembles. It cannot be combined with priority_shooting. A run of one ensemble takes no effect from it, so leave it out there: a single TIS run (a tis task with three interfaces), each input make-tis-files writes, an explore task with two interfaces, and a pptis task with three interfaces and without zero_ensemble = true.

Default: The default value is 0, which leaves the choice unweighted.

Keyword ensemble_engines ¶

ensemble_engines = list of lists of strings

An engine pool: one list of engine sections per interface, as [tis] shooting_moves gives one move per interface. Each list names one engine section, and every move in the ensemble runs its MD with it, e.g. ["engine1"]. The input is refused when it is read if a list names no section or more than one, and the message names the entry. A list names [engine], [engine0] and the numbered engine sections [engine1], [engine2], … of the input, each of which gives a class and the keyword arguments of its engine, as [engine] does. The engine of a section runs with the settings of that section and takes none from [engine]: an internal integrator (Langevin, VelocityVerlet, Verlet) takes timestep and subcycles from its own section, and stores every integration step when the section leaves subcycles out. The input is refused when a list names a section it does not define with a class, when it gives another number of lists than interfaces, and when no list names one of its numbered sections. The kick initiation ([initial-path] method = "kick") generates every initial path with [engine]; with [initial-path] kick-parallel = true it generates the initial path of each ensemble with the engine section of its list. A continuation keeps the engine sections of each ensemble, the class of each engine section other than [engine], and the locked engine settings (timestep, subcycles and gmx_format) of every engine section an ensemble runs with, each compared on the value the engine runs with: the value of the section, or the default of the engine when the section leaves the setting out. It also keeps the temperature each of these engines runs at: the temperature of its section, which the run records for each engine of a pool whose inputs state different temperatures, or else the temperature of the run (see the temperature keyword of the system section). When no ensemble runs with [engine], a continuation keeps its timestep and subcycles only: the analysis converts the path lengths of the run to time with them, and a continuation kicks no path.

Every engine section of the run has one time per step, timestep times subcycles, with subcycles 1 when a section leaves it out: [engine], each section the lists name, and the [engine0] of a quantis run. Under infinite swapping a path held by one ensemble can have been generated by the engine of another ensemble, and a zero swap builds a path from segments of two engines, so the path lengths, counted in steps, convert to time with one time per step only. The engines may differ in every other setting, the split of the time per step into timestep and subcycles among them. A LAMMPS section that leaves timestep out has the time step of its lammps.in (see The time step of LAMMPS). When two sections have different times per step, a path-sampling run is refused when its input is read, before an engine runs, and the message names each section and its time per step. A section whose time per step cannot be read from the input, an OpenMM engine or an engine imported from a module without timestep in its section, is compared with no other section; when no section’s time per step can be read, the run is not refused. The analysis converts the path lengths with the time per step of [engine], the time per step of every section (see the initial flux).

Every run records subcycles_rule = 1 in the [current] provenance of its output.toml. A state file without it was written by a run whose internal integrators all streamed with the subcycles of [engine]. A continuation with [initial-path] method = "restart" compares the subcycles of another section that holds an internal integrator as that value, and its refusal says so; pyretis run -i output.toml of such a state is refused when an internal integrator of another section would stream with other subcycles, and the refusal names the value that resumes as that run streamed, which the section of output.toml can state. For a section with an engine imported from a module whose subcycles is not that value, the comparison is reported as UNKNOWN in a warning.

[simulation]
task = "retis"
interfaces = [0.345, 0.3625, 1.200]
ensemble_engines = [["engine0"], ["engine1"], ["engine2"]]

Default: No default: every ensemble runs with [engine], and the [0^-] ensemble of a quantis run with [engine0].

Keyword load_dir ¶

load_dir = string

Names the per-ensemble directory the initial paths are read from, which is also the name of the store the accepted paths are kept in.

A path staged flat, in <load_dir>/<path number> of the run directory, is input and is only read. A run of a legacy-runner input and a scheduler run started from the Python interface (pyretis.bin.pyretisrun.run_infinite_swapping()) read staged paths; pyretis run of an input with [simulation] task refuses them, as said below. When at least one initial path is staged there, such a fresh run reads every initial path from these directories and keeps a copy of each in the per-ensemble store, <ensemble>/<load_dir>/<path number>. The copy holds files of its own, written byte for byte, and the run reads the frames of the path from it; the order values a load evaluates are written into the copy. The copy takes as much disk space as the staged files, and the log line of each copy gives its size in bytes. Rewriting a staged file afterwards, in place or under a new name, leaves the copy as it was. The copy holds the files of the staged directory and of its accepted/ subdirectory, so a staged traj.txt that names a frame file anywhere else stops the run with a ValueError before the load copies anything. A restart reads the path from the copy, as does a run resumed from the output.toml written before its first cycle completed. Such a fresh run stops before it reads or writes anything, and names the directories, when an initial path has no staged directory, or when the run directory holds, left by an earlier run: a directory of the per-ensemble store for one of the initial paths, or a pathensemble.txt in one of its ensemble directories.

With no initial path staged flat, a fresh run reads its initial paths from the per-ensemble store: the paths pyretis run generates there from [initial-path], the paths the interface optimizer seeds there for each of its steps, and paths a user places there. The run reads these paths in place: their directories become the run’s own, the order values the load evaluates are written into their order.txt, and the run may move one it has replaced to <ensemble>/archive/<path number> or remove it. pyretis run stops before its initiation when the run directory holds a staged initial path, or a directory of the per-ensemble store for one of its initial paths. A run of a legacy-runner input runs no engine before its load. It stops before it starts when the run directory holds the state file of a simulation, an output.toml or 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, and a state file of an earlier PyRETIS, with a [simulation.tis_set] table, is continued by a canonical input of the run with method = “restart”. The run of a legacy-runner input records the canonical form of the input in output.toml of the run directory, and stops as well when its input file is that output.toml; rename such an input file. The interface optimizer stops before its first step when a step directory of the run holds any file. Every fresh run other than one started by pyretis run stops before its load when one of its ensemble directories holds a pathensemble.txt, with data rows (see the restart method) or with the header alone, which the scheduler writes once the load of a run has read its initial paths; it names those directories. pyretis run stops before its initiation when a pathensemble.txt holds data rows, and writes a pathensemble.txt with the header alone afresh.

A load, a restart included, reads the energies of a path from the energy.txt beside its traj.txt, one row per frame. An energy.txt with another number of rows stops the run with a ValueError that names the file; remove it, or replace it with the energies of the path. Without energy.txt, the internal integrators recompute the energies of the frames from the stored frames, OpenMM computes the potential and the kinetic energy of each frame from the stored frame, in kJ/mol as the frames of its MD record them, and the energies of the other engines are written as nan.

The paths an earlier run left in the per-ensemble store before its load wrote the ensemble output are laid out as the paths a user places there: pyretis run leaves the paths it generated there when it stops between its initiation and its load. With no output.toml of that run in the run directory, a fresh run of a legacy-runner input, or a scheduler run started from the Python interface (pyretis.bin.pyretisrun.run_infinite_swapping()), with no path staged flat reads them as its initial paths. Remove those directories, or use a new run directory, before such a run. pyretis tools clean leaves the flat store <load_dir> that a TOML input names in place.

Default: The default value is "accepted".