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, and Frame.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 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 frame (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¶

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

[lx, ly, lz, xy, xz, yz]. See configuration/box.

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¶

Bases: object

Store constraint data.

Use the Frame.constraints attribute to access the constraints.

See also

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

N¶

Number of constraints in the frame (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.Frame¶

Bases: object

System state at one point in time.

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 frame data.

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 that provides Frame instances. This could be another HOOMDTrajectory, a generator that modifies frames, or a list of frames.

property file¶

The file handle.

Type:: gsd.fl.GSDFile

flush()¶: Flush all buffered frames to the file.

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.

See also

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

N¶

Number of particles in the frame (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.

gsd.hoomd.open(name, mode='r')¶

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
`'r'`	Open an existing file for reading.
`'r+'`	Open an existing file for reading and writing.
`'w'`	Open a file for reading and writing. Creates the file if needed, or overwrites an existing file.
`'x'`	Create a gsd file exclusively and opens it for reading and writing. Raise `FileExistsError` if it already exists.
`'a'`	Open a file for reading and writing. Creates the file if it doesn’t exist.

gsd.hoomd.read_log(name: str, scalar_only=False, glob_pattern='*')¶

Read log from a hoomd schema GSD file into a dict of time-series arrays.

Parameters:

name (str) – File name to open.
scalar_only (bool) – Set to True to include only scalar log values.
glob_pattern (bool) – Apply a globbing wildcard filter to the log keys before reading.

The log data includes configuration/step and all matching log/user_defined, log/bonds/user_defined, and log/particles/user_defined quantities in the file that match the provided glob_pattern.

Returns:: dict

Note

read_log issues a RuntimeWarning when there are no matching log/ quantities in the file.

Caution

read_log requires that a logged quantity has the same shape in all frames. Use open and Frame.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