gsd.hoomd

hoomd schema reference implementation

The main package gsd.hoomd is a reference implementation of the GSD schema hoomd. It is a simple, but high performance and memory efficient, reader and writer for the schema. See hoomd-examples for full examples.

Module Contents

fl
gsd
logger
class ConfigurationData

Bases:object

Store configuration data.

Users should not need to instantiate this class. Use the configuration attribute of a Snapshot.

Attributes:

step (int): Time step of this frame (:chunk:`configuration/step`). dimensions (int): Number of dimensions (:chunk:`configuration/dimensions`). box (numpy.ndarray or array_like [float, ndim=1, mode=’c’]): Box dimensions (:chunk:`configuration/box`)

  • [lx, ly, lz, xy, xz, yz].
_default_value
validate(self)

Validate all attributes.

First, convert every array attribute to a numpy array of the proper type. Then validate that all attributes have the correct dimensions.

Ignore any attributes that are None.

Warning:
Array attributes that are not contiguous numpy arrays will be replaced with contiguous numpy arrays of the appropriate type.
class ParticleData

Bases:object

Store particle data chunks.

Users should not need to instantiate this class. Use the particles attribute of a Snapshot.

Instances resulting from file read operations will always store per particle quantities in numpy arrays of the defined types. User created snapshots can provide input data as python lists, tuples, numpy arrays of different types, etc… Such input elements will be converted to the appropriate array type by validate() which is called when writing a frame.

Attributes:
N (int): Number of particles in the snapshot (:chunk:`particles/N`). types (list[str]): Names of the particle types (:chunk:`particles/types`). position (numpy.ndarray or array_like [float, ndim=2, mode=’c’]): Nx3 array defining particle position (:chunk:`particles/position`). orientation (numpy.ndarray or array_like [float, ndim=2, mode=’c’]): Nx4 array defining particle position (:chunk:`particles/orientation`). typeid (numpy.ndarray or array_like [uint32, ndim=1, mode=’c’]): N length array defining particle type ids (:chunk:`particles/typeid`). mass (numpy.ndarray or array_like [float, ndim=1, mode=’c’]): N length array defining particle masses (:chunk:`particles/mass`). charge (numpy.ndarray or array_like [float, ndim=1, mode=’c’]): N length array defining particle charges (:chunk:`particles/charge`). diameter (numpy.ndarray or array_like [float, ndim=1, mode=’c’]): N length array defining particle diameters (:chunk:`particles/diameter`). body (numpy.ndarray or array_like [int32, ndim=1, mode=’c’]): N length array defining particle bodies (:chunk:`particles/body`). moment_inertia (numpy.ndarray or array_like [float, ndim=2, mode=’c’]): Nx3 array defining particle moments of inertia (:chunk:`particles/moment_inertia`). velocity (numpy.ndarray or array_like [float, ndim=2, mode=’c’]): Nx3 array defining particle velocities (:chunk:`particles/velocity`). angmom (numpy.ndarray or array_like [float, ndim=2, mode=’c’]): Nx4 array defining particle angular momenta (:chunk:`particles/angmom`). image (numpy.ndarray or array_like [int32, ndim=2, mode=’c’]): Nx3 array defining particle images (:chunk:`particles/image`).
_default_value
validate(self)

Validate all attributes.

First, convert every per particle attribute to a numpy array of the proper type. Then validate that all attributes have the correct dimensions.

Ignore any attributes that are None.

Warning:
Per particle attributes that are not contiguous numpy arrays will be replaced with contiguous numpy arrays of the appropriate type.
class BondData(M)

Bases:object

Store bond data chunks.

Users should not need to instantiate this class. Use the bonds, angles, dihedrals, or impropers attribute of a Snapshot.

Instances resulting from file read operations will always store per bond quantities in numpy arrays of the defined types. User created snapshots can provide input data as python lists, tuples, numpy arrays of different types, etc… Such input elements will be converted to the appropriate array type by validate() which is called when writing a frame.

Note:

M varies depending on the type of bond. The same python class represents all types of bonds.

Type M
Bond 2
Angle 3
Dihedral 4
Improper 4
Attributes:
N (int): Number of particles in the snapshot (:chunk:`bonds/N`, :chunk:`angles/N`, :chunk:`dihedrals/N`, :chunk:`impropers/N`, :chunk:`pairs/N`). types (list[str]): Names of the particle types (:chunk:`bonds/types`, :chunk:`angles/types`, :chunk:`dihedrals/types`, :chunk:`impropers/types`, :chunk:`pairs/types`). typeid (numpy.ndarray or array_like [uint32, ndim=1, mode=’c’]): - N length array defining bond type ids (:chunk:`bonds/typeid`, :chunk:`angles/typeid`, :chunk:`dihedrals/typeid`, :chunk:`impropers/typeid`, :chunk:`pairs/types`). group (numpy.ndarray or array_like [uint32, ndim=2, mode=’c’]): - NxM array defining tags in the particle bonds (:chunk:`bonds/group`, :chunk:`angles/group`, :chunk:`dihedrals/group`, :chunk:`impropers/group`, :chunk:`pairs/group`).
validate(self)

Validate all attributes.

First, convert every per bond attribute to a numpy array of the proper type. Then validate that all attributes have the correct dimensions.

Ignore any attributes that are None.

Warning:
Per bond attributes that are not contiguous numpy arrays will be replaced with contiguous numpy arrays of the appropriate type.
class ConstraintData

Bases:object

Store constraint data chunks.

Users should not need to instantiate this class. Use the constraints, attribute of a Snapshot.

Instances resulting from file read operations will always store per constraint quantities in numpy arrays of the defined types. User created snapshots can provide input data as python lists, tuples, numpy arrays of different types, etc… Such input elements will be converted to the appropriate array type by validate() which is called when writing a frame.

Attributes:
N (int): Number of particles in the snapshot (:chunk:`constraints/N`). value (numpy.ndarray or array_like [float32, ndim=1, mode=’c’]): N length array defining constraint lengths (:chunk:`constraints/value`). group (numpy.ndarray or array_like [int32, ndim=2, mode=’c’]): Nx2 array defining tags in the particle constraints (:chunk:`constraints/group`).
validate(self)

Validate all attributes.

First, convert every per constraint attribute to a numpy array of the proper type. Then validate that all attributes have the correct dimensions.

Ignore any attributes that are None.

Warning:
Per bond attributes that are not contiguous numpy arrays will be replaced with contiguous numpy arrays of the appropriate type.
class Snapshot

Bases:object

Top level snapshot container.

Attributes:
configuration (ConfigurationData): Configuration data. particles (ParticleData): Particle data snapshot. bonds (BondData): Bond data snapshot. angles (BondData): Angle data snapshot. dihedrals (BondData): Dihedral data snapshot. impropers (BondData): Improper data snapshot. pairs (BondData): Special pair interactions snapshot state (dict): Dictionary containing state data

See the HOOMD schema specification for details on entries in the state dictionary. Entries in this dict are the chunk name without the state prefix. For example, :chunk:`state/hpmc/sphere/radius` is stored in the dictionary entry state['hpmc/sphere/radius'].

validate(self)

Validate all contained snapshot data.

class _HOOMDTrajectoryIterable(trajectory, indices)

Bases:object

Iterable over a HOOMDTrajectory object.

next
__next__(self)
__iter__(self)
__len__(self)
class HOOMDTrajectory(file)

Bases:object

Read and write hoomd gsd files.

Args:
file (gsd.fl.GSDFile): File to access.

Create hoomd GSD files with create().

__len__(self)

The number of frames in the trajectory.

append(self, snapshot)

Append a snapshot to a hoomd gsd file.

Args:
snapshot (Snapshot): Snapshot to append.

Write the given snapshot to the file at the current frame and increase the frame counter. Do not attempt to write any fields that are None. For all non-None fields, scan them and see if they match the initial frame or the default value. If the given data differs, write it out to the frame. If it is the same, do not write it out as it can be instantiated either from the value at the initial frame or the default value.

truncate(self)

Remove all frames from the file.

_should_write(self, path, name, snapshot)

Test if we should write a given data chunk.

Args:
path (str): Path part of the data chunk. name (str): Name part of the data chunk. snapshot (Snapshot): Snapshot data is from.
Returns:
False if the data matches that in the initial frame. False if the data matches all default values. True otherwise.
extend(self, iterable)

Append each item of the iterable to the file.

Args:
iterable: An iterable object the provides Snapshot instances. This could be another
HOOMDTrajectory, a generator that modifies snapshots, or a simple list of snapshots.
read_frame(self, idx)

Read the frame at the given index from the file.

Args:
idx (int): Frame index to read.
Returns:
Snapshot with the frame data

Replace any data chunks not present in the given frame with either data from frame 0, or initialize from default values if not in frame 0. Cache frame 0 data to avoid file read overhead. Return any default data as non-writable numpy arrays.

__getitem__(self, key)

Index trajectory frames.

The index can be a positive integer, negative integer, or slice and is interpreted the same as list indexing.

Warning:
As you loop over frames, each frame is read from the file when it is reached in the iteration. Multiple passes may lead to multiple disk reads if the file does not fit in cache.
__iter__(self)
__enter__(self)
__exit__(self, exc_type, exc_value, traceback)
create(name, snapshot=None)

Create a hoomd gsd file from the given snapshot.

Args:
name (str): File name. snapshot (Snapshot): Snapshot to write to frame 0. No frame is written if snapshot is None.

Deprecated since version 1.2: As of version 1.2, you can create and open hoomd GSD files in the same call to open(). create() is kept for backwards compatibility.

Danger

The file is overwritten if it already exists.

open(name, mode='rb')

Open a hoomd schema GSD file.

The return value of open() can be used as a context manager.

Args:
name (str): File name to open. mode (str): File open mode.
Returns:
An HOOMDTrajectory instance that accesses the file name with the given mode.

Valid values for mode:

mode description
'rb' Open an existing file for reading.
'rb+' Open an existing file for reading and writing. Inefficient for large files.
'wb' Open a file for writing. Creates the file if needed, or overwrites an existing file.
'wb+' Open a file for reading and writing. Creates the file if needed, or overwrites an existing file. Inefficient for large files.
'xb' Create a gsd file exclusively and opens it for writing. Raise an FileExistsError exception if it already exists.
'xb+' Create a gsd file exclusively and opens it for reading and writing. Raise an FileExistsError exception if it already exists. Inefficient for large files.
'ab' Open an existing file for writing. Does not create or overwrite existing files.

New in version 1.2.