hpmc.integrate¶
Overview
HPMC integration for convex polygons (2D). 

HPMC integration for convex polyhedra (3D). 

HPMC integration for convex spheropolygons (2D). 

HPMC integration for spheropolyhedra (3D). 

HPMC integration for unions of convex polyhedra (3D). 

HPMC integration for ellipsoids (2D/3D). 

HPMC integration for faceted spheres (3D). 

Define pairwise interaction matrix 

Base class HPMC integrator. 

HPMC integration for general polyhedra (3D). 

HPMC integration for simple polygons (2D). 

HPMC integration for spheres (2D/3D). 

HPMC integration for unions of spheres (3D). 

HPMC integration for sphinx particles (3D). 
Details

class
hoomd.hpmc.integrate.
convex_polygon
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for convex polygons (2D).
 Parameters
seed (int) – Random number seed
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Note
For concave polygons, use
simple_polygon
.Convex polygon parameters:
vertices (required)  vertices of the polygon as is a list of (x,y) tuples of numbers (distance units)
Vertices MUST be specified in a counterclockwise order.
The origin MUST be contained within the vertices.
Points inside the polygon MUST NOT be included.
The origin centered circle that encloses all vertices should be of minimal size for optimal performance (e.g. don’t put the origin right next to an edge).
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Warning
HPMC does not check that all requirements are met. Undefined behavior will result if they are violated.
Examples:
mc = hpmc.integrate.convex_polygon(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', vertices=[(0.5, 0.5), (0.5, 0.5), (0.5, 0.5), (0.5, 0.5)]); print('vertices = ', mc.shape_param['A'].vertices)

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Example
>>> mc.get_type_shapes() [{'type': 'Polygon', 'rounding_radius': 0, 'vertices': [[0.5, 0.5], [0.5, 0.5], [0.5, 0.5], [0.5, 0.5]]}]
 Returns
A list of dictionaries, one for each particle type in the system.

class
hoomd.hpmc.integrate.
convex_polyhedron
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for convex polyhedra (3D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – (Override the automatic choice for the number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Convex polyhedron parameters:
vertices (required)  vertices of the polyhedron as is a list of (x,y,z) tuples of numbers (distance units)
The origin MUST be contained within the vertices.
The origin centered circle that encloses all vertices should be of minimal size for optimal performance (e.g. don’t put the origin right next to a face).
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Warning
HPMC does not check that all requirements are met. Undefined behavior will result if they are violated.
Example:
mc = hpmc.integrate.convex_polyhedron(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', 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_param['A'].vertices)
Depletants Example:
mc = hpmc.integrate.convex_polyhedron(seed=415236, d=0.3, a=0.4) mc.set_param(nselect=1) mc.shape_param.set('A', 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_param.set('B', vertices=[(0.05, 0.05, 0.05), (0.05, 0.05, 0.05), (0.05, 0.05, 0.05), (0.05, 0.05, 0.05)]); mc.set_fugacity('B',fugacity=3.0)

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Example
>>> mc.get_type_shapes() [{'type': 'ConvexPolyhedron', 'rounding_radius': 0, '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]]}]
 Returns
A list of dictionaries, one for each particle type in the system.

class
hoomd.hpmc.integrate.
convex_spheropolygon
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for convex spheropolygons (2D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Spheropolygon parameters:
vertices (required)  vertices of the polygon as is a list of (x,y) tuples of numbers (distance units)
The origin MUST be contained within the shape.
The origin centered circle that encloses all vertices should be of minimal size for optimal performance (e.g. don’t put the origin right next to an edge).
sweep_radius (default: 0.0)  the radius of the sphere swept around the edges of the polygon (distance units)  optional
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Useful cases:
A 1vertex spheropolygon is a disk.
A 2vertex spheropolygon is a spherocylinder.
Warning
HPMC does not check that all requirements are met. Undefined behavior will result if they are violated.
Examples:
mc = hpmc.integrate.convex_spheropolygon(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', vertices=[(0.5, 0.5), (0.5, 0.5), (0.5, 0.5), (0.5, 0.5)], sweep_radius=0.1, ignore_statistics=False); mc.shape_param.set('A', vertices=[(0,0)], sweep_radius=0.5, ignore_statistics=True); print('vertices = ', mc.shape_param['A'].vertices)

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Example
>>> mc.get_type_shapes() [{'type': 'Polygon', 'rounding_radius': 0.1, 'vertices': [[0.5, 0.5], [0.5, 0.5], [0.5, 0.5], [0.5, 0.5]]}]
 Returns
A list of dictionaries, one for each particle type in the system.

class
hoomd.hpmc.integrate.
convex_spheropolyhedron
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for spheropolyhedra (3D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
A spheropolyhedron can also represent spheres (0 or 1 vertices), and spherocylinders (2 vertices).
Spheropolyhedron parameters:
vertices (required)  vertices of the polyhedron as is a list of (x,y,z) tuples of numbers (distance units)
The origin MUST be contained within the vertices.
The origin centered sphere that encloses all vertices should be of minimal size for optimal performance (e.g. don’t put the origin right next to a face).
A sphere can be represented by specifying zero vertices (i.e. vertices=[]) and a nonzero radius R
Two vertices and a nonzero radius R define a prolate spherocylinder.
sweep_radius (default: 0.0)  the radius of the sphere swept around the edges of the polygon (distance units)  optional
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Warning
HPMC does not check that all requirements are met. Undefined behavior will result if they are violated.
Example:
mc = hpmc.integrate.convex_spheropolyhedron(seed=415236, d=0.3, a=0.4) mc.shape_param['tetrahedron'].set(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_param['A'].vertices) mc.shape_param['SphericalDepletant'].set(vertices=[], sweep_radius=0.1, ignore_statistics=True);
Depletants example:
mc = hpmc.integrate.convex_spheropolyhedron(seed=415236, d=0.3, a=0.4) mc.shape_param['tetrahedron'].set(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_param['SphericalDepletant'].set(vertices=[], sweep_radius=0.1); mc.set_fugacity('B',fugacity=3.0)

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Example
>>> mc.get_type_shapes() [{'type': 'ConvexPolyhedron', 'rounding_radius': 0.1, '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]]}]
 Returns
A list of dictionaries, one for each particle type in the system.

class
hoomd.hpmc.integrate.
convex_spheropolyhedron_union
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4)¶ HPMC integration for unions of convex polyhedra (3D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
capacity (int) – Set to the number of constituent convex polyhedra per leaf node
New in version 2.2.
Convex polyhedron union parameters:
vertices (required)  list of vertex lists of the polyhedra in particle coordinates.
centers (required)  list of centers of constituent polyhedra in particle coordinates.
orientations (required)  list of orientations of constituent polyhedra.
overlap (default: 1 for all particles)  only check overlap between constituent particles for which overlap [i] & overlap[j] is !=0, where ‘&’ is the bitwise AND operator.
sweep_radii (default: 0 for all particle)  radii of spheres sweeping out each constituent polyhedron
New in version 2.4.
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking.
Example:
mc = hpmc.integrate.convex_spheropolyhedron_union(seed=27, d=0.3, 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_param.set('A', vertices=[cube_verts, cube_verts], centers=[[1,0,0],[1,0,0]],orientations=[[1,0,0,0],[1,0,0,0]]); print('vertices of the first cube = ', mc.shape_param['A'].members[0].vertices) print('center of the first cube = ', mc.shape_param['A'].centers[0]) print('orientation of the first cube = ', mc.shape_param['A'].orientations[0])

class
hoomd.hpmc.integrate.
ellipsoid
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for ellipsoids (2D/3D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Ellipsoid parameters:
a (required)  principle axis a of the ellipsoid (radius in the x direction) (distance units)
b (required)  principle axis b of the ellipsoid (radius in the y direction) (distance units)
c (required)  principle axis c of the ellipsoid (radius in the z direction) (distance units)
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Example:
mc = hpmc.integrate.ellipsoid(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', a=0.5, b=0.25, c=0.125); print('ellipsoids parameters (a,b,c) = ', mc.shape_param['A'].a, mc.shape_param['A'].b, mc.shape_param['A'].c)
Depletants Example:
mc = hpmc.integrate.ellipsoid(seed=415236, d=0.3, a=0.4) mc.set_param(nselect=1) mc.shape_param.set('A', a=0.5, b=0.25, c=0.125); mc.shape_param.set('B', a=0.05, b=0.05, c=0.05); mc.set_fugacity('B',fugacity=3.0)

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Example
>>> mc.get_type_shapes() [{'type': 'Ellipsoid', 'a': 1.0, 'b': 1.5, 'c': 1}]
 Returns
A list of dictionaries, one for each particle type in the system.

class
hoomd.hpmc.integrate.
faceted_ellipsoid
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for faceted ellipsoids (3D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
A faceted ellipsoid is an ellipsoid intersected with a convex polyhedron defined through halfspaces. The equation defining each halfspace is given by:
\[n_i\cdot r + b_i \le 0\]where \(n_i\) is the face normal, and \(b_i\) is the offset.
Warning
The origin must be chosen so as to lie inside the shape, or the overlap check will not work. This condition is not checked.
Faceted ellipsoid parameters:
normals (required)  list of (x,y,z) tuples defining the facet normals (distance units)
offsets (required)  list of offsets (distance unit^2)
a (required)  first half axis of ellipsoid
b (required)  second half axis of ellipsoid
c (required)  third half axis of ellipsoid
vertices (required)  list of vertices for intersection polyhedron
origin (required)  origin vector
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Warning
Planes must not be coplanar.
Note
The halfspace intersection of the normals has to match the convex polyhedron defined by the vertices (if nonempty), currently the halfspace intersection is not calculated automatically. For simple intersections with planes that do not intersect within the sphere, the vertices list can be left empty.
Example:
mc = hpmc.integrate.faceted_ellipsoid(seed=415236, d=0.3, 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_param.set('A', normals=slab_normals, offsets=slab_offsets, vertices=slab_verts,a=1.0, b=0.5, c=0.5); print('a = {}, b = {}, c = {}', mc.shape_param['A'].a,mc.shape_param['A'].b,mc.shape_param['A'].c)
Depletants Example:
mc = hpmc.integrate.faceted_ellipsoid(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', normals=[(1,0,0),(1,0,0),(0,1,0),(0,1,0),(0,0,1),(0,0,1)],a=1.0, b=0.5, c=0.25); # depletant sphere mc.shape_param.set('B', normals=[],a=0.1,b=0.1,c=0.1); mc.set_fugacity('B',fugacity=3.0)

class
hoomd.hpmc.integrate.
faceted_ellipsoid_union
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4)¶ HPMC integration for unions of faceted ellipsoids (3D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
capacity (int) – Set to the number of constituent convex polyhedra per leaf node
New in version 2.5.
See
faceted_ellipsoid
for a detailed explanation of the constituent particle parameters.Faceted ellipsiod union parameters:
normals (required)  list of list of (x,y,z) tuples defining the facet normals (distance units)
offsets (required)  list of list of offsets (distance unit^2)
axes (required)  list of half axes, tuple of three per constituent ellipsoid
vertices (required)  list of list list of vertices for intersection polyhedron
origin (required)  list of origin vectors
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking.
Example:
mc = hpmc.integrate.faceted_ellipsoid_union(seed=27, d=0.3, a=0.4) # make a prolate Janus ellipsoid # cut away x halfspace normals = [(1,0,0)] offsets = [0] mc.shape_param.set('A', normals=[normals, normals], offsets=[offsets, offsets], vertices=[[], []], axes=[(.5,.5,2),(.5,.5,2)], centers=[[0,0,0],[0,0,0]], orientations=[[1,0,0,0],[0,0,0,1]]); print('offsets of the first faceted ellipsoid = ', mc.shape_param['A'].members[0].normals) print('normals of the first faceted ellispoid = ', mc.shape_param['A'].members[0].offsets) print('vertices of the first faceted ellipsoid = ', mc.shape_param['A'].members[0].vertices)

class
hoomd.hpmc.integrate.
faceted_sphere
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for faceted spheres (3D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
A faceted sphere is a sphere intersected with halfspaces. The equation defining each halfspace is given by:
\[n_i\cdot r + b_i \le 0\]where \(n_i\) is the face normal, and \(b_i\) is the offset.
Warning
The origin must be chosen so as to lie inside the shape, or the overlap check will not work. This condition is not checked.
Faceted sphere parameters:
normals (required)  list of (x,y,z) tuples defining the facet normals (distance units)
offsets (required)  list of offsets (distance unit^2)
diameter (required)  diameter of sphere
vertices (required)  list of vertices for intersection polyhedron
origin (required)  origin vector
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Warning
Planes must not be coplanar.
Note
The halfspace intersection of the normals has to match the convex polyhedron defined by the vertices (if nonempty), currently the halfspace intersection is not calculated automatically. For simple intersections with planes that do not intersect within the sphere, the vertices list can be left empty.
 Example::
# 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], [.5,.5,.5],[.5,.5,.5],[.5,.5,.5],[.5,.5,.5]]
mc = hpmc.integrate.faceted_sphere(seed=415236, d=0.3, a=0.4) mc.shape_param.set(‘A’, normals=slab_normals,offsets=slab_offsets, vertices=slab_verts,diameter=1.0); print(‘diameter = ‘, mc.shape_param[‘A’].diameter)
Depletants Example:
mc = hpmc.integrate.faceted_sphere(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', normals=[(1,0,0),(1,0,0),(0,1,0),(0,1,0),(0,0,1),(0,0,1)],diameter=1.0); mc.shape_param.set('B', normals=[],diameter=0.1); mc.set_fugacity('B',fugacity=3.0)

class
hoomd.hpmc.integrate.
interaction_matrix
¶ Define pairwise interaction matrix
All shapes use
interaction_matrix
to define the interaction matrix between different pairs of particles indexed by type. The set of pair coefficients is a symmetric matrix defined over all possible pairs of particle types.By default, all elements of the interaction matrix are 1, that means that overlaps are checked between all pairs of types. To disable overlap checking for a specific type pair, set the coefficient for that pair to 0.
Access the interaction matrix with a saved integrator object like so:
from hoomd import hpmc mc = hpmc.integrate.some_shape(arguments...) mv.overlap_checks.set('A', 'A', enable=False) mc.overlap_checks.set('A', 'B', enable=True) mc.overlap_checks.set('B', 'B', enable=False)
New in version 2.1.

set
(a, b, enable)¶ Sets parameters for one type pair.
 Parameters
By default, all interaction matrix elements are set to ‘True’.
It is not an error, to specify matrix elements for particle types that do not exist in the simulation.
There is no need to specify matrix elements for both pairs ‘A’, ‘B’ and ‘B’, ‘A’. Specifying only one is sufficient.
To set the same elements between many particle types, provide a list of type names instead of a single one. All pairs between the two lists will be set to the same parameters.
Examples:
mc.overlap_checks.set('A', 'A', False); mc.overlap_checks.set('B', 'B', False); mc.overlap_checks.set('A', 'B', True); mc.overlap_checks.set(['A', 'B', 'C', 'D'], 'F', True); mc.overlap_checks.set(['A', 'B', 'C', 'D'], ['A', 'B', 'C', 'D'], False);


class
hoomd.hpmc.integrate.
mode_hpmc
¶ Base class HPMC integrator.
mode_hpmc
is the base class for all HPMC integrators. It provides common interface elements. Users should not instantiate this class directly. Methods documented here are available to all hpmc integrators.State data
HPMC integrators can save and restore the following state information to gsd files:
Maximum trial move displacement d
Maximum trial rotation move a
Shape parameters for all types.
State data are not written by default. You must explicitly request that state data for an mc integrator is written to a gsd file (see
hoomd.dump.gsd.dump_state()
).mc = hoomd.hpmc.shape(...) gsd = hoomd.dump.gsd(...) gsd.dump_state(mc)
State data are not restored by default. You must explicitly request that state data be restored when initializing the integrator.
init.read_gsd(...) mc = hoomd.hpmc.shape(..., restore_state=True)
See the State data section of the HOOMD GSD schema for details on GSD data chunk names and how the data are stored.

count_overlaps
()¶ Count the number of overlaps.
 Returns
The number of overlaps in the current system configuration
Example:
mc = hpmc.integrate.shape(..); mc.shape_param.set(....); run(100) num_overlaps = mc.count_overlaps();

get_a
(type=None)¶ Get the maximum trial rotation.
 Parameters
type (str) – Type name to query.
 Returns
The current value of the ‘a’ parameter of the integrator.

get_counters
()¶ Get all trial move counters.
 Returns
A dictionary containing all trial moves counted during the last
hoomd.run()
.
The dictionary contains the entries:
translate_accept_count  count of the number of accepted translate moves
translate_reject_count  count of the number of rejected translate moves
rotate_accept_count  count of the number of accepted rotate moves
rotate_reject_count  count of the number of rejected rotate moves
overlap_checks  estimate of the number of overlap checks performed
translate_acceptance  Average translate acceptance ratio over the run
rotate_acceptance  Average rotate acceptance ratio over the run
move_count  Count of the number of trial moves during the run

get_d
(type=None)¶ Get the maximum trial displacement.
 Parameters
type (str) – Type name to query.
 Returns
The current value of the ‘d’ parameter of the integrator.

get_fugacity
(type)¶  Get depletant fugacity of a given type
New in version 3.0.
 Parameters
type (str) – Type for which fugacity is returned

get_move_ratio
()¶ Get the current probability of attempting translation moves.
Returns: The current value of the ‘move_ratio’ parameter of the integrator.

get_mps
()¶ Get the number of trial moves per second.
 Returns
The number of trial moves per second performed during the last
hoomd.run()
.

get_nselect
()¶ Get nselect parameter.
 Returns
The current value of the ‘nselect’ parameter of the integrator.

get_quermass_mode
()¶ Get the value of the quermass integration setting
 Returns
The current value of the ‘quermass’ parameter of the integrator

get_rotate_acceptance
()¶ Get the average acceptance ratio for rotate moves.
 Returns
The average rotate accept ratio during the last
hoomd.run()
.
Example:
mc = hpmc.integrate.shape(..); mc.shape_param.set(....); run(100) t_accept = mc.get_rotate_acceptance();

get_sweep_radius
()¶ Get the value of the additional sweep radius for depletant simulations
 Returns
The current value of the ‘sweep_radius’ parameter of the integrator

get_translate_acceptance
()¶ Get the average acceptance ratio for translate moves.
 Returns
The average translate accept ratio during the last
hoomd.run()
.
Example:
mc = hpmc.integrate.shape(..); mc.shape_param.set(....); run(100) t_accept = mc.get_translate_acceptance();

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

map_energies
()¶ Build an energy map of the system
 Returns
List of tuples. The i,j entry contains the pairwise interaction energy of the ith and jth particles (by tag)
Note
map_energies()
does not support MPI parallel simulations.Example
mc = hpmc.integrate.shape(…) mc.shape_param.set(…) energy_map = np.asarray(mc.map_energies())

map_overlaps
()¶ Build an overlap map of the system
 Returns
List of tuples. True/false value of the i,j entry indicates overlap/nonoverlap of the ith and jth particles (by tag)
Note
map_overlaps()
does not support MPI parallel simulations.Example
mc = hpmc.integrate.shape(…) mc.shape_param.set(…) overlap_map = np.asarray(mc.map_overlaps())

restore_state
()¶ Restore the state information from the file used to initialize the simulations

set_fugacity
(type, fugacity)¶  Set depletant fugacity of a given type
New in version 3.0.

set_params
(d=None, a=None, move_ratio=None, nselect=None, quermass=None, sweep_radius=None, deterministic=None)¶ Changes parameters of an existing integration mode.
 Parameters
d (float) – (if set) Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – (if set) Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – (if set) New value for the move ratio.
nselect (int) – (if set) New value for the number of particles to select for trial moves in one cell.
quermass (bool) – (if set) Implicit depletants only: Enable/disable quermass integration mode
sweep_radius (float) – (if set): Implicit depletants only: Additional radius of a sphere to sweep the shapes by in quermass mode
deterministic (bool) – (if set) Make HPMC integration deterministic on the GPU by sorting the cell list.
Note
Simulations are only deterministic with respect to the same execution configuration (CPU or GPU) and number of MPI ranks. Simulation output will not be identical if either of these is changed.

test_overlap
(type_i, type_j, rij, qi, qj, use_images=True, exclude_self=False)¶ Test overlap between two particles.
 Parameters
type_i (str) – Type of first particle
type_j (str) – Type of second particle
rij (tuple) – Separation vector rjri between the particle centers
qi (tuple) – Orientation quaternion of first particle
qj (tuple) – Orientation quaternion of second particle
use_images (bool) – If True, check for overlap between the periodic images of the particles by adding the image vector to the separation vector
exclude_self (bool) – If both use_images and exclude_self are true, exclude the primary image
For twodimensional shapes, pass the third dimension of rij as zero.
 Returns
True if the particles overlap.

class
hoomd.hpmc.integrate.
polyhedron
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for general polyhedra (3D).
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 optimal performance. The capacity of leaf nodes is configurable.
Only triangle meshes and spheres are supported. The mesh must be free of selfintersections.
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Polyhedron parameters:
vertices (required)  vertices of the polyhedron as is a list of (x,y,z) tuples of numbers (distance units)
The origin MUST strictly be contained in the generally nonconvex volume defined by the vertices and faces
The (0,0,0) centered sphere that encloses all vertices should be of minimal size for optimal performance (e.g. don’t translate the shape such that (0,0,0) right next to a face).
faces (required)  a list of vertex indices for every face
For visualization purposes, the faces MUST be defined with a counterclockwise winding order to produce an outward normal.
sweep_radius (default: 0.0)  rounding radius applied to polyhedron
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
capacity (default: 4)  set to the maximum number of particles per leaf node for better performance
New in version 2.2.
origin (default: (0,0,0))  a point strictly inside the shape, needed for correctness of overlap checks
New in version 2.2.
hull_only (default: True)  if True, only consider intersections between hull polygons
New in version 2.2.
Warning
HPMC does not check that all requirements are met. Undefined behavior will result if they are violated.
Example:
mc = hpmc.integrate.polyhedron(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', 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_param['A'].vertices) print('faces = ', mc.shape_param['A'].faces)
Depletants Example:
mc = hpmc.integrate.polyhedron(seed=415236, d=0.3, a=0.4) mc.set_param(nselect=1) cube_verts = [(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)]; cube_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]] tetra_verts = [(0.5, 0.5, 0.5), (0.5, 0.5, 0.5), (0.5, 0.5, 0.5), (0.5, 0.5, 0.5)]; tetra_faces = [[0, 1, 2], [3, 0, 2], [3, 2, 1], [3,1,0]]; mc.shape_param.set('A', vertices = cube_verts, faces = cube_faces); mc.shape_param.set('B', vertices = tetra_verts, faces = tetra_faces, origin = (0,0,0));

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Example
>>> mc.get_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]], 'indices': [[0, 1, 2], [0, 3, 1], [0, 2, 3], [1, 3, 2]]}]
 Returns
A list of dictionaries, one for each particle type in the system.

class
hoomd.hpmc.integrate.
simple_polygon
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for simple polygons (2D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Note
For simple polygons that are not concave, use
convex_polygon
, it will execute much faster thansimple_polygon
.Simple polygon parameters:
vertices (required)  vertices of the polygon as is a list of (x,y) tuples of numbers (distance units)
Vertices MUST be specified in a counterclockwise order.
The polygon may be concave, but edges must not cross.
The origin doesn’t necessarily need to be inside the shape.
The origin centered circle that encloses all vertices should be of minimal size for optimal performance.
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Warning
HPMC does not check that all requirements are met. Undefined behavior will result if they are violated.
Examples:
mc = hpmc.integrate.simple_polygon(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', vertices=[(0, 0.5), (0.5, 0.5), (0, 0), (0.5, 0.5)]); print('vertices = ', mc.shape_param['A'].vertices)

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Example
>>> mc.get_type_shapes() [{'type': 'Polygon', 'rounding_radius': 0, 'vertices': [[0.5, 0.5], [0.5, 0.5], [0.5, 0.5], [0.5, 0.5]]}]
 Returns
A list of dictionaries, one for each particle type in the system.

class
hoomd.hpmc.integrate.
sphere
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for spheres (2D/3D).
 Parameters
seed (int) – Random number seed
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float, only with orientable=True) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type. (added in version 2.3)
move_ratio (float, only used with orientable=True) – Ratio of translation moves to rotation moves. (added in version 2.3)
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Hard particle Monte Carlo integration method for spheres.
Sphere parameters:
diameter (required)  diameter of the sphere (distance units)
orientable (default: False)  set to True for spheres with orientation (added in version 2.3)
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Examples:
mc = hpmc.integrate.sphere(seed=415236, d=0.3) mc.shape_param.set('A', diameter=1.0) mc.shape_param.set('B', diameter=2.0) mc.shape_param.set('C', diameter=1.0, orientable=True) print('diameter = ', mc.shape_param['A'].diameter)
Depletants Example:
mc = hpmc.integrate.sphere(seed=415236, d=0.3, a=0.4) mc.set_param(nselect=8) mc.shape_param.set('A', diameter=1.0) mc.shape_param.set('B', diameter=.1) mc.set_fugacity('B',fugacity=3.0)

get_type_shapes
()¶ Get all the types of shapes in the current simulation.
Examples
The types will be ‘Sphere’ regardless of dimensionality.
>>> mc.get_type_shapes() [{'type': 'Sphere', 'diameter': 1}, {'type': 'Sphere', 'diameter': 2}]
 Returns
A list of dictionaries, one for each particle type in the system.

class
hoomd.hpmc.integrate.
sphere_union
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for unions of spheres (3D).
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 optimal performance. The capacity of leaf nodes is configurable.
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
capacity (int) – Set to the number of constituent spheres per leaf node. (added in version 2.2)
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Sphere union parameters:
diameters (required)  list of diameters of the spheres (distance units).
centers (required)  list of centers of constituent spheres in particle coordinates.
overlap (default: 1 for all spheres)  only check overlap between constituent particles for which overlap [i] & overlap[j] is !=0, where ‘&’ is the bitwise AND operator.
New in version 2.1.
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking.
 capacity (default: 4)  set to the maximum number of particles per leaf node for better performance
New in version 2.2.
Example:
mc = hpmc.integrate.sphere_union(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', diameters=[1.0, 1.0], centers=[(0.25, 0.0, 0.0), (0.25, 0.0, 0.0)]); print('diameter of the first sphere = ', mc.shape_param['A'].members[0].diameter) print('center of the first sphere = ', mc.shape_param['A'].centers[0])
Depletants Example:
mc = hpmc.integrate.sphere_union(seed=415236, d=0.3, a=0.4) mc.set_param(nselect=1) mc.shape_param.set('A', diameters=[1.0, 1.0], centers=[(0.25, 0.0, 0.0), (0.25, 0.0, 0.0)]); mc.shape_param.set('B', diameters=[0.05], centers=[(0.0, 0.0, 0.0)]); mc.set_fugacity('B',fugacity=3.0)

class
hoomd.hpmc.integrate.
sphinx
(seed, d=0.1, a=0.1, move_ratio=0.5, nselect=4, restore_state=False)¶ HPMC integration for sphinx particles (3D).
 Parameters
seed (int) – Random number seed.
d (float) – Maximum move displacement, Scalar to set for all types, or a dict containing {type:size} to set by type.
a (float) – Maximum rotation move, Scalar to set for all types, or a dict containing {type:size} to set by type.
move_ratio (float) – Ratio of translation moves to rotation moves.
nselect (int) – The number of trial moves to perform in each cell.
restore_state (bool) – Restore internal state from initialization file when True. See
mode_hpmc
for a description of what state data restored. (added in version 2.2)
Sphinx particles are dimpled spheres (spheres with ‘positive’ and ‘negative’ volumes).
Sphinx parameters:
diameters  diameters of spheres (positive OR negative real numbers)
centers  centers of spheres in local coordinate frame
ignore_statistics (default: False)  set to True to disable ignore for statistics tracking
Quick Example:
mc = hpmc.integrate.sphinx(seed=415236, d=0.3, a=0.4) mc.shape_param.set('A', centers=[(0,0,0),(1,0,0)], diameters=[1,.25]) print('diameters = ', mc.shape_param['A'].diameters)
Depletants Example:
mc = hpmc.integrate.sphinx(seed=415236, d=0.3, a=0.4) mc.set_param(nselect=1) mc.shape_param.set('A', centers=[(0,0,0),(1,0,0)], diameters=[1,.25]) mc.shape_param.set('B', centers=[(0,0,0)], diameters=[.15]) mc.set_fugacity('B',fugacity=3.0)