hoomd.write¶

Overview

`DCD`	Writes simulation snapshots in the DCD format.
`CustomWriter`	Writer wrapper for `hoomd.custom.Action` objects.
`GSD`	Write simulation trajectories in the GSD format.
`Table`	A delimiter separated value file backend for a Logger.

Details

class hoomd.write.Table(trigger, logger, output=stdout, header_sep='.', delimiter=' ', pretty=True, max_precision=10, max_header_len=None)¶

A delimiter separated value file backend for a Logger.

This can serve as a way to output scalar simulation data to standard out. However, this is useable to store simulation scalar data to a file as well.

Note

This only works with scalar and string quantities. If using string quantities, keep in mind that the default space delimiter will make strings with spaces in them will cause read errors if attempting to read the outputed data with a space delimited file reader.

Note

All attributes for this class are static. They cannot be set to new values once created.

Parameters

trigger (hoomd.trigger.Trigger) – The trigger to determine when to run the Table back end.
logger (hoomd.logging.Logger) – The logger to query for output. The ‘scalar’ categories must be set on the logger, and the ‘string’ categories is optional.
output (file-like object , optional) – A file-like object to output the data from, defaults to standard out. The object must have write and flush methods and a mode attribute.
header_sep (str, optional) – String to use to separate names in the logger’s namespace, defaults to ‘.’. For example, if logging the total energy of an hoomd.md.pair.LJ pair force object, the default header would be md.pair.LJ.energy (assuming that max_header_len is not set).
delimiter (str, optional) – String used to separate elements in the space delimitated file, defaults to ‘ ‘.
pretty (bool, optional) – Flags whether to attempt to make output prettier and easier to read, defaults to True. To make the ouput easier to read, the output will compromise on outputted precision for improved readability. In many cases, though the precision will still be high with pretty set to True.
max_precision (int, optional) – If pretty is not set, then this controls the maximum precision to use when outputing numerical values, defaults to 10.
max_header_len (int, optional) – If not None (the default), limit the outputted header names to length max_header_len. When not None, names are grabbed from the most specific to the least. For example, if set to 7 the namespace ‘hoomd.md.pair.LJ.energy’ would be set to ‘energy’. Note that at least the most specific part of the namespace will be used regardless of this setting (e.g. if set to 5 in the previous example, ‘energy’ would still be the header).

trigger¶

The trigger to determine when to run the Table back end.

Type: hoomd.trigger.Trigger

logger¶

The logger to query for output. The ‘scalar’ categories must be set on the logger, and the ‘string’ categories is optional.

Type: hoomd.logging.Logger

output¶

A file-like object to output the data from. The object must have write and flush methods and a mode attribute.

Type: file-like object

header_sep¶

String to use to separate names in the logger’s namespace.’. For example, if logging the total energy of an hoomd.md.pair.LJ pair force object, the default header would be md.pair.LJ.energy (assuming that max_header_len is not set).

Type: str

delimiter¶

String used to separate elements in the space delimitated file.

Type: str

pretty¶

Flags whether to attempt to make output prettier and easier to read. To make the ouput easier to read, the output will compromise on outputted precision for improved readability. In many cases, though the precision will still be high with pretty set to True.

Type: bool

max_precision¶

If pretty is not set, then this controls the maximum precision to use when outputing numerical values, defaults to 10.

Type: int, optional

max_header_len¶

Limits the outputted header names to length max_header_len when not None. Names are grabbed from the most specific to the least. For example, if set to 7 the namespace ‘hoomd.md.pair.LJ.energy’ would be set to ‘energy’. Note that at least the most specific part of the namespace will be used regardless of this setting (e.g. if set to 5 in the previous example, ‘energy’ would still be the header).

Type: int

min_column_width¶

The minimum allowed column width.

Type: int

write()¶

Write out data to self.output.

Writes a row from given hoomd.logging.Logger object data.

class hoomd.write.CustomWriter(action, trigger=1)¶

Writer wrapper for hoomd.custom.Action objects.

For usage see hoomd.custom.CustomOperation.

class hoomd.write.DCD(filename, trigger, filter=hoomd._hoomd.ParticleFilter, overwrite=False, unwrap_full=False, unwrap_rigid=False, angle_z=False)¶

Writes simulation snapshots in the DCD format.

Parameters

filename (str) – File name to write.
trigger (hoomd.trigger.Periodic) – Select the timesteps to write.
filter (hoomd.filter.ParticleFilter) – Select the particles to write. Defaults to hoomd.filter.All.
overwrite (bool) – When False, (the default) an existing DCD file will be appended to. When True, an existing DCD file filename will be overwritten.
unwrap_full (bool) – When False, (the default) particle coordinates are always written inside the simulation box. When True, particles will be unwrapped into their current box image before writing to the DCD file.
unwrap_rigid (bool) – When False, (the default) individual particles are written inside the simulation box which breaks up rigid bodies near box boundaries. When True, particles belonging to the same rigid body will be unwrapped so that the body is continuous. The center of mass of the body remains in the simulation box, but some particles may be written just outside it. unwrap_rigid is ignored when unwrap_full is True.
angle_z (bool) – When True, the particle orientation angle is written to the z component (only useful for 2D simulations)

On each timestep where DCD triggers, it writes the simulation snapshot to the specified file in the DCD file format. DCD only stores particle positions, in distance units.

Examples:

writer = hoomd.write.DCD("trajectory.dcd", hoomd.trigger.Periodic(1000))
dcd = hoomd.write.DCD(filename="data/dump.dcd",
                      trigger=hoomd.trigger.Periodic(100, 10))

Warning

When you use DCD to append to an existing DCD file:

The period must be the same or the time data in the file will not be consistent.
DCD will not write out data at time steps that already are present in the DCD file to maintain a consistent timeline

filename¶

File name to write.

Type: str

trigger¶

Select the timesteps to write.

Type: hoomd.trigger.Periodic

filter¶

Select the particles to write.

Type: hoomd.filter.ParticleFilter

overwrite¶

When False, an existing DCD file will be appended to. When True, an existing DCD file filename will be overwritten.

Type: bool

unwrap_full¶

When False, particle coordinates are always written inside the simulation box. When True, particles will be unwrapped into their current box image before writing to the DCD file.

Type: bool

unwrap_rigid¶

When False, individual particles are written inside the simulation box which breaks up rigid bodies near box boundaries. When True, particles belonging to the same rigid body will be unwrapped so that the body is continuous. The center of mass of the body remains in the simulation box, but some particles may be written just outside it. unwrap_rigid is ignored when unwrap_full is True.

Type: bool

angle_z¶

When True, the particle orientation angle is written to the z component

Type: bool

class hoomd.write.GSD(filename, trigger, filter=hoomd._hoomd.ParticleFilter, mode='ab', truncate=False, dynamic=None, log=None)¶

Write simulation trajectories in the GSD format.

Parameters

filename (str) – File name to write.
trigger (hoomd.trigger.Trigger) – Select the timesteps to write.
filter (hoomd.filter.ParticleFilter) – 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]) – Quantity categories to save in every frame. Defaults to ['property'].
log (hoomd.logging.Logger) – Provide log quantities to write. Defaults to None.

GSD writes a simulation snapshot to the specified file each time it triggers. 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 operation-specific state information necessary for restarting simulations and user-defined log quantities.

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. Additionally, GSD only writes dynamic quantities to all frames. It writes non-dynamic quantities only the first frame. When reading a GSD file, the data in frame 0 is read when a quantity is missing in frame i, supplying data that is static over the entire trajectory. Set the dynamic parameter to specify dynamic attributes by category.

Specify the one or more of the following strings in dynamic to make the corresponding quantities dynamic (property is always dynamic):

property
- particles/position
- particles/orientation (only written when values are not the default: [1,0,0,0])
momentum
- particles/velocity
- particles/angmom (only written when values are not the default: [0,0,0,0])
- particles/image (only written when values are not the default: [0,0,0])
attribute
- particles/N
- particles/types
- particles/typeid
- particles/mass
- particles/charge
- particles/diameter
- particles/body
- particles/moment_inertia
topology
- bonds/*
- angles/*
- dihedrals/*
- impropers/*
- constraints/*
- pairs/*