hoomd.wall

Overview

Cylinder

Define a cylinder in 3D Euclidean space.

Plane

Define a plane in 3D Euclidean space.

Sphere

Define a circle/sphere in 2D/3D Euclidean space.

WallGeometry

Abstract base class for a HOOMD wall geometry.

Details

Implement data classes for supporting HOOMD walls.

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

Define a cylinder in 3D Euclidean space.

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. The magnitude of this vector doesn’t matter.

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

  • inside (bool, optional) – Whether particles are restricted to the space 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 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.

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 bisecting 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 particles are restricted to the space 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)

Define a plane in 3D Euclidean space.

Parameters
  • origin (tuple [float, float, float]) – A point that lies on the plane used with normal to fully specify the plane \([\mathrm{length}]\).

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

  • 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 normal points toward the points with a positive signed distance to the plane.

The signed distance from the wall 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.

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.

origin

A point that lies on the plane used with normal to fully specify the plane \([\mathrm{length}]\).

Type

tuple [float, float, float]

normal

The normal vector to the plane. The vector will be converted to an unit vector.

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)

Define a circle/sphere in 2D/3D Euclidean space.

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 particles are restricted to the space 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.

Whether the wall is interpreted as a sphere or circle is dependent on the dimension of the system the wall is applied to.

The signed distance from the wall 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.

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 particles are restricted to the space 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

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