The RETIS section

The RETIS section specifies settings for RE(PP)TIS simulations. Note that the section for TIS also needs to be defined for a RE(PP)TIS simulation. A keyword of this section that takes no effect on the run is refused (see the keywords that take no effect).

Example RETIS section:

[retis]
swapfreq = 0.5

Keywords for the RETIS section

The following keywords can be set for the RETIS section:

Table 32 Keywords for the RETIS section.

Keyword	Description
nullmoves	Refused: no part of a path-sampling run reads it.
relative_shoots	Selects and defines relative shooting.
priority_shooting	Prioritize the ensembles with fewer moves.
rgen	Refused unless "pcg64", the generator of the scheduler.
seed	Refused: [simulation] seed seeds the scheduler.
swapfreq	The probability of a swap move.
swapsimul	Refused: no part of a path-sampling run reads it.

Keyword nullmoves

nullmoves = boolean

No part of a path-sampling run reads this keyword, so a path-sampling run and make-tis-files refuse it. The infinite-swapping scheduler moves the ensembles of a move and leaves the paths of every other ensemble in place.

Keyword relative_shoots

relative_shoots = None or 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. If relative_shoots = None (the default when the key is omitted) 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

relative_shoots = None (no relative shooting).

Keyword priority_shooting

priority_shooting = boolean

Set this keyword in the simulation section.

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

The scheduler draws every random number of a path-sampling run 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

The default value is rgen = None.

Keyword seed

seed = integer

The scheduler spawns its random streams from [simulation] seed, and the in-process kick initiation seeds its generators from [tis] seed, so a path-sampling run refuses this keyword, with a message that names [simulation] seed.

Default

The default value is seed = None.

Keyword swapfreq

swapfreq = float

The probability of a swap move, the one keyword of 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) when the other ensemble is free; in a repptis run, a move is, with this probability, a swap with an adjacent 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 and a repptis run.

Keyword swapsimul

swapsimul = boolean

No part of a path-sampling run reads this keyword, so a path-sampling run and make-tis-files refuse it.