hoomd.data

Overview

LocalSnapshot	Provides context manager access to HOOMD-blue CPU data buffers.
LocalSnapshotGPU	Provides context manager access to HOOMD-blue GPU data buffers.
AngleLocalAccessBase	Class for directly accessing HOOMD-blue angle data.
BondLocalAccessBase	Class for directly accessing HOOMD-blue bond data.
ConstraintLocalAccessBase	Class for directly accessing HOOMD-blue constraint data.
DihedralLocalAccessBase	Class for directly accessing HOOMD-blue dihedral data.
ImproperLocalAccessBase	Class for directly accessing HOOMD-blue improper data.
PairLocalAccessBase	Class for directly accessing HOOMD-blue special pair data.
ParticleLocalAccessBase	Class for directly accessing HOOMD-blue particle data.
hoomd.data.typeparam.TypeParameter	Implement a type based mutable mapping.

Details

Access State data on the local rank.

LocalSnapshot, LocalSnapshotGPU, and related classes provide direct access to the data buffers managed by hoomd.State.

See also

hoomd.State

class hoomd.data.LocalSnapshot(state)

Provides context manager access to HOOMD-blue CPU data buffers.

The interface of a LocalSnapshot is similar to that of the hoomd.Snapshot. Data is MPI rank local so for MPI parallel simulations only the data possessed by a rank is exposed. This means that users must handle the domain decomposition directly. One consequence of this is that access to ghost particle data is provided. A ghost particle is a particle that is not owned by a rank, but nevertheless is required for operations that use particle neighbors. Also, changing the global or local box within a LocalSnapshot context manager is not allowed.

For every property (e.g. data.particles.position), only grabs the data for the regular (non-ghost) particles. The property can be prefixed with ghost_ to grab the ghost particles in a read only manner. Likewise, suffixing with _with_ghost will grab all data on the rank (regular and ghost particles) in a read only array.

All array-like properties return a hoomd.data.array.HOOMDArray object which prevents invalid memory accesses.

Note

For the LocalAccess classes the affixed attributes mentioned above are not shown. Also of interest, ghost data always come immediately after the regular data.

property angles

Local angle data.

Type:

hoomd.data.AngleLocalAccessBase

property bonds

Local bond data.

Type:

hoomd.data.BondLocalAccessBase

property constraints

Local constraint data.

Type:

hoomd.data.ConstraintLocalAccessBase

property dihedrals

Local dihedral data.

Type:

hoomd.data.DihedralLocalAccessBase

property global_box

The global simulation box.

Type:

hoomd.Box

property impropers

Local improper data.

Type:

hoomd.data.ImproperLocalAccessBase

property local_box

The local box according to the domain decomposition.

Type:

hoomd.Box

property pairs

Local special pair data.

Type:

hoomd.data.PairLocalAccessBase

property particles

Local particle data.

Type:

hoomd.data.ParticleLocalAccessBase

class hoomd.data.LocalSnapshotGPU(*args, **kwargs)

Provides context manager access to HOOMD-blue GPU data buffers.

The interface of a LocalSnapshot is similar to that of the hoomd.Snapshot. Data is MPI rank local so for MPI parallel simulations only the data possessed by a rank is exposed. This means that users must handle the domain decomposition directly. One consequence of this is that access to ghost particle data is provided. A ghost particle is a particle that is not owned by a rank, but nevertheless is required for operations that use particle neighbors. Also, changing the global or local box within a LocalSnapshot context manager is not allowed.

For every property (e.g. data.particles.position), only grabs the data for the regular (non-ghost) particles. The property can be prefixed with ghost_ to grab the ghost particles in a read only manner. Likewise, suffixing with _with_ghost will grab all data on the rank (regular and ghost particles) in a read only array.

All array-like properties return a hoomd.data.array.HOOMDGPUArray object which prevents invalid memory accesses.

property angles

Local angle data.

Type:

hoomd.data.AngleLocalAccessBase

property bonds

Local bond data.

Type:

hoomd.data.BondLocalAccessBase

property constraints

Local constraint data.

Type:

hoomd.data.ConstraintLocalAccessBase

property dihedrals

Local dihedral data.

Type:

hoomd.data.DihedralLocalAccessBase

property global_box

The global simulation box.

Type:

hoomd.Box

property impropers

Local improper data.

Type:

hoomd.data.ImproperLocalAccessBase

property local_box

The local box according to the domain decomposition.

Type:

hoomd.Box

property pairs

Local special pair data.

Type:

hoomd.data.PairLocalAccessBase

property particles

Local particle data.

Type:

hoomd.data.ParticleLocalAccessBase

class hoomd.data.typeparam.TypeParameter(name, type_kind, param_dict)

Implement a type based mutable mapping.

Implements the collections.abc.MutableMapping interface ( __delitem__ is disallowed).

TypeParameter instances extend the base Python mapping interface with smart defaults, value/key validation/processing, and advanced indexing. The class’s intended purpose is to store data per type or per unique combinations of type (such as type pairs for hoomd.md.pair potentials) of a prescribed length.

Indexing

For getting and setting values, multiple index formats are supported. The base case is either a string representing the appropriate type or a tuple of such strings if multiple types are required per key. This is the exact same indexing behavior expect from a Python dict, and all functions (barring those that delete keys) should function as expected for a Python collections.defaultdict.

Two ways to extend this base indexing are supported. First is using an iterator of the final key types. This will perform the method for all specified types in the iterator. Likewise, for each item in the final tuple (if the expected key type is a tuple of multiple string types), an iterator can be used instead of a string which will result in all permutations of such iterators in the tuple. Both advanced indexing methods can be combined.

Note

All methods support advanced indexing as well, and behave as one might expect. Methods that set values will do so for all keys specified, and methods that return values will return values for all keys (within a dict instance).

Note

Ordering in tuples does not matter. Values in tuples are sorted before being stored or queried.

Below are some example indexing values for single and multiple key indexing.

# "A", "B", "C"
["A", "B", "C"]
# ("A", "B")
("A", "B")
# ("A", "B") and ("B", "C")
[("A", "B"), ("B", "C")]
# ("A", "B"), ("A", "C"), and ("A", "D")
("A", ["B", "C", "D"])

Defaults and setting values

TypeParameter instances have default values that can be accessed via default which will be used for all types not defined. In addition, when the type parameter expects a dict-like object, the default will be updated with the set value. This means that values that have defaults do not need to be explicitly specified.

An example of “smart”-setting using the MD LJ potential,

lj = hoomd.md.pair.LJ(nlist=hoomd.md.nlist.Cell())
# params is a TypeParameter object.
# We set epsilon to have a default but sigma is still required
lj.params.default = {"epsilon": 4}
print(lj.params.default)
# {"epsilon": 4.0, "sigma": hoomd.data.typeconverter.RequiredArg}
# We do not need to specify epsilon to use new default value when
# setting
lj.params[("A", "B")] = {"sigma": 1.0}
print(lj.params[("A", "B")])
# {"epsilon": 4.0, "sigma": 1.0}

Note

Before calling hoomd.Simulation.run for the TypeParameter instance’s associated simulation, keys are not checked that their types exist in the hoomd.State object. After calling run, however, all such data for non-existent types is removed, and querying or attempting to set those keys will result in a KeyError.

property default

The default value of the parameter.

class hoomd.data.AngleLocalAccessBase(state)

Class for directly accessing HOOMD-blue angle data.

typeid

The integer type of a angle.

Type:

(N_angles) hoomd.data.array object of int

members

The tags of particles in a angle.

Type:

(N_angles, 3) hoomd.data.array object of int

tag

The angle tags. MPI domain migration reorder angles in memory. The angle tag identifies each angle in the order it existed in the initial configuration.

Type:

(N_angles) hoomd.data.array object of int

rtag

The angle reverse tags. For a given angle tag tag, i = angles.rtag[tag] is the array index holding that angle.

Type:

(N_angles_global) hoomd.data.array object of int

See also

hoomd.State

class hoomd.data.BondLocalAccessBase(state)

Class for directly accessing HOOMD-blue bond data.

typeid

The integer type of a bond.

Type:

(N_bonds) hoomd.data.array object of int

members

The tags of particles in a bond.

Type:

(N_bonds, 2) hoomd.data.array object of int

tag

The bond tags. MPI domain migration reorder bonds in memory. The bond tag identifies each bond in the order it existed in the initial configuration.

Type:

(N_bonds) hoomd.data.array object of int

rtag

the The bond reverse tags. For a given bond tag tag, i = bonds.rtag[tag] is the array index holding that bond.

Type:

(N_bonds_global) hoomd.data.array object of int

See also

hoomd.State

class hoomd.data.ConstraintLocalAccessBase(state)

Class for directly accessing HOOMD-blue constraint data.

value

The constaint value.

Type:

(N_constraints) hoomd.data.array object of float

members

the tags of particles in a constraint.

Type:

(N_constraints, 3) hoomd.data.array object of int

tag

The constraint tags. MPI domain migration reorder constraints in memory. The constraint tag identifies each constraint in the order it existed in the initial configuration.

Type:

(N_constraints) hoomd.data.array object of int

rtag

The constraint reverse tags. For a given constraint tag tag, i = constraints.rtag[tag] is the array index holding that constraint.

Type:

(N_constraints_global) hoomd.data.array object of int

See also

hoomd.State

class hoomd.data.DihedralLocalAccessBase(state)

Class for directly accessing HOOMD-blue dihedral data.

typeid

The integer type of a dihedral.

Type:

(N_dihedrals) hoomd.data.array object of int

members

the tags of particles in a dihedral.

Type:

(N_dihedrals, 4) hoomd.data.array object of int

tag

The dihedral tags. MPI domain migration reorder dihedrals in memory. The dihedral tag identifies each dihedral in the order it existed in the initial configuration.

Type:

(N_dihedrals) hoomd.data.array object of int

rtag

The dihedral reverse tags. For a given dihedral tag tag, i = dihedrals.rtag[tag] is the array index holding that dihedral.

Type:

(N_dihedrals_global) hoomd.data.array object of int

See also

hoomd.State

class hoomd.data.ImproperLocalAccessBase(state)

Class for directly accessing HOOMD-blue improper data.

typeid

The integer type of a improper.

Type:

(N_impropers) hoomd.data.array object of int

members

The tags of particles in a improper.

Type:

(N_impropers, 3) hoomd.data.array object of int

tag

The improper tags. MPI domain migration reorder impropers in memory. The improper tag identifies each improper in the order it existed in the initial configuration.

Type:

(N_impropers) hoomd.data.array object of int

rtag

The improper reverse tags. For a given improper tag tag, i = impropers.rtag[tag] is the array index holding that improper.

Type:

(N_impropers_global) hoomd.data.array object of int

See also

hoomd.State

class hoomd.data.PairLocalAccessBase(state)

Class for directly accessing HOOMD-blue special pair data.

typeid

The type of special pair.

Type:

(N_pairs) hoomd.data.array object of float

members

the tags of particles in a special pair.

Type:

(N_pairs, 3) hoomd.data.array object of int

tag

The special pair tags. MPI domain migration reorder special pairs in memory. The special pair tag identifies each special pair in the order it existed in the initial configuration.

Type:

(N_special_pairs) hoomd.data.array object of int

rtag

The special pair reverse tags. For a given special pair tag tag, i = pairs.rtag[tag] is the array index holding that special pair.

Type:

(N_special_pairs_global) hoomd.data.array object of int

See also

hoomd.State

class hoomd.data.ParticleLocalAccessBase(state)

Class for directly accessing HOOMD-blue particle data.

typeid

The integer type of a particle.

Type:

(N_particles) hoomd.data.array object of float

tag

The particle tags. Spatial sorting and MPI domain migration reorder particles in memory. The particle tag identifies each particle in the order it existed in the initial configuration.

Type:

(N_particles) hoomd.data.array object of int

rtag

The particle reverse tags. For a given particle tag tag, i = particles.rtag[tag] is the array index holding that particle.

Type:

(N_particles_global) hoomd.data.array object of int

position

Particle positions \([\mathrm{length}]\).

Type:

(N_particles, 3) hoomd.data.array object of float

image

A count of how many times each particle crosses the periodic box boundaries.

Type:

(N_particles, 3) hoomd.data.array object of int

velocity

Particle velocities \([\mathrm{velocity}]\).

Type:

(N_particles, 3) hoomd.data.array object of float

acceleration

Particle accelerations \([\mathrm{velocity} \cdot \mathrm{time}^{-1}]\).

Type:

(N_particles, 3) hoomd.data.array object of float

mass

Particle masses \([\mathrm{mass}]\).

Type:

(N_particles) hoomd.data.array object of float

orientation

Particle orientations expressed as quaternions.

Type:

(N_particles, 4) hoomd.data.array object of float

angmom

Particle angular momenta expressed as quaternions \([\mathrm{mass} \cdot \mathrm{velocity} \cdot \mathrm{length}]\).

Type:

(N_particles, 4) hoomd.data.array object of float

moment_inertia

Particle principal moments of inertia \([\mathrm{mass} \cdot \mathrm{length}^2]\).

Type:

(N_particles, 3) hoomd.data.array object of float

charge

Particle electrical charges \([\mathrm{charge}]\).

Type:

(N_particles) hoomd.data.array object of float

diameter

Particle diameters \([\mathrm{length}]\).

Type:

(N_particles) hoomd.data.array object of float

body

The id of the rigid body the particle is in.

Type:

(N_particles) hoomd.data.array object of int

net_force

Net force on particle \([\mathrm{force}]\).

Type:

(N_particles, 3) hoomd.data.array object of float

net_torque

Net torque on particle \([\mathrm{force} \cdot \mathrm{length}]\).

Type:

(N_particles, 3) hoomd.data.array object of float

net_virial

Net virial on particle \([\mathrm{energy}]\).

Type:

(N_particles, 6) hoomd.data.array object of float

net_energy

Net energy of a particle \([\mathrm{energy}]\).

Type:

(N_particles,) hoomd.data.array object of float

Note

Changing some attributes (such as velocity and acceleration) may not alter the trajectory of the system as you would expect. The md.Integrator is responsible for integrating the equations of motion and manages the values in these arrays.

See also

hoomd.State

Modules

• hoomd.data.array