md.force
Overview
Defines a force for molecular dynamics simulations. 

Active force. 

Active force on a manifold. 

Constant force. 

Custom forces implemented in python. 
Details
Apply forces to particles.
 class hoomd.md.force.Force
Defines a force for molecular dynamics simulations.
Force
is the base class for all molecular dynamics forces and provides common methods.A
Force
class computes the force and torque on each particle in the simulation state \(\vec{F}_i\) and \(\vec{\tau}_i\). With a few exceptions (noted in the documentation of the specific force classes),Force
subclasses also compute the contribution to the system’s potential energy \(U\) and the the virial tensor \(W\).Force
breaks the computation of the total system \(U\) and \(W\) into perparticle and additional terms as detailed in the documentation for each specificForce
subclass.\[\begin{split}U & = U_\mathrm{additional} + \sum_{i=0}^{N_\mathrm{particles}1} U_i \\ W & = W_\mathrm{additional} + \sum_{i=0}^{N_\mathrm{particles}1} W_i\end{split}\]Force
represents virial tensors as six element arrays listing the components of the tensor in this order:\[(W^{xx}, W^{xy}, W^{xz}, W^{yy}, W^{yz}, W^{zz}).\]The components of the virial tensor for a force on a single particle are:
\[W^{kl}_i = F^k \cdot r_i^l\]where the superscripts select the x,y, and z components of the vectors. To properly account for periodic boundary conditions, pairwise interactions evaluate the virial:
\[W^{kl}_i = \sum_j F^k_{ij} \cdot \mathrm{minimum\_image}(\vec{r}_j  \vec{r}_i)^l\]Warning
This class should not be instantiated by users. The class can be used for
isinstance
orissubclass
checks. property additional_energy
Additional energy term \(U_\mathrm{additional}\) \([\mathrm{energy}]\).
(
Loggable
: category=”scalar”) Type
 property additional_virial
Additional virial tensor term \(W_\mathrm{additional}\) \([\mathrm{energy}]\).
(
Loggable
: category=”sequence”) Type
(1, 6)
numpy.ndarray
offloat
 property cpu_local_force_arrays
Expose force arrays on the CPU.
Provides direct access to the force, potential energy, torque, and virial data of the particles in the system on the cpu through a context manager. All data is MPI ranklocal.
The
hoomd.md.data.ForceLocalAccess
object returned by this property has four arrays through which one can modify the force data:Note
The local arrays are read only for builtin forces. Use
Custom
to implement custom forces.Examples:
with self.cpu_local_force_arrays as arrays: arrays.force[:] = ... arrays.potential_energy[:] = ... arrays.torque[:] = ... arrays.virial[:] = ...
 property energies
Energy contribution \(U_i\) from each particle \([\mathrm{energy}]\).
Attention
In MPI parallel execution, the array is available on rank 0 only.
energies
isNone
on ranks >= 1.(
Loggable
: category=”particle”) Type
(N_particles, )
numpy.ndarray
offloat
 property energy
The potential energy \(U\) of the system from this force \([\mathrm{energy}]\).
(
Loggable
: category=”scalar”) Type
 property forces
The force \(\vec{F}_i\) applied to each particle \([\mathrm{force}]\).
Attention
In MPI parallel execution, the array is available on rank 0 only.
forces
isNone
on ranks >= 1.(
Loggable
: category=”particle”) Type
(N_particles, 3)
numpy.ndarray
offloat
 property gpu_local_force_arrays
Expose force arrays on the GPU.
Provides direct access to the force, potential energy, torque, and virial data of the particles in the system on the gpu through a context manager. All data is MPI ranklocal.
The
hoomd.md.data.ForceLocalAccessGPU
object returned by this property has four arrays through which one can modify the force data:Note
The local arrays are read only for builtin forces. Use
Custom
to implement custom forces.Examples:
with self.gpu_local_force_arrays as arrays: arrays.force[:] = ... arrays.potential_energy[:] = ... arrays.torque[:] = ... arrays.virial[:] = ...
Note
GPU local force data is not available if the chosen device for the simulation is
hoomd.device.CPU
.
 property torques
The torque \(\vec{\tau}_i\) applied to each particle \([\mathrm{force} \cdot \mathrm{length}]\).
Attention
In MPI parallel execution, the array is available on rank 0 only.
torques
isNone
on ranks >= 1.(
Loggable
: category=”particle”) Type
(N_particles, 3)
numpy.ndarray
offloat
 property virials
Virial tensor contribution \(W_i\) from each particle \([\mathrm{energy}]\).
Attention
To improve performance
Force
objects only compute virials when needed. When not computed,virials
isNone
. Virials are computed on every step when using amd.methods.NPT
ormd.methods.NPH
integrator, on steps where a writer is triggered (such aswrite.GSD
which may log pressure or virials), or whenSimulation.always_compute_pressure
isTrue
.Attention
In MPI parallel execution, the array is available on rank 0 only.
virials
isNone
on ranks >= 1.(
Loggable
: category=”particle”) Type
(N_particles, 6)
numpy.ndarray
offloat
 class hoomd.md.force.Active(filter)
Bases:
Force
Active force.
 Parameters
filter (
hoomd.filter
) – Subset of particles on which to apply active forces.
Active
computes an active force and torque on all particles selected by the filter:\[\begin{split}\vec{F}_i = \mathbf{q}_i \vec{f}_i \mathbf{q}_i^* \\ \vec{\tau}_i = \mathbf{q}_i \vec{u}_i \mathbf{q}_i^*,\end{split}\]where \(\vec{f}_i\) is the active force in the local particle coordinate system (set by type
active_force
) and \(\vec{u}_i\) is the active torque in the local particle coordinate system (set by type inactive_torque
.Note
To introduce rotational diffusion to the particle orientations, use
create_diffusion_updater
.Examples:
all = hoomd.filter.All() active = hoomd.md.force.Active( filter=hoomd.filter.All() ) active.active_force['A','B'] = (1,0,0) active.active_torque['A','B'] = (0,0,0) rotational_diffusion_updater = active.create_diffusion_updater( trigger=10) sim.operations += rotational_diffusion_updater
Note
The energy and virial associated with the active force are 0.
 filter
Subset of particles on which to apply active forces.
 Type
 active_force
Active force vector in the local reference frame of the particle \([\mathrm{force}]\). It is defined per particle type and stays constant during the simulation.
Type:
TypeParameter
[particle_type
,tuple
[float
,float
,float
]]
 active_torque
Active torque vector in the local reference frame of the particle \([\mathrm{force} \cdot \mathrm{length}]\). It is defined per particle type and stays constant during the simulation.
Type:
TypeParameter
[particle_type
,tuple
[float
,float
,float
]]
 create_diffusion_updater(trigger, rotational_diffusion)
Create a rotational diffusion updater for this active force.
 Parameters
trigger (hoomd.trigger.trigger_like) – Select the timesteps to update rotational diffusion.
rotational_diffusion (hoomd.variant.variant_like) – The rotational diffusion as a function of time or a constant.
 Returns
The rotational diffusion updater.
 Return type
 class hoomd.md.force.ActiveOnManifold(filter, manifold_constraint)
Bases:
Active
Active force on a manifold.
 Parameters
filter (
hoomd.filter
) – Subset of particles on which to apply active forces.manifold_constraint (hoomd.md.manifold.Manifold) – Manifold constraint.
ActiveOnManifold
computes a constrained active force and torque on all particles selected by the filter similar toActive
.ActiveOnManifold
restricts the forces to the local tangent plane of the manifold constraint. For more information seeActive
.Hint
Use
ActiveOnManifold
with amd.methods.rattle
integration method with the same manifold constraint.Note
To introduce rotational diffusion to the particle orientations, use
create_diffusion_updater
. The rotational diffusion occurs in the local tangent plane of the manifold.Examples:
all = filter.All() sphere = hoomd.md.manifold.Sphere(r=10) active = hoomd.md.force.ActiveOnManifold( filter=hoomd.filter.All(), rotation_diff=0.01, manifold_constraint = sphere ) active.active_force['A','B'] = (1,0,0) active.active_torque['A','B'] = (0,0,0)
 filter
Subset of particles on which to apply active forces.
 Type
 manifold_constraint
Manifold constraint.
 active_force
Active force vector in the local reference frame of the particle \([\mathrm{force}]\). It is defined per particle type and stays constant during the simulation.
Type:
TypeParameter
[particle_type
,tuple
[float
,float
,float
]]
 active_torque
Active torque vector in local reference frame of the particle \([\mathrm{force} \cdot \mathrm{length}]\). It is defined per particle type and stays constant during the simulation.
Type:
TypeParameter
[particle_type
,tuple
[float
,float
,float
]]
 create_diffusion_updater(trigger, rotational_diffusion)
Create a rotational diffusion updater for this active force.
 Parameters
trigger (hoomd.trigger.trigger_like) – Select the timesteps to update rotational diffusion.
rotational_diffusion (hoomd.variant.variant_like) – The rotational diffusion as a function of time or a constant.
 Returns
The rotational diffusion updater.
 Return type
 class hoomd.md.force.Constant(filter)
Constant force.
 Parameters
filter (
hoomd.filter
) – Subset of particles on which to apply constant forces.
Constant
applies a type dependent constant force and torque on all particles selected by the filter.Constant
sets the force and torque to(0,0,0)
for particles not selected by the filter.Examples:
constant = hoomd.md.force.Constant( filter=hoomd.filter.All() ) constant.constant_force['A'] = (1,0,0) constant.constant_torque['A'] = (0,0,0)
Note
The energy and virial associated with the constant force are 0.
 filter
Subset of particles on which to apply constant forces.
 Type
 class hoomd.md.force.Custom(aniso=False)
Custom forces implemented in python.
Derive a custom force class from
Custom
, and override theset_forces
method to compute forces on particles. Users have direct, zerocopy access to the C++ managed buffers via either thecpu_local_force_arrays
orgpu_local_force_arrays
property. Choose the property that corresponds to the device you wish to alter the data on. In addition to zerocopy access to force buffers, custom forces have access to the local snapshot API via the_state.cpu_local_snapshot
or the_state.gpu_local_snapshot
property.See also
See the documentation in
hoomd.State
for more information on the local snapshot API.Examples:
class MyCustomForce(hoomd.force.Custom): def __init__(self): super().__init__(aniso=True) def set_forces(self, timestep): with self.cpu_local_force_arrays as arrays: arrays.force[:] = 5 arrays.torque[:] = 3 arrays.potential_energy[:] = 27 arrays.virial[:] = np.arange(6)[None, :]
In addition, since data is MPI ranklocal, there may be ghost particle data associated with each rank. To access this readonly ghost data, access the property name with either the prefix
ghost_
of the suffix_with_ghost
.Note
Pass
aniso=True
to themd.force.Custom
constructor if your custom force produces nonzero torques on particles.Examples:
class MyCustomForce(hoomd.force.Custom): def __init__(self): super().__init__() def set_forces(self, timestep): with self.cpu_local_force_arrays as arrays: # access only the ghost particle forces ghost_force_data = arrays.ghost_force # access torque data on this rank and ghost torque data torque_data = arrays.torque_with_ghost
Note
When accessing the local force arrays, always use a context manager.
Note
The shape of the exposed arrays cannot change while in the context manager.
Note
All force data buffers are MPI rank local, so in simulations with MPI, only the data for a single rank is available.
Note
Access to the force buffers is constant (O(1)) time.
Changed in version 3.1.0:
Custom
zeros the force, torque, energy, and virial arrays before calling the userprovidedset_forces
.