Union

class hoomd.hpmc.pair.Union(constituent_potential, leaf_capacity=0)

Bases: Pair

Treat particles as extended bodies.

Parameters:

• constituent_potential (hoomd.hpmc.pair.Pair) – The pair potential to apply between constituent points.

• leaf_capacity (int) – Maximum number of leaf nodes in the tree data structure used by this class. The default leaf_capacity=0 uses an all N*M code path.

Union computes the potential energy between sets of constituent points that rigidly transform about each particle. The union potential between a pair of particles is:

\[U(\vec{r}_{ij}, \mathbf{q}_i, \mathbf{q}_j)) = \sum_{a=1}^{N_{\mathrm{constituents},i}} \sum_{b=1}^{N_{\mathrm{constituents},j}} U_\mathrm{constituent}(\mathbf{q}_j \vec{P}_{j,b} \mathbf{q}_j^* - \vec{P}_{i,a}, \mathbf{q}_i \mathbf{Q}_{i,a}, \mathbf{q}_j \mathbf{Q}_{j,b})\]

where \(N_{\mathrm{constituents},i}\) is the number of constituents on the \(i\) particle and \(U_\mathrm{constituent}\) is the potential evaluated by the given constituent_potential. \(\vec{P}_{i,a}\) and \(\mathbf{Q}_{i,a}\) are the constituent positions and orientations with index \(a\) on the \(i\) particle. \(U_\mathrm{constituent}\) also depends on the constituent particle types and charges (not shown in the equation).

See also

hoomd.md.constrain.Rigid implements a similar evaluation for MD simulations.

Important

Unlike hoomd.md.constrain.Rigid, Union does not automatically include the central particle in the evaluation. You must add a constituent particle with position 0,0,0 when desired.

Note

constituent_potential may be isotropic or have orientation dependence, but it may not be another Union potential.

Tip

The default leaf_capacity=0 performs best for unions with small numbers of constituents. leaf_capacity=4 (or any other non-zero value) activates a tree algorithm that may perform better when you have many constituents.

Example

union = hoomd.hpmc.pair.Union(constituent_potential=lennard_jones)
union.body["R"] = dict(
    types=["A", "A", "A"],
    positions=[(-1, 0, 0), (0, 0, 0), (1, 0, 0)],
)
union.body["A"] = None

simulation.operations.integrator.pair_potentials = [union]

The particle types used as constituents must be particle types present in the system state, even when there are no actual particles of that type. As shown above, set the body for constituent types to None (which is equivalent to dict(types=[], positions=[])).

---

Members inherited from Pair:

property energy

Potential energy contributed by this potential \([\mathrm{energy}]\). Read more...

---

Members defined in Union:

body

The body definition.

Define the position and orientation of each constituent point relative to the position and orientation of the particle (i.e. in the particle reference frame). Set a particle type name for each constituent point which will be used to determine the constituent potential parameters.

The dictionary has the following keys:

• types (list [str]): List of types of constituent points.

• positions (list [tuple [float, float, float]]): List of relative positions of constituent points.

• orientations (list [tuple [float, float, float, float]]): List of orientations (as quaternions) of constituent points (optional, defaults to [(1,0,0,0)] * len(positions)).

• charges (list [float]): List of charges of constituent points (optional, defaults to [0] * len(positions)).

Type: TypeParameter [particle_type, dict] or None

leaf_capacity

Maximum number of leaf nodes in the tree data structure used by this class. Set leaf_capacity=0 to use an all N*M code path.

Example

union.leaf_capacity = 4

Type:

int

property constituent_potential

Interactions between constituent points.

Example

union.constituent_potential

Type:

hpmc.pair.Pair