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. The engines of a path-sampling run draw from streams of numpy’s PCG64 generator spawned from [simulation] seed: the kick initiation hands the engine of each ensemble a stream of its own, and the scheduler the engine of each move. A path-sampling run therefore refuses an rgen of [engine], [engine0] or a numbered engine section other than "pcg64", and a seed of these sections that differs from [simulation] seed (see the keywords that take no effect). An md, md-nve or md-flux task seeds a Langevin engine with the seed and rgen of [engine].

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

Every engine runs at the temperature of one place (see the temperature keyword of the system section): GROMACS, LAMMPS, CP2K, OpenMM and AMS at the temperature their own input states, which PyRETIS reads when the run is set up and when the engine is created (for OpenMM, the integrator and the thermostats and barostats of the simulation of its module: see the temperature of an OpenMM simulation), and the internal integrators, TurtleMD and ASE at [system] temperature, which the input must set for TurtleMD and ASE. An engine of your own runs at the temperature of the class it is built on (see the temperature of a user-defined engine). An engine section may give a temperature as well. It sets no temperature: it must equal the temperature the engine of the section runs at, in the units of that engine, within a relative $10^{-9}$, else the run stops before any engine runs, with a message that names the two values, the section and the setting that holds the temperature of the engine. A [system] temperature is compared with the temperature of an engine input within the same relative $10^{-9}$.

The integrator of a path-sampling run¶

A path-sampling run ([simulation] task retis, tis, explore, pptis or repptis) reverses the velocities of a frame and draws new velocities at a frame, and integrates on from the positions of that frame. It needs an integrator that stores the velocities at the time of the positions it stores. A leap-frog integrator stores them half a time step away from the positions: a reversed or a shot path then does not continue the frame it starts from. A path-sampling run therefore runs with the integrators that store the velocities at the time of the positions, and refuses the others before it starts, before any message about the temperature of the engine input:

GROMACS: every integrator other than md-vv: the leap-frog md and sd, md-vv-avek, which takes the velocities a run starts from as those half a time step before it, bd (Brownian dynamics, below), and the integrators that run no dynamics (steep, nm, …); an mdp template without integrator runs GROMACS’s default md. Use integrator = md-vv, with tcoupl = v-rescale and nsttcouple = 1 for canonical dynamics (see the thermostats and barostats of a path-sampling run).
OpenMM: every integrator other than CustomIntegrator (VerletIntegrator, LangevinIntegrator, LangevinMiddleIntegrator, NoseHooverIntegrator, which integrates with a leap-frog scheme too, …), alone or in a CompoundIntegrator, and the accelerated-MD CustomIntegrator classes (AMDIntegrator, AMDForceGroupIntegrator, DualAMDIntegrator). Use a CustomIntegrator of velocity Verlet or BAOAB Langevin dynamics, whose velocities are at the time of its positions, with the global variable kT, the thermal energy in kJ/mol, which gives PyRETIS the temperature of its velocity draws, or OpenMM’s MTSLangevinIntegrator, which holds kT. A CustomIntegrator without kT that draws no random numbers (velocity Verlet, MTSIntegrator) takes the temperature of a force of the System with a temperature (a thermostat or a barostat), as an AndersenThermostat or a MonteCarloBarostat, and is refused when the System has none; one without kT that draws random numbers is refused (see the OpenMM example).
TurtleMD [engine.integrator] class = "verlet", which stores with the positions of a step the velocity of the step before. Use "velocityverlet", which takes no settings in [engine.integrator.settings], or "langevininertia", which takes the setting gamma. The engine gives the integrator its time step and, to "langevininertia", its inverse temperature and its seed; a setting the integrator does not take, timestep, beta, seed and a missing gamma are refused before the run writes a file.
LAMMPS fix langevin with gjf vhalf, which integrates with the Gronbech-Jensen-Farago Langevin scheme and stores the velocities half a time step away from the positions. Use fix nve with fix langevin without gjf (or with gjf no), fix temp/csvr or fix temp/csld (see the thermostats and barostats of a path-sampling run). A lammps.in with fix gjf or a brownian fix states no temperature that PyRETIS reads, and every task refuses it (see the LAMMPS engine).
Brownian dynamics, which integrates the positions without velocities: GROMACS integrator = bd, OpenMM BrownianIntegrator, TurtleMD "langevinoverdamped" and LAMMPS fix brownian, brownian/sphere, brownian/asphere and brownian/poly. A path-sampling run of Brownian dynamics runs with the internal Langevin engine with high_friction = true, whose path sampling the method validation of PyRETIS covers (its bd_* cases).

The internal Verlet, Velocity Verlet and Langevin engines, LAMMPS (fix nve and the thermostat fixes above, with run_style verlet or respa), CP2K, ASE and AMS integrate with velocity Verlet or a Langevin scheme built on it, which store the velocities at the time of the positions. The md, md-nve and md-flux tasks run with the internal engines, GROMACS, CP2K and LAMMPS, with every integrator of them whose temperature PyRETIS reads; OpenMM, TurtleMD, ASE and AMS run the path-sampling tasks, and an md, md-nve or md-flux task with one of them, by its [engine] class, is refused before it starts, before any message about a temperature.

A continuation ([initial-path] method = "restart", or pyretis run -i output.toml) of a run whose input has an integrator above, or a thermostat, a barostat or a force that a path-sampling run refuses (see the thermostats and barostats of a path-sampling run), is refused before it writes a file: a continuation adds cycles to those of the earlier run. Start a new run from its paths with [initial-path] method = "load" (see the load method) and the dynamics the message advises.

The types of engine are:

Table 21 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.
ASE	External engine, using an ASE calculator.
AMS	External engine, using AMS (proprietary; see note).
User-defined	Internal/External engine, user-defined.

The thermostats and barostats of a path-sampling run¶

Every piece of trajectory that a path-sampling run generates (the backward and the forward piece of a shooting move, the extension of a path in a swap move, …) starts the engine afresh from a stored frame: the positions, the velocities and, where the frame stores it, the box. A thermostat or a barostat that keeps a memory of its own from one time step to the next (the friction variables of a Nose-Hoover chain, the velocity of the box of a barostat, the step count of a coupling applied every N time steps, the target of a temperature ramp) starts that memory again with each piece. A path follows one dynamics from its first frame to its last with the schemes that keep no such memory and start each piece from the frame: velocity Verlet (NVE), Langevin dynamics, stochastic velocity rescaling (CSVR) at every time step, and the Andersen thermostat.

With GROMACS, OpenMM, LAMMPS and CP2K, a path-sampling run reads the thermostat and the barostat of each engine section it uses, before it writes a file of the run (pyretis run -i retis.rst of a legacy .rst input first writes its retis.toml twin, see the migration guide). It checks each engine section in turn: its integrator first (see the integrator of a path-sampling run), then its thermostat and barostat, and both before any message about the temperature of the engine input. A continuation of a run whose input has a scheme refused below is refused as for a refused integrator: start a new run from its paths with [initial-path] method = "load".

It refuses the deterministic schemes that carry a memory between time steps or that lack time reversibility: Nose-Hoover thermostats and their chains, the Berendsen thermostat and barostat, the Parrinello-Rahman and MTTK barostats, plain velocity rescaling, and the other deterministic changes of the velocities that are not time reversible (a momentum reset at a threshold, a velocity reversal at a plane, a velocity exchange between atoms). The message names the input file (for OpenMM, the force and the integrator), the setting and what to use instead.
It warns, and the run goes on, for a scheme that makes the pieces of a path follow different dynamics: a stochastic scheme with a memory between time steps, a coupling applied every N > 1 time steps or at an interval the MD program chooses (the GROMACS default -1), a temperature ramp of an OpenMM CustomIntegrator, and a scheme that changes the velocities, the positions or the box at the start of each piece. Each warning is logged once per engine section when the run is set up, in pyretis.log and on the console: The engine of [engine]: and a text that names the input file or the OpenMM object and the scheme, why it makes the path sampling inexact, and what to set for exact path sampling.
It accepts the other schemes without a message.

The md, md-nve and md-flux tasks, which run with the internal engines, GROMACS, LAMMPS and CP2K, accept the thermostats and barostats that path sampling refuses or warns of, when PyRETIS reads one temperature from the engine input. Every task refuses an input that sets different temperatures (a LAMMPS velocity create unlike the temperature of the thermostat, a GROMACS gen-temp unlike ref-t), whose temperature changes during the run (a GROMACS annealing, a LAMMPS Tstart other than Tstop, a CP2K ANNEALING or TEMPERATURE_ANNEALING other than 1) or that sets it in a way PyRETIS does not read (see the temperature keyword of the system section and the LAMMPS engine). The message of a path-sampling refusal of the integrator, a thermostat, a barostat or a change of the velocities of a GROMACS, LAMMPS or CP2K input ends with what the md, md-nve and md-flux tasks do with that input: they accept it when PyRETIS reads one temperature from it; else the message says that every task refuses it, and why. The refusal of a setting the check cannot use (a coupling interval mdrun never applies, a value grompp does not know, a word or a variable the LAMMPS check cannot read) and of a CP2K noise PyRETIS cannot seed ends with its own advice. For a constant pressure, equilibrate the volume with a barostat in an md task (GROMACS, LAMMPS, CP2K) or in a run of the MD program, and run the path sampling at the box of that run. The internal engines, TurtleMD and ASE select their dynamics by their integrator (see the integrator of a path-sampling run).

GROMACS (grompp.mdp, with integrator = md-vv; an option is compared as grompp compares it, in any case and with - and _ left out):

Refused: tcoupl = berendsen (also written yes) and nose-hoover; pcoupl = berendsen (also written isotropic), parrinello-rahman and mttk; a tcoupl or pcoupl value unknown to GROMACS. With tcoupl = v-rescale: nsttcouple = 0, with which mdrun never applies the thermostat while the run is read as one at ref-t, and nsttcouple below -1, which grompp keeps and with which mdrun gives velocities that are not a number. With pcoupl = c-rescale: nstpcouple = 0, with which mdrun never applies the barostat and the box stays fixed. Set tcoupl = v-rescale with nsttcouple = 1, or tcoupl = no, and pcoupl = no.
Warned: pcoupl = c-rescale, which carries the pressure of its last coupling step to the next coupling; tcoupl = v-rescale with nsttcouple above 1, and pcoupl = c-rescale with nstpcouple above 1: GROMACS couples at the time steps that are multiples of the interval, counted from the start of each piece; set nsttcouple = 1 and nstpcouple = 1. The default, -1, and an nstpcouple below -1, which grompp reads as -1, leave the interval to grompp, which resolves it by the rule of its GROMACS version (another version can choose another interval): they are warned of whenever the coupling acts on a group; set nsttcouple = 1 and nstpcouple = 1. The warning names the interval grompp of GROMACS 2025.4 resolves with the time step of the run, the [engine] timestep (each run writes it as dt): above 1 when the shortest positive tau-t is at least 10 time steps (v-rescale), or the shortest positive tau-p at least 50 time steps (c-rescale; grompp takes tau-p = 5 ps when the mdp file does not set it), else 1, every time step; 100 when no tau-t is positive and a group has tau-t = 0 (mdrun couples the groups with tau-t 0 or above). tcoupl = andersen-massive, which randomises every velocity at the first time step of each piece and then every tau-t / dt time steps, with dt the [engine] timestep; set tcoupl = v-rescale with nsttcouple = 1. Every task refuses an annealing other than no.
Accepted: tcoupl = no; v-rescale with nsttcouple = 1, or with a tau-t below 0 for every group, which mdrun couples to no thermostat; andersen; pcoupl = no.

OpenMM (the simulation of the module; see the OpenMM example):

Refused: an AndersenThermostat, a CMMotionRemover or a Monte Carlo barostat in the System when a CustomIntegrator of the simulation (also a member of a CompoundIntegrator) has no addUpdateContextState() step. Such a force acts only in that step, so it would leave the dynamics unchanged, while the temperature of a thermostat or a barostat is read as a temperature of the run and the velocities are drawn for a System whose CMMotionRemover keeps the centre-of-mass velocity at zero. Call integrator.addUpdateContextState() at the start of the steps of the CustomIntegrator, or remove the force (createSystem(..., removeCMMotion=False) builds a System without a CMMotionRemover). A CustomIntegrator (also a member of a CompoundIntegrator) that carries a global or per-degree-of-freedom variable from one time step to the next (a step reads the variable before it sets it) and whose time steps draw no random numbers: no uniform or gaussian in its expressions, and no AndersenThermostat with a collision frequency above 0 (the context parameter AndersenCollisionFrequency the simulation holds) or Monte Carlo barostat with a frequency above 0 acting in an addUpdateContextState() step. It is a deterministic scheme with a memory, as the friction variable of a Nose-Hoover thermostat written as a CustomIntegrator: each piece starts the variable at the value the integrator held when the module gave the simulation to PyRETIS. The message names the variables.
Warned: a CustomIntegrator that carries a variable from one time step to the next and whose time steps draw random numbers (in its expressions, or through an AndersenThermostat or a Monte Carlo barostat acting in an addUpdateContextState() step), a stochastic scheme with a memory; the warning names the variables. A CustomIntegrator whose steps set kT, a temperature ramp: each piece starts kT at the value the integrator held when the module gave the simulation to PyRETIS, the value the run reads as its temperature. A Monte Carlo barostat (MonteCarloBarostat, MonteCarloAnisotropicBarostat, MonteCarloMembraneBarostat, MonteCarloFlexibleBarostat, RPMDMonteCarloBarostat) with a frequency above 0, which attempts its volume moves at time steps counted from the start of each piece and adapts the size of its trial moves to their acceptance; remove it and run at the box of an equilibrated constant-pressure run. A CMMotionRemover with a frequency N above 1, which sets the centre-of-mass velocity to zero at the time steps whose step count is a multiple of N, counted from 0 at the start of each piece; set the frequency to 1, or remove it.
Accepted: a CustomIntegrator whose steps set every variable before they read it, with kT given once, as a global variable that no step sets: velocity Verlet, BAOAB Langevin dynamics (as MTSLangevinIntegrator), velocity Verlet with an AndersenThermostat in the System and an addUpdateContextState() step, and velocity Verlet with stochastic velocity rescaling (CSVR); a CMMotionRemover with frequency 1. PyRETIS reads which variables the steps of a CustomIntegrator carry and whether they draw random numbers; that its steps are time reversible is the contract of the module. A deterministic CustomIntegrator that carries no variable and rescales the velocities, as a Berendsen thermostat, runs without a message. A step that sets kT, also to its own value, counts as a temperature ramp; in a deterministic CustomIntegrator whose steps read kT before they set it, kT is a carried variable, and the integrator is refused.

LAMMPS (both engines; the fix commands of lammps.in and of the files it includes, a fix that unfix deletes included, with any accelerator suffix):

Refused: fix nvt, npt, nph and every variant of them (nvt/sphere, nvt/asphere, nvt/body, nvt/eff, nvt/sllod, npt/cauchy, nvt/uef, nvt/manifold/rattle, …); rigid/nvt, rigid/npt, rigid/nph and their /small styles; bocs, tgnvt/drude, tgnpt/drude, nphug, pimd, pimd/nvt and pimd/nvt/bosonic (the Nose-Hoover equations); msst and qbmsst; pimd/langevin and pimd/langevin/bosonic with ensemble nve or nph, which integrate a ring polymer without a thermostat, with the beads of the other partitions (and with nph the cell velocity of the barostat) carried between time steps; temp/berendsen, temp/rescale, temp/rescale/eff, press/berendsen, heat and ehex, which rescale the velocities or the box; nve/limit, viscosity, thermal/conductivity and oneway, which change the velocities deterministically and without time reversibility; deform/pressure with a pressure or pressure/mean style (box pressure included), or with volume and vol/balance/p yes, which moves the box by the deviation of the pressure from its target, as press/berendsen, and a deform/pressure command whose parameters, styles and keywords PyRETIS cannot read (a word that is none of them, or a LAMMPS variable at their place). Use fix nve with fix langevin (without gjf, or gjf no), fix temp/csvr or fix temp/csld, each with the seed ${pyretis_seed}; for rigid bodies, fix rigid/nve or rigid/nve/small with the langevin keyword. The message says whether the md, md-nve and md-flux tasks accept lammps.in, by whether PyRETIS reads its temperature: every task refuses the fixes that set the temperature in a way PyRETIS does not read, as heat, ehex, msst or pimd/langevin, a thermostat fix that changes the temperature during the run, with a Tstart other than its Tstop or a temperature from a v_ variable, and a lammps.in that states no temperature.
Warned: fix gld and qtb, which carry auxiliary forces or the random numbers of a colored noise between time steps, and fix langevin and langevin/eff with gjf vfull, which carries the random force of the previous time step: the memory starts again with each piece. fix deform, and deform/pressure with its other styles, which change the box from its shape at the start of each piece, in the same direction on a piece run backward in time; run at a fixed box. fix momentum and momentum/chunk with an N other than 1, which set the momentum to zero at the time steps whose step count is a multiple of N, counted from time step 0 of each piece; set N to 1.
Accepted: fix nve, nve/sphere and nve/asphere, the fix rigid styles rigid, rigid/small, rigid/nve and rigid/nve/small, also with the langevin keyword, run_style respa, fix langevin without gjf or with gjf no, fix temp/csvr and temp/csld, fix momentum and momentum/chunk with N = 1, which act at every time step, pair_style dpd and dpd/tstat.

Every task refuses the other LAMMPS fixes and pair styles with a memory or a friction, as fix gle, ffl, nvk, gjf, press/langevin, eph, the ttm styles, viscous and damping/cundall, and pair_style dpd/fdt/energy, and a thermostat whose Tstart differs from its Tstop or whose target is a v_ variable: PyRETIS reads no temperature of the run from them (see the LAMMPS engine).

CP2K (both engines; the input with its @INCLUDE and @SET directives resolved, keywords in any case):

Refused: MOTION%MD%ENSEMBLE NPT_I, NPT_IA, NPT_F, NPE_I and NPE_F (the momentum of the box of the barostat carries between time steps, and a frame stores no cell), MSST, MSST_DAMPED and HYDROSTATICSHOCK (the velocity of the cell of a shock), NVT_ADIABATIC (Nose-Hoover chains) and REFTRAJ (no dynamics); ENSEMBLE NVT with a MOTION%MD%THERMOSTAT of TYPE NOSE, the default of a THERMOSTAT section, and ENSEMBLE NVT without a THERMOSTAT section, which CP2K stops on. Velocity rescaling: a value other than 0 of MOTION%MD%TEMP_TOL (also written TEMP_TO or TEMPERATURE_TOLERANCE) and of the TEMP_TOL of MOTION%MD%THERMAL_REGION%DEFINE_REGION, in any ensemble, and of the TEMP_TOL of MOTION%MD%SHELL with a shell model; MOTION%MD%ANNEALING other than 1; MOTION%MD%THERMAL_REGION%FORCE_RESCALING on (without a value or with a value CP2K reads as true, as T or .TRUE.), with which CP2K rescales the velocities of each DEFINE_REGION to its TEMPERATURE at the start of each of its runs: of each piece with cp2k, and of each run of subcycles steps within a piece with cp2k_steps (set it F). Momentum resets: MOTION%MD%COMVEL_TOL with any value, 0 included, which sets the velocity of the center of mass to zero in every ensemble (for velocities without a net momentum, set [tis] zero_momentum = true), and MOTION%MD%ANGVEL_TOL with any value in a cell of PERIODIC NONE, which sets the angular momentum to zero; remove them. CP2K applies the TEMP_TOL of MOTION%MD%BAROSTAT and MOTION%MD%ANNEALING_CELL in the ensembles with a barostat, and the TEMP_TOL_FAST and TEMP_TOL_SLOW of MOTION%MD%ADIABATIC_DYNAMICS in NVT_ADIABATIC, which are refused above. A shell model with a MOTION%MD%SHELL%THERMOSTAT of TYPE NOSE (or without TYPE): remove that section. The noise that the engines cannot seed: a thermostat of TYPE GLE, a CSVR thermostat with a REGION other than GLOBAL, and a CSVR thermostat of MOTION%MD%SHELL. Use ENSEMBLE NVE, ENSEMBLE LANGEVIN, or ENSEMBLE NVT with a THERMOSTAT of TYPE CSVR and REGION GLOBAL. Every task refuses an input with a MOTION%MD%THERMAL_REGION section, or with MOTION%MD%ANNEALING or TEMPERATURE_ANNEALING other than 1, whose temperature differs between regions or changes during the run.
Warned: ENSEMBLE NVT with a thermostat of TYPE AD_LANGEVIN, whose friction CP2K carries between time steps and each piece starts from the input; use ENSEMBLE LANGEVIN or a CSVR thermostat with REGION GLOBAL. A MOTION%MD%CASCADE section that is on, whose cascade velocities CP2K gives at the start of each of its runs: of each piece with cp2k, and of each run of subcycles steps within a piece with cp2k_steps; remove the section. A shell model (FORCE_EVAL%MM%FORCEFIELD%SHELL): a frame stores the atoms, and each piece starts the shells from the input; use a model without shells.
Accepted: ENSEMBLE NVE (the default), LANGEVIN, NVT with a CSVR thermostat of REGION GLOBAL, and ISOKIN; ANGVEL_TOL in a periodic cell, where CP2K applies it to no velocity; FORCE_RESCALING F; a CASCADE section that is off. MOTION%MD%VELOCITY_SOFTENING takes no effect on a path-sampling run: CP2K softens no velocities that its input gives, and each piece starts from the velocities of a frame; leave the section out.

The Verlet engine¶

The Verlet engine integrates the equations of motion according to the position Verlet scheme, $x(t + \Delta t) = 2 x(t) - x(t - \Delta t) + a(t) \Delta t^2$, with the velocities as the central differences of the positions. Each step starts from the positions, velocities and forces of the phase point it is given, with the positions one step back $x(t - \Delta t) = x(t) - v(t) \Delta t + a(t) \Delta t^2 / 2$, and ends in the positions and the velocities of the new time. The engine therefore integrates from the velocities a kick or a shooting move draws, integrates a phase point with negated velocities backward in time, and runs path sampling as well as MD. In exact arithmetic it gives the trajectory of the Velocity Verlet engine. 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 22 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 23 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 24 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	The seed of the noise of an md task; a path-sampling run refuses one other than `[simulation] seed`.
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 keyword seeds the random numbers of the stochastic integration in an MD run (task = "md", "md-nve" or "md-flux"). A path-sampling run draws the noise of the engine, in the kick initiation and in every move, from [simulation] seed, and refuses an [engine] seed that differs from it: to change the noise, for instance for an independent replica of a run, change [simulation] seed, which kicks other initial paths as well.

Default:: The default seed of an MD run 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 25 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.
conf	Names the initial configuration in the input folder.
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	Optional, `g96` or `gro`: PyRETIS writes `g96` whatever it says. Leave it out.
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).
`temperature`	Optional, in K. It sets no temperature: it must equal the temperature of the mdp file.
`masses`	The particle masses, in g/mol, of the `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.

With [runner] wmdrun, each worker of a path-sampling run runs its own command of wmdrun in place of mdrun. The kick initiation ([initial-path] method = "kick") and the md, md-nve and md-flux tasks run mdrun: the sequential kick the mdrun of [engine], the parallel kick (kick-parallel = true with kick-from = initial) the mdrun of the engine section of each ensemble’s list in [simulation] ensemble_engines.

Default:: Not any. A run without [runner] wmdrun, a kick initiation and an md, md-nve or md-flux task need it, and PyRETIS refuses them before they start when the engine section they run does not set it.

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 or conf.gro: The initial configuration (see conf).
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. Both GROMACS engines (gromacs and gromacs_steps) set continuation = no in pyretis.mdp for every GROMACS run, in every task, the md tasks included: an md-vv run then starts from the velocities of its configuration as those of the time of its positions. A path-sampling run needs integrator = md-vv in grompp.mdp and refuses md, sd, bd and md-vv-avek, and a template without integrator (GROMACS’s default is md), before it starts (see the integrator of a path-sampling run). For canonical dynamics, set tcoupl = v-rescale with nsttcouple = 1; PyRETIS seeds its random numbers (ld-seed) for each GROMACS run from the random stream of the move. A path-sampling run refuses the Berendsen and Nose-Hoover thermostats and the Berendsen, Parrinello-Rahman and MTTK barostats, and warns for pcoupl = c-rescale, a coupling every N > 1 time steps and tcoupl = andersen-massive (see the thermostats and barostats of a path-sampling run); every task refuses an annealing other than no. The md, md-nve and md-flux tasks accept every GROMACS integrator, thermostat and barostat of an mdp file from which PyRETIS reads one temperature. tinit and init-step pass to GROMACS unchanged. GROMACS writes the frames and the energies at the MD steps that are multiples of subcycles, so both GROMACS engines refuse, when they are set up (in a path-sampling run, after the checks of the integrator and of the couplings), an init-step that is not a multiple of subcycles: the first frame of a run would not be its start, and a leg would not start at its shooting point. A sub-path of multiresolution wire fencing runs with the subcycles of mwf_subcycle_small_by_ensemble or mwf_subcycle_small (by default subcycles // 5) and is refused, before the leg of the sub-path runs, if init-step is not a multiple of them: set init-step to a multiple of both, such as 0, or mwf_subcycle_small to a divisor of init-step. An MD task (md, md-nve, md-flux) with class = "gromacs" records at step i the frame GROMACS writes at the MD step init-step + i * subcycles and the energies of that MD step, and refuses, before GROMACS runs, a start time tinit + init-step * timestep below 0.
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 a conversion of the initial configuration to the other format – 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 conf¶

conf = string

The conf keyword names the initial configuration, a .g96 or .gro file in the folder set by input_path. The engine and the system created for an initial path start from this file; a .gro file is converted to .g96 in the engine’s pyretis-gromacs-* directory.

Without conf, the initial configuration is the conf.g96 or the conf.gro staged in input_path:

when one of them is staged, it is used;
when both are staged and hold the same configuration – the same atoms, and positions, velocities and box that agree to the decimals of the .gro file, as a conversion of one into the other gives – conf.g96 is used, and the log says so;
when both are staged and hold different configurations, the run stops before it starts, with an error naming both files: set conf to the one to start from, or remove the other.

Default:: Resolved from the staged conf.g96 and conf.gro as above.

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 is optional and can be set to g96 or gro. PyRETIS writes every configuration it hands to GROMACS, as a shooting point or the frame a propagation continues from, in the g96 format, whatever gmx_format says: 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. gmx_format = gro is accepted, with a warning, for inputs of earlier versions; leave the keyword out of a new input.

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. gmx_format does not choose the configuration the run starts from: the conf keyword does.

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. The GROMACS engines draw the velocities of aimless shooting only, selected by a negative sigma_v. With engine (the default) the velocities are produced by GROMACS itself, with a zero-step gen_vel run whose seed is drawn from the random numbers of the move; gen_vel removes the centre-of-mass motion, so this mode requires zero_momentum = true. GROMACS scales the velocities gen_vel draws to gen-temp, so the drawn velocities have the kinetic energy of that temperature; PyRETIS writes the temperature of the engine, the one of the mdp file, as the gen-temp of the zero-step run, under the key the mdp file sets it with. With maxwell PyRETIS draws them from a Maxwell-Boltzmann distribution at the temperature of the mdp file, with the random numbers of the move, and resets the momentum as zero_momentum selects. maxwell requires one more keyword of the engine section, and without it the run stops with an error when the engine is set up: masses, the masses of the particles in g/mol, as a list with one mass per particle or as the name of a file in input_path that lists them separated by spaces, commas or line breaks, in the order of the particles of the configuration. A mass that is not a finite, positive number, or another number of masses than of particles, stops the run with an error when the engine is set up. The temperature of both modes is the one the mdp file states, gen-temp and the ref-t of a run coupled to a thermostat, which must be equal (see the temperature keyword of the system section). Neither mode re-scales the drawn velocities to an energy, 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 the continuous engine – it runs CP2K as a single persistent process for a whole propagation segment and reads its trajectory on the fly, which is faster than relaunching CP2K for every order-parameter point. A leg of cp2k writes its frames to a trajectory of its own, <leg>.xyz, and reads them from the output of the CP2K run it starts, which CP2K writes, while it runs, under a project name of the leg name, the id of the PyRETIS process and a random tag (<leg>-<pid>-<tag>-pos-1.xyz, …). When that CP2K run has ended, the output files it leaves take the name of the leg (<leg>-frc-1.xyz, …), beside <leg>.xyz, where keep_traj_fnames of the [output] section looks for the files it keeps with a path. A path-sampling run stopped with Ctrl+C or SIGTERM stops the CP2K of the legs its workers run. A run stopped while it kicks its initial paths in the PyRETIS process itself (every kick but the parallel kick, [initial-path] kick-parallel = true with kick-from = initial) can leave a leg’s CP2K running until CP2K has done its steps (stop it by its process id to free its cores); its output keeps the project name, and a run started again or resumed in the same directory reads none of it. A SIGKILL (kill -9) of the PyRETIS process leaves its workers running: each goes on with the move or the kick it runs, starting and stopping CP2K for its legs, and does not exit; stop the workers and their CP2K by their process ids before you start the run again. The SCF of every CP2K run that the engines start – the first run of a leg, of a kick step and of an md task – starts from CP2K’s initial guess, so a leg gives the same result whatever ran before it: the input names a wavefunction file that does not exist (WFN_RESTART_FILE_NAME doesnotexist.wfn) in place of one the template names, and CP2K uses the guess of the template’s SCF_GUESS (the ATOMIC guess, with a warning, for SCF_GUESS RESTART). No wavefunction is carried from one leg to another. The engines stop with an error before CP2K runs if the directory CP2K runs in holds a file of that name. The relaunches of a cp2k_steps leg continue its own trajectory, and start the SCF from the wavefunction of the previous relaunch of the leg. The input_path folder is only read. The slower relaunch-per-step engine, which chains the run through previous.restart / previous.wfn files, is selected as cp2k_steps. An md, md-nve or md-flux task runs the same with both engines, as the relaunch-per-step engine runs it: one CP2K run of subcycles MD steps from each stored step to the next, chained through those files.

Both CP2K engines seed the random numbers of each CP2K run of a move (a leg, a kick step) with seeds drawn on the random stream of the move, so a fixed PyRETIS seed reproduces a run and two legs draw different noise. An md, md-nve or md-flux task runs CP2K with the seeds of the template, with both engines. The engines write GLOBAL%SEED (the random numbers of CP2K itself, among them the initial state of a Nose-Hoover thermostat) and FORCE_EVAL%SUBSYS%SEED (the noise of ENSEMBLE LANGEVIN and of the AD_LANGEVIN thermostat), and remove an RNG_INIT section of FORCE_EVAL%SUBSYS, which would override that seed. CP2K starts the noise of a CSVR thermostat from a fixed seed, or from the records of the RNG_INIT section of the thermostat; the engines write that record for a CSVR thermostat of MOTION%MD%THERMOSTAT with REGION GLOBAL, and for the thermostat of the barostat of ENSEMBLE NPT_I, NPT_F and NPT_IA when it is a CSVR thermostat: MOTION%MD%BAROSTAT%THERMOSTAT with TYPE CSVR, or with TYPE SAME_AS_PARTICLE, the default, and a CSVR thermostat of the particles. They write no record for a template without a MOTION%MD%BAROSTAT section, so CP2K runs that template as it runs it directly (it stops, at version 2025.2). They stop with an error before the CP2K run of a move for a GLE thermostat, a CSVR thermostat with another region, and a CSVR or GLE thermostat of MOTION%MD%SHELL, whose noise they cannot seed. A path-sampling run refuses these before it starts, and with them the ensembles and thermostats that carry a memory between time steps, which the md tasks run: ENSEMBLE NVT with a Nose-Hoover thermostat and the barostats of NPT_I, NPT_F and NPT_IA (see the thermostats and barostats of a path-sampling run). Each relaunch of cp2k_steps continues the random number streams, those of the barostat included, from previous.restart and draws its own GLOBAL%SEED.

Each CP2K run that starts from a phase point (a leg of the streaming cp2k engine, the first run of a leg, each step of a kick and the first run of a plain MD simulation of either engine) reads the positions of the phase point from the xyz file PyRETIS writes. For a template whose coordinates give the names and the positions of the atoms only, a coordinate file of FORCE_EVAL%SUBSYS%TOPOLOGY in the XYZ format or a COORD section of four words per atom, that xyz file is the coordinate file of the run, and the COORD section of the template is left out. A coordinate file in another format (PDB, CRD, G96, CIF, XTL, CP2K) gives more, such as the elements, the residue and molecule names and, with CHARGE_EXTENDED, CHARGE_OCCUP or CHARGE_BETA, the charges of a PDB file, and so does a COORD line with the molecule and residue names after the position. For such a template, the run keeps the coordinate file, without USE_G96_VELOCITY, and gives the names and the positions of the phase point in the COORD section, with the molecule and residue names of the template’s COORD lines; CP2K reads them in place of those of the coordinate file and the rest from the file, so the run evaluates the force field of the template. CP2K takes the names of the COORD section, as those of an xyz file, for the names of the atomic kinds, so the configuration a simulation starts from names the atoms as the template does. The engines stop with an error before CP2K runs for such a template with more than one FORCE_EVAL%SUBSYS%TOPOLOGY or COORD section, or with a COORD section of another number of atoms than the phase point. The phase points hold every atom of the system, so the engines stop with an error before CP2K runs for a template whose FORCE_EVAL%SUBSYS%TOPOLOGY sets MULTIPLE_UNIT_CELL to a value other than 1 1 1, which would make CP2K replicate them; give every atom in the configuration instead. MULTIPLE_UNIT_CELL of FORCE_EVAL%SUBSYS%CELL is accepted, and the box PyRETIS reads from the template is the replicated cell. The CELL keywords are read as CP2K reads them, in any case, under either name of ALPHA_BETA_GAMMA (ANGLES) and without the comments. PyRETIS stops with an error when it reads the box from a template that gives the cell in another unit than [angstrom] ([deg] for the angles): write the cell in that unit. The engines stop with an error before CP2K runs, and when they read the box, for a template whose CELL sets CELL_FILE_NAME (a cell read from a file) or SYMMETRY other than NONE (a symmetry CP2K imposes on the cell vectors), whose box PyRETIS does not read as CP2K builds it: give the cell with A, B and C, or with ABC and ALPHA_BETA_GAMMA.

Each relaunch of cp2k_steps restarts from previous.restart what the EXT_RESTART section of CP2K restarts by default: the positions, the velocities, the state of the particle thermostat (the random number stream of a CSVR thermostat, and in an md task the variables of a Nose-Hoover chain) and the random number streams of the particles. A leg relaunched for each order-parameter point thus continues one MD run, as the streaming cp2k engine runs a leg in one CP2K run, to the precision of the numbers in the restart file. The input of a relaunch leaves out the COORD section of the template, the keywords of FORCE_EVAL%SUBSYS%TOPOLOGY that read a coordinate file in the XYZ format (COORD_FILE_NAME, COORD_FILE_FORMAT, NUMBER_OF_ATOMS and USE_G96_VELOCITY), and its CENTER_COORDINATES section, which moves the positions before the first step of a run. A coordinate file in another format is kept, without USE_G96_VELOCITY, and CP2K reads the names and the positions of the atoms from previous.restart in place of those of the file. It keeps the other settings of the topology, so a relaunch evaluates the force field of the template with its connectivity (CONN_FILE_NAME, CONN_FILE_FORMAT and the GENERATE and MOL_SET sections) and its exclusions; with CONN_FILE_FORMAT GENERATE, the default, each relaunch generates the connectivity from its own positions. cp2k_steps stops with an error before CP2K runs for a template with more than one FORCE_EVAL%SUBSYS%TOPOLOGY section. The input of a relaunch gives FORCE_EVAL%DFT the keyword WFN_RESTART_FILE_NAME previous.wfn in place of a RESTART_FILE_NAME or WFN_RESTART_FILE_NAME of the template; the first run of a leg, of a kick step and of an md task is given doesnotexist.wfn in the same way. A template without a FORCE_EVAL%DFT section, such as a classical METHOD FIST input, is given no DFT keyword and no wavefunction file.

The inputs that the engines write set the keywords they need in the sections of the template, in any case, and keep the other keywords and the subsections; a section that the template lacks, such as FORCE_EVAL%SUBSYS%TOPOLOGY or the EACH section of the VELOCITIES and TRAJECTORY print keys of MOTION%PRINT, is added with its keywords. The engines write the keywords PROJECT_NAME, RUN_TYPE and PRINT_LEVEL of GLOBAL in place of those of the template, also when the template names them by an alias of CP2K (PROJECT, IOLEVEL), and SEED in place of that of the template for each run they seed; the other keywords and the subsections of GLOBAL, such as EXTENDED_FFT_LENGTHS or PREFERRED_DIAG_LIBRARY, are kept. They stop with an error before CP2K runs for a template whose GLOBAL section sets OUTPUT_FILE_NAME, WALLTIME (which ends a run before its steps) or a PROGRAM_NAME other than CP2K. The engines write the keywords of the RESTART print keys of MOTION%PRINT and FORCE_EVAL%DFT%SCF%PRINT (BACKUP_COPIES 0), of FORCE_EVAL%SUBSYS%VELOCITY and of EXT_RESTART in place of those of the template, and remove the RNG_INIT section of FORCE_EVAL%SUBSYS.

cp2k_steps runs the kick of an initiation one step at a time. Each step is a CP2K run of its own, which starts from the kicked velocities with seeds of its own, as the first run of a leg does, so the state of a thermostat starts anew at each step.

The engines read the CP2K input with its preprocessor directives resolved, as CP2K does: the lines of an @INCLUDE file replace the directive, with a relative file name read from input_path, and the variables that @SET defines replace ${NAME}, ${NAME-default} and $NAME outside the comments. The checks of the thermostats, the seeds, the temperature, the cell and the constraints read the resolved input, and the inputs that the engines write for CP2K hold it, without directives. The engines stop with an error for any other directive, such as @IF and @ENDIF, for a variable without a value, and for an @INCLUDE file that does not exist.

CP2K sets the velocity components that a FIXED_ATOMS section of MOTION%CONSTRAINT fixes to zero before it propagates. The engines set them to zero in the velocities they draw, before the momentum is set to zero (of the components that move) and before the re-scale to rescale_energy, so the kinetic energies of the re-scale and of the acceptance of a soft velocity perturbation are those that CP2K propagates. They read the fixed atoms from LIST and the components from COMPONENTS_TO_FIX, and stop with an error for a section that selects atoms with MOLNAME, MM_SUBSYS or QM_SUBSYS, or excludes the QM or MM atoms. CP2K imposes the constraints of COLLECTIVE, G3X3, G4X6, HBONDS and VIRTUAL_SITE sections on the velocities in the first time step; with one of them, cp2k_steps stops with an error for rescale_energy and for a soft velocity perturbation, and draws aimless shooting velocities. A constraint section with a RESTRAINT subsection is a restraint and changes no velocity.

Keywords for the CP2K engine¶

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

Table 26 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, in the PyRETIS process and in each worker of a path-sampling run ([runner] wmdrun takes no effect on 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. For each LAMMPS run, the engine defines the LAMMPS variable pyretis_seed, a seed drawn on its random generator, and a fix or pair style of lammps.in that draws random numbers must take it as its seed; the engine stops with an error before LAMMPS runs at another seed. Each LAMMPS run starts at time step 0, and the engine stops with an error after a run whose dump has a frame k at a time step other than k * subcycles. A path-sampling run reads the fixes of lammps.in and of the files it reads (include, the branches of if), as LAMMPS reads them, and refuses before it starts a fix of Brownian dynamics and a Gronbech-Jensen-Farago fix with vhalf velocities (see the integrator of a path-sampling run), a fix whose ID, group or, for fix langevin and fix gjf, other words a LAMMPS variable gives that is not a number or one word, and the thermostat and barostat fixes that carry a memory between time steps or lack time reversibility, as fix nvt, npt, nph, temp/berendsen and temp/rescale; it warns for others, as fix gld, fix deform and fix langevin with gjf vfull (see the thermostats and barostats of a path-sampling run).

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
extra_files = [
    "potential.in",
]

Keywords for the LAMMPS engine¶

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

Table 27 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	Lists further files of `input_path` that LAMMPS reads, as files that `lammps.in` includes.
order_mode	Selects whether `class = lammps_steps` takes the order parameters from LAMMPS or from PyRETIS.
velocity_generation	Selects how shooting velocities are drawn.
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, 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, 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, in the PyRETIS process and in each worker of a path-sampling run ([runner] wmdrun takes no effect on 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. A restart file that read_restart of lammps.in names by a relative name is one of them (see A LAMMPS restart file read by lammps.in).

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. This mode is for class = lammps_steps, which takes the order parameters from that output, and its input needs no orderparameter section except to load initial paths ([initial-path] method = "load"), whose frames PyRETIS evaluates with that section; the streaming engine, class = lammps, evaluates the order parameter in PyRETIS and stops with an error at set-up for order_mode = lammps. Every variable of order.in is a column of the order parameter of each frame, and LAMMPS evaluates it on the velocities of the LAMMPS run, which on a backward leg are the velocities of the path reversed; PyRETIS evaluates the order parameter of a frame on the velocities of the path. The engine is therefore set up only when each variable of order.in reads the positions and the box alone: numbers, the math functions, x[i], y[i], z[i], the box keywords (lx, xlo, vol, …), the group and region functions count, mass, charge, xcm, bound, gyration and inertia of a group that is not dynamic, other variables of these, and the computes com, gyration, coord/atom, centro/atom, cna/atom, cluster/atom, orientorder/atom, hexorder/atom, property/atom of positions, identities and image flags, and reduce and reduce/region of these. A variable that reads a velocity (vx[i], vcm(), ke, temp, …), a fix, a $ substitution or any other word stops the set-up with an error that names it: set order_mode = pyretis with an orderparameter section for such an order parameter. A run in this mode that also has an orderparameter section, which PyRETIS evaluates with the collective-variable sections for the frames it reads, as those of a load, needs the two to be one order parameter: each frame LAMMPS propagates is evaluated with both, and the first frame whose two have another number of columns, or a column whose values differ by more than 1e-6, stops the run with an error. x[1] of LAMMPS is the position of atom 1 wrapped into the box, and differs by a box length from the unwrapped position that pyretis_position with periodic = false gives once the atom has crossed a periodic boundary. Set order_mode = pyretis to sample on the orderparameter section.

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: class = lammps_steps runs LAMMPS for the maximum path length and cuts the path after evaluating the order parameter, and class = lammps stops LAMMPS once the path is complete.

class = lammps evaluates the orderparameter section in Python, and a run without one stops with an error when the ensembles are set up. Leave order_mode out with class = lammps: it takes order_mode = pyretis only.

With order_mode = pyretis, both engines evaluate the order parameter of a frame on the configuration of LAMMPS translated by the lower bounds of its box, and in either mode so does PyRETIS for a frame that it reads back from a stored .lammpstrj file, as at a load: the unwrapped positions of the atoms from the lower bounds, x + ix * (xhi - xlo) - xlo along x (the xu of LAMMPS minus xlo) and so on along y and z, in a box of the box lengths of the frame whose lower bounds are 0. A dump with the unwrapped columns xu yu zu gives these positions from them, xu - xlo along x, with or without the columns x y z and ix iy iz beside them. A dump of scaled positions (the columns xs ys zs of dump atom, or xsu ysu zsu) gives the positions its box defines, xlo + xs * (xhi - xlo) along x in an orthogonal box. A non-periodic position or distance follows an atom across a periodic boundary, a periodic position wraps into [0, xhi - xlo), and a permeability coordinate is relative to the box of the frame, also when a barostat moves its bounds. Both engines give the same order parameter for a configuration. A frame of a triclinic box is evaluated in the orthogonal box of its bounds when its tilt factors xy, xz and yz are 0, and a frame of a tilted box stops the run with a NotImplementedError; with order_mode = lammps, LAMMPS evaluates the order parameter of the frames it propagates.

With order_mode = pyretis, a restart compares the order values that its paths store with the values of their frames, and stops with a ValueError when they differ, as for a run started by an earlier version of PyRETIS that evaluated them on other positions. Start a new run from such paths with [initial-path] method = “load”, which evaluates the order parameter of their frames.

The order parameter of a configuration held in a LAMMPS data file, which class = lammps evaluates when the ensembles are set up, takes the positions and the image flags of the Atoms section and the velocities of the Velocities section. A data file without a Velocities section has zero velocities, as LAMMPS read_data gives its atoms. The Velocities section is read as LAMMPS reads it, below the Atoms section, with a row atom-ID vx vy vz for each atom of the header; a section that LAMMPS stops at, a second Velocities section or a row that repeats the atom ID of an earlier row stops the run with an error that names the file.

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 at the SET_TEMP variable of lammps.in, scaled to the kinetic energy of that temperature, so lammps.in must define SET_TEMP: a lammps.in without it stops the run, naming the variable, when the run is set up and when the engine is created, also when it states the temperature with a thermostat fix, a thermostat pair style (dpd/tstat, dpd/ext/tstat) or a velocity command. PyRETIS writes the mom keyword of velocity create 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 at the temperature of lammps.in, with the random numbers of the move, and resets the momentum as zero_momentum selects. The order parameter of the drawn frame is evaluated after each draw, by PyRETIS with order_mode = pyretis and by a LAMMPS run of zero time steps from the frame with order_mode = lammps, so that a kick and a shooting move compare the order parameter of the frame they integrate from. 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_steps and engine, the draw gives a system with constraints, for its constrained motions, the velocities that velocity create gives a system without them: velocities from a Gaussian distribution with their components along the constraints removed, scaled so that the temperature LAMMPS computes, with the constrained degrees of freedom counted, is SET_TEMP. velocity create scales the velocities it creates to SET_TEMP before the setup of a run removes these components, so, as the LAMMPS documentation of the velocity command describes, a run of 0 steps follows it, whose setup removes them, and velocity all scale re-scales the constrained velocities to SET_TEMP; the re-scale to rescale_energy follows. The constraints are those of fix rattle and of the fix rigid styles rigid and rigid/nve and their /small variants, with any accelerator suffix. PyRETIS reads every fix command of lammps.in, of the files that its include and jump commands name, which it reads as LAMMPS reads them from the folder it runs in, and of the branches of its if commands, including a fix that an unfix command deletes; it does not evaluate LAMMPS variables. A system without these fixes is drawn by velocity create alone. The first draw stops the run with an error, before LAMMPS runs, for:

fix shake and fix nve/manifold/rattle, which remove no velocity component along their constraints at the setup of a run: their first time step removes these components, with their kinetic energy, and the shot would run below SET_TEMP and rescale_energy. fix rattle takes the arguments of fix shake.
fix poems, fix rigid/meso and fix lb/rigid/pc/sphere.
A fix rigid style with the keyword infile, or whose last reinit keyword has a value other than yes, on, true or 1: its bodies do not take their velocities from those of their atoms at the setup of every run.
A fix command that names its style, or an include or jump command that names its file, by a LAMMPS variable.

With class = lammps, velocity_generation changes nothing in the run: PyRETIS draws the velocities with both values, from a Maxwell-Boltzmann distribution at the temperature of lammps.in with the random numbers of the move, and resets the momentum as zero_momentum selects. Leave the keyword out with class = lammps; to have LAMMPS draw the velocities, with velocity create, select class = lammps_steps. The velocities of a configuration held in a LAMMPS data file, as the system.data a run starts from, are drawn with the positions, image flags, masses and box of the data file (see atom_style); for a 3D system they are the velocities of the draw of a dump frame of the same configuration. The frame a draw writes keeps the image flags of the configuration. The draws leave the energy as drawn: a positive rescale_energy stops the run with an error before the draw.

The temperature of the run is the one lammps.in states: the SET_TEMP variable, the Tstart (equal to Tstop) of the thermostat fixes and of the thermostat pair styles dpd/tstat and dpd/ext/tstat, and the temperature of the velocity commands, which must agree to four machine epsilons relative (see the temperature keyword of the system section and the user guide on LAMMPS). The draws of PyRETIS are at that temperature, whichever of these settings states it; the draw of LAMMPS (class = lammps_steps with engine) is at SET_TEMP. A lammps.in that states no temperature stops the run with an error when the engine is set up.

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

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.
[system] units, when it is set, must name the units of lammps.in (the LAMMPS lj units are units = "lj"), else the run stops with an error when it is set up.

Default:: The default value is velocity_generation = engine.

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 propagation starts from a frame of a LAMMPS dump that holds wrapped coordinates (x y z) and unwrapped coordinates (xu yu zu) but no image flags, PyRETIS derives the image flags ix iy iz from them in the copy of the frame it hands to LAMMPS, and stops with an error for an atom whose xu - x is not an integer number of box lengths. The order parameter of such a frame is evaluated on xu yu zu. The dump itself is left unchanged and is read only up to that frame: a frame of a LAMMPS dump is named by its time step, the number below its ITEM: TIMESTEP line, in a phase point and in traj.txt. PyRETIS does not derive the image flags for a triclinic dump: a triclinic dump with unwrapped coordinates and no image flags stops the run with an error that asks for ix iy iz. A position is unwrapped with the edge vectors of the box, x + ix * a + iy * b + iz * c, as the LAMMPS dump command defines them.

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

The `ASE` engine¶

The ASE engine integrates the equations of motion with an integrator of the Atomic Simulation Environment (ASE), langevin or velocityverlet ([engine] integrator), on the forces of an ASE calculator that [engine.calculator_settings] names (its module and class, and the arguments of the class). The time step is in fs, and the default unit system of the engine is ase (units). An example is examples/tutorials/path_sampling/ase/H2/infinite_swapping/infswap0.toml.

[system]
temperature = 300

[engine]
class = "ase"
input_path = "."
timestep = 0.2
subcycles = 10
integrator = "langevin"
langevin_friction = 0.001
langevin_fixcm = true

The engine takes its random numbers from the random streams of PyRETIS, so a fixed seed reproduces a run, whichever worker runs a move. ASE draws the noise of the Langevin integrator and the Maxwell-Boltzmann velocities of a shooting move or a kick from a numpy generator (PCG64) that the engine seeds with one number of the random stream of the move for each leg of MD and for each velocity draw; two legs from one phase point draw different noise. The velocity Verlet integrator draws no random numbers. The engine runs, and draws the velocities of aimless shooting, at [system] temperature, in kelvin, and follows zero_momentum; a zero or positive sigma_v, and a positive rescale_energy, stop the run with an error before the draw.

A calculator that writes files, as an ASE FileIOCalculator of a DFT program, writes them in its directory. PyRETIS sets this directory, and the directory of each calculator it holds, below the directory of the move that runs: the directory of the move for a calculator whose directory is "." (the default of ASE), and <directory of the move>/qm for one given directory = "qm". With [runner] workers larger than 1, each worker’s calculations then read and write their own files. An absolute directory, or one that starts with .., stops the run with an error when the engine is set up.

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. Without an AMS installation, the construction of the engine and its MD steps are tested against a mock of scm.plams only; the velocities AMS draws are tested with a licensed AMS. 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 it has not been checked.

Keywords for the AMS engine¶

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

Table 28 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

The temperature of a user-defined engine¶

A user-defined engine runs at the temperature of the class it is built on (see the temperature keyword of the system section):

Built on an internal integrator (MDEngine, Verlet, VelocityVerlet, Langevin), it runs at [system] temperature, 1 when the input sets none, and draws both aimless and soft shooting velocities, as the internal integrators do (see sigma_v).
Built on GROMACS, LAMMPS, CP2K, OpenMM or AMS, it runs at the temperature of its input, as that engine does.
Built on any other class, such as EngineBase or ExternalMDEngine, it runs at [system] temperature, which the input must set, also when the run continues a restart file: a run whose input sets none does not start, with the message The <class> engine of [engine] runs at [system] temperature, which the input does not set. Set [system] temperature to the temperature of the run.

An engine whose constructor takes a temperature argument and runs at [system] temperature is given the temperature of the run; the default value of the argument is not used, so an engine on EngineBase with temperature=300 in its constructor runs at [system] temperature, and a run whose input sets none does not start.

Keywords for user-defined engines¶

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

Table 29 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 integrator of a path-sampling run¶

The thermostats and barostats of a path-sampling run¶

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 conf¶

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 atom_style¶

The ASE engine¶

The AMS engine¶

Keywords for the AMS engine¶

Keyword class¶

Keyword input_path¶

Keyword timestep¶

Keyword subcycles¶

User-defined engines¶

The temperature of a user-defined engine¶

Keywords for user-defined engines¶

Keyword class¶

Keyword module¶

Keyword timestep¶

Additional keywords¶

References¶

The `CP2K` engine¶

The `LAMMPS` engine¶

The `ASE` engine¶

The `AMS` engine¶