The Particles section¶

Particles are added to a simulation in the particles section:

Example Particles section:

[particles]
name = [
    "Ar",
]
ptype = [
    0,
]

[particles.position]
input_file = "initial.gro"

[particles.velocity]
generate = "maxwell"
momentum = true
seed = 0

[particles.mass]
Ar = 1.0

In this example, the particles are read from an input file called 'initial.gro' and the velocities are set according to a Maxwell distribution at the temperature of the system, the temperature keyword of the system section, and the velocities are initiate so that the total momentum is set to zero. Further, the mass of particles with name 'Ar' is set to 1.0 and all particles are named 'Ar' and assigned a particle ptype of 0.

Keywords for the Particles section¶

The following keywords can be specified for the Particles section:

Table 14 Keywords for the Particles section.¶
Keyword	Description
position	Defines how initial positions are set.
velocity	Defines how initial velocities are set.
mass	Defines the masses for the particles.
name	Defines names for the particles.
ptype	Defines the known particle types.
npart	Optional; only the analysis of an `md-flux` run reads it, to check it.
type	Takes no effect: set from `[engine] class`. Remove it from the input.

Keyword position¶

position = dictionary

The position keyword is used to set the initial positions for a simulation. It is also used to define the particles we will use in the simulation. The initial positions can be:

Generated on a lattice,
```
[particles.position]
generate = "fcc"
repeat = [
    3,
    3,
    3,
]
lcon = 1.0
```
When generating on a lattice, the following settings must be provided:
- 'generate' selects what kind of lattice to generate, valid choices are:
  - 'sc': A simple cubic lattice.
  - 'sq': A square lattice (2D) with one atom in the unit cell.
  - 'sq2': A square lattice (2D) with two atoms in the unit cell.
  - 'bcc': A body-centered cubic lattice.
  - 'fcc': A face-centered cubic lattice.
  - 'hcp': A hexagonal close-packed lattice.
  - 'diamond': A diamond-like structure.
- 'repeat' select the number of repetitions of the unit lattice in the spatial directions.
- 'lcon' or 'density' which specify the size of the lattice:
  - 'lcon': Specifies the lattice constant.
  - 'density': Specifies a particle density.
The available lattices are further described in the description of the generate_lattice command from the API.
Or read from a file,
```
[particles.position]
input_file = "initial.gro"
```
When reading initial positions from a input file, the following settings must be provided:
- 'input_file' which specifies the input file to open.
PyRETIS will also attempt to read velocities from the input file when the format supports them. This includes the extended xyz format (the 6-column variant with three velocity columns vx vy vz), as well as GROMACS gro and g96 files. Velocities read this way are assumed to be in the units associated with the file format (Å/fs for xyz, nm/ps for gro and g96) and are converted to the system’s internal units on read. The resulting numbers may therefore look very different from the values written in the file, especially when the system uses reduced units such as lj.

Velocities read from the file can be used directly, so the velocity keyword is optional. If velocity = {'generate': ...} is also specified together with an input_file that provided velocities, the generated velocities override those read from the file and a warning is logged.

Note

The specified input_file name is case-sensitive.

More examples:

# Read a file from the current directory:
[particles.position]
input_file = "initial.gro"

# Read a file from another directory:
[particles.position]
input_file = "/path/to/file/initial.gro"

# Generate an fcc lattice with 4 * 5**3 = 500 particles and
# a lattice constant of 1 in reduced units:
[particles.position]
generate = "fcc"
repeat = [
    5,
    5,
    5,
]
lcon = 1.0

# Generate a bcc lattice with 2 * 5**3 = 250 particles and
# a reduced density of 0.9:
[particles.position]
generate = "bcc"
repeat = [
    5,
    5,
    5,
]
density = 0.9

Keyword velocity¶

velocity = dictionary

The velocity keyword is used to set initial velocities for the particles at the temperature of the system, the temperature keyword of the system section. It is only needed when the position source does not already provide velocities, or when the user wants to override velocities read from an input file. If specified together with an input file that contains velocities, the values produced by velocity take precedence and a warning is logged.

Example:

[particles.velocity]
generate = "maxwell"
momentum = true
seed = 0

The following settings must be provided:

'generate' which specifies the distribution to draw random velocities from. Currently, the only recognised distribution is a Maxwell distribution, which is selected by setting the value 'maxwell', as shown in the example above.
'momentum' which specifies if the resulting momentum should be zero or not. The default value is True which will generate velocities so that the total momentum is zero.
'seed' which can be used to specify a seed for the random number generator. If this value is not given a 0 will be used.

A 'temperature' setting is refused: the velocities are drawn at [system] temperature, the one place of the temperature of the system.

Keyword mass¶

mass = dictionary of floats

The mass keyword sets the masses for different particles. The provided values are assumed to be in internal units. If masses are not set, PyRETIS will try to guess them from the periodic system, however, this might fail unless the names you have used for the particles correspond to names used in the periodic system.

Example 1:

# define masses for particles with name "Ar"
[particles.mass]
Ar = 1.0

Example 2:

# define masses for particles with name "Ar", "Kr" and "big"
[particles.mass]
Ar = 1.0
Kr = 2.098
big = 10.0

Keyword name¶

name = list of strings

The name keyword is used give particles a name. This can, for instance, be used to label specific particles and, when used together with the mass keyword, it can be used to control the masses assigned to the different particles. The particle names are also used when writing output configurations.

Example:

[particles]
name = [
    "Ar",
]

The input value is a list with the particle names in the order they have been generated/read from a file by the position keyword. If the name list is too short, the last item in the list will be repeated.

This means that,

[particles]
name = [
    "Ar",
    "Kr",
]

will name one particle (the first) 'Ar' and the rest of the particles will be named 'Kr'.

Keyword ptype¶

ptype = list of integers

The ptype keyword is used to specify the particle types for the different particles. The particle type is used to distinguish particles, for instance when calculating pair interactions.

The input value is a list with the particle types in the order they have been generated/read from a file by the position keyword. If the ptype list is too short, the last item in the list will be repeated.

Example 1:

[particles]
ptype = [
    0,
    1,
]
name = [
    "Ar",
    "Kr",
]

This can be used to define a simulation where we have particles of two different ptypes with different masses.

Example 2:

[particles]
ptype = [
    0,
]
name = [
    "Ar",
    "Ar2",
    "Ar",
]

This can be used to define a simulation where we have only particles of the same ptype, however, one of the particles have a different name than the others and can, for instance, be assigned a different mass.

Keyword npart¶

npart = integer

The npart keyword states the number of particles in total in the simulation. Only pyretis analyse of an md-flux run reads it, to check it against the number of particles of the run (see below); it takes no effect on the other runs. It does not need to be set, also when the run has more particles than particle names with a mass: the energy analysis reads the number of particles from the restart file of the run, and takes none from mass. A run does not use it and does not check it: pyretis run accepts any npart without a message and copies it into the out.toml it stores, so the analysis of that out.toml checks it too. Leave it out of the input of a run. When a run stated an npart that is not its number of particles, the energy analysis of its input and of its out.toml does not run when it reads the restart file of the run, and does not run at all when the stated npart is not a positive integer (see below): remove the line from the file you analyse, or set it to the number of particles of the run, which the message gives when the stated npart is a positive integer.

The energy analysis draws, over the histograms of the kinetic energy per particle and of the temperature, their Boltzmann distributions at [system] temperature for a run of the internal engine Langevin with high_friction = false in a box without periodic dimensions: the kinetic energy of such a run follows the Boltzmann distribution at [system] temperature with all the degrees of freedom of its particles, the number of particles times [system] dimensions, which its temperature counts. The analysis reads the number of particles, the degrees of freedom that the temperature of the run counts and the engine of the run from the restart file that records the particles of the run: the pyretis.restart the run writes in its directory, or, for a run with [simulation] restart, the restart file it continues, whose engine the continuation runs (see the restart of an md task). The [engine] of the file you analyse does not decide it, except for a continuation with flexible_restart = true (below).

The energy analysis draws neither curve for these runs, and writes its histograms, block analyses and figures without them:

A run of Verlet or VelocityVerlet, in any box. These integrate Newton’s equations of motion at constant total energy (NVE): the kinetic energy of the run is set by the total energy of the particles, not by [system] temperature, and follows no Boltzmann distribution at that temperature. The first 40000 steps of the low-barrier 2D WCA tutorial (examples/tutorials/path_sampling/internal/2D-wca/low-barrier/flux), for example, have the mean temperature 0.90 with the standard deviation 0.14, where the Boltzmann distribution at [system] temperature = 1.0 with the 16 degrees of freedom of its temperature has 1.0 and 0.35.
A Langevin run with high_friction = true. Its overdamped integration stores the random displacement of each step as the velocities of the particles, so the kinetic energy and the temperature of its energy file follow no Boltzmann distribution at [system] temperature.
A Langevin run in a box with a periodic dimension (see periodic). The temperature of the run counts the number of particles times [system] dimensions degrees of freedom, less one for each periodic dimension, the motion of the centre of mass, which Langevin does not conserve: its kinetic energy keeps all the degrees of freedom of its particles.
A run on an engine that [engine] module names, one built on Langevin included, and a run whose restart file does not say which engine ran, or with which high_friction (it records no [engine] class, no state of the engine or the state of another engine, or a high_friction that is neither true nor false): the analysis does not know that the kinetic energy of the run follows the Boltzmann distribution.
A continuation with flexible_restart = true whose input names another [engine] class or module than the restart file it continues: the analysis does not know the engine of the run.
A run on an external engine (CP2K, GROMACS, LAMMPS). Its energy file holds the kinetic energy as the engine reports it (the total kinetic energy for CP2K and GROMACS; for LAMMPS, the kinetic energy per atom in lj units and the total kinetic energy in other units), and the temperature over the degrees of freedom that the engine counts (it subtracts constraints, virtual sites or the motion of the centre of mass), which the analysis does not know.
A run whose restart file is not found (it was removed, or the run was killed or stopped with an error before it wrote one) or cannot be read (the message names the error of the reading). npart gives no degrees of freedom and does not replace the restart file: analyse the run where its restart file is found and can be read.

A warning and the report say why, and pyretis analyse exits with status 0.

An analysis that reads no [system] temperature runs no energy analysis at all: the flux and order parameter analyses complete and their reports are written, the report says why the energy analysis did not run, and pyretis analyse exits with status 1. For example, the analysis of the input of a run reads no [system] temperature when the run is on an engine that [engine] module names, whose temperature the analysis does not read, or on an external engine whose input the analysis cannot read or whose input states another temperature than [system] temperature. The out.toml that this PyRETIS stores for the run records the temperature it ran at: analyse it instead (see the temperature of an analysis).

A stated npart is checked against the number of particles that the restart file of a run on an internal engine records, wherever the analysis reads that file, and takes no other effect. On an external engine, and when the restart file is not found or cannot be read, it is not compared with a number of particles, and takes no effect when it is a positive integer. When the energy analysis runs and draws no curve, a warning says that a stated npart took no effect, or none other than the check.

The energy analysis alone does not run, with a message that says why, when npart is not a positive integer; when npart differs from the number of particles that the restart file records (leave npart out, or set it to that number); when the restart file is read and records particles without a type, or particles of an internal engine without a whole record of their number, masses and velocities and of the degrees of freedom of the temperature of the run (the message says what is missing or does not agree; analyse the run with the restart file that PyRETIS wrote for it); and when the temperature of the run counts no degree of freedom in a dimension (one particle in a periodic box). The flux and order parameter analyses complete and their reports are written, the report says why the energy analysis did not run, and pyretis analyse exits with status 1.

Default: None: the analysis reads the number of particles from the restart file of the run; mass gives no number of particles.

Keyword type¶

type = string

type takes no effect on any run: PyRETIS sets it from the engine that [engine] class names, "external" for the GROMACS, CP2K and LAMMPS engines and "internal" for the others, and replaces the value an input gives without a message. How the trajectories are held follows from the engine, whatever the input sets here. Remove the line from the input.