Input file sections¶
The PyRETIS input file described in detail in the user guide. The short version is:
The input file is TOML. It is organised into sections whose keywords are given values:
[section] keyword = "value"
Comments are marked with a #.
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:
Section |
Usage |
|---|---|
For defining the simulation we are going to run. |
|
For defining system properties. |
|
For defining a simulation box. |
|
For defining the initial state of particles. |
|
For defining a forcefield. |
|
For defining potential functions to use in the force field. |
|
For defining the simulation engine. |
|
For defining the order parameter. |
|
For defining settings for a RETIS simulation. |
|
For defining settings for a PPTIS or REPPTIS simulation. |
|
For defining settings for a TIS simulation. |
|
For configuring the infinite-swapping scheduler (parallel workers). |
|
For defining how the initial path is generated. |
|
For defining output settings. |
|
For defining custom unit systems. |
In addition, an analysis can be defined using:
Section |
Usage |
|---|---|
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 misspelledgamma: 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 withRequired argument "gamma" ... not found!. No warning namesname,seed,rgen,type,parameter,exe_path,input_path,input_files,conf,topology,index,input_o,templateorcp2k_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], theplottable of[analysis]or the[infinit]section ofpyretis tools initdoes not know, such as a misspelled[initial-path] methodor[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-fluxrun, and[simulation] swap_attributesof 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-fileorenergy-filethat is no integer (the run reads its integer part, so0.5writes no file); a[tis] mwf_subcycle_small, or a count ofmwf_subcycle_small_by_ensemble, that is no positive integer; akeep_rejected_statusentry that is no rejection status; akeep_traj_fnamesentry that is no file suffix.An
md,md-nveormd-fluxrun: an[output] backupother than"append"and"backup", in either case; anmd-fluxrun takestrue,"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".
Keyword |
Refused on |
Set instead |
|---|---|---|
|
Every task. |
|
|
Every task but |
|
|
Every task. |
|
|
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
|
|
|
A |
|
|
A path-sampling run. |
|
|
A path-sampling run. |
|
|
A path-sampling run, unless the value is |
|
|
A path-sampling run, unless the value is 0 or equals
|
|
|
A path-sampling run, unless the value equals
|
|
|
Every run in which no ensemble runs it: an ensemble runs it when
its list in |
|
|
A path-sampling run without a \([0^-]\) ensemble, and a run
that gives |
|
|
A path-sampling run other than a |
|
|
A path-sampling run in which no ensemble runs stone skipping
( |
|
|
A path-sampling run without a \([0^-]\) ensemble; unless the
value is |
|
|
An |
|
|
A path-sampling run other than |
|
|
A path-sampling run in which no ensemble shoots with
multiresolution wire fencing ( |
|
|
A |
|
|
A path-sampling run other than |
|
|
A path-sampling run other than |
|
|
A path-sampling run without a \([0^-]\) ensemble (as for
|
|
|
A path-sampling run without a \([0^-]\) ensemble, unless the
value is |
|
|
A path-sampling run of one ensemble (as for |
|
|
A path-sampling run whose |
|
|
A path-sampling run other than a kick from the initial
configuration ( |
|
|
A path-sampling run, when the value is above 1: the run writes a
block for each row of |
The value 1 |
|
A path-sampling run: only the analysis of an |
|
|
Every run: |
|
|
A path-sampling run. |
|
|
A path-sampling run, unless the value is |
|
|
A path-sampling run. |
|
|
A path-sampling run, and an |
|
|
A path-sampling run other than |
|
|
A path-sampling run other than |
|
|
A path-sampling run other than |
|
|
A path-sampling run other than a |
|
|
A path-sampling run. |
|
|
An |
|
|
An |
|
|
Every run, unless |
|
The |
Every run whose section names an engine other than an internal
integrator (Verlet, Velocity Verlet, Langevin) and a class of a
|
|
The |
Every run, unless the section names a class of a |
|
|
Every run, unless the value is the one the run sets from
|
|
|
A path-sampling run none of whose engine sections names a GROMACS
engine ( |
|
|
An |
|
|
An |
|
|
An |
|
A numbered engine section of a pool ( |
An |
|
|
An |
|
|
An |
|
|
An |
|
|
Every run, unless the value is |
|
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.
DATA-TYPE |
Description |
Example |
|---|---|---|
string |
Text, in quotes. |
|
integer |
An integer. |
|
float |
A floating-point number. |
|
boolean |
|
|
dictionary |
A TOML table: names, each with a value. |
|
list |
Values in square brackets. |
|
tuple |
A list of a fixed number of values. |
|
None |
No value: leave the keyword out of the input. |