The Particles section

Particles are added to a simulation in the particles section:

Example Particles section:
Particles
---------
position = {'input_file': 'initial.gro'}
velocity = {'generate': 'maxwell',
            'temperature': 2.0,
            'momentum': True,
            'seed': 0}
mass = {'Ar': 1.0}
name = ['Ar']
ptype = [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 with a temperature of 2.0 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 11 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 Defines the number of particles (analysis specific).

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:

  1. Generated on a lattice,

    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.

  2. Or read from a file,

    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.

    If the specified file is a GROMACS GRO file, PyRETIS will also attempt to read velocities from the input file. These can be used rather than generating velocities with particles-velocity.

    Note

    The specified input_file name is case-sensitive.

More examples:

Particles
---------
# Read a file from the current directory
position = {'input_file': 'initial.gro'}

# Read a file from another position:
position = {'input_file': '/path/to/file/initial.gro'}

# Generate a fcc lattice with 4 * 5**3 = 500 particles and
# a lattice constant of 1 in reduced units:
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:
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 according to a specified temperature.

Example:

velocity = {'generate': 'maxwell',
            'temperature': 2.0,
            '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.
  • 'temperature' which specifies the desired temperature in internal units. If this is not provided, the value set by the input keyword temperature is used.
  • '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.

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'
mass = {'Ar': 1.0}

Example 2:

# define masses for particles with name 'Ar', 'Kr' and 'big'
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:

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,

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:

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:

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 specifies the number of particles in total in the simulation. This keyword is used by the analysis application, and does not need to be set in the input. The PyRETIS application will automatically update this keyword.

Default
None, the PyRETIS application will automatically update this keyword.