md.constrain
Overview
A constraint force that acts on the system. |
|
Constrain pairwise particle distances. |
|
Constrain particles in rigid bodies. |
Details
Constraints.
Constraint forces can constrain particles to be a set distance from each other, to have some relative orientation, or impose other types of constraint.
The Rigid
class is special in that only one is allowed in a system and is set
to an hoomd.md.Integrator
object separately in the
rigid
attribute.
Warning
Constraints will be invalidated if two separate constraints apply to the same particle.
The degrees of freedom removed from the system by constraints are
accounted for in hoomd.md.compute.ThermodynamicQuantities
.
- class hoomd.md.constrain.Constraint
A constraint force that acts on the system.
- class hoomd.md.constrain.Distance(tolerance=0.001)
Constrain pairwise particle distances.
- Parameters
tolerance (float) – Relative tolerance for constraint violation warnings.
Distance
applies forces between particles to constrain the distances between particles to specific values. The algorithm implemented is described in:M. Yoneya, H. J. C. Berendsen, and K. Hirasawa, “A Non-Iterative Matrix Method for Constraint Molecular Dynamics Simulations,” Molecular Simulation, vol. 13, no. 6, pp. 395–405, 1994.
M. Yoneya, “A Generalized Non-iterative 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) = (\vec{r}_j - \vec{r}_i) \cdot (\vec{r}_j - \vec{r}_i) - d_{ij}^2 = 0\]In brief, the second derivative of the Lagrange multipliers with respect to time is set to zero, such that both the distance constraints and their time derivatives are conserved within the accuracy of the Velocity Verlet scheme, i.e. within \(\Delta t^2\). The corresponding linear system of equations is solved. Because constraints are satisfied at \(t + 2 \Delta t\), the scheme is self-correcting and drifts are avoided.
Hint
Define the particles (\(i,j\)) and distances (\(d_{ij}\)) for each pairwise distance constraint in a GSD file with
gsd.hoomd.Snapshot.constraints
or in ahoomd.Snapshot
withhoomd.Snapshot.constraints
.Warning
In MPI simulations, all particles connected through constraints will be communicated between ranks as ghost particles. Therefore, it is an error when molecules defined by constraints extend over more than half the local domain size.
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
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 HOOMD system configuration and can interact with other particles via md 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 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, namely, in body space, the center of mass of the body is at \((0,0,0)\) and the moment of inertia is diagonal. You specify the constituent particles to
Rigid
for each type of body in body coordinates. Then,Rigid
takes control of those particles, and sets their position and orientation in the simulation box relative to the position and orientation of the central particle.Rigid
also transfers forces and torques from constituent particles to the central particle. Then, MD integrators can use these forces and torques to integrate the equations of motion of the central particles (representing the whole rigid body) forward in time.Defining bodies
Rigid
accepts one local body definition per body type. The type of a body is the particle type of the central particle in that body. In this way, each particle of type R in the system configuration defines a body of type R.As a convenience, you do not need to create placeholder entries for all of the constituent particles in your initial configuration. You only need to specify the positions and orientations of all the central particles. When you call
create_bodies
, it will create all constituent particles.Warning
Automatic creation of constituent particles changes particle tags. When there are bonds between particles in the initial configuration, or bonds connect to constituent particles, include the constituent particles in the initial configuration manually.
When you create the constituent particles manually (i.e. in an input file or with snapshots), the central particle of a rigid body must have a lower tag than all of its constituent particles. Constituent particles follow in monotonically increasing tag order, corresponding to the order they were defined in the argument to
Rigid
initialization. The order of central and contiguous particles need not to be contiguous. Additionally, you must set thebody
field for each of the particles in the rigid body to the tag of the central particle (for both the central and constituent particles). Setbody
to -1 for particles that do not belong to a rigid body (i.e. free bodies).Integrating bodies
Most integrators in HOOMD support the integration of rotational degrees of freedom. When there are rigid bodies present in the system, do not apply integrators to the constituent particles, only the central and non-rigid particles.
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 computes thermodynamic quantities (temperature, kinetic energy, etc.) appropriately when there are rigid bodies present in the system. When it does so, it ignores all constituent particles and computes the translational and rotational energies of the central particles, which represent the whole body.
Restarting simulations with rigid bodies.
To restart, use
hoomd.write.GSD
to write restart files. GSD stores all of the particle data fields needed to reconstruct the state of the system, including the body tag, rotational momentum, and orientation of the body. Restarting from a gsd file is equivalent to manual constituent particle creation. You still need to specify the same local body space environment toRigid
as you did in the earlier simulation.To set constituent particle types and coordinates for a rigid body use the
body
attribute.- body
body is a mapping from the central particle type to a body definition represented as a dictionary. The mapping respects
None
as meaning that the type is not a rigid body center. All types are set toNone
by default. The keys for the body definition areconstituent_types
(list[str]): List of types of constituent particlespositions
(list[tuple[float, float, float]]): List of relative positions of constituent particlesorientations
(list[tuple[float, float, float, float]]): List of orientations (as quaternions) of constituent particlescharge
(list[float]): List of charges of constituent particlesdiameters
(list[float]): List of diameters of constituent particles
Type:
TypeParameter
[particle_type
,dict
]
Caution
The constituent particle type must exist.
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)], "charges": [0.0, 0.0], "diameters": [1.0, 1.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)], "charges": [0.0, 1.0], "diameters": [1.5, 1.0] } # Can set rigid body definition to be None explicitly. rigid.body["A"] = None
Warning
Rigid
will significantly slow down a simulation when frequently changing rigid body definitions or adding/removing particles from the simulation.- create_bodies(state)
Create rigid bodies from central particles in state.
- Parameters
state (hoomd.State) – The state in which to create rigid bodies.
This method will remove any existing constituent particles (defined as having a valid body flag without a central particle definition in the rigid
body
attribute).Note
This method will change any exiting body tags.
Tip
If planning on using this function, initialize the
hoomd.State
with free and central particles without worrying about the body tag. Existing body values or constituent particles in the state won’t cause errors, but the method does not need it.Warning
This method must be called before its associated simulation is run.