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, retis
tis	A transition interface sampling simulation.	task, steps, interfaces, ensemble_number, detect	tis
repptis	A replica exchange partial path transition interface sampling simulation.	task, steps, interfaces	tis
pptis	A partial path transition interface sampling simulation.	task, steps, interfaces	tis
explore	A free energy surface exploration simulation.	task, steps, interfaces	tis
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 make-tis-files writes the input files for single TIS simulations and exits, both taking task and steps. 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.

In addition, this task requires that the sections TIS and RETIS are defined.

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 — use load or flexible_restart to change the interface set.

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 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:

Table 3 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.
maxlegth	The maximum number of step allowed for a paths.

In addition, this task requires that the section TIS is defined.

Keyword steps

steps = integer

The steps keyword defines the number of TIS cycles to perform.

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

interfaces is topology-defining: it is locked once the simulation is started. A restart that supplies a different list aborts with a ValueError — use load or flexible_restart to change the interface set.

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.

Keyword ensemble_number

ensemble_number = integer

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, 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

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

Not any.

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 4 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 requires that the sections TIS and RETIS are defined.

(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

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

In addition, this task requires that the section TIS is defined.

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

Keyword steps

steps = integer

The steps keyword defines the number of PPTIS cycles to perform.

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. If the number of interfaces given is 3 or less, a single PPTIS simulation will be performed, otherwise, input files for several single PPTIS simulations will be written. These simulations can then be run manually.

Default

Not any, this keyword must be specified.

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 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 is accepted unconditionally (path status EXP). 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 are overridden automatically regardless of what the input file specifies:

• freq is forced to 0 — only shooting moves are performed, no time-reversal moves.

• allowmaxlength is forced to True — paths that reach maxlegth are treated as valid and accepted.

Setting a short maxlength in the tis section therefore 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.5
maxlength = 100
allowmaxlength = false

Note

freq and allowmaxlength in the tis section are shown here for completeness but are ignored at run time — explore always sets them to 0 and True respectively.

Keywords for the explore task

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

Table 6 Keywords for the explore task.

Keyword	Description
steps	The total number of shooting steps to perform.
interfaces	The interfaces defining the exploration region.
maxlegth	Maximum path length; shorter values restart the trajectory more often and improve landscape coverage.

In addition, this task requires that the section TIS is defined.

Keyword steps

steps = integer

The steps keyword defines the number of shooting cycles to perform.

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, switch task to tis, retis, pptis, or repptis and restart from the saved paths to begin a production run. See the initial-path section for how to load frames from a previous explore run.

See also

The explorer example test in examples-from-tests demonstrates a complete explore run on the 1D double-well potential.

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 7 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 number of MD steps to perform.

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 8 Keywords for the md-nve task

Keyword	Description
steps	The number of overall steps to consider for the simulation.

Keyword steps

steps = integer

The steps keyword specifies the number of MD steps to perform.

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. umbrella gives the window it covers and maxdx bounds a single trial move. The window finishes once it has run mincycle cycles and every particle has passed overlap, so several windows joined together cover the whole order-parameter range.

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

Keyword umbrella

umbrella = list of floats

The two order-parameter values of the window this simulation covers. It is recorded with the simulation and written to the restart file. 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

Every particle has to pass this order-parameter value before the window is allowed to finish, which is what makes 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 all simulation tasks:

Table 9 Common keywords

Keyword	Description
task	Selects the simulation to run.
endcycle	Specifies the cycle step the simulation ended.
exe_path	Specifies the directory from where the simulation was executed.
restart	Specifies the restart file to use.
startcycle	Specifies the cycle step the simulation should start 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 specifies 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 difference from the steps keyword. This keyword will be set and updated by PyRETIS and written to the processed input file of an in-process task. A path-sampling run refuses it, as it does startcycle: the scheduler counts the cycles of a run in the [current] state 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 exe_path keyword specifies the location from where the simulation was executed. This will be set and updated by PyRETIS.

Default

Not any, note that this keyword will be updated and modified by PyRETIS as part of the output process. This keyword does not need to be set in the input file by the user since PyRETIS will update this setting automatically.

Keyword restart

restart = string

The restart keyword specifies the path to the restart file of an in-process task (md, …) to use for restarting/continuing it. To be used, it requires that method keyword in the initial-path section is set to restart. 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

The default value is pyretis.restart.

Keyword startcycle

startcycle = integer

The startcycle keyword specifies the cycle number the simulation starts at. 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: the scheduler counts the cycles of a run in the [current] state of output.toml.

Default

The default value is 0.

Path sampling keywords

These keywords shape the ensembles a path sampling task samples, and what the analysis reports for them.

Table 10 Path sampling keywords

Keyword	Description
flux	Sample the initial flux.
zero_left	Place the left boundary of the minus ensemble.
zero_ensemble	Select whether the plus-zero ensemble is built.
permeability	Report the permeability.
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

Builds the [0^-] ensemble of a pptis task, as zero_left does, and pyretis analyse reports the flux through the first interface. A retis or repptis task always samples the [0^-] and the [0^+], whose path lengths give the flux. 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 builds the [0^-]. 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^-], and zero_left has no effect there. A make-tis-files task refuses it.

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^+]. 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

Reports the permeability: pyretis analyse also computes \(\xi\), \(\frac{\tau}{dz}\) and the permeability, and the middle interface of the [0^-] ensemble is placed midway between zero_left and the first interface.

Default

No default.

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. A run file output.toml of an earlier PyRETIS that holds it is read with its value as [retis] swapfreq, which it won over.

Keyword pick_scheme

pick_scheme = integer

An exponent applied to the ensemble weights when the scheduler picks which ensemble to move next, which biases the choice towards the outer ensembles. It cannot be combined with priority_shooting.

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. The scheduler runs the MD of each ensemble with the engines of its list, and a shooting or wire-fencing move with the first one. 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. [engine] is the engine the in-process kick initiation generates every initial path with; the parallel kick phase ([initial-path] kick-parallel = true) generates the initial path of each ensemble with the first engine 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, temperature 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. 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 timestep of its lammps.in. When two sections have different times per step, the 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"], ["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. When at least one initial path is staged there, 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, a pathensemble.txt in one of its ensemble directories, or the CP2K wavefunction store pyretis-cp2k-wfn.

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, a directory of the per-ensemble store for one of its initial paths, or a pyretis-cp2k-wfn. 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, or a pyretis-cp2k-wfn. 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 and a pyretis-cp2k-wfn beside them. 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.

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. A scheduler run started from the Python interface may follow an initiation run from Python in the same directory, and starts its CP2K SCF from a pyretis-cp2k-wfn it finds there. 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".