hpmc.integrate
Overview
Base class hard particle Monte Carlo integrator. 

Hard convex polygon Monte Carlo. 

Hard convex polyhedron Monte Carlo. 

Hard convex spheropolygon Monte Carlo. 

Hard convex spheropolyhedron Monte Carlo. 

Hard convex spheropolyhedron union Monte Carlo. 

Hard ellipsoid Monte Carlo. 

Hard faceted ellipsoid Monte Carlo. 

Hard convex spheropolyhedron union Monte Carlo. 

Hard polyhedra Monte Carlo. 

Hard simple polygon Monte Carlo. 

Hard sphere Monte Carlo. 

Hard sphere union Monte Carlo. 

Hard sphinx particle Monte Carlo. 
Details
Hard particle Monte Carlo integrators.
 class hoomd.hpmc.integrate.HPMCIntegrator(default_d, default_a, translation_move_probability, nselect)
Base class hard particle Monte Carlo integrator.
Note
HPMCIntegrator
is the base class for all HPMC integrators. Users should not instantiate this class directly. The attributes documented here are available to all HPMC integrators.Hard particle Monte Carlo
In hard particle Monte Carlo systems, the particles in the
hoomd.Simulation
hoomd.State
are extended objects with positions and orientations. During each time step of ahoomd.Simulation.run
,nselect
trial moves are attempted for each particle in the system.A trial move may be a rotation or a translation move, selected randomly according to the
translation_move_probability
. Translation trial moves are selected randomly from a sphere of radiusd
, whered
is set independently for each particle type. Rotational trial moves are selected with a maximum move size ofa
, wherea
is set independently for each particle type. In 2D simulations,a
is the maximum angle (in radians) by which a particle will be rotated. In 3D,a
is the magnitude of the random rotation quaternion as defined in Frenkel and Smit.translation_move_probability
can be set to 0 or 1 to enable only rotation or translation moves, respectively.Note
Full trajectory reproducibility is only possible with the same HOOMD binary installation, hardware, and execution configuration. Recompiling with different options, using a different version of HOOMD, running on a different hardware platform, or changing the parallel execution configuration may produce different trajectories due to limited floating point precision or parallel algorithmic differences.
After proposing the trial move, the HPMC integrator checks to see if the new particle configuration overlaps with any other particles in the system. If there are overlaps, it rejects the move. It accepts the move when there are no overlaps.
Setting elements of
interaction_matrix
to False disables overlap checks between specific particle types.interaction_matrix
is a particle types by particle types matrix allowing for nonadditive systems.The
fugacity
parameter enables implicit depletants when nonzero. TODO: Describe implicit depletants algorithm. No need to write this now, as Jens is rewriting the implementation.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)
Parameters
 default_a
Maximum size of rotation trial moves \([\mathrm{dimensionless}]\).
 Type
TypeParameter
[particle type
,float
]
 default_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','A')
refers to a depletant of type A. The option to set a type pair is temporary and will be removed in the release version. Type
TypeParameter
[tuple
[particle type
,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
.
 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.Attention
map_energies
is not yet implemented in HOOMD v3.x.Example
mc = hpmc.integrate.shape(…) mc.shape_param.set(…) energy_map = np.asarray(mc.map_energies())
 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 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”)
 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.
Attention
test_overlap
is not yet implemented in HOOMD v3.x. Returns
True if the particles overlap.
 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”)
 class hoomd.hpmc.integrate.ConvexPolygon(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)
Bases:
hoomd.hpmc.integrate.HPMCIntegrator
Hard convex polygon Monte Carlo.
 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 defined by their vertices (see
shape
).Important
ConvexPolygon
simulations must be performed in 2D systems.See also
Use
SimplePolygon
for concave polygons.Important
Assign a
shape
specification for each particle type in thehoomd.State
.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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard convex polyhedron Monte Carlo.
 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 defined by their vertices (see
shape
).See also
Use
Polyhedron
for concave polyhedra.Important
Assign a
shape
specification for each particle type in thehoomd.State
.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"])
Depletants Example:
mc = hpmc.integrate.ConvexPolyhedron(default_d=0.3, default_a=0.4, nselect=1) 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)]); mc.shape["B"] = dict(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.depletant_fugacity["B"] = 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 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 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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard convex spheropolygon Monte Carlo.
 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 defined by their vertices and a sweep radius (see
shape
). A spheropolygon is is a polygon rounded by a disk swept along the perimeter. The sweep radius may be 0.Important
ConvexSpheropolygon
simulations must be performed in 2D systems.Tip
A 1vertex spheropolygon is a disk and a 2vertex spheropolygon is a rounded rectangle.
Important
Assign a
shape
specification for each particle type in thehoomd.State
.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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard convex spheropolyhedron Monte Carlo.
 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 defined by their vertices and a sweep radius (see
shape
).Tip
A 1vertex spheropolygon is a sphere and a 2vertex spheropolygon is a spherocylinder.
Important
Assign a
shape
specification for each particle type in thehoomd.State
.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 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)  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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard convex spheropolyhedron union Monte Carlo.
 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 (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.
Important
Assign a
shape
specification for each particle type in thehoomd.State
.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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard ellipsoid Monte Carlo.
 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 defined by 3 half axes (see
shape
).Important
Assign a
shape
specification for each particle type in thehoomd.State
.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"])
Depletants Example:
mc = hpmc.integrate.Ellipsoid(default_d=0.3, default_a=0.4, nselect=1) mc.shape["A"] = dict(a=0.5, b=0.25, c=0.125); mc.shape["B"] = dict(a=0.05, b=0.05, c=0.05); mc.depletant_fugacity["B"] = 3.0
 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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard faceted ellipsoid Monte Carlo.
 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. 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.
Important
Assign a
shape
specification for each particle type in thehoomd.State
.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"])
Depletants Example:
mc = hpmc.integrate.FacetedEllipsoid(default_d=0.3, default_a=0.4) mc.shape["A"] = dict(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["B"] = dict(normals=[], a=0.1, b=0.1, c=0.1); mc.depletant_fugacity["B"] = 3.0
 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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard convex spheropolyhedron union Monte Carlo.
 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 (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.
Important
Assign a
shape
specification for each particle type in thehoomd.State
.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.Polyhedron(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)
Bases:
hoomd.hpmc.integrate.HPMCIntegrator
Hard polyhedra Monte Carlo.
 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 defined by their 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.
Important
Assign a
shape
specification for each particle type in thehoomd.State
.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"])
Depletants Example:
mc = hpmc.integrate.Polyhedron(default_d=0.3, default_a=0.4, 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["A"] = dict(vertices=cube_verts, faces=cube_faces); mc.shape["B"] = dict(vertices=tetra_verts, faces=tetra_faces, origin = (0,0,0)); mc.depletant_fugacity["B"] = 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 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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard simple polygon Monte Carlo.
 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 defined by their vertices (see
shape
).Important
SimplePolygon
simulations must be performed in 2D systems.See also
Use
ConvexPolygon
for faster performance with convex polygons.Important
Assign a
shape
specification for each particle type in thehoomd.State
.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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard sphere Monte Carlo.
 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 defined by their diameter (see
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 withjit
potentials for Monte Carlo simulations of particles interacting by pair potential with no hard core.Tip
Use
Sphere
in a 2D simulation to perform Monte Carlo on hard disks.Important
Assign a
shape
specification for each particle type in thehoomd.State
.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"])
Depletants Example:
mc = hoomd.hpmc.integrate.Sphere(default_d=0.3, default_a=0.4, nselect=8) mc.shape["A"] = dict(diameter=1.0) mc.shape["B"] = dict(diameter=1.0) mc.depletant_fugacity["B"] = 3.0
 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:
hoomd.hpmc.integrate.HPMCIntegrator
Hard sphere union Monte Carlo.
 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 (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.
Important
Assign a
shape
specification for each particle type in thehoomd.State
.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])
Depletants Example:
mc = hpmc.integrate.SphereUnion(default_d=0.3, default_a=0.4, nselect=1) mc.shape["A"] = dict(diameters=[1.0, 1.0], centers=[(0.25, 0.0, 0.0), (0.25, 0.0, 0.0)]); mc.shape["B"] = dict(diameters=[0.05], centers=[(0.0, 0.0, 0.0)]); mc.depletant_fugacity["B"] = 3.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
]
 class hoomd.hpmc.integrate.Sphinx(default_d=0.1, default_a=0.1, translation_move_probability=0.5, nselect=4)
Bases:
hoomd.hpmc.integrate.HPMCIntegrator
Hard sphinx particle Monte Carlo.
 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 defined by their positive and negative diameters (see
shape
).Important
Assign a
shape
specification for each particle type in thehoomd.State
.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"])
Depletants Example:
mc = hpmc.integrate.Sphinx(default_d=0.3, default_a=0.4, nselect=1) mc.shape["A"] = dict(centers=[(0,0,0), (1,0,0)], diameters=[1, .25]) mc.shape["B"] = dict(centers=[(0,0,0)], diameters=[.15]) mc.depletant_fugacity["B"] = 3.0
 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
]