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.

  • 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, and [simulation] swap_attributes of PyRETIS 3, with a warning.

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, and the settings an md task of an earlier PyRETIS stored (out.toml) analyse. 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, explore or biretis, and the refusal applies to make-tis-files as well, which writes the input of a tis run of each ensemble. A path-sampling run refuses an [[ensemble]] section (an Ensemble section of a legacy .rst input, before pyretis run writes its TOML twin): it gives every ensemble the settings of the general sections. make-tis-files writes the settings of each [[ensemble]] section into the input of the tis run of its ensemble, and refuses a setting of an [[ensemble]] section that the tis run of its ensemble refuses, when its value differs from the one of the general sections or the default, and then writes no input: the message names the input of each such run.

An [[ensemble]] section gives the settings of one ensemble, which it names by interface, the left interface of the ensemble, by [tis] ensemble_number, an integer, or by both when they name the same ensemble. The keys of its tables ([ensemble.tis], [ensemble.engine], …) take the place of the keys of the general sections in that ensemble, and its [tis] shooting_move is the move of the ensemble. make-tis-files gives each ensemble the task tis, the interfaces [left, middle, right] and the [tis] detect (the next interface) from [simulation] interfaces, and with a [tis] shooting_moves list the move of its interface. A section that gives one of these another value (a [simulation] task or interfaces equal to the general one is taken), a [tis] shooting_moves list other than the general one (an empty list or a copy of the general list, as the out.toml of a run holds, is taken), a second section of one ensemble and a section that names no ensemble of the input are refused before any input is written.

A value that the run reads as another value, or as no value, is refused in the same message, under “The input sets values that this <task> run does not take”:

  • A path-sampling run and make-tis-files: an [output] order-file or energy-file that is no integer (the run reads its integer part, so 0.5 writes no file); a [tis] mwf_subcycle_small, or a count of mwf_subcycle_small_by_ensemble, that is no positive integer; a keep_rejected_status entry that is no rejection status; a keep_traj_fnames entry that is no file suffix.

  • An md, md-nve or md-flux run: an [output] backup other than "append" and "backup", in either case; an md-flux run takes true, "yes" and "True" as well.

The set-up of a path-sampling run refuses a name of mwf_subcycle_small_by_ensemble that is no ensemble shooting with "mwf", and a [tis] mwf_subcycle_small that the dictionary overrides in every ensemble that shoots with "mwf".

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 run of one ensemble refuses it (a single TIS run, a tis run with [tis] ensemble_number, an explore run with two interfaces, a pptis run with three interfaces and neither a \([0^-]\) nor a \([0^+]\)).

[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. A run without a \([0^-]\) ensemble (a single TIS run, a tis run with [tis] ensemble_number, an explore run, a pptis run without zero_left and flux) runs none.

[tis] quantis

A path-sampling run without a \([0^-]\) ensemble, and a run that gives [simulation] ensemble_engines and attempts no swap (tis, pptis); unless the value is false.

[tis] accept_all

A path-sampling run other than a retis or repptis run with [tis] quantis = true; unless the value is false.

[tis] high_accept

A path-sampling run in which no ensemble runs stone skipping (ss); unless the value is true.

[tis] mirror_freq, target_freq and target_indices

A path-sampling run without a \([0^-]\) ensemble; unless the value is 0 ([] for target_indices).

[tis] shooting_move

An explore run, which shoots with the explore move ("exp"); unless the value is "sh" or "exp".

[tis] shooting_moves

[tis] enforce_must_cross_m

A path-sampling run other than pptis and repptis.

[tis] mwf_subcycle_small

A path-sampling run in which no ensemble shoots with multiresolution wire fencing (mwf).

[tis] interface_cap

A biretis run: every ensemble shoots with sh.

[repptis] memory

A path-sampling run other than repptis.

[pptis] memory on a pptis run

[pptis] memory

A path-sampling run other than pptis.

[repptis] memory on a repptis run

[simulation] zero_left

A path-sampling run without a \([0^-]\) ensemble (as for [engine0] above), unless the value is false; make-tis-files refuses it as well.

[simulation] permeability

A path-sampling run without a \([0^-]\) ensemble, unless the value is false. A run with a \([0^-]\) refuses permeability = true without zero_left.

[simulation] pick_scheme, [simulation] priority_shooting

A path-sampling run of one ensemble (as for [retis] relative_shoots above), and make-tis-files; unless the value is 0, or false.

[initial-path] kick-from

A path-sampling run whose [initial-path] method is not "kick".

[initial-path] kick-parallel

A path-sampling run other than a kick from the initial configuration (method = "kick", kick-from = "initial"), unless the value is false.

[output] order-file, [output] energy-file

A path-sampling run, when the value is above 1: the run writes a block for each row of pathensemble.txt when the value is positive, and no file when it is 0 or less.

The value 1

[analysis] skipcross

A path-sampling run: only the analysis of an md-flux run reads it.

[analysis] report-dir

Every run: pyretis analyse writes the report to the folder report in the directory it runs from.

[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

A path-sampling run.

[simulation] umbrella, overlap, maxdx, mincycle

A path-sampling run, and an md, md-nve or md-flux 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.

[output] trajectory-file

An md, md-nve or md-flux run with an external engine (GROMACS, CP2K, LAMMPS), which writes the trajectory of the engine; unless the value is below 1.

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

[engine] potential

Every run, unless [engine] names a class of a module: the force field of [engine] is the top-level [[potential]] for an internal integrator, and the one of its own input files for another engine.

[[potential]]

The potential of [engine0] and of a numbered engine section of a pool

Every run whose section names an engine other than an internal integrator (Verlet, Velocity Verlet, Langevin) and a class of a module: such an engine integrates with the force field of its own input files. An internal integrator reads a potential list in the [engine0] of a quantis run only, and a run refuses it in any other section (see the engine section).

The particles, box and boltzmann of [engine], [engine0] and of a numbered engine section of a pool

Every run, unless the section names a class of a module: the engines of a run share its particles, its box and its units.

[particles], [box], [system] units

[particles] type

Every run, unless the value is the one the run sets from [engine] class: "external" for a GROMACS, CP2K or LAMMPS class, "internal" for every other class.

[engine] class

[runner] wmdrun

A path-sampling run none of whose engine sections names a GROMACS engine (gromacs, gromacs2, gromacs_steps) or a class of a module.

[runner]

An md, md-nve, md-flux, umbrellawindow or make-tis-files run, which starts no worker.

[tis], [retis], [repptis], [pptis], [shooting-selector]

An md, md-nve or md-flux run.

[simulation] priority_shooting, pick_scheme, zero_left, permeability, flux, zero_ensemble, load_dir, ensemble_engines

An md, md-nve or md-flux run; priority_shooting, zero_left and permeability unless the value is false, pick_scheme unless it is 0.

A numbered engine section of a pool ([engine1], …)

An md, md-nve or md-flux run.

[engine]

[simulation] interfaces, [output] cross-file

An md or md-nve run.

[simulation] task = "md-flux"

[output] order-file

An md, md-nve or md-flux run without an [orderparameter] section.

[orderparameter]

[output] pathensemble-file, archive_every, data_dir, keep_rejected_status, keep_traj_fnames, engine_log

An md, md-nve or md-flux run.

[output] pattern, native_compat, delete_old, delete_old_all, keep_maxop_trajs and [runner] files of a legacy-runner input

Every run, unless the value is false or 0 for pattern, true for native_compat, false for the three deletion keys, [] for files. A canonical input refuses them as unknown keywords.

[output] archive_every for the three deletion keys

The run file output.toml of a run, and the out.toml of an md task, leave out each of these keywords on the runs the table names; on another run they record its value.

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.