The TIS section¶

The TIS section defines settings for (PP)TIS and (PP)RETIS simulations.

Example TIS section:

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

Keywords for the TIS section¶

The following keywords can be set for the TIS section:

Table 34 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	Set the random number generator to use.
seed	Set a seed for the random number generator.
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 35 Keywords for the TIS section, tuning¶
Keyword	Description
enforce_must_cross_m	Require a trial to cross the middle interface in the ensembles that define one.
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 MD advances one kick may spend.
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	Select the scheduler’s quantis zero-ensemble move.
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. During some initialization and sub-path steps, PyRETIS may set this option internally to True.

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 TIS moves are time reversal. Note that if you are running a RETIS simulation, then the percentage of TIS moves will be modified by the percentage of swapping moves, e.g. the percentage of shooting moves will then be given by \((1 - swapfreq) \times (1 - freq)\).

Default: No default, this keyword must be specified.

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. Wire fencing (wf) always uses high acceptance and does not read this keyword; web throwing (wt) keeps its own segment-ratio acceptance, and standard shooting (sh) never reads it. 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 infinite-swapping scheduler’s “quantis” zero-ensemble move: the [0^-]/[0^+] pair propagates from an independently configured [engine0] section (same keys as [engine]) instead of the default [engine]. Only meaningful for a scheduler-routed run; a no-op otherwise. An [engine0] section in a run in which no ensemble runs it is refused. [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

When quantis is set, skip the energy-based Metropolis acceptance rule for the resulting zero swap and accept it unconditionally. Only meaningful together with quantis; a no-op otherwise.

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 resolved settings file the run writes. 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

The random number generator the in-process kick initiation draws the velocities of its kicks with: "pcg64" (numpy’s PCG64), "rgen" (numpy’s legacy MT19937), or a generator for tests ("mock", and the shared "rgen-borg" and "mock-borg"). The scheduler draws every move from streams of numpy’s PCG64 generator spawned from [simulation] seed, so a run that kicks no path in process (a load or a restart initiation, or a parallel kick) refuses 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 boolean

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.

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

This integer is a seed for the random number generator used in the TIS algorithm (e.g. when selecting a shooting point).

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.

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

Keyword enforce_must_cross_m¶

enforce_must_cross_m = boolean

Requires a trial path to cross the middle interface before it counts as a member of an ensemble whose definition names that interface. Ensembles that define no middle interface are unaffected by this keyword.

The requirement holds when the keyword is absent, so a configuration carries a line for it to sample the permissive way: enforce_must_cross_m = false accepts a trial in those ensembles without the middle crossing.

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.

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 an ensemble name to the subcycle count to use for that ensemble, taking precedence over mwf_subcycle_small there. An ensemble the dictionary does not name keeps mwf_subcycle_small.

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 MD advances a single kick may spend reaching a valid shooting point. The engine stops with an error when the bound is reached.

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.

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: No default.

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. The value is multiplied by sqrt(inverse mass) for each particle and used as the standard deviation for Gaussian velocity increments added to the current velocities. These momentum changes are then accepted or rejected with the Metropolis criterion.

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. OpenMM evaluates the criterion with the kinetic energy in kJ/mol and the inverse temperature in mol/kJ.

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.

GROMACS with velocity_generation = engine, and AMS, 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).

This is distinct from the legacy 'exp' shooting heuristic, which is not detailed-balance corrected; prefer 'bias' when rigor matters.

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 runs on the infinite-swapping scheduler – the single execution route for every path-sampling task – so you select it the same way for any run. A scheduler worker runs the biased move respecting the [0^-]/[0^+]/[i^+] ensemble structure, and because the move preserves the path ensemble the crossing-probability / WHAM / rate analysis is unchanged. Per-ensemble moves are set with shooting_moves (the [0^-] ensemble must use "sh"), e.g. shooting_moves = ["sh", "bias", "bias", ...].

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:

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

Example (TOML):

[simulation]
shooting_move = "bias"

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

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