md.constrain

Overview

md.constrain.distance Constrain pairwise particle distances.
md.constrain.rigid Constrain particles in rigid bodies.
md.constrain.sphere Constrain particles to the surface of a sphere.
md.constrain.oneD Constrain particles to move along a specific direction only

Details

Constraints.

Constraint forces constrain a given set of particle to a given surface, to have some relative orientation, or impose some other type of constraint. For example, a group of particles can be constrained to the surface of a sphere with sphere.

As with other force commands in hoomd, multiple constrain commands can be issued to specify multiple constraints, which are additively applied.

Warning

Constraints will be invalidated if two separate constraint commands apply to the same particle.

The degrees of freedom removed from the system by constraints are correctly taken into account when computing the temperature for thermostatting and logging.

class hoomd.md.constrain.distance

Constrain pairwise particle distances.

distance specifies that forces will be applied to all particles pairs for which constraints have been defined.

The constraint algorithm implemented is described in:

  • [1] M. Yoneya, H. J. C. Berendsen, and K. Hirasawa, “A Non-Iterative Matrix Method for Constraint Molecular Dynamics Simulations,” Mol. Simul., vol. 13, no. 6, pp. 395–405, 1994.
  • [2] M. Yoneya, “A Generalized Non-iterative Matrix Method for Constraint Molecular Dynamics Simulations,” J. Comput. Phys., vol. 172, no. 1, pp. 188–197, Sep. 2001.

In brief, the second derivative of the Lagrange multipliers with respect to time is set to zero, such that both the distance constraints and their time derivatives are conserved within the accuracy of the Velocity Verlet scheme, i.e. within \(\Delta t^2\). The corresponding linear system of equations is solved. Because constraints are satisfied at \(t + 2 \Delta t\), the scheme is self-correcting and drifts are avoided.

Warning

In MPI simulations, all particles connected through constraints will be communicated between processors as ghost particles. Therefore, it is an error when molecules defined by constraints extend over more than half the local domain size.

Caution

constrain.distance() does not currently interoperate with integrate.brownian() or integrate.langevin()

Example:

constrain.distance()
disable()

Disable the force.

Example:

force.disable()

Executing the disable command removes the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable()

enable()

Enable the force.

Example:

force.enable()

See disable().

set_params(rel_tol=None)

Set parameters for constraint computation.

Parameters:rel_tol (float) – The relative tolerance with which constraint violations are detected (optional).

Example:

dist = constrain.distance()
dist.set_params(rel_tol=0.0001)
class hoomd.md.constrain.oneD(group, constraint_vector=[0, 0, 1])

Constrain particles to move along a specific direction only

Parameters:
  • group (hoomd.group) – Group on which to apply the constraint.
  • constraint_vector (list) – [x,y,z] list indicating the direction that the particles are restricted to

oneD specifies that forces will be applied to all particles in the given group to constrain them to only move along a given vector.

Example:

constrain.oneD(group=groupA, constraint_vector=[1,0,0])

New in version 2.1.

disable()

Disable the force.

Example:

force.disable()

Executing the disable command removes the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable()

enable()

Enable the force.

Example:

force.enable()

See disable().

class hoomd.md.constrain.rigid

Constrain particles in rigid bodies.

Combine particles into rigid bodies. Rigid bodies are defined by a single central particle, and a number of constituent particles. The type of a particle determines whether it is a central particle or not. For central particle types, the parameters passed to rigid specify which constituent particle types and positions are associated with it.

The system may initialized with the central particles only, and the constituent particles are created automatically around every central particle upon a call to create_bodies()

Example for defining a cylindrical rigid body of two constituent particles of type ‘const’ and a central particle of type ‘central’:

# create the constituent particle type
system.particles.types.add('const')
# define the rigid body type
rigid = md.constrain.rigid()
rigid.set_param('central', positions=[(-0.5,0,0),(0.5,0,0)], types=['const','const'])
# .. create pair.lj() ..
# create constituent particles and run
rigid.create_bodies()
run(100)

In this example, only particles of type ‘central’ are assumed to exist already, whereas the constituent particles will be created with the run() command. Multiple, subsequent run()’s are supported, and the particles won’t be duplicated once created.

Danger

Automatic creation of constituent particles can change particle tags. If bonds have been defined between particles in the initial configuration, or bonds connect to constituent particles, rigid bodies should be created manually.

Example with manual initialization of constituent particles:

# intialize system, including constituent particles and some bonds
system = init.read_xml('init.xml')
rigid.set_param('central', positions=[(-0.5,0,0),(0.5,0,0)], types=['const','const'])
run(100)

Important

When you create the constituent particles manually, the central particle of a rigid body must have a lower tag than all of its constituent particles. Constituent particles follow in monotically increasing tag order, corresponding to the order they were defined in the argument to set_param(). The order of central and contiguous particles need not to be contiguous.

create_bodies(create=True)

Create copies of rigid bodies.

Parameters:create (bool) – When True, create rigid bodies, otherwise validate existing ones.
disable()

Disable the force.

Example:

force.disable()

Executing the disable command removes the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable()

enable()

Enable the force.

Example:

force.enable()

See disable().

set_param(type_name, types, positions, orientations=None, charges=None, diameters=None)

Set constituent particle types and coordinates for a rigid body.

Parameters:
  • type_name (str) – The type of the central particle
  • types (list) – List of types of constituent particles
  • positions (list) – List of relative positions of constituent particles
  • orientations (list) – List of orientations of constituent particles (optional)
  • charge (list) – List of charges of constituent particles (optional)
  • diameters (list) – List of diameters of constituent particles (optional)

Caution

The constituent particle type must be exist. If it does not exist, it can be created on the fly using system.particles.types.add('A_const') (see hoomd.data).

Example:

rigid = constrain.rigd()
rigid.set_param('A', types = ['A_const', 'A_const'], positions = [(0,0,1),(0,0,-1)])
rigid.set_param('B', types = ['B_const', 'B_const'], positions = [(0,0,.5),(0,0,-.5)])
class hoomd.md.constrain.sphere(group, P, r)

Constrain particles to the surface of a sphere.

Parameters:
  • group (hoomd.group) – Group on which to apply the constraint.
  • P (tuple) – (x,y,z) tuple indicating the position of the center of the sphere (in distance units).
  • r (float) – Radius of the sphere (in distance units).

sphere specifies that forces will be applied to all particles in the given group to constrain them to a sphere. Currently does not work with Brownian or Langevin dynamics (hoomd.md.integrate.brownian and hoomd.md.integrate.langevin).

Example:

constrain.sphere(group=groupA, P=(0,10,2), r=10)
disable()

Disable the force.

Example:

force.disable()

Executing the disable command removes the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable()

enable()

Enable the force.

Example:

force.enable()

See disable().