GSD

class hoomd.write.GSD(trigger, filename, filter=hoomd.filter.All(), mode='ab', truncate=False, dynamic=None, logger=None)

Bases: Writer

Write simulation trajectories in the GSD format.

Parameters:

  • trigger (hoomd.trigger.trigger_like) – Select the timesteps to write.

  • filename (any type that converts to str) – File name to write.

  • filter (hoomd.filter.filter_like) – Select the particles to write. Defaults to hoomd.filter.All.

  • mode (str) – The file open mode. Defaults to 'ab'.

  • truncate (bool) – When True, truncate the file and write a new frame 0 each time this operation triggers. Defaults to False.

  • dynamic (list[str]) – Field names and/or field categores to save in all frames. Defaults to ['property'].

  • logger (hoomd.logging.Logger) – Provide log quantities to write. Defaults to None.

GSD writes the simulation trajectory to the specified file in the GSD format. GSD can store all particle, bond, angle, dihedral, improper, pair, and constraint data fields in every frame of the trajectory. GSD can write trajectories where the number of particles, number of particle types, particle types, diameter, mass, charge, or other quantities change over time. GSD can also store arbitrary, scalar, string, and array quantities provided by a hoomd.logging.Logger instance in logger.

Valid file open modes:

mode

description

'wb'

Open the file for writing. Create the file if needed, or overwrite an existing file.

'xb'

Create a GSD file exclusively. Raise an exception when the file exists.

'ab'

Create the file if needed, or append to an existing file.

To reduce file size, GSD does not write properties that are set to defaults. When masses, orientations, angular momenta, etc… are left default for all particles, these fields will not take up any space in the file, except on frame 1+ when the field is also non-default in frame 0. GSD writes all non-default fields to frame 0 in the file.

To further reduce file sizes, GSD allows the user to select which specific fields will be considered for writing to frame 1+ in the dynamic list. When reading a GSD file, the data in frame 0 is read when a quantity is missing in frame i, so any fields not in dynamic are fixed for the entire trajectory.

The dynamic list can contain one or more of the following strings:

  • 'property'

    • 'configuration/box'

    • 'particles/N'

    • 'particles/position'

    • 'particles/orientation'

  • 'momentum'

    • 'particles/velocity'

    • 'particles/angmom'

    • 'particles/image'

  • 'attribute'

    • 'particles/types'

    • 'particles/typeid'

    • 'particles/mass'

    • 'particles/charge'

    • 'particles/diameter'

    • 'particles/body'

    • 'particles/moment_inertia'

  • 'topology'

    • bonds/*

    • angles/*

    • dihedrals/*

    • impropers/*

    • constraints/*

    • pairs/*

When you set a category string ('property', 'momentum', 'attribute'), GSD makes all the category member’s fields dynamic.

Warning

GSD buffers writes in memory. Abnormal exits (e.g. kill, scancel, reaching walltime limits) may cause loss of data. Ensure that your scripts exit cleanly and call flush() as needed to write buffered frames to the file.

See also

See the GSD documentation, GSD HOOMD Schema, and GSD GitHub project for more information on GSD files.

Note

When you use filter to select a subset of the whole system, GSD writes only the selected particles in ascending tag order and does not write out topology.

Tip

All logged data fields must be present in the first frame in the gsd file to provide the default value. To achieve this, set the logger attribute before the operation is triggered to write the first frame in the file.

Some (or all) fields may be omitted on later frames. You can set logger to None or remove specific quantities from the logger, but do not add additional quantities after the first frame.

Example:

gsd = hoomd.write.GSD(
    trigger=hoomd.trigger.Periodic(1_000_000),
    filename=gsd_filename,
)
simulation.operations.writers.append(gsd)

Members inherited from AutotunedObject:

property kernel_parameters

Kernel parameters. Read more...

property is_tuning_complete

Check if kernel parameter tuning is complete. Read more...

tune_kernel_parameters()

Start tuning kernel parameters. Read more...

Members inherited from TriggeredOperation:

trigger

The trigger to activate this operation. Read more...

Members defined in GSD:

filename

File name to write (read-only).

Example:

filename = gsd.filename
Type:

str

filter

Select the particles to write (read-only).

Example:

filter_ = gsd.filter
Type:

hoomd.filter.filter_like

mode

The file open mode (read-only).

Example:

mode = gsd.mode
Type:

str

truncate

When True, truncate the file and write a new frame 0 each time this operation triggers (read-only).

Example:

truncate = gsd.truncate
Type:

bool

dynamic

Field names and/or field categores to save in all frames.

Examples:

gsd.dynamic = ["property"]

gsd.dynamic = ["property", "momentum"]

gsd.dynamic = [
    "property",
    "particles/image",
    "particles/typeid",
]
Type:

list[str]

write_diameter

When False, do not write particles/diameter. Set to True to write non-default particle diameters.

Example:

gsd.write_diameter = True
Type:

bool

maximum_write_buffer_size

Size (in bytes) to buffer in memory before writing to the file.

Example:

gsd.maximum_write_buffer_size = 128 * 1024**2
Type:

int

flush()

Flush the write buffer to the file.

Example:

gsd_writer.flush()

Flush all write buffers:

for writer in simulation.operations.writers:
    if hasattr(writer, "flush"):
        writer.flush()
property logger

Provide log quantities to write.

May be None.

Type:

hoomd.logging.Logger

static write(state, filename, filter=hoomd._hoomd.ParticleFilter, mode='wb', logger=None)

Write the given simulation state out to a GSD file.

Parameters:

The valid file modes for write are 'wb' and 'xb'.