hoomd.wall

Overview

Cylinder

A right circular cylinder.

Plane

A plane.

Sphere

A sphere.

WallGeometry

Abstract base class for a HOOMD wall geometry.

Details

Wall geometries.

Walls define an oriented surface in space. Walls exist only in the primary box image and are not replicated across the periodic boundary conditions. Points on one side of the surface have a positive signed distance to that surface, and points on the other side have a negative signed distance.

Define individual walls with Cylinder, Plane, and Sphere. Create lists of these WallGeometry objects to describe more complex geometries. Use walls to confine particles to specific regions of space in HPMC and MD simulations.

See also

hoomd.hpmc.external.wall

hoomd.md.external.wall

class hoomd.wall.Cylinder(radius, axis, origin=(0.0, 0.0, 0.0), inside=True, open=True)

Bases: WallGeometry

A right circular cylinder.

Parameters:

  • radius (float) – The radius of the circle faces of the cylinder \([\mathrm{length}]\).

  • axis (tuple [float, float, float]) – A vector perpendicular to the circular faces.

  • origin (tuple [float, float, float], optional) – The origin of the cylinder defined as the center of the circle along the cylinder’s axis \([\mathrm{length}]\).

  • inside (bool, optional) – Whether positive signed distances are inside or outside the cylinder.

  • open (bool, optional) – Whether to include the surface of the cylinder in the space. True means do not include the surface, defaults to True.

Cylinder walls in HOOMD span the simulation box in the direction given by the axis attribute.

The signed distance from the wall surface is

\[d = \left( R - \lvert \left( \vec{r} - \vec{r}_o \right) - \left( \left( \vec{r} - \vec{r}_o \right) \cdot \hat{n} \right) \hat{n} \rvert \right)\]

for inside=True, where \(r\) is the particle position, \(\vec{r}_o\) is the origin of the cylinder, \(\hat{n}\) is the cylinder’s unit axis, and \(R\) is the cylinder’s radius. The distance is negated when inside=False.

Warning

When running MD simulations in 2D simulation boxes, set axis=(0,0,1). Otherwise, the wall force will push particles off the xy plane.

Note

Cylinder objects are immutable.

Example:

cylinder = hoomd.wall.Cylinder(radius=10.0, axis=(0,0,1))
radius

The radius of the circle faces of the cylinder \([\mathrm{length}]\).

Type:

float

origin

The origin of the cylinder defined as the center of the circle along the cylinder’s axis \([\mathrm{length}]\).

Type:

tuple [float, float, float]

axis

A vector perpendicular to the circular faces.

Type:

tuple [float, float, float]

inside

Whether positive signed distances are inside or outside the cylinder.

Type:

bool

open

Whether to include the surface of the cylinder in the space. True means do not include the surface.

Type:

bool, optional

__repr__()

A string representation of the Cylinder.

__str__()

A string representation of the Cylinder.

to_dict()

Convert the wall geometry to a dictionary defining the cylinder.

Returns:

The geometry in a Python dictionary.

Return type:

dict

class hoomd.wall.Plane(origin, normal, open=True)

Bases: WallGeometry

A plane.

Parameters:

  • origin (tuple [float, float, float]) – A point that lies on the plane \([\mathrm{length}]\).

  • normal (tuple [float, float, float]) – The normal vector to the plane. The vector will be converted to a unit vector \([\mathrm{dimensionless}]\).

  • open (bool, optional) – Whether to include the surface of the plane in the space. True means do not include the surface, defaults to True.

The signed distance from the wall surface is:

\[d = \hat{n} \cdot \left( \vec{r} - \vec{r}_o \right)\]

where \(\vec{r}\) is the particle position, \(\vec{r}_o\) is the origin of the plane, and \(\hat{n}\) is the plane’s unit normal. The normal points toward the points with a positive signed distance to the plane.

Warning

When running MD simulations in 2D simulation boxes, set normal=(nx,ny,0). Otherwise, the wall force will push particles off the xy plane.

Note

Plane objects are immutable.

Example:

plane = hoomd.wall.Plane(origin=(-10, 0, 0), normal=(1, 0, 0))
origin

A point that lies on the plane \([\mathrm{length}]\).

Type:

tuple [float, float, float]

normal

The unit normal vector to the plane.

Type:

tuple [float, float, float]

open

Whether to include the surface of the plane in the space. True means do not include the surface.

Type:

bool

__repr__()

A string representation of the Plane.

__str__()

A string representation of the Plane.

to_dict()

Convert the wall geometry to a dictionary defining the plane.

Returns:

The geometry in a Python dictionary.

Return type:

dict

class hoomd.wall.Sphere(radius, origin=(0.0, 0.0, 0.0), inside=True, open=True)

Bases: WallGeometry

A sphere.

Parameters:

  • radius (float) – The radius of the sphere \([\mathrm{length}]\).

  • origin (tuple [float, float, float], optional) – The origin of the sphere, defaults to (0, 0, 0) \([\mathrm{length}]\).

  • inside (bool, optional) – Whether positive signed distances are inside or outside the sphere, defaults to True.

  • open (bool, optional) – Whether to include the surface of the sphere in the space. True means do not include the surface, defaults to True.

The signed distance from the wall surface is:

\[d = \left( R - \lvert \vec{r} - \vec{r}_o \rvert \right)\]

for inside=True, where \(r\) is the particle position, \(r_o\) is the origin of the sphere, and \(R\) is the sphere’s radius. The distance is negated when inside=False.

Warning

When running MD simulations in 2D simulation boxes, set origin[2]=(x,y,0). Otherwise, the wall force will push particles off the xy plane.

Note

Sphere objects are immutable.

Example:

sphere = hoomd.wall.Sphere(radius=10.0)
radius

The radius of the sphere \([\mathrm{length}]\).

Type:

float

origin

The origin of the sphere \([\mathrm{length}]\).

Type:

tuple [float, float, float]

inside

Whether positive signed distances are inside or outside the sphere.

Type:

bool

open

Whether to include the surface of the sphere in the space. Open means do not include the surface.

Type:

bool

__repr__()

A string representation of the Sphere.

__str__()

A string representation of the Sphere.

to_dict()

Convert the wall geometry to a dictionary defining the sphere.

Returns:

The geometry in a Python dictionary.

Return type:

dict

class hoomd.wall.WallGeometry

Bases: ABC

Abstract base class for a HOOMD wall geometry.

Walls are used in both HPMC and MD subpackages. Subclasses of WallGeometry abstract over the wall geometries for both use cases.

abstract to_dict()

Convert the wall geometry to a dictionary defining the geometry.

Returns:

The geometry in a Python dictionary.

Return type:

dict