gsd.hoomd module¶
Read and write HOOMD schema GSD files.
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
for full examples.
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.
-
class
gsd.hoomd.
BondData
(M)¶ Store bond data chunks.
Use the
Snapshot.bonds
,Snapshot.angles
,Snapshot.dihedrals
,Snapshot.impropers
, andSnapshot.pairs
attributes to access the bonds.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 anumpy.ndarray
.Note
M varies depending on the type of bond.
BondData
represents all types of bonds.Type
M
Bond
2
Angle
3
Dihedral
4
Improper
4
Pair
2
-
N
¶ Number of particles in the snapshot (
bonds/N
,angles/N
,dihedrals/N
,impropers/N
,pairs/N
).- Type
-
types
¶ Names of the particle types (
bonds/types
,angles/types
,dihedrals/types
,impropers/types
,pairs/types
).- Type
typing.List
[str]
-
typeid
¶ Bond type id (
bonds/typeid
,angles/typeid
,dihedrals/typeid
,impropers/typeid
,pairs/types
).- Type
(N, 3)
numpy.ndarray
ofnumpy.uint32
-
group
¶ Tags of the particles in the bond (
bonds/group
,angles/group
,dihedrals/group
,impropers/group
,pairs/group
).- Type
(N, M)
numpy.ndarray
ofnumpy.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
-
dimensions
¶ Number of dimensions (
configuration/dimensions
).- Type
-
box
¶ Box dimensions (
configuration/box
) [lx, ly, lz, xy, xz, yz].- Type
(6, 1)
numpy.ndarray
ofnumpy.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 chunks.
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 anumpy.ndarray
.-
N
¶ Number of particles in the snapshot (
constraints/N
).- Type
-
value
¶ Constraint length (
constraints/value
).- Type
(N, )
numpy.ndarray
ofnumpy.float32
-
group
¶ Tags of the particles in the constraint (
constraints/group
).- Type
(N, 2)
numpy.ndarray
ofnumpy.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
.-
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 simple list of snapshots.
-
property
file
¶ The underlying file handle.
- Type
-
read_frame
(idx)¶ Read the frame at the given index from the file.
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.
-
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 anumpy.ndarray
.-
N
¶ Number of particles in the snapshot (
particles/N
).- Type
-
types
¶ Names of the particle types (
particles/types
).- Type
typing.List
[str]
-
position
¶ Particle position (
particles/position
).- Type
(N, 3)
numpy.ndarray
ofnumpy.float32
-
orientation
¶ Particle orientation. (
particles/orientation
).- Type
(N, 4)
numpy.ndarray
ofnumpy.float32
-
typeid
¶ Particle type id (
particles/typeid
).- Type
(N, )
numpy.ndarray
ofnumpy.uint32
-
mass
¶ Particle mass (
particles/mass
).- Type
(N, )
numpy.ndarray
ofnumpy.float32
-
charge
¶ Particle charge (
particles/charge
).- Type
(N, )
numpy.ndarray
ofnumpy.float32
-
diameter
¶ Particle diameter (
particles/diameter
).- Type
(N, )
numpy.ndarray
ofnumpy.float32
-
body
¶ Particle body (
particles/body
).- Type
(N, )
numpy.ndarray
ofnumpy.int32
-
moment_inertia
¶ Particle moment of inertia (
particles/moment_inertia
).- Type
(N, 3)
numpy.ndarray
ofnumpy.float32
-
velocity
¶ Particle velocity (
particles/velocity
).- Type
(N, 3)
numpy.ndarray
ofnumpy.float32
-
angmom
¶ Particle angular momentum (
particles/angmom
).- Type
(N, 4)
numpy.ndarray
ofnumpy.float32
-
image
¶ Particle image (
particles/image
).- Type
(N, 3)
numpy.ndarray
ofnumpy.int32
-
type_shapes
¶ Shape specifications for visualizing particle types (
particles/type_shapes
).- Type
-
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
-
particles
¶ Particles.
- Type
-
constraints
¶ Distance constraints.
- Type
-
state
¶ State data.
- Type
-
log
¶ Logged data (values must be
numpy.ndarray
orarray_like
)- Type
-
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
- 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.
'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 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.'ab'
Open an existing file for writing. Does not create or overwrite existing files.