# hpmc.integrate¶

Overview

 HPMCIntegrator Base class hard particle Monte Carlo integrator. ConvexPolygon Hard convex polygon Monte Carlo. ConvexPolyhedron Hard convex polyhedron Monte Carlo. ConvexSpheropolygon Hard convex spheropolygon Monte Carlo. ConvexSpheropolyhedron Hard convex spheropolyhedron Monte Carlo. ConvexSpheropolyhedronUnion Hard convex spheropolyhedron union Monte Carlo. Ellipsoid Hard ellipsoid Monte Carlo. FacetedEllipsoid Hard faceted ellipsoid Monte Carlo. FacetedEllipsoidUnion Hard convex spheropolyhedron union Monte Carlo. Polyhedron Hard polyhedra Monte Carlo. SimplePolygon Hard simple polygon Monte Carlo. Sphere Hard sphere Monte Carlo. SphereUnion Hard sphere union Monte Carlo. Sphinx Hard sphinx particle Monte Carlo.

Details

Hard particle Monte Carlo integrators.

class hoomd.hpmc.integrate.HPMCIntegrator(seed, d, 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 a hoomd.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 radius d, where d is set independently for each particle type. Rotational trial moves are selected with a maximum move size of a, where a 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.

The seed parameter sets the seed for the random number generator. Simulations with the same initial condition and same seed will follow the same trajectory.

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 non-additive systems.

The fugacity parameter enables implicit depletants when non-zero. 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(seed=123)
log = hoomd.logging.Logger()
gsd = hoomd.write.GSD(
'trajectory.gsd', hoomd.trigger.Periodic(1000), log=log)

Parameters

a

Maximum size of rotation trial moves.

Type

TypeParameter [particle type, float]

d

Maximum size of displacement trial moves (distance units).

Type

TypeParameter [particle type, float]

fugacity

Depletant fugacity (in units of 1/volume) (default: 0)

Type

TypeParameter [particle type, float]

interaction_matrix

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

Type

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

translation_move_probability

Fraction of moves to be selected as translation moves.

Type

float

nselect

Number of trial moves to perform per particle per timestep.

Type

int

seed

Random number seed.

Type

int

Attributes

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.

classmethod from_state(state, final_namespace=None, **kwargs)

Creates a new object from another object’s state.

Parameters
• state (str or dict) – A state dictionary for an object of this type, a gsd file name, or a dictionary outputted by hoomd.logging.Logger.

• final_namespace (str) – The name for the key of the parent dictionary from where the state is stored. This is to allow for users to specify the property state information in the case where multiple of the same object have their state information stored in the same location. As an example if two LJ pair potentials are stored, the final namespaces would be LJ and LJ_1.

• frame (int) – Only accepted when a gsd file name is passed for state. The frame to access the state information. Is keyword only.

property loggables

Return a name, category mapping of loggable quantities.

Type

dict[str, str]

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 tags i and j.

Attention

map_overlaps does not support MPI parallel simulations.

(Loggable: category=”sequence”)

Type

list[tuple[int, int]]

property mps

Number of trial moves performed per second.

Note

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

(Loggable: category=”scalar”)

Type

float

property overlaps

Number of overlapping particle pairs.

(Loggable: category=”scalar”)

Type

int

property rotate_moves

Count of the accepted and rejected rotate moves.

Note

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

(Loggable: category=”sequence”)

Type

tuple[int, int]

property state

The state of the object.

Provides a mapping of attributes to their values for use in storing objects state for later object reinitialization. An object’s state can be used to create an identical object using the from_state method (some object require other parameters to be passed in from_state besides the state mapping).

(Loggable: category=”state”)

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 rj-ri 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 two-dimensional 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”)

Type

tuple[int, int]

property type_shapes

Description of shapes in type_shapes format.

Type

list[dict]

class hoomd.hpmc.integrate.ConvexPolygon(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard convex polygon Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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.

Use SimplePolygon for concave polygons.

Important

Assign a shape specification for each particle type in the hoomd.State.

Examples:

mc = hoomd.hpmc.integrate.ConvexPolygon(seed=415236, d=0.3, 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 (distance units).

• Vertices MUST be specified in a counter-clockwise 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 to True to ignore tracked statistics.

• sweep_radius (float, default: 0.0) - Ignored, but present because ConvexPolygon shares data structures with ConvexSpheropolygon.

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(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard convex polyhedron Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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).

Use Polyhedron for concave polyhedra.

Important

Assign a shape specification for each particle type in the hoomd.State.

Example:

mc = hpmc.integrate.ConvexPolyhedron(seed=415236, d=0.3, 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(seed=415236,
d=0.3,
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 (distance units).

• 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 to True to ignore tracked statistics.

• sweep_radius (float, default: 0.0) - Ignored, but present because ConvexPolyhedron shares data structures with ConvexSpheropolyhedron.

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(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard convex spheropolygon Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 1-vertex spheropolygon is a disk and a 2-vertex spheropolygon is a rounded rectangle.

Important

Assign a shape specification for each particle type in the hoomd.State.

Examples:

mc = hoomd.hpmc.integrate.ConvexSpheropolygon(seed=415236, d=0.3, a=0.4)
mc.shape["A"] = dict(vertices=[(-0.5, -0.5),
(0.5, -0.5),
(0.5, 0.5),
(-0.5, 0.5)],

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

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

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

• vertices (list [tuple [float, float]], required) - vertices of the polygon (distance units).

• The origin MUST be contained within the spheropolygon.

• Points inside the polygon should not be included.

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

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

• sweep_radius (default: 0.0) - radius of the disk swept around the edges of the polygon (distance units). Set a non-zero sweep_radius to create a spheropolygon.

Warning

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

Type

TypeParameter [particle type, dict]

class hoomd.hpmc.integrate.ConvexSpheropolyhedron(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard convex spheropolyhedron Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 1-vertex spheropolygon is a sphere and a 2-vertex spheropolygon is a spherocylinder.

Important

Assign a shape specification for each particle type in the hoomd.State.

Example:

mc = hpmc.integrate.ConvexSpheropolyhedron(seed=415236, d=0.3, a=0.4)
mc.shape['tetrahedron'] = dict(vertices=[(0.5, 0.5, 0.5),
(0.5, -0.5, -0.5),
(-0.5, 0.5, -0.5),
(-0.5, -0.5, 0.5)]);
print('vertices = ', mc.shape['tetrahedron']["vertices"])

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

Depletants example:

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

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

• vertices (list [tuple [float, float, float]], required) - vertices of the polyhedron (distance units).

• 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 to True to ignore tracked statistics.

• sweep_radius (float, default: 0.0) - radius of the sphere swept around the surface of the polyhedron (distance units). Set a non-zero 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(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard convex spheropolyhedron union Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 the hoomd.State.

Example:

mc = hoomd.hpmc.integrate.ConvexSpheropolyhedronUnion(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["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. See ConvexSpheropolyhedron.shape for the accepted parameters.

• positions (list [tuple [float, float, float]], required) - Position of each spheropolyhedron in the union.

• orientations (list[ tuple[float, float, float, float]], default: None) - Orientation of each spheropolyhedron in the union. When not None, orientations must have a length equal to that of positions. When None (the default), orientations is initialized with all [1,0,0,0]’s.

• overlap (list [int], default: None) - Check for overlaps between constituent particles when overlap [i] & overlap[j] is nonzero (& is the bitwise AND operator). When not None, overlap must have a length equal to that of positions. When None (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 to True to ignore tracked statistics.

Type

TypeParameter [particle type, dict]

class hoomd.hpmc.integrate.Ellipsoid(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard ellipsoid Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 the hoomd.State.

Example:

mc = hpmc.integrate.Ellipsoid(seed=415236, d=0.3, 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(seed=415236, d=0.3, 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 (distance units)

• b (float, required) - half axis of ellipsoid in the y direction (distance units)

• c (float, required) - half axis of ellipsoid in the z direction (distance units)

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

Type

TypeParameter [particle type, dict]

class hoomd.hpmc.integrate.FacetedEllipsoid(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard faceted ellipsoid Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 the hoomd.State.

Example:

mc = hpmc.integrate.FacetedEllipsoid(seed=415236, d=0.3, a=0.4)

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

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

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

Depletants Example:

mc = hpmc.integrate.FacetedEllipsoid(seed=415236, d=0.3, 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$$ (squared distance units)

• a (float, required) - half axis of ellipsoid in the x direction (distance units)

• b (float, required) - half axis of ellipsoid in the y direction (distance units)

• c (float, required) - half axis of ellipsoid in the z direction (distance units)

• vertices (list [tuple [float, float, float]], default: []) - list of vertices for intersection polyhedron (see note below).

• origin (tuple [float, float, float], default: (0,0,0)) - A point inside the shape.

• ignore_statistics (bool, default: False) - set to True 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 half-space intersection of the normals must match the convex polyhedron defined by the vertices (if non-empty), the half-space intersection is not calculated automatically.

Type

TypeParameter[particle type, dict]

class hoomd.hpmc.integrate.FacetedEllipsoidUnion(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard convex spheropolyhedron union Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 the hoomd.State.

Example:

mc = hpmc.integrate.FacetedEllipsoidUnion(seed=27, d=0.3, 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. See FacetedEllipsoid.shape for the accepted parameters.

• positions (list [tuple [float, float, float]], required) - Position of each faceted ellipsoid in the union.

• orientations (list [tuple [float, float, float, float]], default: None) - Orientation of each faceted ellipsoid in the union. When not None, orientations must have a length equal to that of positions. When None (the default), orientations is initialized with all [1,0,0,0]’s.

• overlap (list [int], default: None) - Check for overlaps between constituent particles when overlap [i] & overlap[j] is nonzero (& is the bitwise AND operator). When not None, overlap must have a length equal to that of positions. When None (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 to True to ignore tracked statistics.

Type

TypeParameter [particle type, dict]

class hoomd.hpmc.integrate.Polyhedron(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard polyhedra Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 self-intersections.

Use ConvexPolyhedron for faster performance with convex polyhedra.

Note

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

Important

Assign a shape specification for each particle type in the hoomd.State.

Example:

mc = hpmc.integrate.Polyhedron(seed=415236, d=0.3, 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(seed=415236, d=0.3, 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 (distance units).

• 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 to True to ignore tracked statistics.

• sweep_radius (float, default: 0.0) - radius of the sphere swept around the surface of the polyhedron (distance units). Set a non-zero sweep_radius to create a spheropolyhedron.

• overlap (list [int], default: None) - Check for overlaps between faces when overlap [i] & overlap[j] is nonzero (& is the bitwise AND operator). When not None, overlap must have a length equal to that of faces. When None (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) - When True, 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(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard simple polygon Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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.

Use ConvexPolygon for faster performance with convex polygons.

Important

Assign a shape specification for each particle type in the hoomd.State.

Examples:

mc = hpmc.integrate.SimplePolygon(seed=415236, d=0.3, 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 (distance units).

• Vertices MUST be specified in a counter-clockwise 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 to True to ignore tracked statistics.

• sweep_radius (float, default: 0.0) - Ignored, but present because SimplePolygon shares data structures with ConvexSpheropolygon.

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(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard sphere Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 parameter orientable is False (the default), Sphere only applies translation trial moves and ignores translation_move_probability.

Tip

Use spheres with diameter=0 in conjunction with jit 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 the hoomd.State.

Examples:

mc = hoomd.hpmc.integrate.Sphere(seed=415236, d=0.3, 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(seed=415236, d=0.3, 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 (distance units).

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

• orientable (bool, default: False) - set to True to allow rotation moves on this particle type.

Type

TypeParameter [particle type, dict]

class hoomd.hpmc.integrate.SphereUnion(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard sphere union Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 the hoomd.State.

Example:

mc = hpmc.integrate.SphereUnion(seed=415236, d=0.3, 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(seed=415236, d=0.3, 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. See Sphere.shape for the accepted parameters.

• positions (list [tuple [float, float, float]], required) - Position of each sphere in the union.

• orientations (list [tuple [float, float, float, float]], default: None) - Orientation of each sphere in the union. When not None, orientations must have a length equal to that of positions. When None (the default), orientations is initialized with all [1,0,0,0]’s.

• overlap (list [int], default: None) - Check for overlaps between constituent particles when overlap [i] & overlap[j] is nonzero (& is the bitwise AND operator). When not None, overlap must have a length equal to that of positions. When None (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 to True to ignore tracked statistics.

Type

TypeParameter [particle type, dict]

class hoomd.hpmc.integrate.Sphinx(seed, d=0.1, a=0.1, translation_move_probability=0.5, nselect=4)

Hard sphinx particle Monte Carlo.

Parameters
• seed (int) – Random number seed.

• d (float) – Default maximum size of displacement trial moves (distance units).

• a (float) – Default maximum size of rotation trial moves.

• 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 the hoomd.State.

Example:

mc = hpmc.integrate.Sphinx(seed=415236, d=0.3, 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(seed=415236, d=0.3, 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) (distance units).

• centers (list [tuple [float, float, float], required) - centers of spheres in local coordinate frame (distance units).

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

Type

TypeParameter [particle type, dict]