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 tolocation
. The values specify the methods of thephase_space
module, valid values areposition
,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”. Ifmemory
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 areposition
,velocity
,species
,mass
. Seehalmd.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.
The returned phase space sample is a table mapping identifiers to the individual data samples and has the following additional attributes.