Input file sections

The PyRETIS input file described in detail in the user guide. The short version is:

1. The input file is TOML. It is organised into sections whose keywords are given values:

   [section]
   keyword = "value"
   

2. Comments are marked with a #.

3. Section names and keywords are lower case, and the file is case-sensitive.

Below, we list the different sections that you can make use of in order to define your simulation:

Table 46 Input sections for defining simulations.

Section	Usage
simulation	For defining the simulation we are going to run.
system	For defining system properties.
box	For defining a simulation box.
particles	For defining the initial state of particles.
forcefield	For defining a forcefield.
potential	For defining potential functions to use in the force field.
engine	For defining the simulation engine.
orderparameter	For defining the order parameter.
retis	For defining settings for a RETIS simulation.
repptis	For defining settings for a PPTIS or REPPTIS simulation.
tis	For defining settings for a TIS simulation.
runner	For configuring the infinite-swapping scheduler (parallel workers).
initial-path	For defining how the initial path is generated.
output	For defining output settings.
unit-system	For defining custom unit systems.

In addition, an analysis can be defined using:

Table 47 Input sections for defining an analysis.

Section	Usage
analysis	For defining an analysis.

Keywords that take no effect on a run

Every keyword an input gives either takes effect on the run, or the input is refused before the run starts, with a message that names each such keyword and its value, says why it takes no effect, and names the keyword to set instead when another keyword sets what it would set. A keyword can take effect on one task and none on another: the [output] keywords of the in-process output are read by the md tasks and refused by a path-sampling run, whose scheduler writes its own output files. The rule is declared in one place, pyretis.inout.key_table.NO_EFFECT, and the settings parse of every input route applies it: a TOML input, and a legacy .rst input, which pyretis run checks before it routes it (a path-sampling one to its TOML twin). A value the table accepts states what the run does (rgen = "pcg64", [engine] subcycles = 1): the run takes it as it takes an input without the keyword. A run file (output.toml) written by an earlier PyRETIS that holds such a keyword continues and analyses: the keyword is left out when the file is read, silently when its value is the one the settings parse gives or an accepted one, and named in a warning otherwise.

In the table, a path-sampling run is a run of the task retis, repptis, tis, pptis or explore, and the refusal applies to make-tis-files as well, which writes the input of a tis run of each ensemble.

Table 48 The keywords a run refuses, and the runs it refuses them on.

Keyword	Refused on	Set instead
[simulation] zeroswap	Every task.	[retis] swapfreq
[simulation] relative_shoots, [tis] relative_shoots	Every task.	[retis] relative_shoots
[retis] relative_shoots	Every task but a path-sampling run that picks the ensemble of its moves: a tis run of one ensemble refuses it.
[retis] swapfreq	A tis, pptis or explore run and make-tis-files, which attempt no swap.
[retis] nullmoves, [retis] swapsimul, [tis] nullmoves	A path-sampling run.
[retis] seed	A path-sampling run.	[simulation] seed
[simulation] rgen, [retis] rgen	A path-sampling run, unless the value is "pcg64", the generator of the scheduler.
[tis] rgen, [engine] rgen, [system] rgen	A path-sampling run that kicks no path in process: a load or a restart initiation, and a parallel kick (kick-parallel = true); unless the value is "pcg64".
[engine0] rgen and the rgen of a numbered engine section of a pool	A path-sampling run, unless the value is "pcg64".
[engine0]	Every run in which no ensemble runs it: an ensemble runs it when its list in [simulation] ensemble_engines names it, and, without ensemble_engines, the \([0^-]\) ensemble of a run with [tis] quantis = true.
[simulation] restart	A path-sampling run.	[initial-path] method = "restart"
[simulation] startcycle, endcycle, umbrella, overlap, maxdx, mincycle	A path-sampling run.
[simulation] flux	A path-sampling run other than pptis.
[simulation] zero_ensemble	A path-sampling run other than pptis; make-tis-files reads it.
[tis] ensemble_number	A path-sampling run other than tis.
[tis] detect	A path-sampling run other than a tis run with [tis] ensemble_number.
[output] backup, cross-file, pathensemble-file, prefix, restart-file, trajectory-file	A path-sampling run.
[engine] subcycles	An md, md-nve or md-flux run with an internal integrator (Verlet, Velocity Verlet, Langevin), which stores a step after each integration step; unless the value is 1.

The run file output.toml of a run records none of these keywords.

The rgen keyword of [simulation], [system], [tis], [engine], [engine0], [retis], [particles.velocity] and of a numbered engine section names a random generator: "pcg64" (numpy’s PCG64), "rgen" (numpy’s legacy MT19937), "mock", "rgen-borg" or "mock-borg". An input whose rgen names no generator is refused on every task, with the values that name one.

Notation for describing keywords

Each keyword entry is shown as:

keyword = DATA-TYPE

where keyword is the input-file key and DATA-TYPE is the kind of value accepted by that key. The paragraph below each keyword explains what it controls. When a keyword has a default value, the default is listed directly below the description.

Example:

task = string

Selects the simulation task to run.

Default:
  md

The data types used in the keyword reference are listed below.

Table 49 The different data types encountered in PyRETIS.

DATA-TYPE	Description	Example
string	A string of characters, i.e. text.	task = retis
integer	An integer.	steps = 100
float	A floating-point number	timestep = 0.002
boolean	A boolean value (True or False).	shift = True
dictionary	A Python dictionary.	mass = {'Ar': 1.0}
list	A Python list.	interfaces = [0.1, 0.2, 0.3]
tuple	A Python tuple.	index = (7,8)
None	This represents an optional value