# 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

Particle data local access.

class hoomd.data.LocalSnapshot(state)

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)

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.

Warning

Values after calling hoomd.Simulation.run are returned by copy not reference. Beforehand, values are returned by reference. For nested data structures, this means that directly editing the internal stuctures such as a list inside a dict will not be reflected after calling hoomd.Simulation.run. Examples of nested structure are the union shape intergrators in HPMC and the table pair potential in MD. The recommended way to handle mutation for nested structures in general is a read-modify-write approach shown below in a code example. Future versions of HOOMD-blue version 3 may lift this restriction and allow for direct modification of nested structures.

union_shape = hoomd.hpmc.integrate.SphereUnion()
union_shape.shape["union"] = {
"shapes": [{"diameter": 1.0}, {"diameter": 1.5}],
"positions": [(0.0, 0.0, 0.0), (-1.0, 0.0, 0.0)]
}
shape_spec = union_shape.shape["union"]
# modify
shape_spec["shapes"][1] = {"diameter": 2.0}
# write
union_shape.shape["union"] = shape_spec

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 tag of the angle. HOOMD-blue uses spacial sorting to improve cache efficiency in angle look-ups. This means the ordering of the array changes. However, angle tags remain constant. This means that if angle.tag[0] is 1, then later whatever angle has a tag of 1 later in the simulation is the same angle.

Type

(N_angles) hoomd.data.array object of int

rtag

The reverse tag of a angle. This means that the value angle.rtag[0] represents the current index for accessing data for the angle with tag 0.

Type

(N_angles_global) hoomd.data.array object of int

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 tag of the bond. HOOMD-blue uses spacial sorting to improve cache efficiency in bond look-ups. This means the ordering of the array changes. However, bond tags remain constant. This means that if bond.tag[0] is 1, then later whatever bond has a tag of 1 later in the simulation is the same bond.

Type

(N_bonds) hoomd.data.array object of int

rtag

the reverse tag of a bond. This means that the value bond.rtag[0] represents the current index to access data for the bond with tag 0.

Type

(N_bonds_global) hoomd.data.array object of int

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 tag of the constraint. HOOMD-blue uses spacial sorting to improve cache efficiency in constraint look-ups. This means the ordering of the array changes. However, constraint tags remain constant. This means that if constraint.tag[0] is 1, then later whatever constraint has a tag of 1 later in the simulation is the same constraint.

Type

(N_constraints) hoomd.data.array object of int

rtag

The reverse tag of a constraint. This means that the value constraint.rtag[0] represents the current index for accessing data for the constraint with tag 0.

Type

(N_constraints_global) hoomd.data.array object of int

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, 3) hoomd.data.array object of int

tag

The tag of the dihedral. HOOMD-blue uses spacial sorting to improve cache efficiency in dihedral look-ups. This means the ordering of the array changes. However, dihedral tags remain constant. This means that if dihedral.tag[0] is 1, then later whatever dihedral has a tag of 1 later in the simulation is the same dihedral.

Type

(N_dihedrals) hoomd.data.array object of int

rtag

The reverse tag of a dihedral. This means that the value dihedral.rtag[0] represents the current index for accessing data for the dihedral with tag 0.

Type

(N_dihedrals_global) hoomd.data.array object of int

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 tag of the improper. HOOMD-blue uses spacial sorting to improve cache efficiency in improper look-ups. This means the ordering of the array changes. However, improper tags remain constant. This means that if improper.tag[0] is 1, then later whatever improper has a tag of 1 later in the simulation is the same improper.

Type

(N_impropers) hoomd.data.array object of int

rtag

The reverse tag of a improper. This means that the value improper.rtag[0] represents the current index for accessing data for the improper with tag 0.

Type

(N_impropers_global) hoomd.data.array object of int

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 tag of the special pair. HOOMD-blue uses spacial sorting to improve cache efficiency in special pair look-ups. This means the ordering of the array changes. However, special pair tags remain constant. This means that if special pair.tag[0] is 1, then later whatever special pair has a tag of 1 later in the simulation is the same special pair.

Type

(N_special_pairs) hoomd.data.array object of int

rtag

The reverse tag of a special pair. This means that the value special pair.rtag[0] represents the current index for accessing data for the special pair with tag 0.

Type

(N_special_pairs_global) hoomd.data.array object of int

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 tag of a particle. HOOMD-blue uses spacial sorting to improve cache efficiency in particle look-ups. This means the ordering of the array changes. However, particle tags remain constant. This means that if particles.tag[0] is 1, then later whatever particle has a tag of 1 later in the simulation is the same particle.

Type

(N_particles) hoomd.data.array object of int

rtag

The reverse tag of a particle. This means that the value particles.rtag[0] represents the current index accessing data for the particle with tag 0.

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

The periodic image a particle occupies

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

particles’ 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, 3) hoomd.data.array object of float

net_energy

net energy of a particle (accounts for duplicate counting of an interaction). $$[\mathrm{energy}]$$

Type

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

Note

That changing some attributes like (velocity or acceleration) may not change the trajectory of the system. Integration of the equations of motion do not necessarily use velocity or accleration directly. This is also true in HOOMD-blue’s MD integration methods (see hoomd.md.methods)

Modules