md.constrain¶
Overview
Constraint force base class. 

Constrain pairwise particle distances. 

Constrain particles in rigid bodies. 
Details
Constraints.
Constraint force classes apply forces and the resulting virial to particles that enforce specific constraints on the positions of the particles. The constraint is satisfied at all times, so there is no potential energy associated with the constraint.
Each constraint removes a number of degrees of freedom from the system.
hoomd.md.compute.ThermodynamicQuantities
accounts for these lost degrees of
freedom when computing kinetic temperature and pressure. See
hoomd.State.update_group_dof
for details on when the degrees of freedom for a
group are calculated.
Warning
Do not apply multiple constraint class instances to the same particle. Each instance solves for its constraints independently.
 class hoomd.md.constrain.Constraint¶
Bases:
Force
Constraint force base class.
Constraint
is the base class for all constraint forces.Warning
This class should not be instantiated by users. The class can be used for
isinstance
orissubclass
checks.
 class hoomd.md.constrain.Distance(tolerance=0.001)¶
Bases:
Constraint
Constrain pairwise particle distances.
 Parameters:
tolerance (float) – Relative tolerance for constraint violation warnings.
Distance
applies forces between particles that constrain the distances between particles to specific values. The algorithm implemented is described in:M. Yoneya, H. J. C. Berendsen, and K. Hirasawa, “A NonIterative Matrix Method for Constraint Molecular Dynamics Simulations,” Molecular Simulation, vol. 13, no. 6, pp. 395–405, 1994.
M. Yoneya, “A Generalized Noniterative Matrix Method for Constraint Molecular Dynamics Simulations,” Journal of Computational Physics, vol. 172, no. 1, pp. 188–197, Sep. 2001.
Each distance constraint takes the form:
\[\chi_{ij}(r) = \mathrm{minimum\_image}(\vec{r}_j  \vec{r}_i)^2  d_{ij}^2 = 0\]Where \(i\) and \(j\) are the the particle tags in the
constraint_group
and \(d_{ij}\) is the constraint distance as given by the system state.The method sets the second derivative of the Lagrange multipliers with respect to time to zero, such that both the distance constraints and their time derivatives are conserved within the accuracy of the Velocity Verlet scheme (\(O(\delta t^2)\). It solves the corresponding linear system of equations to determine the force. The constraints are satisfied at \(t + 2 \delta t\), so the scheme is selfcorrecting and avoids drifts.
Add an instance of
Distance
to the integrator constraints listhoomd.md.Integrator.constraints
to apply the force during the simulation.Warning
In MPI simulations, it is an error when molecules defined by constraints extend over more than half the local domain size because all particles connected through constraints will be communicated between ranks as ghost particles.
Note
tolerance
sets the tolerance to detect constraint violations and issue a warning message. It does not influence the computation of the constraint force.
 class hoomd.md.constrain.Rigid¶
Bases:
Constraint
Constrain particles in rigid bodies.
Overview
Rigid bodies are defined by a single central particle and a number of constituent particles. All of these are particles in the simulation state and can interact with other particles via forces. The mass and moment of inertia of the central particle set the full mass and moment of inertia of the rigid body (constituent particle mass is ignored).
The central particle is at the center of mass of the rigid body and the particle’s orientation quaternion defines the rotation from the body space into the simulation box. Body space refers to a rigid body viewed in a particular reference frame. In body space, the center of mass of the body is at \((0,0,0)\) and the moment of inertia is diagonal.
Constituent particles
Select one or more particle types in the simulation to use as the central particles. For each rigid body particle type, set the constituent particle type, position and orientations in body coordinates (see
body
). Then,Rigid
takes control of the constituent particles and sets their position and orientation in the simulation box relative to the position and orientation of the central particle:\[\begin{split}\vec{r}_c &= \vec{r}_b + \mathbf{q}_b \vec{r}_{c,\mathrm{body}} \mathbf{q}_b^* \\ \mathbf{q}_c &= \mathbf{q}_b \mathbf{q}_{c,\mathrm{body}}\end{split}\]where \(\vec{r}_c\) and \(\mathbf{q}_c\) are the position and orientation of a constituent particle in the simulation box, \(\vec{r}_{c,\mathrm{body}}\) and \(\mathbf{q}_{c,\mathrm{body}}\) are the position and orientation of that particle in body coordinates, and \(\vec{r}_b\) and \(\mathbf{q}_b\) are the position and orientation of the central particle of that rigid body.
Rigid
also sets the constituent particle image consistent with the image of the central particle and the location of the constituent particle wrapped back into the box.Warning
Rigid
overwrites the constituent particle type ids, positions and orientations. To change the position and orientation of a body, set the desired position and orientation of the central particle and callrun(0)
to triggerRigid
to update the particles.In the simulation state, the
body
particle property defines the particle tag of the central particle:b = body[c]
. In setting thebody
array, set central particles to their tag \(b_i = t_i\), constituent particles to their central particle’s tag \(b_i = t_{center}\), and free particles to 1: \(b_i = 1\). Free particles are particles that are not part of a rigid body.The central particle of a rigid body must have a tag smaller than all of its constituent particles. Constituent particles follow in monotonically increasing tag order, corresponding to the order they are defined in the argument to
Rigid
initialization. The central and constituent particles do not need to be contiguous.Tip
To create constituent particles, initialize a simulation state containing only central particles (but both rigid body and constituent particle types). Then call
create_bodies
to add all the constituent particles to the state.Net force and torque
Rigid
transfers forces, energies, and torques from constituent particles to the central particle and adds them to those from the interaction on the central particle itself. The integration methods use these forces and torques to integrate the equations of motion of the central particles (representing the whole rigid body) forward in time.\[\begin{split}\vec{F}_b' &= \vec{F}_b + \sum_c \vec{F}_c \\ \vec{U}_b' &= U_b + \sum_c U_c \\ \vec{\tau}_b' &= \vec{\tau}_b + \sum_c \vec{\tau}_c + (\mathbf{q}_b \vec{r}_{c,\mathrm{body}} \mathbf{q}_b^*) \times \vec{F}_c\end{split}\]Rigid
also computes the corrected virial accounting for the effective constraint force (see Glaser 2020).Note
Include
'body'
in theNeighborlist exclusions
to avoid calculating interbody forces that will sum to 0. This is required in many cases where nearby particles lead to numerical errors from extremely large forces.Integrating bodies
Set the
rigid
attribute ofhoomd.md.Integrator
to an instance ofRigid
to apply rigid body constraints and apply an integration method (or methods) to the central and nonrigid particles (leave the constituent particles out Rigid
will set their position and orientation). Most integration methods support the integration of rotational degrees of freedom.Example:
rigid_centers_and_free_filter = hoomd.filter.Rigid( ("center", "free")) langevin = hoomd.md.methods.Langevin( filter=rigid_centers_and_free_filter, kT=1.0)
Thermodynamic quantities of bodies
hoomd.md.compute.ThermodynamicQuantities
computes thermodynamic quantities (temperature, kinetic energy, etc.) over the central and nonrigid particles in the system, ignoring the consitutent particles. The body central particles contribute translational and rotational energies to the total.Continuing simulations with rigid bodies.
To continue a simulation, write the simulation state to a file with
hoomd.write.GSD
and initialize the newSimulation
usingcreate_state_from_gsd
. GSD stores all the particle data fields needed to reconstruct the state of the system, including the body, angular momentum, and orientation of the body. Set the same local body space environment tobody
as in the earlier simulation  GSD does not store this information.Example:
rigid = constrain.Rigid() rigid.body['A'] = { "constituent_types": ['A_const', 'A_const'], "positions": [(0,0,1),(0,0,1)], "orientations": [(1.0, 0.0, 0.0, 0.0), (1.0, 0.0, 0.0, 0.0)], } rigid.body['B'] = { "constituent_types": ['B_const', 'B_const'], "positions": [(0,0,.5),(0,0,.5)], "orientations": [(1.0, 0.0, 0.0, 0.0), (1.0, 0.0, 0.0, 0.0)], } # Can set rigid body definition to be None explicitly. rigid.body["A"] = None
Warning
Rigid
will significantly slow simulation performance when frequently changing rigid body definitions or adding/removing particles from the simulation. body¶
body
is a mapping from the central particle type to a body definition represented as a dictionary. The mapping respectsNone
as meaning that the type is not a rigid body center. All types are set toNone
by default. The keys for the body definition are:constituent_types
(list
[str
]): List of types of constituent particles.positions
(list
[tuple
[float
,float
,float
]]): List of relative positions of constituent particles.orientations
(list
[tuple
[float
,float
,float
,float
]]): List of orientations (as quaternions) of constituent particles.
Of these,
Rigid
usesconstituent_types
,positions
andorientations
to set the constituent particle type ids, positions and orientations every time step.create_bodies
uses all these parameters to populate those particle properties when creating constituent particles.Type:
TypeParameter
[particle_type
,dict
]
 create_bodies(state, charges=None)¶
Create rigid bodies from central particles in state.
 Parameters:
state (hoomd.State) – The state in which to create rigid bodies.
charges (dict[str, list[float]]) – (optional) The charges for each of the constituent particles, defaults to
None
. IfNone
, all charges are zero. The keys should be the central particles.
create_bodies
removes any existing constituent particles and adds new ones based on the body definitions inbody
. It overwrites all existing particlebody
tags in the state.