gsd.hoomd module#
Read and write HOOMD schema GSD files.
gsd.hoomd
reads and writes GSD files with the hoomd
schema.
HOOMDTrajectory
- Read and write hoomd schema GSD files.Frame
- Store the state of a single frame.ConfigurationData
- Store configuration data in a frame.ParticleData
- Store particle data in a frame.BondData
- Store topology data in a frame.
open
- Open a hoomd schema GSD file.read_log
- Read log from a hoomd schema GSD file into a dict of time-series arrays.
See also
See HOOMD examples for full examples.
- class gsd.hoomd.BondData(M)#
Bases:
object
Store bond data chunks.
Use the
Frame.bonds
,Frame.angles
,Frame.dihedrals
,Frame.impropers
, andFrame.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 frames may provide input data that can be converted to anumpy.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 frame (
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
).
- typeid#
Bond type id (
bonds/typeid
,angles/typeid
,dihedrals/typeid
,impropers/typeid
,pairs/types
).- Type:
(N,)
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#
Bases:
object
Store configuration data.
Use the
Frame.configuration
attribute of a to access the configuration.- step#
Time step of this frame (
configuration/step
).- Type:
- dimensions#
Number of dimensions (
configuration/dimensions
). When not set explicitly, dimensions will default to different values based on the value of \(L_z\) inbox
. When \(L_z = 0\) dimensions will default to 2, otherwise 3. User set values always take precedence.- Type:
- property 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#
Bases:
object
Store constraint data.
Use the
Frame.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 frames may provide input data that can be converted to anumpy.ndarray
.See also
hoomd.State
for a full description of how HOOMD interprets this data.- N#
Number of constraints in the frame (
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.Frame#
Bases:
Snapshot
System state at one point in time.
- configuration#
Configuration data.
- Type:
- particles#
Particles.
- Type:
- constraints#
Distance constraints.
- Type:
- log#
Logged data (values must be
numpy.ndarray
orarray_like
)- Type:
- class gsd.hoomd.HOOMDTrajectory(file)#
Bases:
object
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(frame)#
Append a frame to a hoomd gsd file.
- Parameters:
frame (
Frame
) – Frame to append.
Write the given frame 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
Frame
instances. This could be another HOOMDTrajectory, a generator that modifies frames, or a list of frames.
- property file#
The 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.
Deprecated since version v2.5.
- truncate()#
Remove all frames from the file.
- class gsd.hoomd.ParticleData#
Bases:
object
Store particle data chunks.
Use the
Frame.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 frames may provide input data that can be converted to anumpy.ndarray
.See also
hoomd.State
for a full description of how HOOMD interprets this data.- N#
Number of particles in the frame (
particles/N
).- Type:
- types#
Names of the particle types (
particles/types
).
- 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
).
- 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#
Bases:
object
System state at one point in time.
Deprecated since version 2.8.0: Replaced by
Frame
.- validate()#
Validate all contained frame 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:
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 reading and 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 reading and 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 reading and writing. Does not create or overwrite existing files.
- gsd.hoomd.read_log(name, scalar_only=False)#
Read log from a hoomd schema GSD file into a dict of time-series arrays.
- Parameters:
The log data includes
configuration/step
and all matchinglog/user_defined
,log/bonds/user_defined
, andlog/particles/user_defined
quantities in the file.- Returns:
Note
read_log
issues aRuntimeWarning
when there are no matchinglog/
quantities in the file.Caution
read_log
requires that a logged quantity has the same shape in all frames. Useopen
andFrame.log
to read files where the shape changes from frame to frame.To create a pandas
DataFrame
with the logged data:In [1]: import pandas In [2]: df = pandas.DataFrame(gsd.hoomd.read_log('log-example.gsd', ...: scalar_only=True)) ...: In [3]: df Out[3]: configuration/step log/value/potential_energy 0 0 1.5 1 100 2.5 2 200 3.5 3 300 4.5 4 400 5.5 5 500 6.5 6 600 7.5 7 700 8.5 8 800 9.5 9 900 10.5