hoomd.write
Overview
Writes simulation trajectories in the DCD format. |
|
User-defined writer. |
|
Write simulation trajectories in the GSD format. |
|
Write delimiter separated values to a stream. |
Details
Writers.
Writers write the state of the simulation, logger quantities, or calculated results to output files or streams:
Combine
GSD
with ahoomd.logging.Logger
to save system properties or per-particle calculated results.Use
Table
to display the status of the simulation periodically to standard out.Implement custom output formats with
CustomWriter
.
Writers do not modify the system state.
Tip
OVITO has native support for GSD files, including logged per-particle array quantities and particle shapes.
- class hoomd.write.Table(trigger, logger, output=stdout, header_sep='.', delimiter=' ', pretty=True, max_precision=10, max_header_len=None)
Write delimiter separated values to a stream.
Use
Table
to write scalar and stringhoomd.logging.Logger
quantities to standard out or to a file.Warning
When logger quantities include strings with spaces, the default space delimiter will result in files that are not machine readable.
Important
All attributes for this class are static. They cannot be set to new values once created.
- Parameters
trigger (hoomd.trigger.trigger_like) – The trigger to determine when to run the Table backend.
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 havewrite
andflush
methods and amode
attribute. Examples includesys.stdout
,sys.stderr
and the return value ofopen()
.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 anhoomd.md.pair.LJ
pair force object, the default header would bemd.pair.LJ.energy
(assuming thatmax_header_len
is not set).delimiter (
str
, optional) – String used to separate elements in the space delimited file, defaults to' '
.pretty (
bool
, optional) – Flags whether to attempt to make output prettier and easier to read, defaults to True. To make the output easier to read, the output will compromise on numerical precision for improved readability. In many cases, the precision will still be high with pretty set toTrue
.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 lengthmax_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 backend.
- logger
The logger to query for output. The ‘scalar’ categories must be set on the logger, and the ‘string’ categories is optional.
- Type
- output
A file-like object to output the data from. The object must have
write
andflush
methods and amode
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 bemd.pair.LJ.energy
(assuming thatmax_header_len
is not set).- Type
- pretty
Flags whether to attempt to make output prettier and easier to read. To make the output 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
- 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 notNone
. 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
- write()
Write out data to
self.output
.Writes a row from given
hoomd.logging.Logger
object data.
- class hoomd.write.CustomWriter(trigger, action)
Bases:
CustomOperation
,Writer
User-defined writer.
- Parameters
action (hoomd.custom.Action) – The action to call.
trigger (hoomd.trigger.trigger_like) – Select the timesteps to call the action.
CustomWriter
is ahoomd.operation.Writer
that wraps a user-definedhoomd.custom.Action
object so the action can be added to ahoomd.Operations
instance for use withhoomd.Simulation
objects.Writers may read the system state and generate output files or print to output streams. Writers should not modify the system state.
See also
The base class
hoomd.custom.CustomOperation
.
- class hoomd.write.DCD(trigger, filename, filter=hoomd._hoomd.ParticleFilter, overwrite=False, unwrap_full=False, unwrap_rigid=False, angle_z=False)
Bases:
Writer
Writes simulation trajectories in the DCD format.
- Parameters
trigger (hoomd.trigger.Periodic) – Select the timesteps to write.
filename (str) – File name to write.
filter (hoomd.filter.filter_like) – 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)
DCD
writes the simulation trajectory to the specified file in the DCD file format. DCD stores only particle positions and the box parameters, in length units, and is limited to simulations where the number of particles is fixed.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.
- trigger
Select the timesteps to write.
- filter
Select the particles to write.
- overwrite
When False, an existing DCD file will be appended to. When True, an existing DCD file filename will be overwritten.
- Type
- 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
- 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
- class hoomd.write.GSD(trigger, filename, filter=hoomd._hoomd.ParticleFilter, mode='ab', truncate=False, dynamic=None, log=None)
Bases:
Writer
Write simulation trajectories in the GSD format.
- Parameters
trigger (hoomd.trigger.trigger_like) – Select the timesteps to write.
filename (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 toFalse
.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 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 scalar, string, and array quantities provided by ahoomd.logging.Logger
instance.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 dynamicSpecify 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/*
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 chunks must be present in the first frame in the gsd file to provide the default value. To achieve this, set the
log
attribute before the operation is triggered to write the first frame in the file.Some (or all) chunks may be omitted on later frames. You can set
log
toNone
or remove specific quantities from the logger, but do not add additional quantities after the first frame.- trigger
Select the timesteps to write.
- filter
Select the particles to write.
- truncate
When
True
, truncate the file and write a new frame 0 each time this operation triggers.- Type
- static write(state, filename, filter=hoomd._hoomd.ParticleFilter, mode='wb', log=None)
Write the given simulation state out to a GSD file.
- Parameters
state (State) – Simulation state.
filename (str) – File name to write.
filter (hoomd.filter.filter_like) – Select the particles to write.
mode (str) – The file open mode. Defaults to
'wb'
.log (hoomd.logging.Logger) – Provide log quantities to write.
The valid file modes for
write
are'wb'
and'xb'
.