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, except the keywords listed below. A keyword a section does not know, such as a misspelled one, is refused with a message that names it and its section. A keyword of the table below, which takes no effect on the run, is refused with a message that names it and its value, says why it takes no effect, and names the keyword to set instead when another keyword sets what it would set.

The run does not refuse these keywords yet, so check them against their pages:

  • A keyword of [engine], [engine0], a numbered engine section of a pool, [orderparameter], [[collective-variable]], [[potential]] or [shooting-selector] that the class the section names does not take, such as a misspelled gamma: a warning names it (These settings are not used by "Langevin" and are being IGNORED: "gama"), and the run goes on as if the keyword were not there, with the default in its place. When the class needs the keyword the misspelling leaves out, the run stops instead with Required argument "gamma" ... not found!. No warning names name, seed, rgen, type, parameter, exe_path, input_path, input_files, conf, topology, index, input_o, template or cp2k_format, even in a section whose class does not take them, nor a keyword of [shooting-selector] on a run without a "bias" move, which does not use the section.

  • A keyword that [initial-path], [particles.position], [particles.velocity], the plot table of [analysis] or the [infinit] section of pyretis tools init does not know, such as a misspelled [initial-path] method or [particles.velocity] momentum: no message names it, and PyRETIS takes the input as if the keyword were not there.

  • [particles] type, which the run sets from [engine] class in place of the value an input gives, without a message.

  • Keywords that take no effect on some runs, as their pages say: [particles] npart on every run but the analysis of an md-flux run; [output] archive_every on an md-flux run, and [output] cross-file, and order-file without an [orderparameter] section, on an md-nve run; and [simulation] swap_attributes of PyRETIS 3, with a warning.

  • On an md, md-nve or md-flux task, the keywords that set the moves and the ensembles of a path-sampling run. No message names them when the task starts, and the run is the one it is without them, so leave them out of the input of an md task:

    • every keyword of [tis] and [retis] but relative_shoots, which the task refuses;

    • [simulation] priority_shooting and the path sampling keywords flux, zero_left, zero_ensemble, permeability, pick_scheme and load_dir of [simulation];

    • [simulation] interfaces on an md or md-nve task;

    • [simulation] ensemble_engines with the numbered engine sections [engine1], [engine2], … it names. The task checks that it gives one list per interface (so an input without interfaces refuses any list), that each list names sections the input defines with a class, and that it names each numbered section, but it compares no times per step; an [engine0] section is refused.

    A value that is refused on every task is refused in them too: an rgen that names no generator (see below), and an engine class that is not an engine of PyRETIS in a section without module, or that the module of its section does not define. A restart compares some of these keywords with the restart file (see Restarting an md task).

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. A legacy .rst input is checked in the same way, before pyretis run writes the TOML twin of a path-sampling one. 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. Its [simulation] zeroswap is read as [retis] swapfreq, in place of the swapfreq the file holds, and its [tis] relative_shoots as [retis] relative_shoots when the file sets none; a warning names each value read so. Every other such keyword is left out when the file is read: silently when its value is the one the run takes without the keyword, or one the table accepts, 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] interfaces_b, [simulation] shared

Every task but biretis.

[simulation] task = "biretis"

[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, [tis] rgen, [system] rgen, [engine] rgen, [engine0] rgen and the rgen of a numbered engine section of a pool

A path-sampling run, unless the value is "pcg64": the run draws every random number, the kick initiation included, from numpy’s PCG64 generator seeded with [simulation] seed.

[tis] seed

A path-sampling run, unless the value is 0 or equals [simulation] seed.

[simulation] seed

[engine] seed, [engine0] seed and the seed of a numbered engine section of a pool

A path-sampling run, unless the value equals [simulation] seed.

[simulation] seed

[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"

[initial-path] flexible_restart

A path-sampling run, unless the value is false.

[simulation] allow_setting_change = true to continue with changed settings; [initial-path] method = "load" to change the interfaces or the number of ensembles

[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 data types of the keywords, as a TOML input writes them.

DATA-TYPE

Description

Example

string

Text, in quotes.

task = "retis"

integer

An integer.

steps = 100

float

A floating-point number.

timestep = 0.002

boolean

true or false, in lower case.

shift = true

dictionary

A TOML table: names, each with a value.

mass = {Ar = 1.0}

list

Values in square brackets.

interfaces = [0.1, 0.2, 0.3]

tuple

A list of a fixed number of values.

index = [7, 8]

None

No value: leave the keyword out of the input.