The TIS section¶

The TIS section defines settings for (PP)TIS and (PP)RETIS simulations. An md, md-nve or md-flux task takes no effect from it, and refuses an rgen that names no generator (see the keywords that take no effect), so leave it out of the input of an md task. Every task refuses [tis] relative_shoots: set [retis] relative_shoots instead.

Example TIS section:

[tis]
allowmaxlength = false
freq = 0.5
high_accept = true
maxlength = 20000
n_jumps = 8
rescale_energy = false
shooting_moves = ["sh", "sh", "ss", "ss"]
sigma_v = -1
zero_momentum = false

The example is for a tis or retis run of four interfaces: shooting_moves gives one move per interface, and a pptis or repptis run refuses the "ss" moves. shooting_move sets one move for every ensemble instead.

Keywords for the TIS section¶

The following keywords can be set for the TIS section:

Table 35 Keywords for the TIS section, commonly set¶
Keyword	Description
allowmaxlength	Select whether shooting moves may use the full `maxlength` cap directly.
freq	Define how often time reversal moves are performed.
high_accept	Set the Stone Skipping version to use.
maxlength	Set the maximum length of the paths generated.
n_jumps	Set the number of jumps for SS, WT and WF moves.
rgen	Refused unless `"pcg64"`: the run draws from `[simulation] seed`.
seed	Refused unless 0 or `[simulation] seed`, which seeds the kicks and the moves.
rescale_energy	Selects re-scaling of velocities.
shooting_moves	Set the MC shooting moves in each ensemble.
sigma_v	Set the velocity-perturbation width, or select aimless shooting when negative.
zero_momentum	Specify whether momentum should be set to zero after each velocity draw.

The remaining keywords of the section tune a particular move, the initiation or the infinite-swapping scheduler:

Table 36 Keywords for the TIS section, tuning¶
Keyword	Description
enforce_must_cross_m	Require a trial to cross the middle interface in a pptis or repptis run.
interface_sour	Sets the position of SOUR for Web Throwing.
mwf_subcycle_small	Set the subcycle count the intermediate mwf sub-paths are shot with.
mwf_subcycle_small_by_ensemble	Override mwf_subcycle_small for named ensembles.
mwf_nsubpath	Set how many sub-paths one mwf set holds.
shooting_move	Set one MC shooting move for every ensemble.
aimless	Deprecated; the sign of sigma_v selects aimless shooting.
kick_maxtries	Bound the kicks the kick initiation spends searching for a crossing.
initial_path_maxtries	Bound the attempts spent generating an initial path.
initial_path_fix_maxtries	Bound the attempts spent repairing an initial path.
mirror_freq	Set how often the mirror move is performed.
target_freq	Set how often the target swap move is performed.
target_indices	List the order-parameter indices a target swap may switch to.
perm_threshold	Set the largest block the permanent is computed exactly for.
perm_n_samples	Set the sample count of the stochastic permanent.
exact_perm_only	Require the exact permanent.
quantis	Run the \([0^-]\) ensemble with `[engine0]` and test its swaps on the energies of both engines.
accept_all	Skip the Metropolis acceptance of the quantis move.
interface_cap	Set the cap value for subpaths generated by the WF move.

Keyword allowmaxlength¶

allowmaxlength = boolean

Controls the length cap used when generating trial paths with shooting moves. If True, the trial path may use the full value given by keyword maxlength as its hard cap. If False, PyRETIS first draws a stochastic cap based on the length of the current path and then also limits it by maxlength.

This keyword does not force all paths to have the same length. The propagation still stops when the path reaches the required interface, so paths may be shorter than maxlength. The False setting is the default for regular path sampling because the random cap is part of the detailed-balance treatment for variable-length shooting paths. The kick initiation, the subpaths of wire fencing (wf, mwf) and the biased move (bias) use the full maxlength cap, whatever this keyword says.

Default: The default is allowmaxlength = false.

Keyword freq¶

freq = float

This defines how often time reversal moves are performed: E.g. if freq = 0.4 then 40% of the moves picked in an ensemble, other than swaps, are time reversals, and the others use the shooting move of the ensemble. In a retis run, a move picked in the \([0^-]\) or the \([0^+]\) ensemble is first, with the probability swapfreq, the swap of the two ensembles, so the percentage of shooting moves among the moves picked in these two ensembles is \((1 - swapfreq) \times (1 - freq)\), and \(1 - freq\) in the other ensembles. In a repptis run, a move picked in any ensemble is first, with that probability, a swap with an adjacent ensemble, so the percentage is \((1 - swapfreq) \times (1 - freq)\) in every ensemble. With several workers, a swap is not made while another worker moves the other ensemble, and the move is then made in the picked ensemble alone.

Default: The default is freq = 0: no time reversal moves.

Keyword interface_sour¶

interface_sour = float

This defines the position of the SOUR interface for Web Throwing. It HAS to be smaller then the interface defining the ensemble where WT is used. Note that an improper selection of interface_sour will hinder the sampling efficiency.

Default: No default, this keyword must be specified if WT is used.

Keyword high_accept¶

high_accept = boolean

Selects the acceptance rule of stone skipping (ss). With high_accept = true a trial path is accepted and carries a weight, which the swaps and the analysis apply (the HA-weight column of pathensemble.txt); with high_accept = false stone skipping uses Metropolis acceptance on the crossing count. High acceptance is the more efficient of the two. The keyword takes effect only in the ensembles that use stone skipping: wire fencing (wf) always uses high acceptance, web throwing (wt) has its own acceptance on the ratio of the segments, and the other moves do not use it. A run without an ss move takes no effect from it and does not refuse it: leave it out of such an input. Note that the current implementation, due to detailed balance, DOES NOT ALLOW to have multiple shooting methods in the same ensemble.

The same keyword and default apply to the deprecated legacy-runner schema, as high_accept in [simulation.tis_set], which its conversion to the canonical schema places in [tis]. A run records the value it samples with in the [tis] section of its output.toml; a resumed run keeps it.

Default: The default is high_accept = true.

Keyword quantis¶

quantis = boolean

Selects the quantis move: the \([0^-]\) ensemble propagates with the engine of an [engine0] section (same keys as [engine]) and the other ensembles with [engine], and a swap of the \([0^-]\) and \([0^+]\) paths is accepted with a Metropolis test on the energies the two engines give (see accept_all). The keyword takes effect on a run with a \([0^-]\) ensemble: a retis or repptis run, a tis run with two, or four or more interfaces (which makes no swap), and a pptis run with a \([0^-]\) ensemble (flux or zero_left). A single TIS run (a tis run with three interfaces), an explore run and a pptis run without a \([0^-]\) ensemble take no effect from it and do not refuse it, nor the [engine0] section: leave both out of such an input. The energy test weighs the energies of each engine with the inverse temperature \(1/(k_B T)\) that the engine runs at, in the energy unit of the engine: Velocity Verlet, Langevin, TurtleMD and ASE at [system] temperature, and the other engines at the temperature of their own input. Any of these engines can be [engine] or [engine0]. An engine that gives no temperature to weigh with, such as AMS, stops the run at the first swap whose two paths carry energies, with an error that names the engine. [engine0] has the time per step of [engine], timestep times subcycles, and a run whose two sections differ is refused before it starts (see the engine section).

Default: The default is quantis = false.

Keyword accept_all¶

accept_all = boolean

With quantis = true, accept every swap of the \([0^-]\) and \([0^+]\) paths without the Metropolis test on the energies of [engine0] and [engine]. The test accepts every swap anyway when the two engines give the same energies; when they differ, accepting every swap breaks the detailed balance of the swap. Without quantis = true the keyword takes no effect, and a run does not refuse it: leave it out of such an input.

Default: The default is accept_all = false.

Keyword maxlength¶

maxlength = integer

This determines the maximum length of the paths generated. Ideally, no paths should be longer than this value. A value too restrictive can invalidate detailed balance.

A path may hold maxlength frames: a trajectory that crosses an interface on its last allowed frame is complete, and one that has not crossed by then is rejected (BTX or FTX). The shooting and swap moves build their paths under this ceiling, and loading or restarting admits paths of at most maxlength frames.

Default: The default is maxlength = 20000, a deliberately generous cap so that an input which does not mention path lengths still samples correctly. Because a cap that is too small biases the sampling, a run that falls back to this default says so in its log, and the value it used is recorded in the [tis] section of the run file output.toml. Set it explicitly for systems whose paths are expected to be long.

Keyword n_jumps¶

n_jumps = integer

The number of jumps for Stone Skipping, Wire Fencing and of web for Web Throwing.

Default: No default for Stone Skipping and Web Throwing: this keyword must be specified if either is used, and an input that uses them without it is refused. Wire Fencing and Multiresolution Wire Fencing take 2 when the keyword is not set, which the run record output.toml of such a run writes as n_jumps = 2.

Keyword rgen¶

rgen = string

A path-sampling run draws every random number from streams of numpy’s PCG64 generator spawned from [simulation] seed: the kicks of the kick initiation, one ensemble after the other or in parallel, and the moves. A path-sampling run and make-tis-files therefore refuse a value other than "pcg64" (see the keywords that take no effect).

Default: The default is rgen = "pcg64".

Keyword rescale_energy¶

rescale_energy = float or false

If this keyword is set to a positive number, then the velocities are re-scaled so that the total energy is equal to the given number. This is useful for performing NVE simulations. If the keyword is set to False, or to a number that is not positive, then the energies will not be re-scaled. True names no energy and stops the run with an error.

Every shooting move re-scales the velocities it draws: the shooting moves of every ensemble, including the shots of wire fencing and biased shooting and the one-step jumps of stone skipping, and the shots of the initiation. The internal integrators and OpenMM also re-scale each kick of the search for a crossing with the middle interface in the initiation; the kicks of the other engines keep the energy they are drawn with.

The internal integrators, OpenMM and cp2k_steps re-scale in PyRETIS; cp2k_steps needs the potential energy of the shooting point and stops with an error for a point that does not carry one. lammps_steps with velocity_generation = engine re-scales in LAMMPS, which evaluates the energy as its thermo keywords pe and ke do: per atom under thermo_modify norm yes, the LAMMPS default for lj units. GROMACS, AMS, TurtleMD, ASE, the streaming cp2k and lammps engines, and lammps_steps with velocity_generation = maxwell do not re-scale: a positive value stops the run with an error at the first shooting move, before any velocities are drawn.

A shooting point whose potential energy is above rescale_energy cannot be re-scaled to it: the internal integrators, OpenMM, cp2k_steps and lammps_steps log a WARNING and keep the energy of the draw. lammps_steps compares the pe of LAMMPS with rescale_energy in LAMMPS, and PyRETIS reads the outcome back from the generate_vel log of the engine.

A continuation with method = “restart” is refused when it re-scales the shooting velocities differently from the run it continues; see the draws a restart compares.

Default: The default value is rescale_energy = false.

Keyword seed¶

seed = integer

The kicks of the kick initiation and the moves of a path-sampling run, among them the choice of the shooting point, draw from [simulation] seed. A path-sampling run and make-tis-files accept [tis] seed = 0 and a value equal to [simulation] seed, and refuse any other value with a message that names [simulation] seed. To kick other initial paths and sample other moves, change [simulation] seed. In an input of PyRETIS 3 that seeds its run with [tis] seed, set [simulation] seed to that value.

Default: The default is seed = 0.

Keyword shooting_moves¶

shooting_moves = list of strings

This list contains the flags that determines the shooting move to be used for each ensemble. Usable moves are 'sh' for shooting, 'ss' for Stone Skipping, 'wt' for Web Throwing, 'wf' for Wire Fencing, 'mwf' for Multiresolution Wire Fencing, which shoots the intermediate wire-fencing sub-paths at a reduced subcycle count set by mwf_subcycle_small, and 'bias' for biased shooting-point selection. See Move types for the full list of move type codes and their descriptions.

The list holds one move per interface, and a list of another length is refused: a run of four interfaces takes four moves. In a run with a \([0^-]\) ensemble, the moves go to the ensembles in the order of the interfaces, the \([0^-]\) ensemble first. Without the list, every ensemble uses shooting_move.

A partial-path task (task = "pptis" or task = "repptis") refuses the subtrajectory moves 'ss', 'wt', 'wf' and 'mwf'. Those moves build one complete path out of subpaths and weight it as a complete path. PPTIS and REPPTIS sample partial paths, each carrying weight 1, and rebuild the kinetics from the local crossing probabilities. Use 'sh' for a partial-path task.

Default: The default value is []: every ensemble uses shooting_move.

Keyword enforce_must_cross_m¶

enforce_must_cross_m = boolean

Requires a trial path in the \([0^+]\) and the body ensembles of a pptis or repptis run to cross the middle interface of its ensemble, as the definition of these partial-path ensembles asks. enforce_must_cross_m = false accepts a trial in those ensembles without the middle crossing. The keyword takes no effect on a retis, tis or explore run, and such a run does not refuse it: leave it out of their inputs.

Default: The default value is true.

Keyword mwf_subcycle_small¶

mwf_subcycle_small = integer

The number of engine subcycles the intermediate sub-paths of the Multiresolution Wire Fencing move are shot with. The final sub-path of each set uses the engine’s own subcycles. It has to be a positive integer: another value is replaced by the default.

Default: One fifth of the engine’s subcycles, and at least 1.

Keyword mwf_subcycle_small_by_ensemble¶

mwf_subcycle_small_by_ensemble = dictionary

Maps the name of an ensemble, the name of its directory ("001", "002", …), to the subcycle count to use for that ensemble, taking precedence over mwf_subcycle_small there, e.g. mwf_subcycle_small_by_ensemble = { "002" = 1, "003" = 2 }. An ensemble the dictionary does not name keeps mwf_subcycle_small, and so does an ensemble given a count that is not a positive integer.

Default: No default.

Keyword mwf_nsubpath¶

mwf_nsubpath = integer

The number of sub-paths one Multiresolution Wire Fencing set holds. The number of sets is n_jumps.

Default: The default value is 3.

Keyword shooting_move¶

shooting_move = string

Sets the shooting move used in every ensemble, taking the move codes of shooting_moves. A per-ensemble shooting_moves list takes precedence over this keyword.

Default: The default value is "sh".

Keyword aimless¶

aimless = boolean

Deprecated. The sign of sigma_v selects aimless shooting in every engine; an aimless line is removed from the settings, with a notice when it agrees with sigma_v and a warning when it disagrees.

Default: No default.

Keyword kick_maxtries¶

kick_maxtries = integer

Bounds the number of kicks the kick initiation spends searching for a crossing with the middle interface of an ensemble: each kick draws new velocities and advances the system. When the search finds no crossing within the bound, the run stops with an error that names this keyword.

Default: The default value is 100000.

Keyword initial_path_maxtries¶

initial_path_maxtries = integer

Bounds the number of attempts the kick initiation may spend generating an initial path.

Default: The default value is 1000.

Keyword initial_path_fix_maxtries¶

initial_path_fix_maxtries = integer

Bounds the number of attempts the kick initiation may spend repairing an initial path. A kicked 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. A repair that reaches the bound stops the run with Could not fix the initial path for ensemble.

Default: The default value is 1000.

Keyword mirror_freq¶

mirror_freq = float

Sets how often the mirror move (mr) is performed. A run that uses it requires workers = 1. An accepted mirror move changes which side of the mirror the order parameter measures, and the path it produces carries that state into every ensemble it is swapped to.

Default: The default value is 0, which does not use the move.

Keyword target_freq¶

target_freq = float

Sets how often the target swap move (ts) is performed. A run that uses it requires workers = 1. An accepted target swap changes which molecule the order parameter tracks, and the path it produces carries that state into every ensemble it is swapped to.

Default: The default value is 0, which does not use the move.

Keyword target_indices¶

target_indices = list of integers

The order-parameter target indices the target swap move may switch the order function to. The index the run starts from has to appear in this list.

Default: The default value is [].

Keyword perm_threshold¶

perm_threshold = integer

The largest ensemble block the infinite-swapping permanent is computed exactly for. A larger block is approximated stochastically, with perm_n_samples samples.

Default: The default value is 12.

Keyword perm_n_samples¶

perm_n_samples = integer

The number of samples the stochastic permanent approximation draws for a block larger than perm_threshold.

Default: The default value is 10000.

Keyword exact_perm_only¶

exact_perm_only = boolean

Requires the exact permanent: a block larger than perm_threshold stops the run with an error instead of being approximated stochastically.

Default: The default value is false.

Keyword interface_cap¶

interface_cap = float

This defines the position of the cap interface for Wire Fencing. It HAS to be larger than the interface defining the ensemble where WF is used. Note that an inproper selection of interface_cap can hinder the sampling efficiency.

Default: Without the keyword, wire fencing caps its subpaths at the right interface of its ensemble, the last interface of the run.

Keyword sigma_v¶

sigma_v = float

Controls whether shooting is aimless and, for non-aimless shooting, sets the width of the velocity perturbation. If sigma_v is negative, PyRETIS uses aimless shooting: new velocities are drawn from the Maxwellian distribution using the system temperature and masses. The default sigma_v = -1 therefore selects aimless shooting.

If sigma_v is zero or positive, PyRETIS uses non-aimless shooting: Gaussian increments with the standard deviation sigma_v are added to the current velocities, the same for every particle in every dimension, whatever its mass. These momentum changes are then accepted or rejected with the Metropolis criterion on the change of the kinetic energy (a rejection is MCR in moves.txt). PyRETIS 3 multiplied sigma_v by sqrt(inverse mass) for each particle, so with masses other than 1 the same sigma_v gives other increments than in PyRETIS 3.

The internal integrators, OpenMM and cp2k_steps draw both kinds of shooting. GROMACS, LAMMPS, AMS, TurtleMD, ASE and the streaming cp2k engine draw the velocities of aimless shooting only: with a zero or positive sigma_v a shooting move stops the run with an error before any velocities are drawn. OpenMM stops in the same way for a System with constraints: the Metropolis criterion uses the kinetic energy of every velocity component, including the components along the constraints that the integrator removes, and this breaks detailed balance for the Maxwellian distribution of the constrained velocities. An engine of your own (see user-defined engines) built on an internal integrator draws both kinds as the internal integrators do; one built on GROMACS, LAMMPS, CP2K, OpenMM, AMS, TurtleMD or ASE draws as that engine does; one built on EngineBase or ExternalMDEngine stops the run at its first soft perturbation, with a message that asks for aimless shooting, unless it has a beta attribute, which the criterion takes as the inverse temperature, in the energy unit of the kinetic energies its modify_velocities returns. The internal integrators evaluate the criterion at the inverse temperature of the system, from [system] temperature; OpenMM and cp2k_steps at the one of the engine, from the temperature their input states and the Boltzmann constant of the engine (see the temperature keyword of the system section). OpenMM evaluates the criterion with the kinetic energy in kJ/mol and the inverse temperature in mol/kJ, and cp2k_steps in hartree and 1/hartree.

Default: The default value is sigma_v = -1.

Keyword zero_momentum¶

zero_momentum = boolean

If this keyword is set to True, then the linear momentum of the system is set to zero after random velocities are drawn: for a shooting move (including the shots of wire fencing and the one-step jumps of stone skipping), and for every kick of the search for a crossing with the middle interface in the initiation. If False, the drawn velocities are used as drawn. The keyword has this meaning in every engine. Where the MD program draws the velocities itself, the setting is handed to it or checked against it:

LAMMPS with class = lammps_steps and velocity_generation = engine draws with velocity create, whose mom keyword PyRETIS writes from it: mom yes for True and mom no for False. With class = lammps, PyRETIS draws the velocities in both velocity_generation modes and resets the momentum as this keyword selects.
GROMACS with velocity_generation = engine draws with gen_vel, which removes the centre-of-mass motion, so it requires zero_momentum = true.
AMS draws the velocities with GenerateVelocities, and PyRETIS uses them as drawn. With RandomVelocitiesMethod = Gromacs and Exact, the AMS default, the draws have zero net linear momentum (for Boltzmann this is not checked), so it requires zero_momentum = true.
OpenMM with a CMMotionRemover in its System (createSystem adds one by default) sets the centre-of-mass velocity to zero while it integrates, so a re-scaled draw (rescale_energy > 0) or a soft perturbation (sigma_v >= 0) requires zero_momentum = true: the energy of the draw is then the energy the run keeps.

GROMACS with velocity_generation = engine, AMS, and the OpenMM draws above stop the run with an error before the first velocity draw for zero_momentum = false.

The paths the ensembles hold were shot with velocities drawn under this keyword. A continuation with method = “restart” is refused when its shooting velocities are drawn from another distribution than those of the run it continues, and pyretis run -i output.toml is refused for an output.toml that does not record its draws when the settings it records draw differently from the engine of that run; see the draws a restart compares.

Default: The default value is zero_momentum = false.

Biased shooting-point selection¶

The standard shooting move picks the shooting point uniformly among the interior frames of the current path. Setting shooting_move = "bias" (or listing 'bias' for an ensemble in shooting_moves) instead picks it non-uniformly, biased toward “interesting” frames – for example near the barrier top – which can reduce the number of MD steps needed to converge a rate.

Crucially, biased selection does not change the sampled path ensemble: the crossing probability and the rate are statistically identical to the uniform move. Only the sampling efficiency changes. This is guaranteed by an exact acceptance correction.

How it works¶

A selector assigns a strictly positive weight \(w(x)\) to each interior frame. The shooting point is drawn with probability \(w_i / W\), where \(W = \sum_j w_j\) is the sum over the interior frames of the current path. The trial path is then integrated to completion (up to maxlength; the stochastic length cap of the uniform move is not used), and a valid trial path is accepted with the Metropolis probability

\[P_\mathrm{acc} = \min\!\left(1, \frac{W_\mathrm{old}}{W_\mathrm{new}}\right),\]

where \(W_\mathrm{old}\) and \(W_\mathrm{new}\) are the interior weight sums of the old and the trial path. The weight of the shooting point itself cancels, because it is the same physical frame shared by both paths. With constant weights this reduces to the standard flexible-length two-way-shooting acceptance, so the scheme is correct by construction. A valid trial path rejected by this test is recorded with the status code SAR (selection-bias acceptance rejection).

The 'exp' shooting move of PyRETIS 3, a heuristic without this correction, does not run outside an explore run: use 'bias'.

Restrictions¶

Aimless only. Biased shooting requires aimless velocities (sigma_v < 0, the default), so that \(\min(1, W_\mathrm{old}/W_\mathrm{new})\) is the sole acceptance correction. A non-negative sigma_v is rejected at set-up time.
It biases the per-ensemble shooting move; swapping moves are unaffected.

Where it runs¶

Biased shooting is selected in the same way for every path-sampling task (tis, retis, pptis and repptis), and because the move preserves the path ensemble, the analysis of the crossing probability and the rate is the one of the standard move. Per-ensemble moves are set with shooting_moves, one move per interface, e.g. shooting_moves = ["sh", "sh", "bias", "bias"] for four interfaces, which keeps the standard move in the \([0^-]\) and \([0^+]\) ensembles, as the validation runs in examples/validation/methods do.

A single [shooting-selector] section is shared by every biased ensemble.

The `[shooting-selector]` section¶

When shooting_move = "bias" is used, a shooting-selector section selects and parameterises the weight function. Like the engine and orderparameter sections it accepts either a built-in class or a user module/class pair (see extending PyRETIS for writing your own).

Built-in selectors:

class = "gaussian" – \(w(x) = \exp\!\big(-\alpha\,(\lambda(x) - \lambda_0)^2\big)\), a bias toward the order-parameter value lambda0 with sharpness alpha.
class = "uniform" – constant weights; reproduces the standard uniform move through the explicit-acceptance scheme (useful as a reference/validation).

Example (TOML):

[tis]
shooting_move = "bias"
sigma_v = -1            # must be < 0 (aimless)

[shooting-selector]
class = "gaussian"
alpha = 50.0
lambda0 = 0.0           # order-parameter value to bias toward