class halmd.mdsim.particle(args)

Construct particle instance.

  • args (table) – keyword arguments
  • args.dimension (number) – dimension of space
  • args.particles (number) – number of particles
  • args.species (number) – number of species (default: 1)
  • args.memory (string) – device where the particle information is stored (optional)
  • args.precision (string) – floating point precision (optional)
  • args.label (string) – instance label (default: all)

The supported values for memory are host and gpu. If memory is not specified, the memory location is selected according to the compute device.

The supported values for precision are single and double-single if memory equals gpu, and @HALMD_HOST_PRECISION@ for host memory. If precision is not specified, the highest available precision is used.


Number of particles.


Number of particle species.


Device where the particle memory resides.


Floating-point precision of the data stored.


Instance label.


Pseudo-table providing access to the particle data:

table =["position"]["position"] = table

or using the equivalent syntax:

table = = table

The following named arrays holding per-particle data are predefined:

  • scalar integer data:
    • id: particle ID, unique within instance of halmd.mdsim.particle
    • reverse_id: maps a particle ID to its current array index in memory
  • scalar floating-point data:
  • vector integer data:
    • image: periodic image of the simulation box that contains the given particle
  • vector floating-point data:
    • force: force acting on each particle
    • position: position reduced to the original periodic simulation box
    • velocity: velocity of each particle
  • other floating-point fields:
    • potential_stress_tensor: contribution to the potential part of the stress tensor. In d dimensions, d diagonal entries of this symmetric tensor are followed by d(d-1)/2 off-diagonal entries.


Accessing particle data using this table is equivalent to calling get() and set(), respectively, and involves a full copy of the data to a lua table.


During simulation, particle arrays may be reordered in memory according to a space-filling curve, see halmd.mdsim.sorts. To access particles in initial order, use get_reverse_id() to retrieve a map from particle IDs to current particle indices in memory.


Returns particle data identified by the name of the particle array.

Parameters:name (string) – identifier of the particle array
set(name, data)

Set particle data identified by the name of the particle array.

  • name (string) – identifier of the particle array
  • data (table) – table containing the data

Shift all velocities by vector.

shift_velocity_group(group, vector)

Shift velocities of group by vector.


Rescale magnitude of all velocities by scalar.

rescale_velocity_group(group, scalar)

Rescale magnitude of velocities of group by scalar.

shift_rescale_velocity(vector, scalar)

First shift, then rescale all velocities.

shift_rescale_velocity_group(group, vector, scalar)

First shift, then rescale velocities of group.


Enable the computation of auxliliary variables in the next on_force() step. These are: stress_pot and potential_energy and derived properties (such as the internal energy or the virial). The auxiliary variables should be activated like this:

sampler:on_prepare(function() particle:aux_enable() end, every, start)

Connect nullary slot to signal.

Returns:signal connection

Connect nullary slot to signal.

Returns:signal connection

Connect nullary slot to signal.

Returns:signal connection
Parameters:other – instance of halmd.mdsim.particle

Implements the equality operator a = b and returns true if the other particle instance is the same as this one.