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

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

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

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.

property loggables

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. It returns None when there is more than one MPI rank.

(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]

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(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 the hoomd.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 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 \([\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 the hoomd.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 to True to ignore tracked statistics.

  • sweep_radius (float, default: 0.0) - Ignored, but present because ConvexPolyhedron shares data structures with ConvexSpheropolyhedron \([\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 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(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 to True to ignore tracked statistics.

  • sweep_radius (default: 0.0) - radius of the disk swept around the edges of the polygon \([\mathrm{length}]\). 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(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 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(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 to True 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 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(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 the hoomd.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. See ConvexSpheropolyhedron.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 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(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 the hoomd.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 to True 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 the hoomd.State.

Example:

mc = hpmc.integrate.FacetedEllipsoid(default_d=0.3, default_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(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 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(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 the hoomd.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. See FacetedEllipsoid.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 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(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 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(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 to True 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 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(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 the hoomd.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 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 \([\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 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(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 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(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 the hoomd.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. See Sphere.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 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(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 the hoomd.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 to True to ignore tracked statistics.

Type

TypeParameter [particle type, dict]