State

class hoomd.State(simulation, snapshot, domain_decomposition)

The state of a Simulation object.

Note

This object cannot be directly instantiated. Use Simulation.create_state_from_gsd and Simulation.create_state_from_snapshot to instantiate a State object as part of a simulation.

Overview

State stores the data that describes the thermodynamic microstate of a Simulation object. This data consists of the box, particles, bonds, angles, dihedrals, impropers, special pairs, and constraints.

Box

The simulation box describes the space that contains the particles as a Box object.

Particles

The state contains N_particles particles. Each particle has a position, orientation, type id, body, mass, moment of inertia, charge, diameter, velocity, angular momentum, image, and tag:

  • \(\vec{r}\): position \([\mathrm{length}]\) - X,Y,Z cartesian coordinates defining the position of the particle in the box.

  • \(\mathbf{q}\): orientation \([\mathrm{dimensionless}]\) - Unit quaternion defining the rotation from the particle’s local reference frame to the box reference frame. The four components are in the order \(s\), \(a_x\), \(a_y\), \(a_z\) for the in complex notation \(s + a_x i + a_y j + a_z k\).

  • particle_typeid: type id \([\mathrm{dimensionless}]\) - An integer in the interval [0,len(particle_types)) that identifies the particle’s type. particle_types maps type ids to names with: name = particle_types[particle_typeid].

  • particle_body: body id \([\mathrm{dimensionless}]\) - An integer that identifies the particle’s rigid body. A value of -1 indicates that this particle does not belong to a body. A positive value indicates that the particle belongs to the body particle_body. This particle is the central particle of a body when the body id is equal to the tag \(\mathrm{particle\_body} = \mathrm{particle\_tag}\). (used by hoomd.md.constrain.Rigid)

  • \(m\): mass \([\mathrm{mass}]\) - The particle’s mass.

  • \(I\): moment of inertia \([\mathrm{mass} \cdot \mathrm{length}^2]\) - \(I_{xx}\), \(I_{yy}\), \(I_{zz}\) elements of the diagonal moment of inertia tensor in the particle’s local reference frame. The off-diagonal elements are 0.

  • \(q\): charge \([\mathrm{charge}]\) - The particle’s charge.

  • \(d\): diameter \([\mathrm{length}]\) - Deprecated in v3.0.0. HOOMD-blue reads and writes particle diameters, but does not use them in any computations.

  • \(\vec{v}\): velocity \([\mathrm{velocity}]\) - X,Y,Z components of the particle’s velocity in the box’s reference frame.

  • \(\mathbf{P_S}\): angular momentum \([\mathrm{mass} \cdot \mathrm{velocity} \cdot \mathrm{length}]\) - Quaternion defining the particle’s angular momentum (see note).

  • \(\vec{n}\) : image \([\mathrm{dimensionless}]\) - Integers x,y,z that record how many times the particle has crossed each of the periodic box boundaries.

  • particle_tag : tag \([\mathrm{dimensionless}]\) - An integer that uniquely identifies a given particle. The particles are stored in tag order when writing and initializing to/from a GSD file or snapshot: \(\mathrm{particle\_tag}_i = i\). When accessing data in local snapshots, particles may be in any order.

Note

HOOMD stores angular momentum as a quaternion because that is the form used when integrating the equations of motion (see Kamberaj 2005). The angular momentum quaternion \(\mathbf{P_S}\) is defined with respect to the orientation quaternion of the particle \(\mathbf{q}\) and the vector angular momentum of the particle, lifted into pure imaginary quaternion form \(\mathbf{S}^{(4)}\) as:

\[\mathbf{P_S} = 2 \mathbf{q} \times \mathbf{S}^{(4)}\]

. Following this, the angular momentum vector \(\vec{S}\) in the particle’s local reference frame is:

\[\vec{S} = \frac{1}{2}im(\mathbf{q}^* \times \mathbf{P_S})\]

Bonded groups

The state contains N_bonds bonds, N_angles angles, N_dihedrals dihedrals, N_impropers impropers, and N_special_pairs special pairs. Each of these data structures is similar, differing in the number of particles in the group and what operations use them. Bonds, angles, dihedrals, and impropers contain 2, 3, 4, and 4 particles per group respectively. Bonds specify the toplogy used when computing energies and forces in md.bond, angles define the same for md.angle, dihedrals for md.dihedral and impropers for md.improper. These collectively implement bonding potentials used in molecular dynamics force fields. Like bonds, special pairs define connections between two particles, but special pairs are intended to adjust the 1-4 pairwise interactions in some molecular dynamics force fields: see md.special_pair. Each bonded group is defined by a type id, the group members, and a tag.

  • bond_typeid: type id \([\mathrm{dimensionless}]\) - An integer in the interval [0,len(bond_types)) that identifies the bond’s type. bond_types maps type ids to names with: name = bond_types[bond_typeid]. Similarly, angle_types lists the angle types, dihedral_types lists the dihedral types, improper_types lists the improper types, and special_pair_types lists the special pair types.

  • bond_group: A list of integers in the interval \([0, \max(\mathrm{particle\_tag})]\) that defines the tags of the particles in the bond (2), angle in angle_group (3), dihedral in dihedral_group (4), improper in improper_group (4), or special pair in pair_group (2).

  • bond_tag : tag \([\mathrm{dimensionless}]\) - An integer that uniquely identifies a given bond. The bonds are in tag order when writing and initializing to/from a GSD file or snapshot \(\mathrm{bond\_tag}_i = i\). When accessing data in local snapshots, bonds may be in any order. The same applies to angles with angle_tag, dihedrals with dihedral_tag, impropers with improper_tag, and special pairs with pair_tag.

Constraints

The state contains N_constraints distance constraints between particles. These constraints are used by hoomd.md.constrain.Distance. Each distance constraint consists of a distance value and the group members.

  • constraint_group: A list of 2 integers in the interval \([0, \max(\mathrm{particle\_tag})]\) that identifies the tags of the particles in the constraint.

  • \(d\): constraint value \([\mathrm{length}]\) - The distance between particles in the constraint.

MPI domain decomposition

When running in serial or on 1 MPI rank, the entire simulation state is stored in that process. When using more than 1 MPI rank, HOOMD-blue employs a domain decomposition approach to split the simulation box an integer number of times in the x, y, and z directions (domain_decomposition). Each MPI rank stores and operates on the particles local to that rank. Local particles are those contained within the region defined by the split planes (domain_decomposition_split_fractions). Each MPI rank communicates with its neighbors to obtain the properties of particles near the boundary between ranks (ghost particles) so that it can compute interactions across the boundary.

Accessing Data

Two complementary APIs provide access to the state data: local snapshots that access data directly available on the local MPI rank (including the local and ghost particles) and global snapshots that collect the entire state on rank 0. See State.cpu_local_snapshot, State.gpu_local_snapshot, get_snapshot, and set_snapshot for information about these data access patterns.

See also

To write the simulation to disk, use write.GSD.

property N_angles

The number of angles in the simulation state.

Example:

N_angles = simulation.state.N_angles
Type:

int

property N_bonds

The number of bonds in the simulation state.

Example:

N_bonds = simulation.state.N_bonds
Type:

int

property N_constraints

The number of constraints in the simulation state.

Example:

N_constraints = simulation.state.N_constraints
Type:

int

property N_dihedrals

The number of dihedrals in the simulation state.

Example:

N_dihedrals = simulation.state.N_dihedrals
Type:

int

property N_impropers

The number of impropers in the simulation state.

Example:

N_impropers = simulation.state.N_impropers
Type:

int

property N_particles

The number of particles in the simulation state.

Example:

N_particles = simulation.state.N_particles
Type:

int

property N_special_pairs

The number of special pairs in the simulation state.

Type:

int

property angle_types

List of all angle types in the simulation state.

Example:

angle_types = simulation.state.angle_types
Type:

list[str]

property bond_types

List of all bond types in the simulation state.

Example:

bond_types = simulation.state.bond_types
Type:

list[str]

property box

A copy of the current simulation box.

Note

The box property cannot be set. Call set_box to set a new simulation box.

Example:

box = simulation.state.box
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, constraint, 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 Snapshot.

The hoomd.data.LocalSnapshot data access is mediated through hoomd.data.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 guaranteed 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 simulation.state.cpu_local_snapshot as local_snapshot:
    local_snapshot.particles.position[:, 2] = 0

Note

The state’s box and the number of particles, bonds, angles, dihedrals, impropers, constraints, 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 state.

Example:

angle_types = simulation.state.angle_types
Type:

list[str]

property domain_decomposition

Number of domains in the x, y, and z directions.

Type:

tuple(int, int, int)

property domain_decomposition_split_fractions

Box fractions of the domain split planes in the x, y, and z directions.

Type:

tuple(list[float], list[float], list[float])

get_snapshot()

Make a copy of the simulation current state.

State.get_snapshot makes a copy of the simulation state and makes it available in a single object. set_snapshot resets the internal state to that in the given snapshot. Use these methods to implement techniques like hybrid MD/MC or umbrella sampling where entire system configurations need to be reset to a previous one after a rejected move.

Note

Data across all MPI ranks and from GPUs is gathered on the root MPI rank’s memory. When accessing data in MPI simulations, use a if snapshot.communicator.rank == 0: conditional to access data arrays only on the root rank.

Note

State.get_snapshot is an order \(O(N_{particles} + N_{bonds} + \ldots)\) operation.

See also

set_snapshot

Returns:

The current simulation state

Return type:

Snapshot

Example:

snapshot = simulation.state.get_snapshot()
property gpu_local_snapshot

Expose simulation data on the GPU.

Provides access directly to the system state’s particle, bond, angle, dihedral, improper, constraint, 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 Snapshot.

The hoomd.data.LocalSnapshotGPU data access is mediated through hoomd.data.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 simulation.state.gpu_local_snapshot as local_snapshot:
    local_snapshot.particles.position[:, 2] = 0

Warning

This property is only available when running on a GPU (or multiple GPUs).

Note

The state’s box and the number of particles, bonds, angles, dihedrals, impropers, constraints, 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 state.

Example:

improper_types = simulation.state.improper_types
Type:

list[str]

property particle_types

List of all particle types in the simulation state.

Example:

particle_types = simulation.state.particle_types
Type:

list[str]

replicate(nx, ny, nz=1)

Replicate the state of the system along the periodic box directions.

Parameters:

  • nx (int) – Number of times to replicate in the x direction.

  • ny (int) – Number of times to replicate in the y direction.

  • nz (int) – Number of times to replicate in the z direction.

replicate makes the system state nx * ny * nz times larger. In each of the new periodic box images, it places a copy of the initial state with the particle positions offset to locate them in the image and the bond, angle, dihedral, improper, and pair group tags offset to apply to the copied particles. All other particle properties (mass, typeid, velocity, charge, …) are copied to the new particles without change.

After placing the particles, replicate expands the simulation box by a factor of nx, ny, and nz in the direction of the first, second, and third box lattice vectors respectively and adjusts the particle positions to center them in the new box.

Example:

simulation.state.replicate(nx=2, ny=2, nz=2)
set_box(box)

Set a new simulation box.

Parameters:

box (hoomd.box.box_like) – New simulation box.

Note

All particles must be inside the new box. set_box does not change any particle properties.

See also

hoomd.update.BoxResize.update

Example:

simulation.state.set_box(box)
set_snapshot(snapshot)

Restore the state of the simulation from a snapshot.

Also calls update_group_dof to count the number of degrees in the system with the new state.

Parameters:

snapshot (Snapshot) – Snapshot of the system from get_snapshot

Warning

set_snapshot can only make limited changes to the simulation state. While it can change the number of particles/bonds/etc… or their properties, it cannot change the number or names of the particle/bond/etc.. types.

Note

set_snapshot is an order \(O(N_{particles} + N_{bonds} + \ldots)\) operation and is very expensive when the simulation device is a GPU.

See also

get_snapshot

Simulation.create_state_from_snapshot

Example:

simulation.state.set_snapshot(snapshot)
property special_pair_types

List of all special pair types in the simulation state.

Example:

special_pair_types = simulation.state.special_pair_types
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 inertia. Each particle can have 0, 1, 2, or 3 rotational degrees of freedom as determine by its moment of inertia.

See also

md.methods.thermostats.MTTK.thermalize_dof

md.methods.ConstantPressure.thermalize_barostat_dof

Example:

simulation.state.thermalize_particle_momenta(
    filter=hoomd.filter.All(), kT=1.5
)
property types

dictionary of all types in the state.

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

Type:

dict[str, list[str]]

update_group_dof()

Schedule an update to the number of degrees of freedom in each group.

update_group_dof requests that Simulation update the degrees of freedom provided to each group by the Integrator. Simulation will perform this update at the start of Simulation.run or at the start of the next timestep during an ongoing call to Simulation.run.

This method is called automatically when:

Call update_group_dof manually to force an update, such as when you modify particle moments of inertia with cpu_local_snapshot.

Example:

box = simulation.state.update_group_dof()