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.

typeparam.TypeParameter

Store parameters by type or type pair.

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.

See also

Access the local snapshot of a state via hoomd.State.cpu_local_snapshot.

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.

See also

Access the local snapshot of a state via hoomd.State.gpu_local_snapshot.

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)

Store parameters by type or type pair.

Implements the collections.abc.MutableMapping interface (excluding __delitem__).

Many operations in HOOMD-blue utilize parameters that depend on the type or pairs of types. For example, the Langevin drag coefficient (hoomd.md.methods.Langevin.gamma) are set by particle type and Lennard-Jones pair potential parameters (hoomd.md.pair.LJ.params) are set by pairs of particle types.

TypeParameter holds the values of these type (or type pair) dependent parameters. It also provides convenience methods for setting defaults and multiple parameters on one line.

Important

Parameters for all types (or unordered pairs of types) in the simulation state must be defined prior to calling Simulation.run().

Note

TypeParameter removes types (or type pairs) not present in the simulation state after its operation is added to the simulation and the simulation has been run for 0 or more steps.

The examples below use hoomd.md.methods.Langevin and hoomd.md.pair.LJ to demonstrate.

lj = hoomd.md.pair.LJ(nlist=hoomd.md.nlist.Cell(buffer=0.4))
langevin = hoomd.md.methods.Langevin(filter=hoomd.filter.All(), kT=1.0)
__delitem__(key)

__delitem__ is not available for TypeParameter objects.

__eq__(other)

Test for equality.

langevin.gamma == lj.params
__getitem__(key)

Access parameters by key or keys.

Examples:

gamma_A = langevin.gamma['A']
lj_epsilon_AB = lj.params[('A', 'B')]['epsilon']

Multiple keys

When key denotes multiple pairs (see __setitem__), __getitem__ returns multiple items in a dictionary:

gammas = langevin.gamma[['A', 'B']]

is equivalent to:

gammas = {key: langevin.gamma[key] for key in ['A', 'B']}
__iter__()

Iterate over the keys in the mapping.

Example:

for type_pair in lj.params:
    pass
__len__()

Get the number of type parameters in the mapping.

Example:

n_type_pairs = len(lj.params)
__setitem__(key, value)

Set parameters for a given type (or type pair).

Examples:

Index types by name:

langevin.gamma['A'] = 2.0

Set parameters for multiple types:

langevin.gamma[['B', 'C']] = 3.0

Set type pair parameters with a tuple of names:

lj.params[('A', 'A')] = dict(epsilon=1.5, sigma=2.0)

Set parameters for multiple pairs (e.g. (‘A’, ‘B’) and (‘A’, ‘C’)):

lj.params[('A', ['B', 'C'])] = dict(epsilon=0, sigma=0)

Set parameters for multiple pairs (e.g. (‘B’, ‘B’), (‘B’, ‘C’), (‘C’, ‘B’), and (‘C’, ‘C’)):

lj.params[(['B', 'C'], ['B', 'C'])] = dict(epsilon=1, sigma=1)

Note

Setting the value for (a,b) automatically sets the symmetric (b,a) parameter to the same value.

property default

The default value of the parameter.

TypeParameter uses the default value for any type (or type pair) in the simulation state that is not explicitly set by __setitem__ or setdefault.

Examples:

Set a default value:

langevin.gamma.default = 2.0

When the parameter is a dictionary, set defaults for zero or more keys in that dictionary:

lj.params.default = dict(epsilon=0)
lj.params.default = dict(epsilon=1, sigma=1)
get(key, default)

Get the value of the key with undefined keys returning default.

Parameters:
  • key – Valid keys specifications (depends on the expected key length).

  • default – The value to default to if a key is not found in the mapping.

Returns:

Returns the parameter value for the key when set. Otherwise, returns the provided default.

Example:

gamma_D = langevin.gamma.get('D', default=5.0)
setdefault(key, default)

Set the value for the keys if not already specified.

Parameters:
  • key – Valid keys specifications (depends on the expected key length).

  • default – The value to set when the key is not found in the mapping.

Example

langevin.gamma.setdefault('D', default=5.0)
to_base()

Convert to a Python dict.

Example:

plain_dict = lj.params.to_base()
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

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

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

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

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

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

class hoomd.data.ParticleLocalAccessBase(state)

Class for directly accessing HOOMD-blue particle data.

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.

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

Modules