Correlation Function

This module permits the implementation of a user-defined time correlation function within the Lua simulation script.

The following example shows the use of this module together with halmd.observables.dynamics.blocking_scheme to determine the mean-square displacement of the centre of mass of a certain particle group. From this, the collective self-diffusion constant may be obtained. The centre of mass is computed efficiently by halmd.observables.thermodynamics.center_of_mass(), the squared displacement is then computed by the script function passed as correlate.

local msv = observables.thermodynamics({box = box, group = group, force = force})
local collective_msd = dynamics.correlation({
    -- acquire centre of mass
    acquire = function()
        return msv:center_of_mass()
    -- correlate centre of mass at first and second point in time
    , correlate = function(first, second)
        local result = 0
        for i = 1, #first do
            result = result + math.pow(second[i] - first[i], 2)
        return result
    -- module description
    , desc = "collective mean-square displacement of AA particles"

local blocking_scheme = dynamics.blocking_scheme({
    max_lag = max_lag
    , every = 100
    , size = 10
    , separation = separation
    tcf = collective_msd, file = file
  , location = {"dynamics", "AA", "collective_mean_square_displacement"}
class halmd.observables.dynamics.correlation(args)

Construct user-defined correlation function.

  • args – keyword arguments
  • args.acquire – callable(s) that return a (multi-dimensional) value
  • args.correlate – callable that accepts two values and returns a number or a numeric table
  • args.shape (number table) – array shape of the result (optional)
  • args.location (string table) – default location within file
  • args.desc (string) – module description

The argument acquire is a callable or a table of up to 2 callables that yield the samples to be correlated.

The argument shape specifies the array shape of the outcomes of correlate. It is only required if the result is a table. Currently, only 1-dimensional arrays are supported, for which shape = { size }.

The argument location defines the default value of writer(). For H5MD files, it obeys the structure {"dynamics", particle group, name of correlation function}.


Acquire sample(s).

correlate(first, second)

Correlate two samples.

  • first – first sample
  • second – second sample



Module description.

class writer(args)

Construct file writer.

  • args (table) – keyword arguments
  • args.file – instance of file writer
  • args.location (string table) – location within file

file writer as returned by file:writer().

The argument location specifies a path in a structured file format like H5MD given as a table of strings. It defaults to args.location passed upon construction of the correlation module.