The TIS section¶

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

Example TIS section:

TIS settings
------------
allowmaxlength = False
freq = 0.5
high_accept = True
interface_sour = None
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 32 Keywords for the TIS section¶
Keyword	Description
allowmaxlength	Select whether shooting moves may use the full `maxlength` cap directly.
freq	Define how often time reversal moves are performed.
interface_sour	Sets the position of SOUR for Web Throwing.
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.
interface_cap	Set the cap value for subpaths generated by the WF move.
sigma_v	Set the velocity-perturbation width, or select aimless shooting when negative.
zero_momentum	Specify whether momentum should be set to zero when shooting.

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

This select the version of Stone Skipping that is going to be used. Potential High Accept should always been choosen since it is more efficient. Note that the current implementation, due to detailed balance, DOES NOT ALLOW to have multiple shooting methods in the same ensemble.

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.

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.

Default: No default, this keyword must be specified.

Keyword n_jumps¶

n_jumps = integer

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

Default: No default, this keyword must be specified if Stone Skipping, Wire Fencing or Web Throwing are going to be used.

Keyword rgen¶

rgen = string

Selection of the random number generator to use. The option allows the use of bias random number generator (mock) or an easy implementation of more advanced random number generators.

Default: The default is rgen = rgen.

Keyword rescale_energy¶

rescale_energy = float or boolean

If this keyword is set to a 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, then the energies will not be re-scaled.

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 and 'bias' for biased shooting-point selection. See Move types for the full list of move type codes and their descriptions.

Default: The default value is [].

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.

Default: The default value is sigma_v = -1.

Keyword zero_momentum¶

zero_momentum = boolean

If this keyword is set to True, then the momentum of the system is set to zero after creating random velocities for shooting. If False, this is not done.

Default: The default 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 works on both PyRETIS execution routes, so you select it the same way regardless of how the run is driven:

the native in-process loop (task = "tis", and task = "retis" with PYRETIS_NATIVE_LOOP=1), and
the infinite-swapping scheduler – which is the default route for task = "retis" and the multi-worker runs. 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