gsd.hoomd module

Read and write HOOMD schema GSD files.

gsd.hoomd reads and writes GSD files with the hoomd schema.

open - Open a hoomd schema GSD file.
HOOMDTrajectory - Read and write hoomd schema GSD files.
Snapshot - Store the state of a single frame.
- ConfigurationData - Store configuration data in a snapshot.
- ParticleData - Store particle data in a snapshot.
- BondData - Store topology data in a snapshot.

See also

See HOOMD examples for full examples.

class gsd.hoomd.BondData(M)

Store bond data chunks.

Use the Snapshot.bonds, Snapshot.angles, Snapshot.dihedrals, Snapshot.impropers, and Snapshot.pairs attributes to access the bond topology.

Instances resulting from file read operations will always store array quantities in numpy.ndarray objects of the defined types. User created snapshots may provide input data that can be converted to a numpy.ndarray.

See also

hoomd.State for a full description of how HOOMD interprets this data.

Note

M varies depending on the type of bond. BondData represents all types of topology connections.

Type	M
Bond	2
Angle	3
Dihedral	4
Improper	4
Pair	2

N

Number of bonds/angles/dihedrals/impropers/pairs in the snapshot (bonds/N, angles/N, dihedrals/N, impropers/N, pairs/N).

Type: int

types

Names of the particle types (bonds/types, angles/types, dihedrals/types, impropers/types, pairs/types).

Type: list[str]

typeid

Bond type id (bonds/typeid, angles/typeid, dihedrals/typeid, impropers/typeid, pairs/types).

Type: (N,) numpy.ndarray of numpy.uint32

group

Tags of the particles in the bond (bonds/group, angles/group, dihedrals/group, impropers/group, pairs/group).

Type: (N, M) numpy.ndarray of numpy.uint32

validate()

Validate all attributes.

Convert every array attribute to a numpy.ndarray of the proper type and check 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 gsd.hoomd.ConfigurationData

Store configuration data.

Use the Snapshot.configuration attribute of a to access the configuration.

step

Time step of this frame (configuration/step).

Type: int

dimensions

Number of dimensions (configuration/dimensions). When not set explicitly, dimensions will default to different values based on the value of \(L_z\) in box. When \(L_z = 0\) dimensions will default to 2, otherwise 3. User set values always take precedence.

Type: int

property box

Box dimensions (configuration/box).

[lx, ly, lz, xy, xz, yz].

Type: ((6, 1) numpy.ndarray of numpy.float32)

validate()

Validate all attributes.

Convert every array attribute to a numpy.ndarray of the proper type and check 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 gsd.hoomd.ConstraintData

Store constraint data.

Use the Snapshot.constraints attribute to access the constraints.

Instances resulting from file read operations will always store array quantities in numpy.ndarray objects of the defined types. User created snapshots may provide input data that can be converted to a numpy.ndarray.

See also

hoomd.State for a full description of how HOOMD interprets this data.

N

Number of constraints in the snapshot (constraints/N).

Type: int

value

Constraint length (constraints/value).

Type: (N, ) numpy.ndarray of numpy.float32

group

Tags of the particles in the constraint (constraints/group).

Type: (N, 2) numpy.ndarray of numpy.uint32

validate()

Validate all attributes.

Convert every array attribute to a numpy.ndarray of the proper type and check 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 gsd.hoomd.HOOMDTrajectory(file)

Read and write hoomd gsd files.

Parameters: file (gsd.fl.GSDFile) – File to access.

Open hoomd GSD files with open.

__enter__(): Enter the context manager.

__exit__(exc_type, exc_value, traceback): Close the file when the context manager exits.

__getitem__(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__(): Iterate over frames in the trajectory.

__len__(): The number of frames in the trajectory.

append(snapshot)

Append a snapshot to a hoomd gsd file.

Parameters: snapshot (Snapshot) – Snapshot to append.

Write the given snapshot to the file at the current frame and increase the frame counter. Do not 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.

close(): Close the file.

extend(iterable)

Append each item of the iterable to the file.

Parameters: iterable – An iterable object the provides Snapshot instances. This could be another HOOMDTrajectory, a generator that modifies snapshots, or a list of snapshots.

property file

The file handle.

Type: gsd.fl.GSDFile

read_frame(idx)

Read the frame at the given index from the file.

Parameters: 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.

Deprecated since version v2.5.

truncate(): Remove all frames from the file.

class gsd.hoomd.ParticleData

Store particle data chunks.

Use the Snapshot.particles attribute of a to access the particles.

Instances resulting from file read operations will always store array quantities in numpy.ndarray objects of the defined types. User created snapshots may provide input data that can be converted to a numpy.ndarray.

See also

hoomd.State for a full description of how HOOMD interprets this data.

N

Number of particles in the snapshot (particles/N).

Type: int

types

Names of the particle types (particles/types).

Type: tuple[str]

position

Particle position (particles/position).

Type: (N, 3) numpy.ndarray of numpy.float32

orientation

Particle orientation. (particles/orientation).

Type: (N, 4) numpy.ndarray of numpy.float32

typeid

Particle type id (particles/typeid).

Type: (N, ) numpy.ndarray of numpy.uint32

mass

Particle mass (particles/mass).

Type: (N, ) numpy.ndarray of numpy.float32

charge

Particle charge (particles/charge).

Type: (N, ) numpy.ndarray of numpy.float32

diameter

Particle diameter (particles/diameter).

Type: (N, ) numpy.ndarray of numpy.float32

body

Particle body (particles/body).

Type: (N, ) numpy.ndarray of numpy.int32

moment_inertia

Particle moment of inertia (particles/moment_inertia).

Type: (N, 3) numpy.ndarray of numpy.float32

velocity

Particle velocity (particles/velocity).

Type: (N, 3) numpy.ndarray of numpy.float32

angmom

Particle angular momentum (particles/angmom).

Type: (N, 4) numpy.ndarray of numpy.float32

image

Particle image (particles/image).

Type: (N, 3) numpy.ndarray of numpy.int32

type_shapes

Shape specifications for visualizing particle types (particles/type_shapes).

Type: tuple[dict]

validate()

Validate all attributes.

Convert every array attribute to a numpy.ndarray of the proper type and check 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 gsd.hoomd.Snapshot

Snapshot of a system state.

configuration

Configuration data.

Type: ConfigurationData

particles

Particles.

Type: ParticleData

bonds

Bonds.

Type: BondData

angles

Angles.

Type: BondData

dihedrals

Dihedrals.

Type: BondData

impropers

Impropers.

Type: BondData

pairs

Special pair.

Type: BondData

constraints

Distance constraints.

Type: ConstraintData

state

State data.

Type: dict

log

Logged data (values must be numpy.ndarray or array_like)

Type: dict

validate(): Validate all contained snapshot data.

gsd.hoomd.open(name, mode='rb')

Open a hoomd schema GSD file.

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

Parameters

name (str) – File name to open.
mode (str) – File open mode.

Returns

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.
`'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.
`'xb'`	Create a gsd file exclusively and opens it for writing. Raise `FileExistsError` if it already exists.
`'xb+'`	Create a gsd file exclusively and opens it for reading and writing. Raise `FileExistsError` if it already exists.
`'ab'`	Open an existing file for writing. Does not create or overwrite existing files.