hoomd

Overview

Box

Define box dimensions.

Operations

A mutable collection of operations which act on a hoomd.Simulation.

Simulation

Define a simulation.

Snapshot

State

The state of a hoomd.Simulation object.

Details

HOOMD-blue python API.

hoomd provides a high level user interface for defining and executing simulations using HOOMD.

class hoomd.Box(Lx, Ly, Lz=0, xy=0, xz=0, yz=0)

Define box dimensions.

Parameters
  • Lx (float) – box extent in the x direction (distance units).

  • Ly (float) – box extent in the y direction (distance units).

  • Lz (float) – box extent in the z direction (distance units).

  • xy (float) – tilt factor xy (dimensionless).

  • xz (float) – tilt factor xz (dimensionless).

  • yz (float) – tilt factor yz (dimensionless).

Simulation boxes in hoomd are specified by six parameters, Lx, Ly, Lz, xy, xz, and yz. Box provides a way to specify all six parameters for a given box and perform some common operations with them. A Box can be passed to an initialization method or to assigned to a saved State variable (state.box = new_box) to set the simulation box.

Access attributes directly:

box = hoomd.Box.cube(L=20)
box.xy = 1.0
box.yz = 0.5
box.Lz = 40

Two dimensional systems

2D simulations in HOOMD use boxes with Lz == 0. 2D boxes ignore xz and yz. If a new Box is assigned to a system with different dimensionality, a warning will be shown.

In 2D boxes, volume is in units of area.

Factory Methods

Box has factory methods to enable easier creation of boxes: cube, square, from_matrix, and from_box. See the method documentation for usage.

Examples:

  • Cubic box with given length: hoomd.Box.cube(L=1)

  • Square box with given length: hoomd.Box.square(L=1)

  • From an upper triangular matrix: hoomd.Box.from_matrix(matrix)

  • Specify all values: hoomd.Box(Lx=1., Ly=2., Lz=3., xy=1., xz=2., yz=3.)

property L

The box lengths, [Lx, Ly, Lz].

Can be set with a float which sets all lengths, or a length 3 vector.

Type
  1. numpy.ndarray of float

property Lx

The length of the box in the x dimension.

Type

float

property Ly

The length of the box in the y dimension.

Type

float

property Lz

The length of the box in the z dimension.

Type

float

classmethod cube(L)

Create a cube with side lengths L.

Parameters

L (float) – The box side length (distance units).

Returns

The created 3D box.

Return type

hoomd.Box

property dimensions

The dimensionality of the box.

If Lz == 0, the box is treated as 2D, otherwise it is 3D. This property is not settable.

Type

int

classmethod from_box(box)

Initialize a Box instance from a box-like object.

Parameters

box – A box-like object

Note

Objects that can be converted to HOOMD-blue boxes include lists like [Lx, Ly, Lz, xy, xz, yz], dictionaries with keys 'Lx', 'Ly', 'Lz', 'xy', 'xz', 'yz', objects with attributes :code:`Lx, Ly, Lz, xy, xz, yz, 3x3 matrices (see `from_matrix), or existing hoomd.Box objects.

If any of Lz, xy, xz, yz are not provided, they will be set to 0.

If all values are provided, a triclinic box will be constructed. If only Lx, Ly, Lz are provided, an orthorhombic box will be constructed. If only Lx, Ly are provided, a rectangular (2D) box will be constructed.

Returns

The resulting box object.

Return type

hoomd.Box

classmethod from_matrix(box_matrix)

Create a box from an upper triangular matrix.

Parameters

box_matrix ((3, 3) numpy.ndarray of float) –

An upper triangular matrix representing a box. The values for Lx, Ly, Lz, xy, xz, and yz are related to the matrix by the following expressions.

[[Lx, Ly * xy, Lz * xz],
[0,  Ly,      Lz * yz],
[0,  0,       Lz]]

Returns

The created box.

Return type

hoomd.Box

property is2D

Flag whether the box is 2D.

If Lz == 0, the box is treated as 2D, otherwise it is 3D. This property is not settable.

Type

bool

property lattice_vectors

Box lattice vectors.

The lattice vectors are read-only.

Type

(3, 3) numpy.ndarray of float

property matrix

The upper triangular matrix that defines the box.

Can be used to set the box to one defined by an upper triangular matrix.

[[Lx, Ly * xy, Lz * xz],
 [0,  Ly,      Lz * yz],
 [0,  0,       Lz]]
Type

(3, 3) numpy.ndarray float

property periodic

The periodicity of each dimension.

Type
  1. numpy.ndarray of bool

scale(s)

Scale box dimensions.

Scales the box by the given scale factors. Tilt factors are not modified.

Parameters

s (float or Sequence[float]) – scale factors in each dimension. If a single float is given then scale all dimensions by s; otherwise, s must be a sequence of 3 values used to scale each dimension.

classmethod square(L)

Create a square with side lengths L.

Parameters

L (float) – The box side length (distance units).

Returns

The created 2D box.

Return type

hoomd.Box

property tilts

The box tilts, [xy, xz, yz].

Can be set using one tilt for all axes or three tilts. If the box is 2D xz and yz will automatically be set to zero.

Type
  1. numpy.ndarray of float

property volume

The current volume (area in 2D) of the box.

When setting volume the aspect ratio of the box is maintained while the lengths are changed.

Type

float

property xy

The tilt for the xy plane.

Type

float

property xz

The tilt for the xz plane.

Type

float

property yz

The tilt for the yz plane.

Type

float

class hoomd.Operations

A mutable collection of operations which act on a hoomd.Simulation.

The Operations class contains all the operations acting on a simulation. These operations are classes that perform various actions on a hoomd.Simulation. Operations can be added and removed at any point from a hoomd.Operations instance. The class provides the interface defined by collections.abc.Collection. Other methods for manipulating instances attempt to mimic Python objects where possible, but the class is not simply a mutable list or set. Since there are multiple types of operations in HOOMD-blue, Operations objects manage multiple independent sequences described below.

The types of operations which can be added to an Operations object are tuners, updaters, integrators, writers, and computes. An Operations can only ever hold one integrator at a time. On the other hand, an Operations object can hold any number of tuners, updaters, writers, or computes. To see examples of these types of operations see hoomd.tune (tuners), hoomd.update (updaters), hoomd.hpmc.integrate or hoomd.md.integrate (integrators), , hoomd.write (writers), and hoomd.md.thermo (computes).

A given instance of an operation class can only be added to a single Operations container. Likewise, a single instance cannot be added to the same Operations container more than once.

All Operations instances start with a hoomd.tune.ParticleSorter instance in their tuners attribute. This increases simulation performance. However, users can choose to modify or remove this tuner if desired.

Note

An Operations object is created by default when a new simulation is created.

__contains__(operation)

Whether an operation is contained in this container.

Parameters

operation – Returns whether this exact operation is contained in the collection.

__iadd__(operation)

Works the same as Operations.add.

Parameters

operation (hoomd.operation.Operation) – A HOOMD-blue tuner, updater, integrator, writer, or compute to add to the object.

__isub__(operation)

Works the same as Operations.remove.

Parameters

operation (hoomd.operation.Operation) – A HOOMD-blue integrator, tuner, updater, integrator, analzyer, or compute to remove from the collection.

__iter__()

Iterates through all contained operations.

__len__()

Return the number of operations contained in this collection.

add(operation)

Add an operation to this container.

Adds the provided operation to the appropriate attribute of the Operations instance.

Parameters

operation (hoomd.operation.Operation) – A HOOMD-blue tuner, updater, integrator, writer, or compute, to add to the collection.

Raises

Note

Since only one integrator can be associated with an Operations object at a time, this removes the current integrator when called with an integrator operation. Also, the integrator property cannot be set to None using this function. Use operations.integrator = None explicitly for this.

property computes

A list of tuner operations.

Holds the list of tuners associated with this collection. The list can be modified as a standard Python list.

Type

list[hoomd.operation.Compute]

property integrator

An MD or HPMC integrator object.

Operations objects have an initial integrator property of None. Can be set to MD or HPMC integrators. The property can also be set to None.

Type

hoomd.integrate.BaseIntegrator

remove(operation)

Remove an operation from the Operations object.

Remove the item from the collection whose id is the same as operation. See https://docs.python.org/3/library/functions.html#id for the concept of a Python object id.

Parameters

operation (hoomd.operation.Operation) – A HOOMD-blue integrator, tuner, updater, integrator, or compute to remove from the container.

Raises
  • ValueError – If operation is not found in this container.

  • TypeError – If operation is not of a valid type.

property tuners

A list of tuner operations.

Holds the list of tuners associated with this collection. The list can be modified as a standard Python list.

Type

list[hoomd.operation.Tuner]

property updaters

A list of updater operations.

Holds the list of updaters associated with this collection. The list can be modified as a standard Python list.

Type

list[hoomd.operation.Updater]

property writers

A list of writer operations.

Holds the list of writers associated with this collection. The list can be modified as a standard Python list.

Type

list[hoomd.operation.Writer]

class hoomd.Simulation(device, seed=None)

Define a simulation.

Parameters

Simulation is the central class in HOOMD-blue that defines a simulation, including the state of the system, the operations that apply to the state during a simulation run, and the device to use when executing the simulation.

seed sets the seed for the random number generator used by all operations added to this Simulation.

property always_compute_pressure

Always compute the virial and pressure (defaults to False).

By default, HOOMD only computes the virial and pressure on timesteps where it is needed (when hoomd.write.GSD writes log data to a file or when using an NPT integrator). Set always_compute_pressure to True to make the per particle virial, net virial, and system pressure available to query any time by property or through the hoomd.logging.Logger interface.

Note

Enabling this flag will result in a moderate performance penalty when using MD pair potentials.

Type

bool

create_state_from_gsd(filename, frame=- 1)

Create the simulation state from a GSD file.

Parameters
  • filename (str) – GSD file to read

  • frame (int) – Index of the frame to read from the file. Negative values index back from the last frame in the file.

create_state_from_snapshot(snapshot)

Create the simulations state from a Snapshot.

Parameters

snapshot (Snapshot or gsd.hoomd.Snapshot) – Snapshot to initialize the state from. A gsd.hoomd.Snapshot will first be converted to a hoomd.Snapshot.

When timestep is None before calling, create_state_from_snapshot sets timestep to 0.

property device

Device used to execute the simulation.

Type

hoomd.device.Device

property final_timestep

run will end at this timestep.

final_timestep is the timestep on which the currently executing run will complete.

(Loggable: category=”scalar”)

Type

float

property loggables

Return a name, category mapping of loggable quantities.

Type

dict[str, str]

property operations

The operations that apply to the state.

Type

hoomd.Operations

run(steps, write_at_start=False)

Advance the simulation a number of steps.

Parameters
  • steps (int) – Number of steps to advance the simulation.

  • write_at_start (bool) – When True, writers with triggers that evaluate True for the initial step will be exected before the time step loop.

Note

Initialize the simulation’s state before calling run.

During each step run, Simulation applies its operations to the state in the order: Tuners, Updaters, Integrator, then Writers following the logic in this pseudocode:

if write_at_start:
    for writer in operations.writers:
        if writer.trigger(timestep):
            writer.write(timestep)

end_step = timestep + steps
while timestep < end_step:
    for tuner in operations.tuners:
        if tuner.trigger(timestep):
            tuner.tune(timestep)

    for updater in operations.updaters:
        if updater.trigger(timestep):
            updater.update(timestep)

    if operations.integrator is not None:
        operations.integrator(timestep)

    timestep += 1

    for writer in operations.writers:
        if writer.trigger(timestep):
            writer.write(timestep)

This order of operations ensures that writers (such as hoomd.dump.GSD) capture the final output of the last step of the run loop. For example, a writer with a trigger hoomd.trigger.Periodic(period=100, phase=0) active during a run(500) would write on steps 100, 200, 300, 400, and 500. Set write_at_start=True on the first call to run to also obtain output at step 0.

Warning

Using write_at_start=True in subsequent calls to run will result in duplicate output frames.

property seed

Random number seed.

Seeds are in the range [0, 65535]. When set, seed will take only the lowest 16 bits of the given value.

HOOMD-blue uses a deterministic counter based pseudorandom number generator. Any time a random value is needed, HOOMD-blue computes it as a function of the user provided seed seed (16 bits), the current timestep (lower 40 bits), particle identifiers, MPI ranks, and other unique identifying values as needed to sample uncorrelated values: random_value = f(seed, timestep, ...)

(Loggable: category=”scalar”)

Type

int

property state

The current simulation state.

Type

hoomd.State

property timestep

Current time step of the simulation.

Note

Functions like create_state_from_gsd will set the initial timestep from the input. Set timestep before creating the simulation state to override values from create_ methods:

sim.timestep = 5000
sim.create_state_from_gsd('gsd_at_step_10000000.gsd')
assert sim.timestep == 5000

(Loggable: category=”scalar”)

Type

int

property tps

The average number of time steps per second.

tps is the number of steps executed divided by the elapsed walltime in seconds. It is updated during the run loop and remains fixed after run completes.

Note

The start time and step are reset at the beginning of each call to run.

(Loggable: category=”scalar”)

Type

float

property walltime

The walltime spent during the last call to run.

walltime is the number seconds that the last call to run took to complete. It is updated during the run loop and remains fixed after run completes.

Note

walltime resets to 0 at the beginning of each call to run.

(Loggable: category=”scalar”)

Type

float

write_debug_data(filename)

Write debug data to a JSON file.

Parameters

filename (str) – Name of file to write.

The debug data file contains useful information for others to help you troubleshoot issues.

Note

The file format and particular data written to this file may change from version to version.

Warning

The specified file name will be overwritten.

class hoomd.Snapshot(communicator=None)
property angles
property bonds
property configuration
property constraints
property dihedrals
property exists
classmethod from_gsd_snapshot(gsd_snap, communicator)

Constructs a hoomd.Snapshot from a gsd.hoomd.Snapshot object.

Parameters
property impropers
property pairs
property particles
replicate(nx, ny, nz)
class hoomd.State(simulation, snapshot)

The state of a hoomd.Simulation object.

Provides access (read/write) to a hoomd.Simulation object’s particle, bond, angle, etc. data. Data access is facilitated through two complementary APIs: global and local snapshots (note that global does not refer to variable scope here). See State.snapshot, State.cpu_local_snapshot, and State.gpu_local_snapshot for information about these data access patterns. In addition, many commonly used smaller quantities such as the number of particles in a simulation are available directly through State object properties.

Note

This object should never be directly instantiated by users. There is no way to set a state created outside of a hoomd.Simulation object to a simulation. Use hoomd.Simulation.create_state_from_gsd and hoomd.Simulation.create_state_from_snapshot to instantiate a State object.

property N_angles

The number of angles in the simulation.

Type

int

property N_bonds

The number of bonds in the simulation.

Type

int

property N_dihedrals

The number of dihedrals in the simulation.

Type

int

property N_impropers

The number of impropers in the simulation.

Type

int

property N_particles

The number of particles in the simulation.

Type

int

property N_special_pairs

The number of special pairs in the simulation.

Type

int

property angle_types

List of all angle types in the simulation.

Type

list[str]

property bond_types

List of all bond types in the simulation.

Type

list[str]

property box

The current simulation box.

Editing the box directly is not allowed. For example state.box.scale(1.1) would not scale the state’s box. To set the state’s box to a new box state.box = new_box must be used.

Type

hoomd.Box

property cpu_local_snapshot

Expose simulation data on the CPU.

Provides access directly to the system state’s particle, bond, angle, dihedral, improper, constaint, and pair data through a context manager. Data in State.cpu_local_snapshot is MPI rank local, and the hoomd.data.LocalSnapshot object is only usable within a context manager (i.e. with sim.state.cpu_local_snapshot as data:). Attempts to assess data outside the context manager will result in errors. The local snapshot interface is similar to that of hoomd.Snapshot.

The hoomd.data.LocalSnapshot data access is mediated through hoomd.array.HOOMDArray objects. This lets us ensure memory safety when directly accessing HOOMD-blue’s data. The interface provides zero-copy access (zero-copy is guarenteed on CPU, access may be zero-copy if running on GPU).

Changing the data in the buffers exposed by the local snapshot will change the data across the HOOMD-blue simulation. For a trivial example, this example would set all particle z-axis positions to 0.

with sim.state.cpu_local_snapshot as data:
    data.particles.position[:, 2] = 0

Note

The state’s box and the number of particles, bonds, angles, dihedrals, impropers, constaints, and pairs cannot change within the context manager.

Note

Getting a local snapshot object is order \(O(1)\) and setting a single value is of order \(O(1)\).

Type

hoomd.data.LocalSnapshot

property dihedral_types

List of all dihedral types in the simulation.

Type

list[str]

property gpu_local_snapshot

Expose simulation data on the GPU.

Provides access directly to the system state’s particle, bond, angle, dihedral, improper, constaint, and pair data through a context manager. Data in State.gpu_local_snapshot is GPU local, and the hoomd.data.LocalSnapshotGPU object is only usable within a context manager (i.e. with sim.state.gpu_local_snapshot as data:). Attempts to assess data outside the context manager will result in errors. The local snapshot interface is similar to that of hoomd.Snapshot.

The hoomd.data.LocalSnapshotGPU data access is mediated through hoomd.array.HOOMDGPUArray objects. This helps us maintain memory safety when directly accessing HOOMD-blue’s data. The interface provides zero-copy access on the GPU (assuming data was last accessed on the GPU).

Changing the data in the buffers exposed by the local snapshot will change the data across the HOOMD-blue simulation. For a trivial example, this example would set all particle z-axis positions to 0.

with sim.state.gpu_local_snapshot as data:
    data.particles.position[:, 2] = 0

Warning

This property is only available when running on a GPU(s).

Note

The state’s box and the number of particles, bonds, angles, dihedrals, impropers, constaints, and pairs cannot change within the context manager.

Note

Getting a local snapshot object is order \(O(1)\) and setting a single value is of order \(O(1)\).

Type

hoomd.data.LocalSnapshotGPU

property improper_types

List of all improper types in the simulation.

Type

list[str]

property particle_types

List of all particle types in the simulation.

Type

list[str]

replicate()
property snapshot

All data of a simulation’s current microstate.

State.snapshot should be used when all of a simulation’s state information is desired in a single object. When accessed, data across all MPI ranks and from GPUs is gathered on the root MPI rank’s memory. When accessing data in MPI simulations, it is recommended to use a if snapshot.exists: conditional to prevent attempting to access data on a non-root rank.

This property can be set to replace the system state with the given hoomd.Snapshot object. Example use cases in which a simulation’s state may be reset from a snapshot include Monte Carlo schemes implemented at the Python script level, where the current snapshot is passed to the Monte Carlo simulation before being passed back after running some Monte Carlo steps.

Warning

Using State.snapshot multiple times will gather data across MPI ranks and GPUs every time. If the snapshot is needed for more than one use, it is recommended to store it in a variable.

Note

Setting or getting a snapshot is an order \(O(N_{particles} + N_{bonds} + \ldots)\) operation.

Type

hoomd.Snapshot

property special_pair_types

List of all special pair types in the simulation.

Type

list[str]

thermalize_particle_momenta(filter, kT)

Assign random values to particle momenta.

Parameters

thermalize_particle_momenta assigns the selected particle’s velocities and angular momentum to random values drawn from a Gaussian distribution consistent with the given thermal energy kT.

Velocity

thermalize_particle_momenta assigns random velocities to the x and y components of each particle’s velocity. When the simulation box is 3D, it also assigns a random velocity to the z component. When the simulation box is 2D, it sets the z component to 0. Finally, sets the center of mass velocity of the selected particles to 0.

Angular momentum

thermalize_particle_momenta assigns random angular momenta to each rotational degree of freedom that has a non-zero moment of intertia. Each particle can have 0, 1, 2, or 3 rotational degrees of freedom.

See also

md.methods.NVT.thermalize_extra_dof

md.methods.NPT.thermalize_extra_dof

property types

dictionary of all types in the state.

Combines the data from State.particle_types, State.bond_types, State.angle_types, State.dihedral_types, State.improper_types, and State.special_pair_types into a dictionary with keys matching the property names.

Type

dict[str, list[str]]

update_group_dof()

Update the number of degrees of freedom in each group.

The groups of particles selected by filters each need to know the number of degrees of freedom given to that group by the simulation’s Integrator. This method is called automatically when:

  • The Integrator is attached to the simulation

Call it manually to force an update.

Modules