The RETIS section

The RETIS section specifies settings for RE(PP)TIS simulations. The moves of each ensemble are set in the TIS section. On a path-sampling run, a keyword of this section that takes no effect on the run is refused. An md, md-nve or md-flux task takes no effect from the section, and refuses its relative_shoots and an rgen that names no generator (see the keywords that take no effect), so leave the section out of the input of an md task.

Example RETIS section:

[retis]
swapfreq = 0.5

Keywords for the RETIS section

The following keywords can be set for the RETIS section:

Table 33 Keywords for the RETIS section.

Keyword	Description
nullmoves	On a path-sampling run, refused; remove it: a move leaves the paths of the other ensembles in place.
relative_shoots	Selects and defines relative shooting.
priority_shooting	A keyword of [simulation], which this section refuses: prioritize the ensembles with fewer moves.
rgen	On a path-sampling run, refused unless "pcg64", the generator of the run.
seed	On a path-sampling run, refused: [simulation] seed seeds the run.
swapfreq	The probability of a swap move.
swapsimul	On a path-sampling run, refused; remove it: a move swaps one pair of ensembles at most.

Keyword nullmoves

nullmoves = boolean

A path-sampling run and make-tis-files refuse this keyword: remove it from an input of PyRETIS 3. A move changes the paths of the ensembles it is made in and leaves the paths of every other ensemble in place; no null move is made.

Keyword relative_shoots

relative_shoots = list of floats

This keyword selects and defines relative shooting. Relative shooting means that the ensembles are shot in with unequal frequencies. This is selected by specifying the relative frequency for each ensemble in a list, e.g. relative_shoots = [0.1, 0.1, 0.2, 0.6] for four ensembles (one weight per ensemble, in interface order — the [0^-] minus ensemble first when it is present), where these numbers give the relative probability of the move being performed in that ensemble. The infinite-swapping scheduler that drives all path-sampling runs weights its per-ensemble move selection by these frequencies, so a heavier ensemble is worked on more often. The weights are state-independent, so every ensemble still samples its own path distribution and the computed rate is unchanged — only the allocation of sampling effort across the ensembles changes. The weights set only which ensemble’s move is chosen; the path the move starts from is drawn from the paths that ensemble holds, by their occupancy, as without the keyword.

The weights need not sum to one (they are normalised internally); they must be non-negative with a positive sum. When the key is not set, the ensembles are selected with the sampler’s own, roughly uniform, frequencies. relative_shoots cannot be combined with priority_shooting.

[retis] relative_shoots is the one keyword of the weights: an input that sets relative_shoots in [tis] or [simulation] is refused, with a message that names [retis] relative_shoots. A run that picks no ensemble, a tis run of one ensemble or a task that runs no move, refuses it.

Default

Not set (no relative shooting).

Keyword priority_shooting

priority_shooting = boolean

Set this keyword in the simulation section; the [retis] section refuses it as an unknown keyword.

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 rgen

rgen = string

A path-sampling run draws every random number, in the kick initiation and in the moves, from streams of numpy’s PCG64 generator spawned from [simulation] seed, so a path-sampling run refuses any value of this keyword other than "pcg64".

Default

Not set: the run draws from numpy’s PCG64 generator.

Keyword seed

seed = integer

The kicks of the kick initiation and the moves of a path-sampling run draw from [simulation] seed, so a path-sampling run refuses this keyword, with a message that names [simulation] seed.

Keyword swapfreq

swapfreq = float

The probability of a swap move; [retis] swapfreq is the one keyword that sets it. In a retis run, a move picked in the \([0^-]\) or the \([0^+]\) ensemble is, with this probability, the swap of the paths of the two (the zero swap), unless another worker is moving the other ensemble; the moves of the other ensembles are never swaps, so swapfreq is not the share of swaps in the whole run as in PyRETIS 3; in a repptis run, a move is, with this probability, a swap with an adjacent ensemble, unless another worker is moving that ensemble. A tis, pptis or explore run attempts no swap, and refuses the keyword. An input that sets [simulation] zeroswap is refused, with a message that names [retis] swapfreq; the run file output.toml records the probability as [retis] swapfreq.

Default

The default value is swapfreq = 0.5 for a retis run. A repptis run needs the keyword: without it the run stops before its first move, with the message Missing required setting "retis" for simulation "REPPTIS simulation".

Keyword swapsimul

swapsimul = boolean

A path-sampling run and make-tis-files refuse this keyword: remove it from an input of PyRETIS 3. A move swaps one pair of ensembles at most: the \([0^-]\) and \([0^+]\) paths in a retis run, two adjacent ensembles in a repptis run (see swapfreq).