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.

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, flag 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.

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.

Type: float

property overlaps¶

Number of overlapping particle pairs.

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.

Type: tuple[int, int]

property state¶

The state of the object.

The state counts as anything stored in the _param_dict and _typeparam_dict.

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.

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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.

See also

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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

See also

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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)],
                     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 (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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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=[],
                                      sweep_radius=0.1,
                                      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.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 (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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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.

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 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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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.

See also

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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)¶

Bases: hoomd.hpmc.integrate.HPMCIntegrator

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]