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:

Table 16 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.
User-defined	Internal/External engine, user-defined.

The Verlet engine¶

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

Example Engine section for Verlet:

Engine
------
class = Verlet # select Verlet integrator
timestep = 0.002  # time step for the integration

Keywords for the Verlet engine¶

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

Table 17 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 # select Velocity Verlet integrator
timestep = 0.002  # time step for the integration

Keywords for the Velocity Verlet engine¶

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

Table 18 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 # select Langevin integrator
timestep = 0.002  # time step for the integration
gamma = 0.3  # set gamma value,
seed = 0  # set seed for random value generator used
high_friction = False  # are we in the high friction limit?

Keywords for the Langevin engine¶

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

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

Keyword class¶

class = Langevin

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

Keyword timestep¶

timestep = float

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

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

Keyword gamma¶

gamma = float

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

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

Keyword seed¶

seed = integer

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

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

Keyword high_friction¶

high_friction = boolean

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

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

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

where $\mathbf{f}(t)$ is the force and the velocities ( $\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 settings
---------------
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

Currently, there is also an experimental gromacs2 engine implemented in PyRETIS. This engine can read the output from GROMACS on the fly, but it has not been extensively tested. It will however run faster than the gromacs engine.

Keywords for the GROMACS engine¶

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

Table 20 Keywords for the GROMACS engine.¶
Keyword	Description
class	Selects the GROMACS engine.
gmx	Defines the command used to execute the GROMACS `gmx` program.
mdrun	Defines the command used to execute the GROMACS `mdrun` program.
input_path	Defines the folder containing the input to GROMACS.
timestep	Which defines the time step.
subcycles	Which defines the number of steps GROMACS will execute before we calculate order parameters, i.e. the frequency of output from GROMACS.
maxwarn	Which sets the `-maxwarn` option of GROMACS grompp.
write_vel	Determines if velocities should be written by GROMACS or not.
write_force	Determines if forces should be written by GROMACS or not.
gmx_format	Can be used to select the format used for GROMACS configurations.

Keyword class¶

class = gromacs

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

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 version of GROMACS installed, for instance, a single precision build named gmx and a double precision build named gmx_d.

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

Keyword mdrun¶

mdrun = string

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

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

Keyword input_path¶

input_path = string

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

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

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

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

Keyword timestep¶

timestep = float

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

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

Keyword subcycles¶

subcycles = integer

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

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

Keyword maxwarn¶

maxwarn = integer

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

Default:: The default value is maxwarn = 0.

Keyword write_vel¶

write_vel = boolean

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

Default:: The default value is write_vel = True.

Keyword write_force¶

write_force = boolean

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

Default:: The default value is write_force = False.

Keyword gmx_format¶

gmx_format = string

The gmx_format keyword specifies the format to use for GROMACS configurations. It can be set to gro or g96.

Default:: The default value is gmx_format = gro.

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

Keywords for the CP2K engine¶

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

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

Keyword class¶

class = cp2k

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

Keyword cp2k¶

cp2k = string

The command used for executing CP2K.

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

Keyword input_path¶

input_path = string

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

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

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

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

Keyword timestep¶

timestep = float

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

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

Keyword subcycles¶

subcycles = integer

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

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

The `LAMMPS` engine¶

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

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

Example Engine section for lammps:

Engine
------
class = lammps
lmp = lmp
input_path = lammps_input
subcycles = 1
extra_files = ['potential.in']

Keywords for the LAMMPS engine¶

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

Table 22 Keywords for the LAMMPS engine.¶
Keyword	Description
class	Selects the LAMMPS engine.
lmp	Defines the command used to execute LAMMPS.
input_path	Defines the location of input files to use for LAMMPS.
subcycles	Which defines the number of steps LAMMPS will execute before we calculate order parameter(s).
extra_files	Defines the location of input files to use for LAMMPS.

Keyword class¶

class = lammps

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

Keyword lmp¶

lmp = string

The command used for executing LAMMPS.

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

Keyword input_path¶

input_path = string

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

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

system.data: A LAMMPS data file with the initial configuration.
lammps.in: A LAMMPS input file, defining a MD simulation.
order.in: A LAMMPS input file, defining the order parameter calculation.

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

Keyword subcycles¶

subcycles = integer

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

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

Keyword extra¶

extra_files = list of strings

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

Default:: None.

User-defined engines¶

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

Example Engine section for a user-defined engine:

Engine
------
class = VelocityVerletF
module = vvengineF.py
timestep = 0.002

Keywords for user-defined engines¶

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

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

References¶

[1]	M. P. Allen and D. J. Tildesley, Computer Simulation of Liquids, 1989, Oxford University Press.

[2]	http://www.gromacs.org

[3]	https://www.cp2k.org/

[4]	https://lammps.sandia.gov/

The Engine section¶

The Verlet engine¶

Keywords for the Verlet engine¶

Keyword class¶

Keyword timestep¶

The Velocity Verlet engine¶

Keywords for the Velocity Verlet engine¶

Keyword class¶

Keyword timestep¶

The Langevin engine¶

Keywords for the Langevin engine¶

Keyword class¶

Keyword timestep¶

Keyword gamma¶

Keyword seed¶

Keyword high_friction¶

The GROMACS engine¶

Keywords for the GROMACS engine¶

Keyword class¶

Keyword gmx¶

Keyword mdrun¶

Keyword input_path¶

Keyword timestep¶

Keyword subcycles¶

Keyword maxwarn¶

Keyword write_vel¶

Keyword write_force¶

Keyword gmx_format¶

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¶

User-defined engines¶

Keywords for user-defined engines¶

Keyword class¶

Keyword module¶

Keyword timestep¶

Additional keywords¶

References¶

The `CP2K` engine¶

The `LAMMPS` engine¶