Rigid¶

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 call run(0) to trigger Rigid 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 the body 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 the Neighborlist exclusions to avoid calculating inter-body 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 of hoomd.md.Integrator to an instance of Rigid to apply rigid body constraints and apply an integration method (or methods) to the central and non-rigid 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 non-rigid 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 new Simulation using create_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 to body 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.

Members inherited from AutotunedObject:

property kernel_parameters¶: Kernel parameters. Read more...

property is_tuning_complete¶: Check if kernel parameter tuning is complete. Read more...

tune_kernel_parameters()¶: Start tuning kernel parameters. Read more...

Members inherited from Force:

additional_energy¶: Additional energy term. Read more...

additional_virial¶: Additional virial tensor term \(W_\mathrm{additional}\). Read more...

cpu_local_force_arrays¶: Local force arrays on the CPU. Read more...

energies¶: Energy contribution \(U_i\) from each particle. Read more...

energy¶: The potential energy \(U\) of the system from this force. Read more...

forces¶: The force \(\vec{F}_i\) applied to each particle. Read more...

gpu_local_force_arrays¶: Local force arrays on the GPU. Read more...

torques¶: The torque \(\vec{\tau}_i\) applied to each particle. Read more...

virials¶: Virial tensor contribution \(W_i\) from each particle. Read more...

Members defined in Rigid:

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 to None 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 uses constituent_types, positions and orientations 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. If None, 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 in body. It overwrites all existing particle body tags in the state.