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 ID, 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 only be updated when the underlying particle data has changed, so you can reuse the same sampler with multiple observable modules for optimal performance.

acquire(name)

Returns data slot to acquire phase space sample for the given particle array.

Parameters:name (string) – identifier of the particle array to be sampled

The memory location of the sample depends on the type of the particle array. GPU particle arrays (e.g. “g_position”) will be sampled to GPU memory, host wrappers (e.g. “position”) will be sampled to Host memory.

acquire_position()

Returns data slot to acquire position data. The memory type is inferred from the particle instance (for GPU particles this samples the “g_position” data, for Host particles the “position” data).

acquire_velocity()

Returns data slot to acquire velocity data. The memory type is inferred from the particle instance (for GPU particles this samples the “g_velocity” data, for Host particles the “velocity” data).

acquire_species()

Returns data slot to acquire species data. This always samples to host memory, as species data is packed together with position data on GPU memory. acquire(“g_position”) can be used to obtain a GPU sample of both position and species.

acquire_mass()

Returns data slot to acquire mass data. This always samples to host memory, as mass data is packed together with velocity data on GPU memory. acquire(“g_velocity”) can be used to obtain a GPU sample of both velocity and mass.

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

Sets particle data from phase space samples.

Parameters:samples (table) – List of samples to be set. The keys of the table contain the identifiers for the particle array, the values the 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 is a table mapping identifiers to the individual data samples and has the following additional 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.