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()
    end
    -- 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)
        end
        return result
    end
    -- 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
})
blocking_scheme:correlation({
    tcf = collective_msd, file = file
  , location = {"dynamics", "AA", "collective_mean_square_displacement"}
})

class halmd.observables.dynamics.correlation(args)

Construct user-defined correlation function.

Parameters:

• 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()

Acquire sample(s).

Returns:

sample

correlate(first, second)

Correlate two samples.

Parameters:

• first – first sample

• second – second sample

Returns:

value

desc

Module description.

class writer(args)

Construct file writer.

Parameters:

• args (table) – keyword arguments

• args.file – instance of file writer

• args.location (string table) – location within file

Returns:

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.