# hoomd.hpmc.integrate

Overview

 ConvexPolygon Convex polygon hard particle Monte Carlo integrator. ConvexPolyhedron Convex polyhedron hard particle Monte Carlo integrator. ConvexSpheropolygon Convex spheropolygon hard particle Monte Carlo integrator. ConvexSpheropolyhedron Convex spheropolyhedron hard particle Monte Carlo integrator. ConvexSpheropolyhedronUnion Convex spheropolyhedron union hard particle Monte Carlo integrator. Ellipsoid Ellipsoid hard particle Monte Carlo integrator. FacetedEllipsoid Faceted ellipsoid hard particle Monte Carlo integrator. FacetedEllipsoidUnion Faceted ellispod union hard particle Monte Carlo integrator. HPMCIntegrator Base class hard particle Monte Carlo integrator. Polyhedron Polyhedron hard particle Monte Carlo integrator. SimplePolygon Simple polygon hard particle Monte Carlo integrator. Sphere Sphere hard particle Monte Carlo integrator. SphereUnion Sphere union hard particle Monte Carlo integrator. Sphinx Sphinx hard particle Monte Carlo integrator.

Details

Hard particle Monte Carlo integrators.

Metropolis Monte Carlo

The hard particle Monte Carlo (HPMC) integrator HPMCIntegrator samples equilibrium system states using the Metropolis Monte Carlo method. In this method, HPMCIntegrator takes the existing system state in the configuration $$C = (\vec{r}_0, \vec{r}_1, \ldots \vec{r}_{N_\mathrm{particles}-1}, \mathbf{q}_0, \mathbf{q}_2, \ldots \mathbf{q}_{N_\mathrm{particles}-1})$$ with potential energy $$U$$ and perturbs it to a trial configuration $$C^t$$ with potential energy $$U^t$$ leading to an energy difference $$\Delta U = U^t - U$$. The trial move is accepted with the probability:

$\begin{split}p_\mathrm{accept} = \begin{cases} \exp(-\beta \Delta U) & \Delta U > 0 \\ 1 & \Delta U \le 0 \\ \end{cases}\end{split}$

When the trial move is accepted, the system state is set to the the trial configuration. When it is not accepted, the move is rejected and the state is not modified.

Local trial moves

HPMCIntegrator generates local trial moves for a single particle $$i$$ at a time. The move is either a translation move or a rotation move, selected randomly with the probability of a translation move set by HPMCIntegrator.translation_move_probability ($$p_\mathrm{translation}$$).

The form of the trial move depends on the dimensionality of the system. Let $$u$$ be a random value in the interval $$[0,1]$$, $$\vec{v}$$ be a random vector uniformly distributed within the ball of radius 1, and $$\mathbf{w}$$ be a random unit quaternion from the set of uniformly distributed rotations. Then the 3D trial move for particle $$i$$ is:

$\begin{split}\begin{cases} \left( \begin{array}{l} \vec{r}^t_i = \vec{r}_i + d_i \vec{v}, \\ \mathbf{q}^t_i = \mathbf{q}_i \end{array} \right) & u \le p_\mathrm{translation} \\ \left( \begin{array}{l} \vec{r}^t_i = \vec{r}_i, \\ \mathbf{q}^t_i = \frac{\mathbf{q}_i + a_i \mathbf{w}} {\vert \mathbf{q}_i + a_i \mathbf{w} \vert} \end{array} \right) & u > p_\mathrm{translation} \\ \end{cases}\end{split}$

where $$d_i$$ is the translation move size for particle $$i$$ (set by particle type with HPMCIntegrator.d) and $$a_i$$ is the rotation move size (set by particle type with HPMCIntegrator.a).

In 2D boxes, let $$\vec{v}$$ be a random vector uniformly distributed within the disk of radius 1 in the x,y plane and $$\alpha$$ be a random angle in radians in the interval $$[-a_i,a_i]$$. Form a quaternion that rotates about the z axis by $$\alpha$$: $$\mathbf{w} = (\cos(\alpha/2), 0, 0, \sin(\alpha/2))$$. The 2D trial move for particle $$i$$ is:

$\begin{split}\begin{cases} \left( \begin{array}{l} \vec{r}^t_i = \vec{r}_i + d_i \vec{v}, \\ \mathbf{q}^t_i = \mathbf{q}_i \end{array} \right) & u \le p_\mathrm{translation} \\ \left( \begin{array}{l} \vec{r}^t_i = \vec{r}_i, \\ \mathbf{q}^t_i = \frac{\mathbf{q}_i \cdot \mathbf{w}} {\vert \mathbf{q}_i \cdot \mathbf{w} \vert} \end{array} \right) & u > p_\mathrm{translation} \\ \end{cases}\end{split}$

Note

For non-orientable spheres, $$p_\mathrm{translation} = 1$$.

Timesteps

In the serial CPU implementation, HPMCIntegrator performs nselect trial moves per particle in each timestep (which defaults to 4). To achieve detailed balance at the level of a timestep, HPMCIntegrator randomly chooses with equal probability to loop through particles in forward index or reverse index order (random selection severely degrades performance due to cache incoherency). In the GPU and MPI implementations, trial moves are performed in parallel for particles in active domains while leaving particles on the border fixed (see Anderson 2016 for a full description). As a consequence, a single timestep may perform more or less than nselect trial moves per particle when using the parallel code paths. Monitor the number of trial moves performed with HPMCIntegrator.translate_moves and HPMCIntegrator.rotate_moves.

Random numbers

HPMCIntegrator uses a pseudorandom number stream to generate the trial moves. Set the seed using hoomd.Simulation.seed. Given the same seed, the same initial configuration, and the same execution configuration (device and MPI configuration), HPMCIntegrator, will produce exactly the same trajectory.

Note

Due to limited floating point precision, full trajectory reproducibility is only possible with the same binary installation running on the same hardware device. Compiler optimizations, changes to the HOOMD source code, and machine specific code paths may lead to different trajectories.

Energy evaluation

HPMCIntegrator evaluates the energy of a configuration from a number of terms:

$U = U_{\mathrm{pair}} + U_{\mathrm{shape}} + U_{\mathrm{external}}$

To enable simulations of small systems, the pair and shape energies evaluate interactions between pairs of particles in multiple box images:

$\begin{split}U_{\mathrm{pair}} = & \sum_{i=0}^{N_\mathrm{particles}-1} \sum_{j=i+1}^{N_\mathrm{particles}-1} U_{\mathrm{pair},ij}(\vec{r}_j - \vec{r}_i, \mathbf{q}_i, \mathbf{q}_j) \\ + & \sum_{i=0}^{N_\mathrm{particles}-1} \sum_{j=i}^{N_\mathrm{particles}-1} \sum_{\vec{A} \in B_\mathrm{images}, \vec{A} \ne \vec{0}} U_{\mathrm{pair},ij}(\vec{r}_j - (\vec{r}_i + \vec{A}), \mathbf{q}_i, \mathbf{q}_j)\end{split}$

where $$\vec{A} = h\vec{a}_1 + k\vec{a}_2 + l\vec{a}_3$$ is a vector that translates by periodic box images and the set of box images includes all image vectors necessary to find interactions between particles in the primary image with particles in periodic images The first sum evaluates interactions between particle $$i$$ with other particles (not itself) in the primary box image. The second sum evaluates interactions between particle $$i$$ and all potentially interacting periodic images of all particles (including itself). HPMCIntegrator computes $$U_{\mathrm{shape}}$$ similarly (see below).

External potentials apply to each particle individually:

$U_\mathrm{external} = \sum_{i=0}^\mathrm{N_particles-1} U_{\mathrm{external},i}(\vec{r}_i, \mathbf{q}_i)$

Potential classes in hoomd.hpmc.pair evaluate $$U_{\mathrm{pair},ij}$$. Assign a class instance to HPMCIntegrator.pair_potential to apply it during integration. Similarly, potential classes in hoomd.hpmc.external evaluate $$U_{\mathrm{external},i}$$. Assign a class instance to HPMCIntegrator.external_potential to apply it during integration.

Shape overlap tests

HPMCIntegrator performs shape overlap tests to evaluate $$U_{\mathrm{shape}}$$. Let $$S$$ be the set of all points inside the shape in the local coordinate system of the shape:

$S = \{ \vec{a} \in \mathbb{R}^3 : \vec{a} \enspace \mathrm{inside\ the\ shape} \}$

See the subclasses of HPMCIntegrator for formal definitions of the shapes, whose parameters are set by particle type. Let $$S_i$$ refer specifically to the shape for particle $$i$$.

The quaternion $$\mathbf{q}$$ represents a rotation of the shape from its local coordinate system to the given orientation:

$S(\mathbf{q}) = \{ \mathbf{q}\vec{a}\mathbf{q}^* : \vec{a} \in S \}$

The full transformation from the local shape coordinate system to the simulation box coordinate system includes a rotation and translation:

$S(\mathbf{q}, \vec{r}) = \{ \mathbf{q}\vec{a}\mathbf{q}^* + \vec{r} : \vec{a} \in S \}$

HPMCIntegrator defines the shape overlap test for two shapes:

$\mathrm{overlap}(S_1, S_2) = S_1 \bigcap S_2$

To check for overlaps between two particles in the box, rotating both shapes from their local frame to the box frame, and translate $$S_2$$ relative to particle 1:

$\mathrm{overlap}(S_1(\mathbf{q}_1), S_2(\mathbf{q}_2, \vec{r}_2 - \vec{r}_1))$

The complete hard shape interaction energy for a given configuration is:

$\begin{split}U_\mathrm{shape} = \quad & \infty \cdot \sum_{i=0}^{N_\mathrm{particles}-1} \sum_{j=i+1}^{N_\mathrm{particles}-1} \left[ \mathrm{overlap}\left( S_i(\mathbf{q}_i), S_j(\mathbf{q}_j, \vec{r}_j - \vec{r}_i) \right) \ne \emptyset \right] \\ + & \infty \cdot \sum_{i=0}^{N_\mathrm{particles}-1} \sum_{j=i}^{N_\mathrm{particles}-1} \sum_{\vec{A} \in B_\mathrm{images}, \vec{A} \ne \vec{0}} \left[ \mathrm{overlap}\left( S_i(\mathbf{q}_i), S_j(\mathbf{q}_j, \vec{r}_j - (\vec{r}_i + \vec{A})) \right) \ne \emptyset \right]\end{split}$

where the square brackets denote the Iverson bracket.

Note

While this notation is written in as sums over all particles HPMCIntegrator uses spatial data structures to evaluate these calculations efficiently. Similarly, while the overlap test is notated as a set intersection, HPMCIntegrator employs efficient computational geometry algorithms to determine whether there is or is not an overlap.

Implicit depletants

Set HPMCIntegrator.depletant_fugacity to activate the implicit depletant code path. This inerts depletant particles during every trial move and modifies the acceptance criterion accordingly. See Glaser 2015 for details.

Warning

The algorithm and API for implicit depletants is experimental and will change in a future minor releases. Specifically, it will switch to accepting a single type parameter: fugacity['A', 'A'] -> fugacity['A']

class hoomd.hpmc.integrate.ConvexPolygon(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Convex polygon hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of convex polygons. The shape $$S$$ of a convex polygon includes the points inside and on the surface of the convex hull of the vertices (see shape). For example:

Important

ConvexPolygon simulations must be performed in 2D systems.

Use SimplePolygon for concave polygons.

Wall support.

ConvexPolygon supports no hoomd.wall geometries.

Examples:

mc = hoomd.hpmc.integrate.ConvexPolygon(default_d=0.3, default_a=0.4)
mc.shape["A"] = dict(vertices=[(-0.5, -0.5),
(0.5, -0.5),
(0.5, 0.5),
(-0.5, 0.5)]);
print('vertices = ', mc.shape["A"]["vertices"])

shape

The shape parameters for each particle type. The dictionary has the following keys.

Warning

HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Example

>>> mc.type_shapes()
'vertices': [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]]}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.ConvexPolyhedron(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Convex polyhedron hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of convex polyhedra. The shape $$S$$ of a convex polyhedron includes the points inside and on the surface of the convex hull of the vertices (see shape). For example:

Use Polyhedron for concave polyhedra.

Wall support.

ConvexPolyhedron supports all hoomd.wall geometries.

Example:

mc = hpmc.integrate.ConvexPolyhedron(default_d=0.3, default_a=0.4)
mc.shape["A"] = dict(vertices=[(0.5, 0.5, 0.5),
(0.5, -0.5, -0.5),
(-0.5, 0.5, -0.5),
(-0.5, -0.5, 0.5)]);
print('vertices = ', mc.shape["A"]["vertices"])

shape

The shape parameters for each particle type. The dictionary has the following keys.

Warning

HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Example

>>> mc.type_shapes()
'vertices': [[0.5, 0.5, 0.5], [0.5, -0.5, -0.5],
[-0.5, 0.5, -0.5], [-0.5, -0.5, 0.5]]}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.ConvexSpheropolygon(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Convex spheropolygon hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of convex spheropolygons. The shape $$S$$ of a convex spheropolygon includes the points inside and on the surface of the convex hull of the vertices plus a disk (with radius sweep_radius)swept along the perimeter (see shape). For example:

Important

ConvexSpheropolygon simulations must be performed in 2D systems.

Tip

To model mixtures of convex polygons and convex spheropolygons, use ConvexSpheropolygon and set the sweep radius to 0 for some shape types.

Tip

A 1-vertex spheropolygon is a disk and a 2-vertex spheropolygon is a rectangle with half disk caps.

Wall support.

ConvexSpheropolygon supports no hoomd.wall geometries.

Examples:

mc = hoomd.hpmc.integrate.ConvexSpheropolygon(default_d=0.3,
default_a=0.4)
mc.shape["A"] = dict(vertices=[(-0.5, -0.5),
(0.5, -0.5),
(0.5, 0.5),
(-0.5, 0.5)],

mc.shape["A"] = dict(vertices=[(0,0)],
ignore_statistics=True);

print('vertices = ', mc.shape["A"]["vertices"])

shape

The shape parameters for each particle type. The dictionary has the following keys:

• vertices (list [tuple [float, float]], required) - vertices of the polygon $$[\mathrm{length}]$$.

• The origin MUST be contained within the spheropolygon.

• Points inside the polygon should not be included.

• The origin centered circle that encloses all vertices should be of minimal size for optimal performance.

• ignore_statistics (bool, default: False) - set to True to ignore tracked statistics.

• sweep_radius (default: 0.0) - radius of the disk swept around the edges of the polygon $$[\mathrm{length}]$$. Set a non-zero sweep_radius to create a spheropolygon.

Warning

HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Example

>>> mc.type_shapes()
'vertices': [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]]}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.ConvexSpheropolyhedron(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Convex spheropolyhedron hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of convex spheropolyhedra. The shape $$S$$ of a convex spheropolyhedron includes the points inside and on the surface of the convex hull of the vertices plus a sphere (with radius sweep_radius) swept along the perimeter (see shape). See ConvexSpheropolygon for a visual example in 2D.

Tip

A 1-vertex spheropolygon is a sphere and a 2-vertex spheropolygon is a spherocylinder.

Wall support.

ConvexSpheropolyhedron supports the hoomd.wall.Sphere and hoomd.wall.Plane geometries.

Example:

mc = hpmc.integrate.ConvexSpheropolyhedron(default_d=0.3, default_a=0.4)
mc.shape['tetrahedron'] = dict(vertices=[(0.5, 0.5, 0.5),
(0.5, -0.5, -0.5),
(-0.5, 0.5, -0.5),
(-0.5, -0.5, 0.5)]);
print('vertices = ', mc.shape['tetrahedron']["vertices"])

mc.shape['SphericalDepletant'] = dict(vertices=[],
ignore_statistics=True);


Depletants example:

mc = hpmc.integrate.ConvexSpheropolyhedron(default_d=0.3, default_a=0.4)
mc.shape["tetrahedron"] = dict(vertices=[(0.5, 0.5, 0.5),
(0.5, -0.5, -0.5),
(-0.5, 0.5, -0.5),
(-0.5, -0.5, 0.5)]);
mc.depletant_fugacity["SphericalDepletant"] = 3.0

shape

The shape parameters for each particle type. The dictionary has the following keys:

Warning

HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Example

>>> mc.type_shapes()
'vertices': [[0.5, 0.5, 0.5], [0.5, -0.5, -0.5],
[-0.5, 0.5, -0.5], [-0.5, -0.5, 0.5]]}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.ConvexSpheropolyhedronUnion(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Convex spheropolyhedron union hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of unions of convex sphereopolyhedra. The union shape $$S$$ is the set union of the given convex spheropolyhedra:

$S = \bigcup_k S_k(\mathbf{q}_k, \vec{r}_k)$

Each constituent shape in the union has its own shape parameters $$S_k$$, position $$\vec{r}_k$$, and orientation $$\mathbf{q}_k$$ (see shape).

Note

This shape uses an internal OBB tree for fast collision queries. Depending on the number of constituent spheropolyhedra in the tree, different values of the number of spheropolyhedra per leaf node may yield different performance. The capacity of leaf nodes is configurable.

Wall support.

ConvexSpheropolyhedronUnion supports no hoomd.wall geometries.

Example:

mc = hoomd.hpmc.integrate.ConvexSpheropolyhedronUnion(default_d=0.3,
default_a=0.4)
cube_verts = [[-1,-1,-1],
[-1,-1,1],
[-1,1,1],
[-1,1,-1],
[1,-1,-1],
[1,-1,1],
[1,1,1],
[1,1,-1]]
mc.shape["A"] = dict(shapes=[cube_verts, cube_verts],
positions=[(0, 0, 0), (0, 0, 1)],
orientations=[(1, 0, 0, 0), (1, 0, 0, 0)],
overlap=[1, 1]);
print('vertices of the first cube = ',
mc.shape["A"]["shapes"][0]["vertices"])
print('center of the first cube = ', mc.shape["A"]["positions"][0])
print('orientation of the first cube = ',
mc.shape_param["A"]["orientations"][0])

shape

The shape parameters for each particle type. The dictionary has the following keys:

Type

TypeParameter [particle type, dict]

class hoomd.hpmc.integrate.Ellipsoid(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Ellipsoid hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of ellipsoids. The shape $$S$$ includes all points inside and on the surface of an ellipsoid:

$S = \left \{ \vec{r} : \frac{r_x^2}{a^2} + \frac{r_y^2}{b^2} + \frac{r_z^2}{c^2} \le 1 \right\}$

where $$r_x$$, $$r_y$$, $$r_z$$ are the components of $$\vec{r}$$, and the parameters $$a$$, $$b$$, and $$c$$ are the half axes of the ellipsoid set in shape.

Wall support.

Ellipsoid supports no hoomd.wall geometries.

Example:

mc = hpmc.integrate.Ellipsoid(default_d=0.3, default_a=0.4)
mc.shape["A"] = dict(a=0.5, b=0.25, c=0.125);
print('ellipsoids parameters (a,b,c) = ',
mc.shape["A"]["a"],
mc.shape["A"]["b"],
mc.shape["A"]["c"])

shape

The shape parameters for each particle type. The dictionary has the following keys:

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Example

>>> mc.type_shapes()
[{'type': 'Ellipsoid', 'a': 1.0, 'b': 1.5, 'c': 1}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.FacetedEllipsoid(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Faceted ellipsoid hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of faceted ellipsoids. The shape $$S$$ of a faceted ellipsoid is the intersection of an ellipsoid with a convex polyhedron defined through halfspaces (see shape). The equation defining each halfspace is given by:

$\vec{n}_i\cdot \vec{r} + b_i \le 0$

where $$\vec{n}_i$$ is the face normal, and $$b_i$$ is the offset.

Wall support.

FacetedEllipsoid supports no hoomd.wall geometries.

Example:

mc = hpmc.integrate.FacetedEllipsoid(default_d=0.3, default_a=0.4)

# half-space intersection
slab_normals = [(-1,0,0),(1,0,0),(0,-1,0),(0,1,0),(0,0,-1),(0,0,1)]
slab_offsets = [-0.1,-1,-.5,-.5,-.5,-.5]

# polyedron vertices
slab_verts = [[-.1,-.5,-.5],
[-.1,-.5,.5],
[-.1,.5,.5],
[-.1,.5,-.5],
[1,-.5,-.5],
[1,-.5,.5],
[1,.5,.5],
[1,.5,-.5]]

mc.shape["A"] = dict(normals=slab_normals,
offsets=slab_offsets,
vertices=slab_verts,
a=1.0,
b=0.5,
c=0.5);
print('a = {}, b = {}, c = {}',
mc.shape["A"]["a"], mc.shape["A"]["b"], mc.shape["A"]["c"])

shape

The shape parameters for each particle type. The dictionary has the following keys:

Important

The origin must be chosen so as to lie inside the shape, or the overlap check will not work. This condition is not checked.

Warning

Planes must not be coplanar.

Note

For simple intersections with planes that do not intersect within the sphere, the vertices list can be left empty. When specified, the half-space intersection of the normals must match the convex polyhedron defined by the vertices (if non-empty), the half-space intersection is not calculated automatically.

Type

TypeParameter[particle type, dict]

class hoomd.hpmc.integrate.FacetedEllipsoidUnion(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Faceted ellispod union hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of unions of faceted ellipsoids. The union shape $$S$$ is the set union of the given faceted ellipsoids:

$S = \bigcup_k S_k(\mathbf{q}_k, \vec{r}_k)$

Each constituent shape in the union has its own shape parameters $$S_k$$, position $$\vec{r}_k$$, and orientation $$\mathbf{q}_k$$ (see shape).

Note

This shape uses an internal OBB tree for fast collision queries. Depending on the number of constituent faceted ellipsoids in the tree, different values of the number of faceted ellipsoids per leaf node may yield different performance. The capacity of leaf nodes is configurable.

Wall support.

FacetedEllipsoidUnion supports no hoomd.wall geometries.

Example:

mc = hpmc.integrate.FacetedEllipsoidUnion(default_d=0.3, default_a=0.4)

# make a prolate Janus ellipsoid
# cut away -x halfspace
normals = [(-1,0,0)]
offsets = [0]
slab_normals = [(-1,0,0),(1,0,0),(0,-1,0),(0,1,0),(0,0,-1),(0,0,1)]
slab_offsets = [-0.1,-1,-.5,-.5,-.5,-.5)

# polyedron vertices
slab_verts = [[-.1,-.5,-.5],
[-.1,-.5,.5],
[-.1,.5,.5],
[-.1,.5,-.5],
[1,-.5,-.5],
[1,-.5,.5],
[1,.5,.5],
[1,.5,-.5]]

faceted_ellipsoid1 = dict(normals=slab_normals,
offsets=slab_offsets,
vertices=slab_verts,
a=1.0,
b=0.5,
c=0.5);
faceted_ellipsoid2 = dict(normals=slab_normals,
offsets=slab_offsets,
vertices=slab_verts,
a=0.5,
b=1,
c=1);

mc.shape["A"] = dict(shapes=[faceted_ellipsoid1, faceted_ellipsoid2],
positions=[(0, 0, 0), (0, 0, 1)],
orientations=[(1, 0, 0, 0), (1, 0, 0, 0)],
overlap=[1, 1]);

print('offsets of the first faceted ellipsoid = ',
mc.shape["A"]["shapes"][0]["offsets"])
print('normals of the first faceted ellipsoid = ',
mc.shape["A"]["shapes"][0]["normals"])
print('vertices of the first faceted ellipsoid = ',
mc.shape["A"]["shapes"][0]["vertices"]

shape

The shape parameters for each particle type. The dictionary has the following keys:

Type

TypeParameter [particle type, dict]

class hoomd.hpmc.integrate.HPMCIntegrator(default_d, default_a, translation_move_probability, nselect)

Bases: Integrator

Base class hard particle Monte Carlo integrator.

HPMCIntegrator is the base class for all HPMC integrators. The attributes documented here are available to all HPMC integrators.

The module level documentation hoomd.hpmc.integrate describes the hard particle Monte Carlo algorithm.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.

Ignoring overlap checks

Set elements of interaction_matrix to False to disable overlap checks between specific pairs of particle types.

Writing type_shapes to GSD files.

Use a Logger in combination with a HPMC integrator and a GSD writer to write type_shapes to the GSD file for use with OVITO. For example:

mc = hoomd.hpmc.integrate.Sphere()
log = hoomd.logging.Logger()
gsd = hoomd.write.GSD(
'trajectory.gsd', hoomd.trigger.Periodic(1000), log=log)


HPMC integrators use threaded execution on multiple CPU cores only when placing implicit depletants (depletant_fugacity != 0).

Mixed precision

All HPMC integrators use reduced precision floating point arithmetic when checking for particle overlaps in the local particle reference frame.

Parameters

a

Maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

Type

TypeParameter [particle type, float]

d

Maximum size of displacement trial moves $$[\mathrm{length}]$$.

Type

TypeParameter [particle type, float]

depletant_fugacity

Depletant fugacity $$[\mathrm{volume}^{-1}]$$ (default: 0)

Allows setting the fugacity per particle type, e.g. 'A' refers to a depletant of type A.

Warning

The algorithm and API for implicit depletants is experimental and will change in a future minor releases. Specifically, it will switch to accepting a single type parameter: fugacity['A', 'A'] -> fugacity['A']

Type

TypeParameter [ particle type, float]

depletant_ntrial

Multiplicative factor for the number of times a depletant is inserted. This factor is accounted for in the acceptance criterion so that detailed balance is unchanged. Higher values of ntrial (than one) can be used to reduce the variance of the free energy estimate and improve the acceptance rate of the Markov chain.

Type

TypeParameter [particle type, int]

interaction_matrix

Set to False for a pair of particle types to disable overlap checks between particles of those types (default: True).

Type

TypeParameter [ tuple [particle type, particle type], bool]

translation_move_probability

Fraction of moves to be selected as translation moves.

Type

float

nselect

Number of trial moves to perform per particle per timestep.

Type

int

Attributes

__dir__()

Expose all attributes for dynamic querying in notebooks and IDEs.

property counters

Trial move counters.

The counter object has the following attributes:

Note

The counts are reset to 0 at the start of each hoomd.Simulation.run.

Type

dict

property external_potential

The user-defined potential energy field integrator.

Defines the external energy $$U_{\mathrm{external},i}$$. Defaults to None. May be set to an object from hoomd.hpmc.external.

property loggables

Name, category mapping of loggable quantities.

Type

dict[str, str]

property map_overlaps

List of overlapping particles.

The list contains one entry for each overlapping pair of particles. When a tuple (i,j) is present in the list, there is an overlap between the particles with tags i and j.

Attention

map_overlaps does not support MPI parallel simulations. It returns None when there is more than one MPI rank.

(Loggable: category=”sequence”)

Type

list[tuple[int, int]]

property mps

Number of trial moves performed per second.

Note

The count is reset at the start of each hoomd.Simulation.run.

(Loggable: category=”scalar”)

Type

float

property overlaps

Number of overlapping particle pairs.

(Loggable: category=”scalar”)

Type

int

property pair_potential

The user-defined pair potential.

Defines the pairwise particle interaction energy $$U_{\mathrm{pair},ij}$$. Defaults to None. May be set to an object from hoomd.hpmc.pair.

property rotate_moves

Count of the accepted and rejected rotate moves.

Note

The counts are reset to 0 at the start of each hoomd.Simulation.run.

(Loggable: category=”sequence”)

Type

tuple[int, int]

property translate_moves

Count of the accepted and rejected translate moves.

Note

The counts are reset to 0 at the start of each hoomd.Simulation.run.

(Loggable: category=”sequence”)

Type

tuple[int, int]

class hoomd.hpmc.integrate.Polyhedron(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Polyhedron hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of general polyhedra. The shape $$S$$ contains the points inside the polyhedron defined by vertices and faces (see shape). Polyhedron supports triangle meshes and spheres only. The mesh must be free of self-intersections.

Use ConvexPolyhedron for faster performance with convex polyhedra.

Note

This shape uses an internal OBB tree for fast collision queries. Depending on the number of constituent faces in the tree, different values of the number of faces per leaf node may yield different optimal performance. The capacity of leaf nodes is configurable.

Wall support.

Polyhedron supports no hoomd.wall geometries.

Example:

mc = hpmc.integrate.Polyhedron(default_d=0.3, default_a=0.4)
mc.shape["A"] = dict(vertices=[(-0.5, -0.5, -0.5),
(-0.5, -0.5, 0.5),
(-0.5, 0.5, -0.5),
(-0.5, 0.5, 0.5),
(0.5, -0.5, -0.5),
(0.5, -0.5, 0.5),
(0.5, 0.5, -0.5),
(0.5, 0.5, 0.5)],
faces=[[0, 2, 6],
[6, 4, 0],
[5, 0, 4],
[5, 1, 0],
[5, 4, 6],
[5, 6, 7],
[3, 2, 0],
[3, 0, 1],
[3, 6, 2],
[3, 7, 6],
[3, 1, 5],
[3, 5, 7]])
print('vertices = ', mc.shape["A"]["vertices"])
print('faces = ', mc.shape["A"]["faces"])

shape

The shape parameters for each particle type. The dictionary has the following keys:

Warning

HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Example

>>> mc.type_shapes()
[{'type': 'Mesh', 'vertices': [[0.5, 0.5, 0.5], [0.5, -0.5, -0.5],
[-0.5, 0.5, -0.5], [-0.5, -0.5, 0.5]],
'faces': [[0, 1, 2], [0, 3, 1], [0, 2, 3], [1, 3, 2]]}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.SimplePolygon(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Simple polygon hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of simple polygons. The shape $$S$$ of a simple polygon includes the points inside and on the surface of the simple polygon defined by the vertices (see shape). For example:

Important

SimplePolygon simulations must be performed in 2D systems.

Use ConvexPolygon for faster performance with convex polygons.

Wall support.

SimplePolygon supports no hoomd.wall geometries.

Examples:

mc = hpmc.integrate.SimplePolygon(default_d=0.3, default_a=0.4)
mc.shape["A"] = dict(vertices=[(0, 0.5),
(-0.5, -0.5),
(0, 0),
(0.5, -0.5)]);
print('vertices = ', mc.shape["A"]["vertices"])

shape

The shape parameters for each particle type. The dictionary has the following keys:

Warning

HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Example

>>> mc.type_shapes()
'vertices': [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]]}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.Sphere(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Sphere hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of spheres. The shape $$S$$ includes all points inside and on the surface of a sphere:

$S = \left \{ \vec{r} : \frac{\vec{r}\cdot\vec{r}}{(d/2)^2} \le 1 \right\}$

where $$d$$, is the diameter set in shape. When the shape parameter orientable is False (the default), Sphere only applies translation trial moves and ignores translation_move_probability.

Tip

Use spheres with diameter=0 in conjunction with pair potentials for Monte Carlo simulations of particles with no hard core.

Tip

Use Sphere in a 2D simulation to perform Monte Carlo on hard disks.

Wall support.

Sphere supports all hoomd.wall geometries.

Examples:

mc = hoomd.hpmc.integrate.Sphere(default_d=0.3, default_a=0.4)
mc.shape["A"] = dict(diameter=1.0)
mc.shape["B"] = dict(diameter=2.0)
mc.shape["C"] = dict(diameter=1.0, orientable=True)
print('diameter = ', mc.shape["A"]["diameter"])

shape

The shape parameters for each particle type. The dictionary has the following keys:

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Examples

The types will be ‘Sphere’ regardless of dimensionality.

>>> mc.type_shapes
[{'type': 'Sphere', 'diameter': 1},
{'type': 'Sphere', 'diameter': 2}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.SphereUnion(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Sphere union hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of unions of spheres. The union shape $$S$$ is the set union of the given spheres:

$S = \bigcup_k S_k(\mathbf{q}_k, \vec{r}_k)$

Each constituent shape in the union has its own shape parameters $$S_k$$, position $$\vec{r}_k$$, and orientation $$\mathbf{q}_k$$ (see shape).

Note

This shape uses an internal OBB tree for fast collision queries. Depending on the number of constituent spheres in the tree, different values of the number of spheres per leaf node may yield different performance. The capacity of leaf nodes is configurable.

Wall support.

SphereUnion supports no hoomd.wall geometries.

Example:

mc = hpmc.integrate.SphereUnion(default_d=0.3, default_a=0.4)
sphere1 = dict(diameter=1)
sphere2 = dict(diameter=2)
mc.shape["A"] = dict(shapes=[sphere1, sphere2],
positions=[(0, 0, 0), (0, 0, 1)],
orientations=[(1, 0, 0, 0), (1, 0, 0, 0)],
overlap=[1, 1])
print('diameter of the first sphere = ',
mc.shape["A"]["shapes"][0]["diameter"])
print('center of the first sphere = ', mc.shape["A"]["positions"][0])

shape

The shape parameters for each particle type. The dictionary has the following keys:

Type

TypeParameter [particle type, dict]

property type_shapes

Description of shapes in type_shapes format.

Examples

The type will be ‘SphereUnion’ regardless of dimensionality.

>>> mc.type_shapes
[{'type': 'SphereUnion',
'centers': [[0, 0, 0], [0, 0, 1]],
'diameters': [1, 0.5]},
{'type': 'SphereUnion',
'centers': [[1, 2, 3], [4, 5, 6]],
'diameters': [0.5, 1]}]


(Loggable: category=”object”)

Type

list[dict]

class hoomd.hpmc.integrate.Sphinx(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)

Bases: HPMCIntegrator

Sphinx hard particle Monte Carlo integrator.

Parameters
• default_d (float) – Default maximum size of displacement trial moves $$[\mathrm{length}]$$.

• default_a (float) – Default maximum size of rotation trial moves $$[\mathrm{dimensionless}]$$.

• translation_move_probability (float) – Fraction of moves that are translation moves.

• nselect (int) – Number of trial moves to perform per particle per timestep.

Perform hard particle Monte Carlo of sphere unions and differences, depending on the sign of the diameter. The shape $$S$$ is:

$S = \left(\bigcup_{k,d_k\ge 0} S_k((1, 0, 0, 0), \vec{r}_k) \right) \setminus \left(\bigcup_{k,d_k < 0} S_k((1, 0, 0, 0), \vec{r}_k) \right)$

Where $$d_k$$ is the diameter given in shape, $$\vec{r}_k$$ is the center given in shape and $$S_k$$ is the set of points in a sphere or diameter $$|d_k|$$.

Wall support.

Sphinx supports no hoomd.wall geometries.

Example:

mc = hpmc.integrate.Sphinx(default_d=0.3, default_a=0.4)
mc.shape["A"] = dict(centers=[(0,0,0),(1,0,0)], diameters=[1,.25])
print('diameters = ', mc.shape["A"]["diameters"])

shape

The shape parameters for each particle type. The dictionary has the following keys:

Type

TypeParameter [particle type, dict]