Phase Space

A phase_space sampler acquires particle coordinates from an instance of particle or particle_group. The sampler can copy particle data from host to host, gpu to host, or gpu to gpu memory. The particles are ordered by tag, which guarantees that a particle has the same array index over the course of the simulation.

class halmd.observables.phase_space(args)

Construct phase_space sampler.

Parameters:
  • args (table) – keyword arguments
  • args.group – instance of halmd.mdsim.particle_group
  • args.box – instance of halmd.mdsim.box

Note

The sample will be updated at most once per step, so you can reuse the same sampler with multiple observable modules for optimal performance.

acquire(args)

Returns data slot to acquire phase space sample.

Parameters:
  • args (table) – keyword arguments (optional)
  • args.memory (string) – memory location of phase space sample (optional)

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

position()

Returns data slot that acquires phase space sample and returns position array.

Returns:data slot that returns position array in host memory
velocity()

Returns data slot that acquires phase space sample and returns velocity array.

Returns:data slot that returns velocity array in host memory
species()

Returns data slot that acquires phase space sample and returns species array.

Returns:data slot that returns species array in host memory
mass()

Returns data slot that acquires phase space sample and returns mass array.

Returns:data slot that returns mass array in host memory
set(sample)

Set positions, velocities, species and masses from phase space sample.

disconnect()

Disconnect phase_space sampler from profiler.

group

The particle group used by the sampler.

class writer(args)

Write trajectory of particle group to file.

http://nongnu.org/h5md/h5md.html#particles-group

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

instance of group writer

The table fields specifies which data fields are written. It may either be passed as an indexed table, e.g. {"position", "velocity"}, or as a dictionary, e.g., {r = "position", v = "velocity"}; the table form is interpreted as {position = "position", ...}. The keys denote the field names in the file and are appended to location. The values specify the methods of the phase_space module, valid values are position, velocity, species, mass.

The argument location specifies a path in a structured file format like H5MD given as a table of strings. If omitted it defaults to {"particles", group.label}.

If every is not specified or 0, a phase space sample will be written at the start and end of the simulation.

disconnect()

Disconnect phase_space writer from observables sampler.

class halmd.observables.phase_space.reader(args)

Construct reader for given particles group.

http://nongnu.org/h5md/h5md.html#particles-group

Parameters:
  • args (table) – keyword arguments
  • args.file – instance of file reader, e.g, halmd.io.readers.h5md
  • args.fields (string table) – data field names to be read
  • args.location (string table) – location within file
  • args.memory (string) – memory location of phase space sample (optional)

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

Returns a group reader, and a phase space sample.

The table fields specifies which data fields are read, valid values are position, velocity, species, mass. See halmd.observables.phase_space:writer() for details.

The argument location specifies a path in a structured file format like H5MD given as a table of strings, for example {"particles", group label}.

Construction of the reader module opens the file for inspection of the space dimension and particle number, which are then used to allocate a phase space sample in host memory. The sample is only filled upon calling, e.g., read_at_step().

Example:

local file = halmd.io.readers.h5md({path = "input.h5"})
local reader, sample = halmd.observables.phase_space.reader({
   file = file, fields = {"position"}, location = {"particles", "all"}
})
reader:read_at_step(0)
local nparticle = assert(sample.size)
local dimension = assert(sample.dimension)

The returned group reader has these methods.

read_at_step(step)

Read sample at given step.

If step is negative, seek backward from last (-1) sample.

read_at_time(time)

Read sample at given time in MD units.

If time is negative, seek backward from last (-0) sample.

The returned phase space sample has these attributes.

nparticle

Returns number of particles.

nspecies

Returns number of species.

Note

This attribute is determined from the maximum element of the species array.

dimension

Returns dimension of positional coordinates.