The System section

The system section defines some properties of the system.

Example System section:

[system]
units = "reduced"
dimensions = 2
temperature = 1.0

Keywords for the System section

The following keywords can be set for the System section:

Table 12 Keywords for the System section

Keyword	Description
dimensions	Specify the dimensionality of the system.
temperature	Specify the temperature of the run.
units	Specify the unit system to use.

Keyword dimensions

dimensions = integer

Specify the dimensionality of the system. Should be 1, 2, or 3 for 1D, 2D or 3D, respectively.

Default:

The default value is dimensions = 3.

Keyword temperature

temperature = float

The temperature, \(T\), of the run. Every engine takes the temperature it runs at from one place:

• The internal integrators, TurtleMD and ASE run at temperature. It gives \(\beta = 1/(k_\text{B} \times T)\), with the Boltzmann constant \(k_\text{B}\) of the unit system (of the boltzmann setting for TurtleMD), for the velocities of the particles (the velocity keyword of the particles section), the velocities of a shooting move, the Langevin dynamics and the acceptance of a soft velocity perturbation. TurtleMD gives its Langevin integrator this \(\beta\), and refuses a beta in the settings of the integrator. TurtleMD takes temperature in the temperature unit of its boltzmann, and ASE in kelvin: the input of a run with either must set temperature, and a run whose input sets none does not start.

• An engine of your own, which [engine] module names (see user-defined engines), runs at the temperature of the class it is built on. Built on an internal integrator (MDEngine, Verlet, VelocityVerlet, Langevin), it runs at temperature, 1 when the input sets none. Built on GROMACS, LAMMPS, CP2K, OpenMM or AMS, it runs at the temperature of its input, as these engines do (below). Built on any other class, such as EngineBase or ExternalMDEngine, it runs at temperature, which the input must set: 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. An engine of your own that runs at temperature and whose constructor takes a temperature argument is given the temperature of the run (1 for one built on an internal integrator when the input sets none); the default value of the argument is not used.

• GROMACS, LAMMPS, CP2K, OpenMM and AMS run at the temperature their own input states, which PyRETIS reads when the engine is created: gen-temp and, for a run coupled to a thermostat (integrator = sd or bd, or tcoupl other than no), the ref-t of each tc-grps group of the mdp file; the SET_TEMP variable, the thermostat fixes, the thermostat pair styles dpd/tstat and dpd/ext/tstat and the velocity commands of lammps.in (class = "lammps_steps" with velocity_generation = "engine" asks LAMMPS to draw the velocities at SET_TEMP, and a lammps.in without it does not start such a run); MOTION/MD TEMPERATURE of the CP2K input; the temperatures the integrator and the forces of the OpenMM simulation state (see the temperature of an OpenMM simulation below); and MolecularDynamics%InitialVelocities%Temperature and the Temperature of each Thermostat of ams.inp. The settings of one input that hold a temperature must be one temperature, equal to four machine epsilons relative to the larger, as the temperatures of an OpenMM simulation below, and an input that leaves its temperature out (an mdp file without gen-temp, a CP2K input without TEMPERATURE, an OpenMM simulation that states no temperature) stops the run with a message that names what to set: the 300 K that GROMACS and CP2K take by default is not taken, and no temperature is assumed for an OpenMM simulation. For these engines temperature is optional. When it is set, it must equal the temperature of the input of every engine of the run within a relative \(10^{-9}\), else the run does not start. When it is not set and the inputs of the engines of the run state one temperature, the run sets it to that temperature, output.toml records it, and pyretis analyse reads it there. The inputs state one temperature when the lowest and the highest of their temperatures are equal to four machine epsilons relative, as the temperatures of an OpenMM simulation below. The run then takes the temperature of the first of those engine sections (the sections whose engine reads the temperature of its input), in the order [engine], [engine0], then the sections of the pool as the input lists them. The engines of a pool whose inputs state different temperatures each run at their own: temperature is then left unset, output.toml records the temperature of each engine in its engine section, and a run that also has an engine that runs at temperature does not start. An input that declares its unit system (the LAMMPS units command) must declare the one of the units keyword.

An OpenMM simulation runs at the temperature it states, in two places:

• its integrator, when the integrator has a temperature. A CustomIntegrator states it in its global variable kT, the thermal energy in kJ/mol, which PyRETIS divides by the molar gas constant MOLAR_GAS_CONSTANT_R of OpenMM (the integrator of the OpenMM example and OpenMM’s MTSLangevinIntegrator hold one): compute kT as MOLAR_GAS_CONSTANT_R times the temperature, as a kT computed with another value of the gas constant reads as another temperature. The integrator of the simulation, when its class has getTemperature (as those of openmmtools), states both temperatures, that of getTemperature first; getTemperature must return a temperature Quantity (as 300.0 * unit.kelvin). Every integrator a CompoundIntegrator holds that has a temperature states it, whether or not it is the integrator that steps the simulation, and so does every integrator of a CompoundIntegrator it holds; OpenMM gives a CustomIntegrator it holds as its own CustomIntegrator, which states the temperature of its kT only;

• each force of the System that has a temperature: a thermostat (AndersenThermostat) or a barostat (MonteCarloBarostat and the other Monte Carlo barostats).

All the temperatures the simulation states must be one temperature, else the run does not start, with a message that names each of them. Two temperatures are one temperature when they differ by at most four machine epsilons relative to the larger (for 300 K, about 2.7e-13 K): a kT computed from a temperature divides back to it within a few units in the last place. The run takes the first of them, that of the integrator the simulation steps with when that integrator has a temperature.

A CustomIntegrator without kT that draws no random numbers (none of its expressions uses uniform or gaussian), such as one of velocity Verlet or OpenMM’s MTSIntegrator, has no temperature. A simulation with such an integrator and no force with a temperature states no temperature, and is refused: the run stops before any engine runs, with a message that says how to state one. To state the temperature without changing the dynamics, add to the System an AndersenThermostat at the temperature of the run (here 300 K) with collision frequency 0, and give the CustomIntegrator an addUpdateContextState() step, in which it applies the thermostat (a path-sampling run refuses an AndersenThermostat beside a CustomIntegrator without one). It changes no velocity, and the integrator draws no random numbers, so the trajectory is that of the integrator alone, step for step. The simulation runs at the temperature of the thermostat:

system.addForce(openmm.AndersenThermostat(300 * unit.kelvin,
                                          0 / unit.picosecond))

PyRETIS reads the temperature of a CustomIntegrator from its global variable kT, spelled so. A CustomIntegrator that holds a variable named kT of another kind, a per-degree-of-freedom variable (kT, KT, kt or Kt) or a global variable in another letter case (KT, kt or Kt), alone or in a CompoundIntegrator, is refused, whatever forces the System holds: such a variable stands for the temperature of a thermostat of the integrator’s own, which PyRETIS cannot compare with the temperature the simulation states. Hold that temperature in the global variable kT.

A CustomIntegrator that draws random numbers (uniform or gaussian) and has no global variable kT, alone or in a CompoundIntegrator, is refused too, whatever forces the System holds: its random numbers act at a temperature it holds in a variable of its own, which PyRETIS does not read. Hold its thermal energy in the global variable kT, MOLAR_GAS_CONSTANT_R times the temperature, and use kT in the expressions that draw random numbers. A CustomIntegrator with kT, or one that draws no random numbers, that thermostats at a temperature held under another name, or read from a parameter of a force, runs at the temperature the simulation states, and must thermostat at that temperature.

A path-sampling run refuses every integrator of OpenMM other than a CustomIntegrator, alone or in a CompoundIntegrator (the Drude integrators, NoseHooverIntegrator and the integrators with a variable step size, VariableVerletIntegrator and VariableLangevinIntegrator, with which a step of PyRETIS has no fixed time, among them), and the accelerated-MD CustomIntegrator classes, also in a CompoundIntegrator, before any message about the temperature; the steps of the CustomIntegrator must give the velocities at the time of its positions (see the integrator of a path-sampling run). OpenMM runs the path-sampling tasks only.

An engine section ([engine], [engine0] and the numbered sections of a pool) may give a temperature too. It sets no temperature: it is compared with the temperature the engine of the section runs at, from the place given above, in the units of that engine, and the two must agree within a relative \(10^{-9}\). Otherwise 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. When the engine runs at the temperature of the kT of an OpenMM CustomIntegrator, this message, and that of a [system] temperature that differs, say how PyRETIS reads kT: kT divided by OpenMM’s MOLAR_GAS_CONSTANT_R. output.toml records it in its section. A velocity keyword of the particles section that sets temperature is refused: the velocities of the particles are drawn at the temperature of the system.

A temperature that is not a finite, positive number (a string, a boolean, a list, a table, nan, inf, zero or a negative number), here or in an engine section, is refused before the run starts, and when a resume, a continuation or pyretis analyse reads it from a run file, a restart file or an input: true is not read as the temperature 1. So is a temperature of this section so small that \(1/T\), or \(\beta = 1/(k_\text{B} \times T)\) with the Boltzmann constant of the units keyword, is not a finite number, such as 1e-320, or 1e-290 with units = "si": the message says that it is so small.

Default:

temperature = 1.0 for a run whose engines are all internal integrators, or engines of your own built on one. TurtleMD, ASE and the other engines of your own that run at temperature have no default, and neither has the umbrellawindow task, whose Monte Carlo moves are accepted at temperature: the input of such a run must set it. A run with an engine that reads its temperature from its input runs at that temperature. An md, md-nve, md-flux or umbrellawindow run that continues a restart file ([simulation] restart) and leaves temperature out runs at the temperature of the run it continues (see the restart of create_simulation); with a TurtleMD or ASE engine, or another engine without a default, its input must still set it.

Keyword units

units = string

The units keyword defines the system of units to use by PyRETIS. Currently, the following system of units are defined by PyRETIS (see the definitions of unit systems):

• lj: A Lennard-Jones type of (reduced) units (based on Argon [1]).

• real: A system of units similar to the LAMMPS [2] unit real.

• metal: A system of units similar to the LAMMPS [2] unit metal.

• au: Atomic units. [3]

• electron: A system of units similar to the LAMMPS [2] unit electron.

• si: A system of units similar to the LAMMPS [2] unit si.

• gromacs: A system of units similar to the units used by GROMACS. [4]

• openmm: nm, kJ/mol and g/mol, the units of OpenMM.

• cp2k: Å, hartree and the electron mass.

• reduced: Å, \(k_\text{B} \times 1\,\text{K}\) and g/mol, in which \(k_\text{B} = 1\).

• ase: eV, Å and fs, the energy and length units of ASE and the unit of the time step of the ASE engine.

The system of units should be one of the systems defined by PyRETIS listed above. Alternatively, you can define your own unit system by making use of a special unit-system section in combination with the units keyword.

Default:

The default is the unit system of the engine: lj for the internal integrators, gromacs for GROMACS, openmm for OpenMM, cp2k for CP2K, reduced for TurtleMD, ase for ASE, and the units command of the LAMMPS input for LAMMPS.

References

[1]

L. A. Rowley, D. Nicholson and N. G. Parsonage, Monte Carlo grand canonical ensemble calculation in a gas-liquid transition region for 12-6 Argon, J. Comput. Phys. 17, 401-414 (1975), https://doi.org/10.1016/0021-9991(75)90042-X

[2] (1,2,3,4)

The LAMMPS manual, http://lammps.sandia.gov/doc/units.html

[3]

https://en.wikipedia.org/wiki/Atomic_units

[4]

The GROMACS manual, version 5.1.1, tables 2.1 and 2.2 on page. 8, http://manual.gromacs.org/documentation/5.1.1/manual-5.1.1.pdf