hoomd.data
Overview
Provides context manager access to HOOMD-blue CPU data buffers. |
|
Provides context manager access to HOOMD-blue GPU data buffers. |
|
Class for directly accessing HOOMD-blue angle data. |
|
Class for directly accessing HOOMD-blue bond data. |
|
Class for directly accessing HOOMD-blue constraint data. |
|
Class for directly accessing HOOMD-blue dihedral data. |
|
Class for directly accessing HOOMD-blue improper data. |
|
Class for directly accessing HOOMD-blue special pair data. |
|
Class for directly accessing HOOMD-blue particle data. |
|
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
- 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 thehoomd.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 aLocalSnapshot
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 withghost_
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.
- property bonds
Local bond data.
- property constraints
Local constraint data.
- property dihedrals
Local dihedral data.
- property impropers
Local improper data.
- property pairs
Local special pair data.
- property particles
Local particle data.
- 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 thehoomd.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 aLocalSnapshot
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 withghost_
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.
- property bonds
Local bond data.
- property constraints
Local constraint data.
- property dihedrals
Local dihedral data.
- property impropers
Local improper data.
- property pairs
Local special pair data.
- property particles
Local particle data.
- 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 forhoomd.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 Pythoncollections.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 viadefault
which will be used for all types not defined. In addition, when the type parameter expects adict
-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 theTypeParameter
instance’s associated simulation, keys are not checked that their types exist in thehoomd.State
object. After callingrun
, however, all such data for non-existent types is removed, and querying or attempting to set those keys will result in aKeyError
.- 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 ofint
- members
The tags of particles in a angle.
- Type
(N_angles, 3)
hoomd.data.array
object ofint
- 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 ofint
- 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 ofint
See also
- 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 ofint
- members
The tags of particles in a bond.
- Type
(N_bonds, 2)
hoomd.data.array
object ofint
- 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 ofint
- 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 ofint
See also
- class hoomd.data.ConstraintLocalAccessBase(state)
Class for directly accessing HOOMD-blue constraint data.
- value
The constaint value.
- Type
(N_constraints)
hoomd.data.array
object offloat
- members
the tags of particles in a constraint.
- Type
(N_constraints, 3)
hoomd.data.array
object ofint
- 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 ofint
- 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 ofint
See also
- 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 ofint
- members
the tags of particles in a dihedral.
- Type
(N_dihedrals, 4)
hoomd.data.array
object ofint
- 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 ofint
- 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 ofint
See also
- 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 ofint
- members
The tags of particles in a improper.
- Type
(N_impropers, 3)
hoomd.data.array
object ofint
- 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 ofint
- 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 ofint
See also
- 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 offloat
- members
the tags of particles in a special pair.
- Type
(N_pairs, 3)
hoomd.data.array
object ofint
- 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 ofint
- 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 ofint
See also
- 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 offloat
- 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 ofint
- 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 ofint
- position
Particle positions \([\mathrm{length}]\).
- Type
(N_particles, 3)
hoomd.data.array
object offloat
- image
A count of how many times each particle crosses the periodic box boundaries.
- Type
(N_particles, 3)
hoomd.data.array
object ofint
- velocity
Particle velocities \([\mathrm{velocity}]\).
- Type
(N_particles, 3)
hoomd.data.array
object offloat
- acceleration
Particle accelerations \([\mathrm{velocity} \cdot \mathrm{time}^{-1}]\).
- Type
(N_particles, 3)
hoomd.data.array
object offloat
- mass
Particle masses \([\mathrm{mass}]\).
- Type
(N_particles)
hoomd.data.array
object offloat
- orientation
Particle orientations expressed as quaternions.
- Type
(N_particles, 4)
hoomd.data.array
object offloat
- angmom
Particle angular momenta expressed as quaternions \([\mathrm{mass} \cdot \mathrm{velocity} \cdot \mathrm{length}]\).
- Type
(N_particles, 4)
hoomd.data.array
object offloat
- moment_inertia
Particle principal moments of inertia \([\mathrm{mass} \cdot \mathrm{length}^2]\).
- Type
(N_particles, 3)
hoomd.data.array
object offloat
- charge
Particle electrical charges \([\mathrm{charge}]\).
- Type
(N_particles)
hoomd.data.array
object offloat
- diameter
Particle diameters \([\mathrm{length}]\).
- Type
(N_particles)
hoomd.data.array
object offloat
- body
The id of the rigid body the particle is in.
- Type
(N_particles)
hoomd.data.array
object ofint
- net_force
Net force on particle \([\mathrm{force}]\).
- Type
(N_particles, 3)
hoomd.data.array
object offloat
- net_torque
Net torque on particle \([\mathrm{force} \cdot \mathrm{length}]\).
- Type
(N_particles, 3)
hoomd.data.array
object offloat
- net_virial
Net virial on particle \([\mathrm{energy}]\).
- Type
(N_particles, 3)
hoomd.data.array
object offloat
- net_energy
Net energy of a particle \([\mathrm{energy}]\).
- Type
(N_particles,)
hoomd.data.array
object offloat
Note
Changing some attributes (such as
velocity
andacceleration
) may not alter the trajectory of the system as you would expect. Themd.Integrator
is responsible for integrating the equations of motion and manages the values in these arrays.See also
Modules