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.

See also

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:

hoomd.hpmc.integrate.ConvexPolyhedron

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:

hoomd.hpmc.integrate.ConvexPolyhedron

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]