This module calculates the instantaneous values of thermodynamic state variables for the particles of a given group.

class halmd.observables.thermodynamics(args)

Construct thermodynamics module.

  • args (table) – keyword arguments
  • – instance of halmd.mdsim.particle_groups
  • – instance of
  • args.volume – a number or a nullary function yielding the reference volume (default: box.volume)

The argument volume expects a callable function(), which is used to query the reference volume of the particle group; the volume may change in the course of the simulation. If group refers to the whole simulation domain box.volume is passed, which is the default:

volume = function() return box.volume end  -- convert box.volume into a callable, thereby capturing box

For a sub-domain, e.g., if group is an instance of region, returning a constant value may be appropriate.


Returns the number of particles N selected by


Returns the volume V as obtained from the function passed upon construction.


Returns the number density \rho = N / V.


Returns the mean kinetic energy per particle: u_{\text{kin}} = \frac{1}{N} \sum_{i=1}^N \frac{1}{2} m_i \vec v_i^2.


Returns the mean potential energy per particle: u_{\text{pot}} = \frac{1}{N} \sum_{i=1}^N U_{\text{tot}}(\vec r_i), where U_{\text{tot}} denotes the sum of external and pair potentials.


Returns the mean internal energy per particle: u_{\text{int}} = u_{\text{kin}} + u_{\text{pot}}.


Returns the pressure computed from the virial: p = \rho (k_B T + \mathcal{V} / d).


Returns the instantaneous temperature as given by the kinetic energy: k_B T = 2 u_{\text{kin}} / d.


Returns the total force: \vec F_{\text{tot}} = \sum_{i=1}^N \vec F_i.


Returns the centre-of-mass velocity: \vec v_{\text{cm}} = \sum_{i=1}^N m_i \vec v_i / \sum_{i=1}^N m_i.


Returns the centre of mass: \vec r_{\text{cm}} = \sum_{i=1}^N m_i \vec r_i' / \sum_{i=1}^N m_i, where \vec r_i' refers to absolute particle positions, i.e., extended by their image vectors for periodic boundary conditions.


Returns the mean particle mass: \bar m = \frac{1}{N} \sum_{i=1}^N m_i.


Returns mean virial per particle as computed from the trace of the potential part of the stress tensor:

\mathcal{V} = - \frac{1}{2 N} \sum_{i \neq j} r_{ij} \, U'(r_{ij}) \, .


Returns the elements of the stress tensor \Pi_{\alpha\beta} as a vector. The first d (= dimension) elements contain the diagonal followed by d(d-1)/2 off-diagonal elements \Pi_{xy},
\Pi_{xz}, \dots, \Pi_{yz}, \dots The stress tensor is computed as

\Pi_{\alpha\beta} = \sum_{i=1}^N \left[
  m_i v_{i\alpha} v_{i\beta} -
  \frac{1}{2}\sum_{j \neq i} \frac{r_{ij\alpha} r_{ij\beta}}{r_{ij}} \, U'(r_{ij})
  \right] \/,

where \vec r_{ij} = \vec r_i - \vec r_j in nearest image convention.


Space dimension d of the simulation box as a number.


Instance of halmd.mdsim.particle_groups used to construct the module.


Write state variables to a file.

  • args (table) – keyword arguments
  • args.file – instance of file writer
  • args.every (number) – sampling interval
  • args.location (string table) – location within file (optional)
  • args.fields (table) – data fields to be written (optional)

instance of group writer

The optional argument location specifies a path in a structured file format like H5MD given as a table of strings. It defaults to {"observables", and nil or group.label}.

The optional table fields specifies which data fields are written. It may either be passed as an indexed table, e.g. {"pressure"}, or as a dictionary, e.g., {p = "pressure"}; the table form is interpreted as {pressure = "pressure", …}. The keys denote the field names in the file and are appended to location. The values specify the data methods of the thermodynamics module, i.e., all methods described above except for dimension and group. The default is {"potential_energy", "pressure", "temperature", "center_of_mass_velocity"}.


Disconnect thermodynamics writer from observables sampler.