hoomd.hpmc.integrate#
Overview
Convex polygon hard particle Monte Carlo integrator. 

Convex polyhedron hard particle Monte Carlo integrator. 

Convex spheropolygon hard particle Monte Carlo integrator. 

Convex spheropolyhedron hard particle Monte Carlo integrator. 

Convex spheropolyhedron union hard particle Monte Carlo integrator. 

Ellipsoid hard particle Monte Carlo integrator. 

Faceted ellipsoid hard particle Monte Carlo integrator. 

Faceted ellispod union hard particle Monte Carlo integrator. 

Base class hard particle Monte Carlo integrator. 

Polyhedron hard particle Monte Carlo integrator. 

Simple polygon hard particle Monte Carlo integrator. 

Sphere hard particle Monte Carlo integrator. 

Sphere union hard particle Monte Carlo integrator. 

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:
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.
Temperature
HPMC assumes that \(\beta = \frac{1}{kT} = 1\). This is not relevant to systems of purely hard particles where \(\Delta U\) is either 0 or \(\infty\). To adjust the effective temperature in systems with finite interactions (see Energy evaluation below), scale the magnitude of the energetic interactions accordingly.
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:
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:
Note
For nonorientable 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:
To enable simulations of small systems, the pair and shape energies evaluate interactions between pairs of particles in multiple box images:
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:
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:
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:
The full transformation from the local shape coordinate system to the simulation box coordinate system includes a rotation and translation:
HPMCIntegrator
defines the shape overlap test for two shapes:
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:
The complete hard shape interaction energy for a given configuration is:
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.
Deprecated since version 4.4.0: depletant_fugacity > 0
is deprecated.
 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.See also
Use
SimplePolygon
for concave polygons.Wall support.
ConvexPolygon
supports nohoomd.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.
vertices
(list
[tuple
[float
,float
]], required)  vertices of the polygon \([\mathrm{length}]\).Vertices MUST be specified in a counterclockwise order.
The origin MUST be contained within the polygon.
Points inside the polygon MUST 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 toTrue
to ignore tracked statistics.sweep_radius
(float
, default: 0.0)  Ignored, but present becauseConvexPolygon
shares data structures withConvexSpheropolygon
\([\mathrm{length}]\).
Warning
HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.
 Type:
TypeParameter
[particle type
,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:See also
Use
Polyhedron
for concave polyhedra.Wall support.
ConvexPolyhedron
supports allhoomd.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.
vertices
(list
[tuple
[float
,float
,float
]], required)  vertices of the polyhedron \([\mathrm{length}]\).The origin MUST be contained within the polyhedron.
The origin centered sphere that encloses all vertices should be of minimal size for optimal performance.
ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.sweep_radius
(float
, default: 0.0)  Ignored, but present becauseConvexPolyhedron
shares data structures withConvexSpheropolyhedron
\([\mathrm{length}]\).
Warning
HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.
 Type:
TypeParameter
[particle type
,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 (seeshape
). 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 1vertex spheropolygon is a disk and a 2vertex spheropolygon is a rectangle with half disk caps.
Wall support.
ConvexSpheropolygon
supports nohoomd.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)], sweep_radius=0.1); mc.shape["A"] = dict(vertices=[(0,0)], sweep_radius=0.5, 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 toTrue
to ignore tracked statistics.sweep_radius
(default: 0.0)  radius of the disk swept around the edges of the polygon \([\mathrm{length}]\). Set a nonzerosweep_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
]
 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 (seeshape
). SeeConvexSpheropolygon
for a visual example in 2D.Tip
A 1vertex spheropolygon is a sphere and a 2vertex spheropolygon is a spherocylinder.
Wall support.
ConvexSpheropolyhedron
supports thehoomd.wall.Sphere
andhoomd.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=[], sweep_radius=0.1, 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.shape["SphericalDepletant"] = dict(vertices=[], sweep_radius=0.1); mc.depletant_fugacity["SphericalDepletant"] = 3.0
 shape#
The shape parameters for each particle type. The dictionary has the following keys:
vertices
(list
[tuple
[float
,float
,float
]], required)  vertices of the polyhedron \([\mathrm{length}]\).The origin MUST be contained within the polyhedron.
The origin centered sphere that encloses all vertices should be of minimal size for optimal performance.
ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.sweep_radius
(float
, default: 0.0)  radius of the sphere swept around the surface of the polyhedron \([\mathrm{length}]\). Set a nonzero sweep_radius to create a spheropolyhedron.
Warning
HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.
 Type:
TypeParameter
[particle type
,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 nohoomd.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:
shapes
(list
[dict
], required)  Shape parameters for each spheropolyhedron in the union. SeeConvexSpheropolyhedron.shape
for the accepted parameters.positions
(list
[tuple
[float
,float
,float
]], required)  Position of each spheropolyhedron in the union. \([\mathrm{length}]\)orientations
(list
[tuple
[float
,float
,float
,float
]], default: None)  Orientation of each spheropolyhedron in the union. When notNone
,orientations
must have a length equal to that ofpositions
. WhenNone
(the default),orientations
is initialized with all [1,0,0,0]’s.overlap
(list
[int
], default:None
)  Check for overlaps between constituent particles whenoverlap [i] & overlap[j]
is nonzero (&
is the bitwise AND operator). When notNone
,overlap
must have a length equal to that ofpositions
. WhenNone
(the default),overlap
is initialized with all 1’s.capacity
(int
, default: 4)  set the maximum number of particles per leaf node to adjust performance.ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.
 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 nohoomd.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:
a
(float
, required)  half axis of ellipsoid in the x direction \([\mathrm{length}]\)b
(float
, required)  half axis of ellipsoid in the y direction \([\mathrm{length}]\)c
(float
, required)  half axis of ellipsoid in the z direction \([\mathrm{length}]\)ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.
 Type:
TypeParameter
[particle type
,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 nohoomd.wall
geometries.Example:
mc = hpmc.integrate.FacetedEllipsoid(default_d=0.3, default_a=0.4) # halfspace 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:
normals
(list
[tuple
[float
,float
,float
]], required)  facet normals \(\\vec{n}_i\).offsets
(list
[float
], required)  list of offsets \(b_i\) \([\mathrm{length}^2]\)a
(float
, required)  half axis of ellipsoid in the x direction \([\mathrm{length}]\)b
(float
, required)  half axis of ellipsoid in the y direction \([\mathrm{length}]\)c
(float
, required)  half axis of ellipsoid in the z direction \([\mathrm{length}]\)vertices
(list
[tuple
[float
,float
,float
]], default: [])  list of vertices for intersection polyhedron (see note below). \([\mathrm{length}]\)origin
(tuple
[float
,float
,float
], default: (0,0,0))  A point inside the shape. \([\mathrm{length}]\)ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.
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 halfspace intersection of the normals must match the convex polyhedron defined by the vertices (if nonempty), the halfspace 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 nohoomd.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:
shapes
(list
[dict
], required)  Shape parameters for each faceted ellipsoid in the union. SeeFacetedEllipsoid.shape
for the accepted parameters.positions
(list
[tuple
[float
,float
,float
]], required)  Position of each faceted ellipsoid in the union. \([\mathrm{length}]\)orientations
(list
[tuple
[float
,float
,float
,float
]], default:None
)  Orientation of each faceted ellipsoid in the union. When notNone
,orientations
must have a length equal to that ofpositions
. WhenNone
(the default),orientations
is initialized with all [1,0,0,0]’s.overlap
(list
[int
], default:None
)  Check for overlaps between constituent particles whenoverlap [i] & overlap[j]
is nonzero (&
is the bitwise AND operator). When notNone
,overlap
must have a length equal to that ofpositions
. WhenNone
(the default),overlap
is initialized with all 1’s.capacity
(int
, default: 4)  set the maximum number of particles per leaf node to adjust performance.ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.
 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.See also
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
orissubclass
checks.Ignoring overlap checks
Set elements of
interaction_matrix
toFalse
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() log.add(mc, quantities=['type_shapes']) gsd = hoomd.write.GSD( 'trajectory.gsd', hoomd.trigger.Periodic(1000), log=log)
Threading
HPMC integrators use threaded execution on multiple CPU cores only when placing implicit depletants (
depletant_fugacity != 0
).Deprecated since version 4.4.0:
num_cpu_threads >= 1
is deprecated. Setnum_cpu_threads = 1
.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. 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
]
Attributes
 __dir__()#
Expose all attributes for dynamic querying in notebooks and IDEs.
 property counters#
Trial move counters.
The counter object has the following attributes:
translate
:tuple
[int
,int
]  Number of accepted and rejected translate trial moves.rotate
:tuple
[int
,int
]  Number of accepted and rejected rotate trial moves.overlap_checks
:int
 Number of overlap checks performed.overlap_errors
:int
 Number of overlap checks that were too close to resolve.
Note
The counts are reset to 0 at the start of each
hoomd.Simulation.run
. Type:
 property external_potential#
The userdefined 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 is_tuning_complete#
Check if kernel parameter tuning is complete.
True
when tuning is complete andkernel_parameters
has locked optimal parameters for all active kernels used by this object.Example:
while (not operation.is_tuning_complete): simulation.run(1000)
 Type:
 property kernel_parameters#
Kernel parameters.
The dictionary maps GPU kernel names to tuples of integers that control how the kernel executes on the GPU. These values will change during the tuning process and remain static after tuning completes. Set the kernel parameters for one or more kernels to force specific values and stop tuning.
Warning
The keys and valid values in this dictionary depend on the hardware device, the HOOMDblue version, and the value of class attributes. Keys and/or valid values may change even with new patch releases of HOOMDblue.
Provided that you use the same HOOMDblue binary on the same hardware and execute a script with the same parameters, you may save the tuned values from one run and load them in the next.
Examples:
kernel_parameters = operation.kernel_parameters
operation.kernel_parameters = kernel_parameters
 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 tagsi
andj
.Attention
map_overlaps
does not support MPI parallel simulations. It returnsNone
when there is more than one MPI rank.(
Loggable
: category=”sequence”)
 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:
 property pair_potential#
The userdefined 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”)
 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”)
 tune_kernel_parameters()#
Start tuning kernel parameters.
After calling
tune_kernel_parameters
,AutotunedObject
will vary the kernel parameters in subsequent time steps, check the run time of each, and lock to the fastest performing parameters after the scan is complete.Example:
operation.tune_kernel_parameters()
 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 selfintersections.See also
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 nohoomd.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:
vertices
(list
[tuple
[float
,float
,float
]], required)  vertices of the polyhedron \([\mathrm{length}]\).The origin MUST strictly be contained in the generally nonconvex volume defined by the vertices and faces.
The origin centered sphere that encloses all vertices should be of minimal size for optimal performance.
faces
(list
[tuple
[int
,int
,int
], required)  Vertex indices for every triangle in the mesh.For visualization purposes, the faces MUST be defined with a counterclockwise winding order to produce an outward normal.
ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.sweep_radius
(float
, default: 0.0)  radius of the sphere swept around the surface of the polyhedron \([\mathrm{length}]\). Set a nonzero sweep_radius to create a spheropolyhedron.overlap
(list
[int
], default: None)  Check for overlaps between faces whenoverlap [i] & overlap[j]
is nonzero (&
is the bitwise AND operator). When notNone
,overlap
must have a length equal to that offaces
. WhenNone
(the default),overlap
is initialized with all 1’s.capacity
(int
, default: 4)  set the maximum number of particles per leaf node to adjust performance.origin
(tuple
[float
,float
,float
], default: (0,0,0))  a point strictly inside the shape, needed for correctness of overlap checks.hull_only
(bool
, default:False
)  WhenTrue
, only check for intersections between the convex hulls.
Warning
HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.
 Type:
TypeParameter
[particle type
,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.See also
Use
ConvexPolygon
for faster performance with convex polygons.Wall support.
SimplePolygon
supports nohoomd.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:
vertices
(list
[tuple
[float
,float
]], required)  vertices of the polygon \([\mathrm{length}]\).Vertices MUST be specified in a counterclockwise order.
The polygon may be concave, but edges must not cross.
The origin may be inside or outside the shape.
The origin centered circle that encloses all vertices should be of minimal size for optimal performance.
ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.sweep_radius
(float
, default: 0.0)  Ignored, but present becauseSimplePolygon
shares data structures withConvexSpheropolygon
\([\mathrm{length}]\).
Warning
HPMC does not check that all vertex requirements are met. Undefined behavior will result when they are violated.
 Type:
TypeParameter
[particle type
,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 parameterorientable
isFalse
(the default),Sphere
only applies translation trial moves and ignorestranslation_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 allhoomd.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:
diameter
(float
, required)  Sphere diameter \([\mathrm{length}]\).ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.orientable
(bool
, default:False
)  set toTrue
to allow rotation moves on this particle type.
 Type:
TypeParameter
[particle type
,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 nohoomd.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:
shapes
(list
[dict
], required)  Shape parameters for each sphere in the union. SeeSphere.shape
for the accepted parameters.positions
(list
[tuple
[float
,float
,float
]], required)  Position of each sphere in the union. \([\mathrm{length}]\)orientations
(list
[tuple
[float
,float
,float
,float
]], default:None
)  Orientation of each sphere in the union. When notNone
,orientations
must have a length equal to that ofpositions
. WhenNone
(the default),orientations
is initialized with all [1,0,0,0]’s.overlap
(list
[int
], default:None
)  Check for overlaps between constituent particles whenoverlap [i] & overlap[j]
is nonzero (&
is the bitwise AND operator). When notNone
,overlap
must have a length equal to that ofpositions
. WhenNone
(the default),overlap
is initialized with all 1’s.capacity
(int
, default: 4)  set the maximum number of particles per leaf node to adjust performance.ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.
 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”)
 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 inshape
and \(S_k\) is the set of points in a sphere or diameter \(d_k\).Wall support.
Sphinx
supports nohoomd.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:
diameters
(list
[float
], required)  diameters of spheres (positive OR negative real numbers) \([\mathrm{length}]\).centers
(list
[tuple
[float
,float
,float
], required)  centers of spheres in local coordinate frame \([\mathrm{length}]\).ignore_statistics
(bool
, default:False
)  set toTrue
to ignore tracked statistics.
 Type:
TypeParameter
[particle type
,dict
]