Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

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

  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.

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

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

  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.

  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, scalar_only=False)

  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.

  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.

  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