The Engine section¶
The engine
section specifies the engine to use for the dynamics.
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:
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.
NB: Only MD is allowed for this scheme. The engine is selected by
specifying the class Verlet
and the time step:
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:
Keyword | Description |
---|---|
class | Selects the Verlet engine. |
timestep | Defines the time step. |
Keyword class¶
Verlet
.Keyword timestep¶
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:
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:
Keyword | Description |
---|---|
class | Selects the Velocity Verlet engine. |
timestep | Defines the time step. |
Keyword class¶
VelocityVerlet
.Keyword timestep¶
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:
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:
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¶
Langevin
.Keyword timestep¶
The timestep
keyword defines the time step for the
engine in internal units.
- Default:
- Not any. This keyword must be specified.
Keyword gamma¶
This is the gamma parameter (, see the integration scheme) for the Langevin integrator.
- Default:
- Not any. This keyword must be specified.
Keyword seed¶
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¶
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
isTrue
, we are in the high friction limit and the equations of motion are integrated according towhere is the deterministic force and the displacements () are drawn from a normal distribution,
If
high_friction
isFalse
, we are in the low friction limit and the equations of motion are integrated according towhere,
and , and . In this case, and 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:
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:
Keyword | Description |
---|---|
class | Selects the GROMACS engine. |
gmx | Defines the command used to execute the GROMACS
gmx program. |
mdrun | Defines the command used to execute the GROMACS
mdrun program. |
input_path | Defines the folder containing the input to GROMACS. |
timestep | Which defines the time step. |
subcycles | Which defines the number of steps GROMACS will execute before we calculate order parameters, i.e. the frequency of output from GROMACS. |
maxwarn | Which sets the -maxwarn option of GROMACS
grompp. |
write_vel | Determines if velocities should be written by GROMACS or not. |
write_force | Determines if forces should be written by GROMACS or not. |
gmx_format | Can be used to select the format used for GROMACS configurations. |
domain_decomp | Can be toggled on if domain decomposition is used in GROMACS. |
Keyword class¶
gromacs
.Keyword gmx¶
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¶
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¶
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 apyretis.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¶
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¶
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¶
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¶
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¶
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¶
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
.
Keyword domain_decomp¶
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
.
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:
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:
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¶
cp2k
.Keyword cp2k¶
The command used for executing CP2K.
- Default:
- Not any. This keyword must be specified.
Keyword input_path¶
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¶
The timestep
keyword defines the time step for the
engine in internal units.
- Default:
- Not any. This keyword must be specified.
Keyword subcycles¶
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:
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:
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¶
lammps
.Keyword lmp¶
The command used for executing LAMMPS.
- Default:
- Not any. This keyword must be specified.
Keyword input_path¶
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¶
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¶
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:
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:
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¶
Keyword module¶
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¶
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.:
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/ |