The Engine section¶

The engine section specifies the engine to use for the dynamics.

Example engine section:

[engine]
class = "VelocityVerlet"
timestep = 0.002

In PyRETIS, the engines are used as numerical integrators for Newton’s equations of motion. The different engines need different settings and this is specified in detail below for the different types.

A path sampling input may give further engine sections, each with a class and the settings of its engine as below: [engine0], the engine of the [0^-] ensemble of a quantis run, and the numbered sections [engine1], [engine2], … of an engine pool, which [simulation] ensemble_engines assigns to the ensembles. The engine of such a section runs with the settings of that section only: an internal integrator takes its timestep and subcycles from it. Every engine section of a run, [engine] and the [engine0] of a quantis run included, has the same time per step, timestep times subcycles: under infinite swapping a path held by one ensemble can have been generated by the engine of another ensemble, a zero swap builds a path from segments of two engines, and the flux adds the lengths of the [0^-] and [0^+] paths, so the path lengths, counted in steps, convert to time with one time per step only. The engines may differ in every other setting. A run whose engine sections have different times per step is refused before it starts (see ensemble_engines). An [engine0] section in a run in which no ensemble runs it is refused, and so is an rgen of [engine0] or of a numbered engine section other than "pcg64": the scheduler hands the engine of each move a stream of numpy’s PCG64 generator spawned from [simulation] seed. The rgen of [engine] is the generator of the engine of the in-process kick initiation, and a run that kicks no path in process refuses a value other than "pcg64" (see the keywords that take no effect).

An internal integrator (Verlet, Velocity Verlet, Langevin) stores a frame of a path every subcycles integration steps of its section (1 when the section sets none), in a path the scheduler streams and in a path the in-process kick initiation generates with the engine of [engine], so the initial paths of the kick have the time per frame of the paths of the run. An md, md-nve or md-flux run stores a step after each integration step of an internal integrator, so such a run refuses an [engine] subcycles other than 1 for it (see the keywords that take no effect).

The types of engine are:

Table 20 Supported engines in PyRETIS¶
Engine	Description
Verlet	Internal engine, integrate using the Verlet scheme.
Langevin	Internal engine, stochastic dynamics.
Velocity Verlet	Internal engine, integration using the Velocity verlet scheme.
GROMACS	External engine, using GROMACS.
CP2K	External engine, using CP2K.
LAMMPS	External engine, using LAMMPS.
AMS	External engine, using AMS (proprietary; see note).
User-defined	Internal/External engine, user-defined.

The Verlet engine¶

The Verlet engine integrates the equations of motion according to the Verlet scheme. NB: Only MD is allowed for this scheme. The engine is selected by specifying the class Verlet and the time step:

Example Engine section for Verlet:

[engine]
class = "Verlet"
timestep = 0.002

Keywords for the Verlet engine¶

For the Verlet engine, the following keywords can be set:

Table 21 Keywords for the Verlet engine.¶
Keyword	Description
class	Selects the Verlet engine.
timestep	Defines the time step.

Keyword class¶

class = Verlet

The class selects the Verlet engine and it should be set to Verlet.

Keyword timestep¶

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:: Not any. This keyword must be specified.

The Velocity Verlet engine¶

The Velocity Verlet engine integrates the equations of motion according to the Velocity Verlet scheme. The engine is selected by specifying the class VelocityVerlet and the time step:

Example Engine section for VelocityVerlet:

[engine]
class = "VelocityVerlet"
timestep = 0.002

Keywords for the Velocity Verlet engine¶

For the Velocity Verlet engine, the following keywords can be set:

Table 22 Keywords for the Velocity Verlet engine.¶
Keyword	Description
class	Selects the Velocity Verlet engine.
timestep	Defines the time step.

Keyword class¶

class = VelocityVerlet

The class selects the Velocity Verlet engine and it should be set to VelocityVerlet.

Keyword timestep¶

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:: Not any. This keyword must be specified.

The Langevin engine¶

The engine is selected by specifying the class Langevin. This is a stochastic (Brownian) integrator and a description of the implementation can be found in e.g. [1]. The integrator is fully specified as follows:

Example Engine section for Langevin:

[engine]
class = "Langevin"
timestep = 0.002
gamma = 0.3
seed = 0
high_friction = false

Keywords for the Langevin engine¶

For the Langevin engine, the following keywords can be set:

Table 23 Keywords for the Langevin engine.¶
Keyword	Description
class	Selects the Langevin engine.
timestep	Which defines the time step.
gamma	Which defines the the friction parameter.
seed	Which defines a seed to use for the random number generator.
high_friction	Which determines if we are in the high friction limit or not.

Keyword class¶

class = Langevin

The class selects the Langevin engine and it should be set to Langevin.

Keyword timestep¶

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:: Not any. This keyword must be specified.

Keyword gamma¶

gamma = float

This is the gamma parameter ($\gamma$, see the integration scheme) for the Langevin integrator.

Default:: Not any. This keyword must be specified.

Keyword seed¶

seed = integer

The seed value is an integer that is used to seed the random number generator used for the stochastic integration.

Default:: The default seed is zero: seed = 0

Keyword high_friction¶

high_friction = boolean

This keyword determines how the equations of motion are integrated. This is a boolean value and thus it can be set to True or False:

If high_friction is True, we are in the high friction limit and the equations of motion are integrated according to

\[\mathbf{r}(t + \Delta t) = \mathbf{r}(t) + \gamma \Delta t \mathbf{f}(t)/m + \delta \mathbf{r},\]

where $\mathbf{f}(t)$ is the deterministic force and the displacements ($\delta \mathbf{r}$) are drawn from a normal distribution,
If high_friction is False, we are in the low friction limit and the equations of motion are integrated according to

\[\mathbf{r}(t + \Delta t) = \mathbf{r}(t) + c_1 \Delta t \mathbf{v}(t) + c_2 \mathbf{a}(t) \Delta t^2 + \delta \mathbf{r},\]

where,

\[\mathbf{v}(r + \Delta t) = c_0 \mathbf{v}(t) + (c_1-c_2) \Delta t \mathbf{a}(t) + c_2 \Delta t \mathbf{a}(t+\Delta t) + \delta \mathbf{v},\]

and $c_0 = \text{e}^{-\gamma \Delta t}$, $c_1 = (1 - c_0) / ( \gamma \Delta t)$ and $c_2 = (1 - c_1) / ( \gamma \Delta t)$. In this case, $\delta \mathbf{r}$ and $\delta \mathbf{v}$ are obtained as stochastic variables.

Default:: The default setting is high_friction = False

The GROMACS engine¶

The GROMACS engine will use GROMACS [2] in order to integrate the equations of motion. The engine is selected by specifying the class gromacs with some additional keywords:

Example Engine section for gromacs:

[engine]
class = "gromacs"
gmx = "gmx"
mdrun = "gmx mdrun"
input_path = "gromacs_input"
timestep = 0.002
subcycles = 3
maxwarn = 0
write_vel = true
write_force = false
gmx_format = "g96"

Engine naming: the bare gromacs engine is the streaming engine – it reads the GROMACS output on the fly and runs faster than relaunching GROMACS for every order-parameter point. The slower relaunch-per-step engine is selected as gromacs_steps. The former name gromacs2 is a deprecated alias of gromacs (it still resolves to the streaming engine but emits a discontinuation warning). LAMMPS follows the same convention: lammps is the streaming engine and lammps_steps the relaunch engine, which launches LAMMPS once per propagation and reads its trajectory when the LAMMPS run has ended.

Keywords for the GROMACS engine¶

For the GROMACS engine, the following keywords can be set:

Table 24 Keywords for the GROMACS engine.¶
Keyword	Description
class	Selects the GROMACS engine.
gmx	Defines the command used to execute the GROMACS `gmx` program.
mdrun	Defines the command used to execute the GROMACS `mdrun` program.
input_path	Defines the folder containing the input to GROMACS.
timestep	Which defines the time step.
subcycles	Which defines the number of steps GROMACS will execute before we calculate order parameters, i.e. the frequency of output from GROMACS.
maxwarn	Which sets the `-maxwarn` option of GROMACS grompp.
write_vel	Determines if velocities should be written by GROMACS or not.
write_force	Determines if forces should be written by GROMACS or not.
gmx_format	Can be used to select the format used for GROMACS configurations.
domain_decomp	Can be toggled on if domain decomposition is used in GROMACS.
velocity_generation	Selects how shooting velocities are drawn (the engine’s own generator or a Python Maxwell draw).

Keyword class¶

class = gromacs

The class selects the GROMACS engine and it should be set to gromacs.

gromacs is the streaming engine: it launches mdrun once per propagated path segment and reads the trajectory frames on the fly, stopping the run as soon as the path leaves the ensemble. This is the fast, recommended choice. The historical alias gromacs2 selects the same engine and is kept for backward compatibility.

For the slower relaunch-per-step engine — a fresh mdrun launch for every order-parameter point — set class = gromacs_steps. The two engines integrate the same dynamics (see examples/tests/test-gromacs/test-integrate/); prefer gromacs unless you specifically need the per-step relaunch behaviour. (Before this release the bare name gromacs selected the relaunch engine; it now selects the streaming engine — update old inputs to gromacs_steps if they relied on the previous behaviour.)

Keyword gmx¶

gmx = string

This keyword sets the command PyRETIS will use for executing the GROMACS gmx program. This can be used if you have different versions of GROMACS installed, for instance, a single precision build named gmx and a double precision build named gmx_d.

Default:: Not any. This keyword must be specified.

Keyword mdrun¶

mdrun = string

This keyword sets the command PyRETIS will use for executing the GROMACS mdrun program. This can be used to execute an MPI compiled version of mdrun, by, for instance, setting: mdrun = mpiexec_mpt mdrun_mpi. Note that this command is specific to the system you are using.

Default:: Not any. This keyword must be specified.

Keyword input_path¶

input_path = string

This keyword sets the directory where PyRETIS will look for input files to use with GROMACS. If, for instance, input_path = gromacs-input is set, then PyRETIS will look in the folder gromacs-input relative to the directory PyRETIS is executed in.

Further, in the folder specified by input_path the following files must be present:

conf.g96: The initial configuration.
grompp.mdp: The simulation settings to use. Note that PyRETIS will alter the frequency of output and time step to match the setting given in the input to PyRETIS using the timestep and subcycles keywords. Effectively, PyRETIS will use grompp.mdp as a template and create a pyretis.mdp, which is used for the GROMACS simulations.
topol.top: The topology for your system.

PyRETIS only reads this folder. The files it derives from the input – pyretis.mdp, the .tpr built from it and, when only one of conf.g96 and conf.gro is staged, its conversion to the other – are written to a directory pyretis-gromacs-* of the engine’s own in the directory PyRETIS is executed in, which is removed when the run ends.

Default:: Not any. This keyword must be specified.

Keyword timestep¶

timestep = float

The timestep keyword defines the time step for the engine in internal units, which in this case will be gromacs units.

Default:: Not any. This keyword must be specified.

Keyword subcycles¶

subcycles = integer

The subcycles keyword defines the frequency of output from GROMACS and thus the frequency by which the order parameter(s) are obtained.

Default:: Not any. This keyword must be specified.

Keyword maxwarn¶

maxwarn = integer

The maxwarn keyword set the maximum number of warnings the GROMACS grompp command will ignore.

Default:: The default value is maxwarn = 0.

Keyword write_vel¶

write_vel = boolean

The write_vel keyword determines if GROMACS should write velocities when integrating the equations of motion. This can safely be set to False if your order parameter does not depend on the velocities.

Default:: The default value is write_vel = True.

Keyword write_force¶

write_force = boolean

The write_force keyword determines if GROMACS should write forces when integrating the equations of motion. Typically, the forces are not needed unless your order parameter depends on them.

Default:: The default value is write_force = False.

Keyword gmx_format¶

gmx_format = string

The gmx_format keyword specifies the format PyRETIS writes for GROMACS configurations. It can be set to gro or g96, and it is optional.

Both formats are always read: the engine takes the format from the file it is given, so a loaded path, a staged initial configuration or a frame from an external tool may be in either, whatever this keyword says.

g96 is the default because it is the one that does not lose precision. A gro file stores three decimals (1e-3 nm) against g96’s nine, and that truncation is enough to change a cutoff- or count-based order parameter – so a configuration written to gro and read back can report a different order parameter than the frame it came from. External compatibility is not lost: a .gro copy is regenerated from the staged g96 for tools that need one.

Default:: The default value is gmx_format = g96.

Keyword domain_decomp¶

domain_decomp = boolean

The domain_decomp keyword will execute gmx trjconv -pbc whole ... to a frame from which the system is propagated. This was implemented as some GROMACS versions did not handle bonds over periodic boundaries correctly.

Default:: The default value is domain_decomp = False.

Keyword velocity_generation¶

velocity_generation = string

The velocity_generation keyword selects how the shooting velocities are drawn for a shooting move. With engine (the default) the velocities are produced by GROMACS itself, with a zero-step gen_vel run; gen_vel removes the centre-of-mass motion, so this mode requires zero_momentum = True. With maxwell PyRETIS draws them from a Maxwell-Boltzmann distribution (the draw_maxwellian_velocities helper, sharing the same reproducible random stream as the rest of the move), and the momentum is reset as zero_momentum selects. maxwell additionally requires a temperature and the particle masses, and the g96 configuration format. Neither mode re-scales the energy of the drawn velocities, so a positive rescale_energy stops the run with an error before the draw.

Default:: The default value is velocity_generation = engine.

The `CP2K` engine¶

The CP2K engine will use CP2K [3] in order to integrate the equations of motion. The engine is selected by specifying the class cp2k with some additional keywords:

Example Engine section for cp2k:

[engine]
class = "cp2k"
cp2k = "cp2k"
input_path = "cp2k-input"
timestep = 0.002
subcycles = 5

Engine naming: as for GROMACS and LAMMPS, the bare cp2k engine is now the continuous engine – it runs CP2K as a single persistent process for a whole propagation segment and reads its trajectory on the fly (warm-starting the wavefunction from a .wfn restart), which is faster than relaunching CP2K for every order-parameter point. The wavefunctions are kept in the directory pyretis-cp2k-wfn of the run directory, shared by the initiation, the workers and a restart of the run; the input_path folder is only read. When the run directory holds a pyretis-cp2k-wfn of an earlier run, a new run stops, and names the directory to remove: pyretis run before its initiation, a run of a legacy-runner input before it starts, the interface optimizer before its first step when a step directory of the run holds one, and a scheduler run of initial paths staged flat in <load_dir>/<path number>, or in a directory whose ensemble directories hold a pathensemble.txt, before its load. A scheduler run started from the Python interface, with no path staged flat and no pathensemble.txt in its ensemble directories, may follow an initiation run from Python in the same directory, and starts from the store it finds there (see load_dir). The slower relaunch-per-step engine, which chains the run through previous.restart / previous.wfn files, is selected as cp2k_steps.

Keywords for the CP2K engine¶

For the CP2K engine, the following keywords can be set:

Table 25 Keywords for the CP2K engine.¶
Keyword	Description
class	Selects the CP2K engine.
cp2k	Defines the command used to execute CP2K.
input_path	Defines the location of input files to use for CP2K.
timestep	Which defines the time step.
subcycles	Which defines the number of steps CP2K will execute before we calculate order parameter(s).

Keyword class¶

class = cp2k

The class selects the CP2K engine and it should be set to cp2k.

Keyword cp2k¶

cp2k = string

The command used for executing CP2K.

Default:: Not any. This keyword must be specified.

Keyword input_path¶

input_path = string

This keyword sets the directory where PyRETIS will look for input files to use with CP2K. If for instance input_path = cp2k-input is set, then PyRETIS will look in the folder cp2k-input relative to the directory PyRETIS is executed in.

Further, in the folder specified by input_path the following files must be present:

initial.xyz: A file with the initial configuration.
cp2k.inp: A CP2K input file, defining a MD simulation.

Default:: Not any. This keyword must be specified.

Keyword timestep¶

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:: Not any. This keyword must be specified.

Keyword subcycles¶

subcycles = integer

The subcycles defines the frequency of the output from CP2K and thus the frequency by which the order parameter(s) are obtained.

Default:: Not any. This keyword must be specified.

The `LAMMPS` engine¶

The LAMMPS engine will use LAMMPS [4] in order to integrate the equations of motion. A description of how to use the LAMMPS engine with PyRETIS can be found in the user guide on LAMMPS.

The engine is selected by specifying the class lammps with some additional keywords:

Example Engine section for lammps:

[engine]
class = "lammps"
lmp = "lmp"
input_path = "lammps_input"
subcycles = 1
temperature = 300.0
extra_files = [
    "potential.in",
]

Keywords for the LAMMPS engine¶

For the LAMMPS engine, the following keywords can be set:

Table 26 Keywords for the LAMMPS engine.¶
Keyword	Description
class	Selects the LAMMPS engine.
lmp	Defines the command used to execute LAMMPS.
input_path	Defines the location of input files to use for LAMMPS.
subcycles	Which defines the number of steps LAMMPS will execute before we calculate order parameter(s).
extra_files	Defines the location of input files to use for LAMMPS.
order_mode	Selects whether order parameters are evaluated by LAMMPS or by PyRETIS.
velocity_generation	Selects how shooting velocities are drawn.
temperature	Sets the temperature of the velocities PyRETIS draws.
atom_style	Defines how atom rows in a LAMMPS data file are interpreted by PyRETIS.

Keyword class¶

class = lammps

The class selects the LAMMPS engine and it should be set to lammps or lammps_steps.

class = lammps selects the streaming engine (pyretis.engines.lammps.LAMMPSEngine), analogous to the GROMACS gromacs engine: a propagation runs one LAMMPS process, PyRETIS reads its dump trajectory as LAMMPS writes it and stops the process once the path is complete. class = lammps_steps selects the relaunch engine (pyretis.engines.lammps_steps.LAMMPSEngineSteps), which reads the trajectory of a propagation once the LAMMPS run has ended. The two engines draw the shooting velocities differently; see velocity_generation.

Keyword lmp¶

lmp = string

The command used for executing LAMMPS.

Default:: Not any. This keyword must be specified.

Keyword input_path¶

input_path = string

This keyword sets the directory where PyRETIS will look for input files to use with LAMMPS. If for instance input_path = lammps_input is set, then PyRETIS will look in the folder lammps_input relative to the directory PyRETIS is executed in.

Further, in the folder specified by input_path the following files must be present:

system.data: A LAMMPS data file with the initial configuration. class = lammps reads its Atoms and Masses sections when it is set up, and its box when it draws the velocities, or evaluates the order parameter, of the configuration held in it, as atom_style describes.
lammps.in: A LAMMPS input file, defining a MD simulation.
order.in: A LAMMPS input file, defining the order parameter calculation. This file is required when order_mode = lammps and optional when order_mode = pyretis.

Default:: Not any. This keyword must be specified.

Keyword subcycles¶

subcycles = integer

The subcycles defines the frequency of the output from LAMMPS, and thus the frequency by which the order parameter(s) are obtained.

Default:: Not any. This keyword must be specified.

Keyword extra¶

extra_files = list of strings

The extra_files defines additional files that might be needed to execute LAMMPS. For instance, may the user refer to several additional LAMMPS script in the given lammps.in file. This keyword is to make PyRETIS aware of these additional files.

Default:: None.

Keyword order_mode¶

order_mode = string

The order_mode keyword selects how order parameters and collective variables are evaluated for the LAMMPS engine.

With order_mode = lammps, LAMMPS variables defined in order.in are printed by LAMMPS, and v_op_1 is used by LAMMPS halt fixes to stop path propagation at the interfaces.

order_mode = pyretis uses LAMMPS only for propagation. PyRETIS reads the dumped LAMMPS trajectory frames and evaluates the normal orderparameter and collective-variable sections in Python. In this mode, LAMMPS cannot halt directly on v_op_1; PyRETIS truncates the generated path after evaluating the order parameter.

Default:: pyretis for class = lammps and lammps for class = lammps_steps.

Keyword velocity_generation¶

velocity_generation = string

The velocity_generation keyword selects how the shooting velocities are drawn for a shooting move.

With class = lammps_steps and engine (the default), LAMMPS produces the velocities itself, with velocity create, and PyRETIS writes its mom keyword from zero_momentum: mom yes for zero_momentum = True and mom no for zero_momentum = False. With maxwell, PyRETIS draws them from a Maxwell-Boltzmann distribution (the draw_maxwellian_velocities helper, sharing the same reproducible random stream as the rest of the move) and resets the momentum as zero_momentum selects. With engine, a positive rescale_energy makes LAMMPS re-scale the created velocities so that pe + ke, as LAMMPS evaluates them, equals rescale_energy (per atom under thermo_modify norm yes, the LAMMPS default for lj units), and keeps them, with a WARNING, for a pe above rescale_energy; the maxwell draw does not re-scale, and a positive rescale_energy stops the run with an error before the draw.

With class = lammps, PyRETIS draws the velocities in both modes, from a Maxwell-Boltzmann distribution at temperature on the same random stream, and resets the momentum as zero_momentum selects, so the two values draw the same velocities. The velocities of a configuration held in a LAMMPS data file, as the system.data a run starts from, are drawn as class = lammps_steps with maxwell draws them, with the positions, image flags, masses and box of the data file (see atom_style). For a 3D system, the positions, velocities and kinetic energy of that draw are those of the draw of a dump frame of the same configuration; the frame that the draw of a dump frame writes has the image flags 0 0 0. The draws leave the energy as drawn: a positive rescale_energy stops the run with an error before the draw.

The draws of PyRETIS, those of class = lammps and of class = lammps_steps with maxwell, use the constants of LAMMPS real units. They require a temperature and the units real command in lammps.in:

Without a temperature, maxwell stops the run with an error when the engine is set up, and class = lammps with engine at its first draw.
A units command of lammps.in that sets other units stops the run with an error at the first draw. Without [system] units, PyRETIS takes the units of the run from that command, and the LAMMPS units that PyRETIS does not define, cgs, nano and micro, stop the run earlier, when the ensembles are set up.
PyRETIS reads the units command of lammps.in itself, not of a file it includes, so units real goes in lammps.in. LAMMPS runs a lammps.in without a units command in lj units, unless a file it includes sets the units. Without [system] units, PyRETIS takes the units of the run from the units command of lammps.in, and a lammps.in without one stops the run with an error when the settings are read; with [system] units set, it stops the run with an error at the first draw.

Default:: The default value is velocity_generation = engine.

Keyword temperature¶

temperature = float

The temperature keyword sets the temperature, in K, of the Maxwell-Boltzmann distribution that PyRETIS draws the shooting velocities from. Every velocity draw of class = lammps requires it. Without it, velocity_generation = maxwell stops the run with an error when the engine is set up, for both engines, and class = lammps with velocity_generation = engine at its first draw. With class = lammps_steps and velocity_generation = engine, LAMMPS draws the velocities at the SET_TEMP variable of lammps.in (see the user guide on LAMMPS).

Default:: Not set.

Keyword atom_style¶

atom_style = string

The atom_style keyword tells PyRETIS how columns in the LAMMPS data file’s Atoms section are laid out. With it, PyRETIS reads the atom types of the data file, and so the masses, and the positions of a configuration held in a data file. The rows are read in the style of the first of these that is given:

the atom_style keyword;
the # style annotation of the Atoms header, as in Atoms # full, which a data file written by LAMMPS carries;
the atom_style command of lammps.in;
atomic, the style LAMMPS uses when its input sets none.

PyRETIS reads the atom_style command of lammps.in itself, not of a file it includes. An atom_style command whose style is a LAMMPS variable, as atom_style ${style}, is not a source, since PyRETIS does not evaluate LAMMPS variables: the rows are read in the style of the atom_style keyword or of the annotation, and without either of them the run stops with an error that asks for the atom_style keyword. The supported styles, and the columns of their rows as LAMMPS read_data reads them, are:

atomic: atom-ID atom-type x y z;
charge: atom-ID atom-type q x y z;
molecular, bond and angle: atom-ID molecule-ID atom-type x y z;
full: atom-ID molecule-ID atom-type q x y z.

Each row can end with the three image flags. The styles molecular, bond and angle have the same rows, so any two of them agree. A style with the suffix of an accelerator package, as full/kk or full/kk/device of KOKKOS, has the rows of the style without the suffix and agrees with it; write_data of a LAMMPS run with -sf kk can write such a style in the Atoms annotation.

PyRETIS reads a data file as LAMMPS read_data lays it out. The header is the lines below the title line up to the first line that does not start with a number. It gives N atoms, N atom types and the box bounds, a line lo hi xlo xhi, lo hi ylo yhi or lo hi zlo zhi for each axis, in any order of the lines; an axis whose line the header leaves out, as the z axis of a 2D system often is, has the bounds -0.5 0.5, the default of LAMMPS. A header line is read, as LAMMPS reads it, by the keywords at their positions in the line, and the words after them are ignored, so 0 10 xlo xhi extra gives x the bounds 0 10; the other lines of the header, as N bonds, are not read. The rows of the Masses and Atoms sections start at the second line below the keyword line of the section, whatever the line between them holds, one row for each atom type or atom of the header, and the keyword line of the next section can follow the last row with no blank line between them. LAMMPS reads a keyword line together with the line below it, and a keyword line that is the last line of the file ends the read, so PyRETIS does not read that line either. PyRETIS takes the masses of the atoms from the Masses section. These stop the run with an error:

a style that is not supported, as sphere or hybrid, from any of the three sources;
two of the three sources that are given and name styles with different rows, as an Atoms # atomic annotation and atom_style full in lammps.in; the error names both;
a header line that has a keyword of these lines and is neither one of them nor another header line of LAMMPS, such as 0 40 zlo zhj or 0 10 xhi xlo, which LAMMPS stops at with Unknown identifier in data file; a number of atoms or atom types that is not written in digits; a bound, or a number of a line of a triclinic box, that is not a number; a hi bound that is not above its lo bound; the error names the file and the line;
a blank line or a comment among the rows of a Masses or Atoms section, a section that ends with the file before its last row, and a line below the rows that starts with a number, as a row beyond the N atoms or N atom types of the header does: LAMMPS reads that line as the keyword line of a section and stops at it, unless it is the last line of the file, which LAMMPS leaves out; the error names the file and the line;
an Atoms row whose number of columns fits the style neither without nor with the three image flags (7 or 10 columns for full), or is not the number of columns of the first row, as LAMMPS read_data requires, so either every row ends with the image flags or none does; an Atoms row whose atom ID, atom type or image flags are not integers, as the atom type 1.0, whose atom ID is not positive, or that repeats the atom ID of an earlier row; the error names the file and the row; a second Atoms section;
a Masses row that is not an integer atom type and a positive mass, or whose atom type is not one of the N atom types of the header, numbered from 1; a Masses section that gives an atom type twice, or not the atom type of an atom; the error names the file;
with class = lammps, a mass command in lammps.in, which sets masses in LAMMPS in place of those of the Masses section; with class = lammps_steps and velocity_generation = maxwell, such a command for the draw of a configuration held in a data file. The error names the command and asks for the masses in the Masses section. PyRETIS reads the mass commands of lammps.in itself, not of a file it includes.

With class = lammps, these errors come when the engine is set up, as it reads the masses from the system.data of input_path, or when it draws the velocities, or evaluates the order parameter, of a configuration held in another data file; the draw reads the data file before it writes any file. class = lammps_steps reads a data file only in the draw of velocity_generation = maxwell, and the errors come at the first draw. That draw reads the data file conf.data of the run directory: for a configuration held in a data file, a copy of that file, and for a frame of a dump, the data file that LAMMPS write_data writes for the frame, whose Masses section holds the masses that LAMMPS has, those of the mass commands of lammps.in among them. A mass command therefore stops the draw of a configuration held in a data file only, before the file is copied, and the errors of the data file come after it is written. With velocity_generation = engine the engine does not read the data file.

The velocity draw of a configuration held in a data file, of both engines, its order parameter, of class = lammps, and every draw of class = lammps_steps with velocity_generation = maxwell read the box of the data file too, as an orthogonal box from its lo and hi bounds. These stop them with an error that names the file and the line:

a data file of a triclinic box, whose header has an xy xz yz line, even with zero tilt factors, or an avec, bvec, cvec or abc origin line of a general triclinic box, with or without words after its keywords. write_data writes the xy xz yz line for a frame of a dump in a triclinic box, so every draw of class = lammps_steps with velocity_generation = maxwell in a triclinic box stops;
a header with two lines for the bounds of one axis, of which LAMMPS read_data takes the last.

The set-up of class = lammps reads no box of system.data, so a run from a system.data of a triclinic box sets up, and stops at the first draw or order parameter of a configuration held in a data file.

With class = lammps, a configuration names its data file by a path, absolute or relative to the directory PyRETIS runs in, or by a bare file name. A bare name that is not a file of the directory PyRETIS runs in is the file of that name in the run directory, and, without one, the system.data of input_path when it has its name. A configuration whose data file is none of these stops the run with an error that names the file. The propagation of both engines, which copies a configuration held in a data file to the system.data of the run directory, reads a path in the same way, and a bare name as the file of that name in the run directory.

The rows of charge and those of molecular, bond and angle have the same number of columns, 6 or 9, and the positions in the same columns, so the number of columns cannot tell them apart. Read as molecular rows, charge rows give their charge as the atom type, and only a charge that is not an integer stops the run; read as charge rows, molecular rows give their molecule ID as the atom type. For these rows the style must be right.

When a file-backed initial LAMMPS trajectory contains wrapped coordinates (x/y/z) and unwrapped coordinates (xu/yu/zu), but omits image flags, PyRETIS derives ix/iy/iz while extracting the selected timestep into a canonical one-frame starting dump. The source trajectory remains unchanged and is read only up to the referenced timestep. For triclinic dumps, image flags must currently be provided explicitly.

Default:: Not set: the style comes from the data file or lammps.in, as listed above.

The `AMS` engine¶

The AMS engine drives the Amsterdam Modeling Suite (AMS) to integrate the equations of motion. Unlike the other external engines it does not launch a command-line executable per step; it controls a persistent AMS process through the scm.plams AMSWorker Python API, reading the run definition (geometry, time step, thermostat) from an ams.inp in the engine’s input_path.

Note

AMS is proprietary software (SCM – Software for Chemistry & Materials) and its scm.plams Python binding must be licensed and installed separately; PyRETIS cannot install it. A mock-engine test (test/engines/mockams.py with test/engines/test_ams_mock.py) injects fake scm.plams modules so the engine’s construction and MD-step logic run without an AMS installation. The tests of the velocities AMS draws (test/infswap/engines/test_velocity_functions.py, test/engines/test_ams_draw_momentum.py) need a licensed AMS and are skipped without one. There is no numerically-validated AMS reference suite. The avatar above is a generic PyRETIS-drawn molecule, not the SCM/AMS logo.

The engine is selected by specifying the class ams with some additional keywords:

Example Engine section for ams:

[engine]
class = "ams"
input_path = "ams_input"
timestep = 0.5
subcycles = 1

AMS draws the shooting and kick velocities with its own generator (GenerateVelocities), and PyRETIS uses them as drawn. With RandomVelocitiesMethod = Gromacs and Exact, the AMS default, the draws have zero net linear momentum, so the AMS engine requires zero_momentum = True; zero_momentum = False, the default, stops the run with an error before the draw. The AMS engine draws the velocities of aimless shooting, selected by a negative sigma_v, and leaves their energy as drawn: a zero or positive sigma_v, and a positive rescale_energy, stop the run with an error before the draw.

Note

The SCM manual states the removal of the net momentum for RandomVelocitiesMethod = Gromacs, and draws of Exact, the AMS default from AMS2023.1, have zero total momentum. For Boltzmann, the method of the AMS velocity tests (test/infswap/engines/ams_inp/ams.inp), it has not been checked: the check needs a licensed AMS (AMSBIN set, NSCM=1).

Keywords for the AMS engine¶

For the AMS engine, the following keywords can be set:

Table 27 Keywords for the AMS engine.¶
Keyword	Description
class	Selects the AMS engine (`class = ams`).
input_path	The directory holding `ams.inp` (and the geometry it references).
timestep	The MD time step; it must match the `timestep` in `ams.inp` (a mismatch is rejected).
subcycles	The number of AMS MD steps run before each order- parameter evaluation.

Keyword class¶

class = ams

Selects the AMS engine; set it to ams.

Keyword input_path¶

input_path = ams_input

The directory that holds the ams.inp AMS input file (and the geometry file it references).

Keyword timestep¶

timestep = 0.5

The MD time step. It must agree with the time step declared in ams.inp; PyRETIS raises an error on a mismatch.

Keyword subcycles¶

subcycles = 1

The number of AMS MD steps taken between order-parameter evaluations.

User-defined engines¶

It is also possible to extend PyRETIS with user-defined engines, written in for instance Python, FORTRAN or C. User-defined engines are specified in Python modules that PyRETIS can load and they are typically specified as follows:

Example Engine section for a user-defined engine:

[engine]
class = "VelocityVerletF"
module = "vvengineF.py"
timestep = 0.002

Keywords for user-defined engines¶

Typically, the user-defined engines requires that, at least, the following keywords are set:

Table 28 Keywords for user-defined engines.¶
Keyword	Description
class	Selects the engine.
module	Defines the Python file where the engine class is defined.
timestep	Defines the timestep for the engine.

Keyword class¶

class = string

This keyword selects the engine and it should be set to the class name as it is defined in the given module.

Keyword module¶

module = string

This keyword specified the location of the file containing the user-defined class. This file must be accessible by PyRETIS.

Default: Not any. This keyword must be specified.

Keyword timestep¶

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:: Not any. This keyword must be specified.

Additional keywords¶

In addition, user-defined keywords can be specified, e.g.:

Example Engine section for a user-defined engine:

[engine]
class = "VelocityVerletF"
module = "vvintegratorf.py"
timestep = 0.002
keyword = 100
otherkeyword = 31

The Engine section¶

The Verlet engine¶

Keywords for the Verlet engine¶

Keyword class¶

Keyword timestep¶

The Velocity Verlet engine¶

Keywords for the Velocity Verlet engine¶

Keyword class¶

Keyword timestep¶

The Langevin engine¶

Keywords for the Langevin engine¶

Keyword class¶

Keyword timestep¶

Keyword gamma¶

Keyword seed¶

Keyword high_friction¶

The GROMACS engine¶

Keywords for the GROMACS engine¶

Keyword class¶

Keyword gmx¶

Keyword mdrun¶

Keyword input_path¶

Keyword timestep¶

Keyword subcycles¶

Keyword maxwarn¶

Keyword write_vel¶

Keyword write_force¶

Keyword gmx_format¶

Keyword domain_decomp¶

Keyword velocity_generation¶

The CP2K engine¶

Keywords for the CP2K engine¶

Keyword class¶

Keyword cp2k¶

Keyword input_path¶

Keyword timestep¶

Keyword subcycles¶

The LAMMPS engine¶

Keywords for the LAMMPS engine¶

Keyword class¶

Keyword lmp¶

Keyword input_path¶

Keyword subcycles¶

Keyword extra¶

Keyword order_mode¶

Keyword velocity_generation¶

Keyword temperature¶

Keyword atom_style¶

The AMS engine¶

Keywords for the AMS engine¶

Keyword class¶

Keyword input_path¶

Keyword timestep¶

Keyword subcycles¶

User-defined engines¶

Keywords for user-defined engines¶

Keyword class¶

Keyword module¶

Keyword timestep¶

Additional keywords¶

References¶

The `CP2K` engine¶

The `LAMMPS` engine¶

The `AMS` engine¶