hoomd.dump

Overview

hoomd.dump.dcd Writes simulation snapshots in the DCD format
hoomd.dump.getar Analyzer for dumping system properties to a getar file at intervals.
hoomd.dump.gsd Writes simulation snapshots in the GSD format

Details

Write system configurations to files.

Commands in the dump package write the system state out to a file every period time steps. Check the documentation for details on which file format each command writes.

class hoomd.dump.dcd(filename, period, group=None, overwrite=False, unwrap_full=False, unwrap_rigid=False, angle_z=False, phase=0)

Writes simulation snapshots in the DCD format

Parameters:
  • filename (str) – File name to write.
  • period (int) – Number of time steps between file dumps.
  • group (hoomd.group) – Particle group to output to the dcd file. If left as None, all particles will be written.
  • 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)
  • phase (int) – When -1, start on the current time step. When >= 0, execute on steps where (step + phase) % period == 0.

Every period time steps a new simulation snapshot is written to the specified file in the DCD file format. DCD only stores particle positions, in distance units - see Units.

Due to constraints of the DCD file format, once you stop writing to a file via disable(), you cannot continue writing to the same file, nor can you change the period of the dump at any time. Either of these tasks can be performed by creating a new dump file with the needed settings.

Examples:

dump.dcd(filename="trajectory.dcd", period=1000)
dcd = dump.dcd(filename"data/dump.dcd", period=1000)

Warning

When you use dump.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.
  • dump.dcd will not write out data at time steps that already are present in the dcd file to maintain a consistent timeline
disable()

Disable the analyzer.

Examples:

my_analyzer.disable()

Executing the disable command will remove the analyzer from the system. Any hoomd.run() command executed after disabling an analyzer will not use that analyzer during the simulation. A disabled analyzer can be re-enabled with enable().

enable()

The DCD dump writer cannot be re-enabled

restore_state()

Restore the state information from the file used to initialize the simulations

set_period(period)

Changes the period between analyzer executions

Parameters:period (int) – New period to set (in time steps)

Examples:

analyzer.set_period(100)
analyzer.set_period(1)

While the simulation is running (hoomd.run(), the action of each analyzer is executed every period time steps. Changing the period does not change the phase set when the analyzer was first created.

class hoomd.dump.getar(filename, mode='w', static=[], dynamic={}, _register=True)

Analyzer for dumping system properties to a getar file at intervals.

Getar files are a simple interface on top of archive formats (such as zip and tar) for storing trajectory data efficiently. A more thorough description of the format and a description of a python API to read and write these files is available at the libgetar documentation.

Properties to dump can be given either as a getar.DumpProp object or a name. Supported property names are specified in the Supported Property Table in hoomd.init.read_getar.

Files can be opened in write, append, or one-shot mode. Write mode overwrites files with the same name, while append mode adds to them. One-shot mode is intended for restorable system backups and is described below.

One-shot mode

In one-shot mode, activated by passing mode=’1’ to the getar constructor, properties are written to a temporary file, which then overwrites the file with the given filename. In this way, the file with the given filename should always have the most recent frame of successfully written data. This mode is designed for being able to dump restoration data often without wasting large amounts of space saving earlier data. Note that this create-and-overwrite process can be stressful on filesystems, particularly lustre filesystems, and can get your account blocked on some supercomputer resources if overused.

For convenience, you can also specify composite properties, which are expanded according to the table below.

Name Result
global_all box, dimensions
angle_all angle_type_names, angle_tag, angle_type
bond_all bond_type_names, bond_tag, bond_type
dihedral_all dihedral_type_names, dihedral_tag, dihedral_type
improper_all improper_type_names, improper_tag, improper_type
particle_all angular_momentum, body, charge, diameter, image, mass, moment_inertia, orientation, position, type, type_names, velocity
all particle_all, angle_all, bond_all, dihedral_all, improper_all, global_all
viz_static type, type_names, dimensions
viz_dynamic position, box
viz_all viz_static, viz_dynamic
viz_aniso_dynamic viz_dynamic, orientation
viz_aniso_all viz_static, viz_aniso_dynamic

Particle-related metadata

Metadata about particle shape (for later visualization or use in restartable scripts) can be stored in a simple form through hoomd.dump.getar.writeJSON(), which encodes JSON records as strings and stores them inside the dump file. Currently, classes inside hoomd.dem and hoomd.hpmc are equipped with get_type_shapes() methods which can provide per-particle-type shape information as a list.

Example:

dump = hoomd.dump.getar.simple('dump.sqlite', 1e3,
    static=['viz_static'],
    dynamic=['viz_aniso_dynamic'])

dem_wca = hoomd.dem.WCA(nlist, radius=0.5)
dem_wca.setParams('A', vertices=vertices, faces=faces)
dump.writeJSON('type_shapes.json', dem_wca.get_type_shapes())

mc = hpmc.integrate.convex_polygon(seed=415236)
mc.shape_param.set('A', vertices=[(-0.5, -0.5), (0.5, -0.5), (0.5, 0.5), (-0.5, 0.5)])
dump.writeJSON('type_shapes.json', mc.get_type_shapes(), dynamic=True)
class DumpProp(name, highPrecision=False, compression=hoomd.dump.getar.Compression.FastCompress)

Create a dump property specification.

Parameters:
  • name – Name of the property to dump
  • highPrecision – True if the property should be dumped in high precision, if possible
  • compression – Compression level to save the property with, if possible
__init__(filename, mode='w', static=[], dynamic={}, _register=True)

Initialize a getar dumper. Creates or appends an archive at the given file location according to the mode and prepares to dump the given sets of properties.

Parameters:
  • filename (str) – Name of the file to open
  • mode (str) – Run mode; see mode list below.
  • static (list) – List of static properties to dump immediately
  • dynamic (dict) – Dictionary of {prop: period} periodic dumps
  • _register (bool) – If True, register as a hoomd analyzer (internal)

Note that zip32-format archives can not be appended to at the moment; for details and solutions, see the libgetar documentation, section “Zip vs. Zip64.” The gtar.fix module was explicitly made for this purpose, but be careful not to call it from within a running GPU HOOMD simulation due to strangeness in the CUDA driver.

Valid mode arguments:

  • ‘w’: Write, and overwrite if file exists
  • ‘a’: Write, and append if file exists
  • ‘1’: One-shot mode: keep only one frame of data. For details on one-shot mode, see the “One-shot mode” section of getar.

Property specifications can be either a property name (as a string) or DumpProp objects if you desire greater control over how the property will be dumped.

Example:

# detailed API; see `dump.getar.simple` for simpler wrappers
zip = dump.getar('dump.zip', static=['types'],
          dynamic={'orientation': 10000,
                   'velocity': 5000,
                   dump.getar.DumpProp('position', highPrecision=True): 10000})
close()

Closes the trajectory if it is open. Finalizes any IO beforehand.

disable()

Disable the analyzer.

Examples:

my_analyzer.disable()

Executing the disable command will remove the analyzer from the system. Any hoomd.run() command executed after disabling an analyzer will not use that analyzer during the simulation. A disabled analyzer can be re-enabled with enable().

enable()

Enables the analyzer

Examples:

my_analyzer.enable()

See disable().

classmethod immediate(filename, static, dynamic)

Immediately dump the given static and dynamic properties to the given filename.

For detailed explanation of arguments, see getar.

Example:

hoomd.dump.getar.immediate(
    'snapshot.tar', static=['viz_static'], dynamic=['viz_dynamic'])
restore_state()

Restore the state information from the file used to initialize the simulations

classmethod simple(filename, period, mode='w', static=[], dynamic=[], high_precision=False)

Create a getar dump object with a simpler interface.

Static properties will be dumped once immediately, and dynamic properties will be dumped every period steps. For detailed explanation of arguments, see getar.

Parameters:
  • filename (str) – Name of the file to open
  • period (int) – Period to dump the given dynamic properties with
  • mode (str) – Run mode; see mode list in getar.
  • static (list) – List of static properties to dump immediately
  • dynamic (list) – List of properties to dump every period steps
  • high_precision (bool) – If True, dump precision properties

Example:

# [optionally] dump metadata beforehand with libgetar
with gtar.GTAR('dump.sqlite', 'w') as trajectory:
    metadata = json.dumps(hoomd.meta.dump_metadata())
    trajectory.writeStr('hoomd_metadata.json', metadata)
# for later visualization of anisotropic systems
zip2 = hoomd.dump.getar.simple(
     'dump.sqlite', 100000, 'a', static=['viz_static'], dynamic=['viz_aniso_dynamic'])
# as backup to restore from later
backup = hoomd.dump.getar.simple(
    'backup.tar', 10000, '1', static=['viz_static'], dynamic=['viz_aniso_dynamic'])
writeJSON(name, contents, dynamic=True)

Encodes the given JSON-encodable object as a string and writes it (immediately) as a quantity with the given name. If dynamic is True, writes the record as a dynamic record with the current timestep.

Parameters:
  • name (str) – Name of the record to save
  • contents (str) – Any datatype encodable by the json module
  • dynamic (bool) – If True, dump a dynamic quantity with the current timestep; otherwise, dump a static quantity

Example:

dump = hoomd.dump.getar.simple('dump.sqlite', 1e3,
    static=['viz_static'], dynamic=['viz_dynamic'])
dump.writeJSON('params.json', dict(temperature=temperature, pressure=pressure))
dump.writeJSON('metadata.json', hoomd.meta.dump_metadata())
class hoomd.dump.gsd(filename, period, group, overwrite=False, truncate=False, phase=0, time_step=None, static=None, dynamic=None)

Writes simulation snapshots in the GSD format

Parameters:
  • filename (str) – File name to write
  • period (int) – Number of time steps between file dumps, or None to write a single file immediately.
  • group (hoomd.group) – Particle group to output to the gsd file.
  • overwrite (bool) – When False (the default), any existing GSD file will be appended to. When True, an existing GSD file filename will be overwritten.
  • truncate (bool) – When False (the default), frames are appended to the GSD file. When True, truncate the file and write a new frame 0 every time.
  • phase (int) – When -1, start on the current time step. When >= 0, execute on steps where (step + phase) % period == 0.
  • time_step (int) – Time step to write to the file (only used when period is None)
  • dynamic (list) – A list of quantity categories to save every frame. (added in version 2.2)
  • static (list) – A list of quantity categories save only in frame 0 (may not be set in conjunction with dynamic, deprecated in version 2.2).

Write a simulation snapshot to the specified GSD file at regular intervals. GSD is capable of storing all particle and bond data fields in hoomd, in every frame of the trajectory. This allows GSD to store simulations where the number of particles, number of particle types, particle types, diameter, mass, charge, and other quantities change over time. GSD can also store integrator state information necessary for restarting simulations and user-defined log quantities.

To save on space, GSD does not write values that are all set at defaults. So if all masses, orientations, angular momenta, etc… are left default, these fields will not take up any space in the file. Additionally, only dynamic quantities are written to all frames, non-dynamic quantities are only written to frame 0. The GSD schema defines that data not present in frame i is to be read from frame 0. This makes every single frame of a GSD file fully specified and simulations initialized with hoomd.init.read_gsd() can select any frame of the file.

You can control what quantities are dynamic by category. property is always dynamic. The categories listed in the dynamic will also be written out to every frame, but only if they have changed from the defaults.

  • attribute

    • particles/N
    • particles/types
    • particles/typeid
    • particles/mass
    • particles/charge
    • particles/diameter
    • particles/body
    • particles/moment_inertia
  • property

    • particles/position
    • particles/orientation (only written when changed from default)
  • momentum

    • particles/velocity
    • particles/angmom (only written when changed from default)
    • particles/image
  • topology

    • bonds/
    • angles/
    • dihedrals/
    • impropers/
    • constraints/
    • pairs/

See https://github.com/glotzerlab/gsd and http://gsd.readthedocs.io/ for more information on GSD files.

If you only need to store a subset of the system, you can save file size and time spent analyzing data by specifying a group to write out. gsd will write out all of the particles in the group in ascending tag order. When the group is not hoomd.group.all(), gsd will not write the topology fields.

To write restart files with gsd, set truncate=True. This will cause gsd to write a new frame 0 to the file every period steps.

State data

gsd can save internal state data for the following hoomd objects:

Call dump_state() with the object as an argument to enable saving its state. State saved in this way can be restored after initializing the system with hoomd.init.read_gsd().

User-defined log quantities

Associate a name with a callable python object that returns a numpy array in log, and gsd will save the data you provide on every frame. Prefix per-particle quantities with particles/ and per-bond quantities with bonds/ so that visualization tools such as OVITO will make them available in their pipelines. OVITO also understand scalar values (length 1 numpy arrays) and strings encoded as uint8 numpy arrays.

Examples:

dump.gsd(filename="trajectory.gsd", period=1000, group=group.all(), phase=0)
dump.gsd(filename="restart.gsd", truncate=True, period=10000, group=group.all(), phase=0)
dump.gsd(filename="configuration.gsd", overwrite=True, period=None, group=group.all(), time_step=0)
dump.gsd(filename="momentum_too.gsd", period=1000, group=group.all(), phase=0, dynamic=['momentum'])
dump.gsd(filename="saveall.gsd", overwrite=True, period=1000, group=group.all(), dynamic=['attribute', 'momentum', 'topology'])
disable()

Disable the analyzer.

Examples:

my_analyzer.disable()

Executing the disable command will remove the analyzer from the system. Any hoomd.run() command executed after disabling an analyzer will not use that analyzer during the simulation. A disabled analyzer can be re-enabled with enable().

dump_shape(obj)

Writes particle shape information stored by a hoomd object.

This method writes particle shape information into a GSD file, in the chunk particle/type_shapes. This information can be used by other libraries for visualization. The following classes support writing shape information to GSD files:

See the Shape Visualization Specification section of the GSD package documentation for a detailed description of shape definitions.

New in version 2.7.

dump_state(obj)

Write state information for a hoomd object.

Call dump_state() if you want to write the state of a hoomd object to the gsd file.

New in version 2.2.

enable()

Enables the analyzer

Examples:

my_analyzer.enable()

See disable().

log

Dictionary mapping user-defined names to callbacks.

Add an item to log to save user-defined data in the gsd file. The key provides the name of the data chunk in the gsd file (e.g. particles/lj_potential_energy). The value is a callable python object that takes the current time step as an argument and returns a numpy array that has 1 or 2 dimensions and has a data type supported by gsd.

Delete a key from log to stop logging that quantity.

Note

All logged data chunks must be present in the first frame in the gsd file to provide the default value. Some (or all) chunks may be omitted on later frames:

Note

In MPI parallel simulations, the callback will be called on all ranks. gsd will write the data returned by the root rank. Return values from all other ranks are ignored (and may be None).

New in version 2.7.

restore_state()

Restore the state information from the file used to initialize the simulations

set_period(period)

Changes the period between analyzer executions

Parameters:period (int) – New period to set (in time steps)

Examples:

analyzer.set_period(100)
analyzer.set_period(1)

While the simulation is running (hoomd.run(), the action of each analyzer is executed every period time steps. Changing the period does not change the phase set when the analyzer was first created.

write_restart()

Write a restart file at the current time step.

Call write_restart() at the end of a simulation where are writing a gsd restart file with truncate=True to ensure that you have the final frame of the simulation written before exiting. See Restartable jobs for examples.