hoomd.hpmc.shape_move

Overview

Elastic

Elastic shape move.

ShapeMove

Base class for all shape moves.

ShapeSpace

Apply shape moves in a \(N\) dimensional shape space.

Vertex

Apply shape moves where particle vertices are translated.

Details

Shape moves for a for alchemical simulations in extended ensembles.

ShapeMove subclasses extend the Hamiltonian of the system by adding degrees of freedom to the shape of the hard particle.

class hoomd.hpmc.shape_move.Elastic(stiffness, mc, default_step_size=None, normal_shear_ratio=0.5)

Bases: ShapeMove

Elastic shape move.

Apply volume preserving normal and shear shape moves to particles with a deformation energy penalty. When volume preserving deformations, the strain energy penalty is approximated as:

\[U \approx \mu \text{Tr}[\boldsymbol{\varepsilon}^2]V\]

where \(\mu\) is the stiffness constant, \(\text{Tr}\) is the trace operator, \(\boldsymbol{\varepsilon}\) is the strain tensor and \(V\) is the particle volume.

Parameters
  • stiffness (hoomd.variant.variant_like) – Shape stiffness against deformations.

  • mc (type or hoomd.hpmc.integrate.HPMCIntegrator) – The class of the MC shape integrator or an instance (see hoomd.hpmc.integrate) to use with this elastic shape. Must be a compatible class. We use this argument to create validation for reference_shape.

  • default_step_size (float, optional) – Default maximum size of shape trial moves (default: None). By default requires setting step size for all types.

  • normal_shear_ratio (float, optional) – Fraction of normal to shear deformation trial moves (default: 0.5).

Shape support.

The following shapes are supported:

Note

An instance is only able to be used with the passed HPMC integrator class.

Example:

mc = hoomd.hpmc.integrate.ConvexPolyhedron()
verts = [(1, 1, 1), (-1, -1, 1), (1, -1, -1), (-1, 1, -1)]
mc.shape["A"] = dict(vertices=verts)
elastic_move = hoomd.hpmc.shape_move.Elastic(stiffness=10, mc)
elastic_move.stiffness = 100
elastic_move.reference_shape["A"] = verts
stiffness

Shape stiffness against deformations.

Type

hoomd.variant.Variant

step_size

Maximum size of shape trial moves.

Type

TypeParameter [particle type, float]

reference_shape

Reference shape against to which compute the deformation energy.

Type

TypeParameter [particle type, dict]

normal_shear_ratio

Fraction of normal to shear deformation trial moves (default: 0.5).

Type

float, optional

class hoomd.hpmc.shape_move.ShapeMove(default_step_size=None)

Bases:

Base class for all shape moves.

Parameters

default_step_size (float, optional) – Default maximum size of shape trial moves (default: None). By default requires setting step size for all types.

Note

See the documentation of each derived class for a list of supported shapes.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.

step_size

Maximum size of shape trial moves.

Type

TypeParameter [particle type, float]

class hoomd.hpmc.shape_move.ShapeSpace(callback, default_step_size=None, param_move_probability=1)

Bases: ShapeMove

Apply shape moves in a \(N\) dimensional shape space.

Parameters
  • callback (callable [str, list], dict ]) – The python callable that will be called to map the given shape parameters to a shape definition. The callable takes the particle type and a list of parameters as arguments and return a dictionary with the shape definition whose keys must match the shape definition of the integrator: callable[[str, list], dict]. There is no type validation of the callback.

  • default_step_size (float, optional) – Default maximum size of shape trial moves (default: None). By default requires setting step size for all types.

  • param_move_probability (float, optional) – Average fraction of shape parameters to change each timestep (default: 1).

Shape support.

The following shapes are supported:

Attention

ShapeSpace only works with spheropolyhedra that have zero rounding or are spheres.

Note

Parameters must be given for every particle type and must be between 0 and 1. The class does not performs any consistency checks internally. Therefore, any shape constraint (e.g. constant volume, etc) must be performed within the callback.

Example:

mc = hoomd.hpmc.integrate.ConvexPolyhedron()
mc.shape["A"] = dict(vertices=[(1, 1, 1), (-1, -1, 1),
                               (1, -1, -1), (-1, 1, -1)])
# example callback
class ExampleCallback:
    def __init__(self):
        default_dict = dict(sweep_radius=0, ignore_statistics=True)
    def __call__(self, type, param_list):
        # do something with params and define verts
        return dict("vertices":verts, **self.default_dict))
move = hpmc.shape_move.ShapeSpace(callback = ExampleCallback)
callback

The python function that will be called to map the given shape parameters to a shape definition. The function takes the particle type and a list of parameters as arguments and return a dictionary with the shape definition whose keys must match the shape definition of the integrator: callable[[str, list], dict].

Type

callable [str, list], dict ]

step_size

Maximum size of shape trial moves.

Type

TypeParameter [particle type, float]

params

List of tunable parameters to be updated. The length of the list defines the dimension of the shape space for each particle type.

Type

TypeParameter [particle type, list]

param_move_probability

Average fraction of shape parameters to change each timestep (default: 1).

Type

float, optional

class hoomd.hpmc.shape_move.Vertex(default_step_size=None, vertex_move_probability=1)

Bases: ShapeMove

Apply shape moves where particle vertices are translated.

Vertices are rescaled during each shape move to ensure that the shape maintains a constant volume. To preserve detail balance, the maximum step size is rescaled by volume**(1/3) every time a move is accepted.

Parameters
  • default_step_size (float, optional) – Default maximum size of shape trial moves (default: None). By default requires setting step size for all types.

  • vertex_move_probability (float, optional) – Average fraction of vertices to change during each shape move (default: 1).

Vertex moves apply a uniform move on each vertex with probability vertex_move_probability in a shape up to a maximum displacement of step_size for the composing instance. The shape volume is rescaled at the end of all the displacements to the specified volume. To preserve detail balance, the maximum step size is rescaled by \(V^{1 / 3}\) every time a move is accepted.

Shape support.

The following shapes are supported:

Note

hoomd.hpmc.integrate.ConvexPolyhedron models shapes that are the the convex hull of the given vertices.

Example:

mc = hoomd.hpmc.integrate.ConvexPolyhedron(23456)
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(vertices=numpy.asarray(cube_verts) / 2)
vertex_move = shape_move.Vertex()
vertex_move.volume["A"] = 1
step_size

Maximum size of shape trial moves.

Type

TypeParameter [particle type, float]

vertex_move_probability

Average fraction of vertices to change during each shape move.

Type

float

volume

Volume of the particles to hold constant. The particles size is always rescaled to maintain this volume.

Type

TypeParameter [particle type, float]