md.external.wall

Overview

ForceShiftedLJ

Force-shifted Lennard-Jones wall potential.

Gauss

Gaussian wall potential.

LJ

Lennard-Jones wall potential.

Mie

Mie wall potential.

Morse

Morse wall potential.

Yukawa

Yukawa wall potential.

WallPotential

Generic wall potential.

Details

Wall potentials.

Wall potentials add forces to any particles within a certain distance, \(r_{\mathrm{cut}}\), of each wall surface. In the extrapolated mode, all particles outside of the wall boundary are included as well.

class hoomd.md.external.wall.ForceShiftedLJ(walls)

Force-shifted Lennard-Jones wall potential.

Parameters

walls (list [hoomd.wall.WallGeometry ]) – A list of wall definitions to use for the potential.

Wall force evaluated using the Force-shifted Lennard-Jones potential. See hoomd.md.pair.ForceShiftedLJ for force details and base parameters and WallPotential for generalized wall potential implementation.

Example:

walls = [hoomd.wall.Sphere(radius=4.0)]
shifted_lj_wall = hoomd.md.external.wall.ForceShiftedLJ(
    walls=walls)
shifted_lj_wall.params['A'] = {
    "epsilon": 1.0, "sigma": 1.0, "r_cut": 3.0}
shifted_lj_wall.params[['A','B']] = {
    "epsilon": 0.5, "sigma": 3.0, "r_cut": 3.2}
walls

A list of wall definitions to use for the potential.

Type

list [hoomd.wall.WallGeometry ]

params

The potential parameters per type. The dictionary has the following keys:

  • epsilon (float, required) - energy parameter \(\varepsilon\) \([\mathrm{energy}]\)

  • sigma (float, required) - particle size \(\sigma\) \([\mathrm{length}]\)

  • r_cut (float, required) - The cut off distance for the wall potential \([\mathrm{length}]\)

  • r_extrap (float, optional) - The distance to extrapolate the potential, defaults to 0 \([\mathrm{length}]\)

Type: TypeParameter [particle_types, dict]

class hoomd.md.external.wall.Gauss(walls)

Gaussian wall potential.

Parameters

walls (list [hoomd.wall.WallGeometry ]) – A list of wall definitions to use for the potential.

Wall force evaluated using the Gaussian potential. See hoomd.md.pair.Gauss for force details and base parameters and WallPotential for generalized wall potential implementation.

Example:

walls = [hoomd.wall.Sphere(radius=4.0)]
gaussian_wall = hoomd.md.external.wall.Gauss(walls=walls)
gaussian_wall.params['A'] = {"epsilon": 1.0, "sigma": 1.0, "r_cut": 2.5}
gaussian_wall.params[['A','B']] = {
    "epsilon": 2.0, "sigma": 1.0, "r_cut": 1.0}
walls

A list of wall definitions to use for the potential.

Type

list [hoomd.wall.WallGeometry ]

params

The potential parameters per type. The dictionary has the following keys:

  • epsilon (float, required) - energy parameter \(\varepsilon\) \([\mathrm{energy}]\)

  • sigma (float, required) - particle size \(\sigma\) \([\mathrm{length}]\)

  • r_cut (float, required) - The cut off distance for the wall potential \([\mathrm{length}]\)

  • r_extrap (float, optional) - The distance to extrapolate the potential \([\mathrm{length}]\), defaults to 0.

Type: TypeParameter [particle_types, dict]

class hoomd.md.external.wall.LJ(walls)

Lennard-Jones wall potential.

Parameters

walls (list [hoomd.wall.WallGeometry ]) – A list of wall definitions to use for the potential.

Wall force evaluated using the Lennard-Jones potential. See hoomd.md.pair.LJ for force details and base parameters and WallPotential for generalized wall potential implementation.

Example:

walls = [hoomd.wall.Sphere(radius=4.0)]
lj = hoomd.md.external.wall.LJ(walls=walls)
lj.params['A'] = {"sigma": 1.0, "epsilon": 1.0, "r_cut": 2.5}
lj.params[['A','B']] = {"epsilon": 2.0, "sigma": 1.0, "r_cut": 2.8}
lj.params["A"] = {"r_extrap": 1.1}
params

The potential parameters per type. The dictionary has the following keys:

  • epsilon (float, required) - energy parameter \(\varepsilon\) \([\mathrm{energy}]\)

  • sigma (float, required) - particle size \(\sigma\) \([\mathrm{length}]\)

  • r_cut (float, required) - The cut off distance for the wall potential \([\mathrm{length}]\)

  • r_extrap (float, optional) - The distance to extrapolate the potential, defauts to 0 \([\mathrm{length}]\) .

Type: TypeParameter [particle_types, dict]

class hoomd.md.external.wall.Mie(walls)

Mie wall potential.

Parameters

walls (list [hoomd.wall.WallGeometry ]) – A list of wall definitions to use for the potential.

Wall force evaluated using the Mie potential. See hoomd.md.pair.Mie for force details and base parameters and WallPotential for generalized wall potential implementation.

Example:

walls = [hoomd.wall.Sphere(radius=4.0)]
mie_wall = hoomd.md.external.wall.Mie(walls=walls)
mie_wall.params['A'] = {
    "epsilon": 1.0, "sigma": 1.0, "n": 12, "m": 6, "r_cut": 3.0}
mie_wall.params[['A','B']] = {
    "epsilon": 0.5, "sigma": 3.0, "n": 49, "m": 50, "r_cut": 3.2}
walls

A list of wall definitions to use for the potential.

Type

list [hoomd.wall.WallGeometry ]

params

The potential parameters per type. The dictionary has the following keys:

  • epsilon (float, required) - energy parameter \(\varepsilon\) \([\mathrm{energy}]\)

  • sigma (float, required) - particle size \(\sigma\) \([\mathrm{length}]\)

  • r_cut (float, required) - The cut off distance for the wall potential \([\mathrm{length}]\)

  • r_extrap (float, optional) - The distance to extrapolate the potential, defaults to 0 \([\mathrm{length}]\)

Type: TypeParameter [particle_types, dict]

class hoomd.md.external.wall.Morse(walls)

Morse wall potential.

Parameters

walls (list [hoomd.wall.WallGeometry ]) – A list of wall definitions to use for the potential.

Wall force evaluated using the Morse potential. See hoomd.md.pair.Morse for force details and base parameters and WallPotential for generalized wall potential implementation.

Example:

walls = [hoomd.wall.Sphere(radius=4.0)]
morse_wall = hoomd.md.external.wall.Morse(walls=walls)
morse_wall.params['A'] = {
    "D0": 1.0, "alpha": 1.0, "r0": 1.0, "r_cut": 3.0}
morse_wall.params[['A','B']] = {
    "D0": 0.5, "alpha": 3.0, "r0": 1.0, "r_cut": 3.2}
walls

A list of wall definitions to use for the potential.

Type

list [hoomd.wall.WallGeometry ]

params

The potential parameters per type. The dictionary has the following keys:

  • epsilon (float, required) - energy parameter \(\varepsilon\) \([\mathrm{energy}]\)

  • sigma (float, required) - particle size \(\sigma\) \([\mathrm{length}]\)

  • r_cut (float, required) - The cut off distance for the wall potential \([\mathrm{length}]\)

  • r_extrap (float, optional) - The distance to extrapolate the potential, defaults to 0 \([\mathrm{length}]\)

Type: TypeParameter [particle_types, dict]

class hoomd.md.external.wall.WallPotential(walls)

Generic wall potential.

Wall potential classes compute the potential energy and force between all particles and the given walls. The potential \(V(d)\) is a function of the signed cutoff distance between the particle and wall’s surface \(d\). The resulting force \(\vec{F}\) is is parallel to \(\vec{d}\), the vector pointing from the closest point on the wall’s surface to the particle. \(V(d)\) is related to a pair potential \(V_{\mathrm{pair}}\) as defined below and each subclass of WallPotential implements a different functional form of \(V_{\mathrm{pair}}\).

Walls are two-sided surfaces with positive signed distances to points on the active side of the wall and negative signed distances to points on the inactive side. Additionally, the wall’s mode controls how forces and energies are computed for particles on or near the inactive side. The inside flag (or normal in the case of hoomd.wall.Plane) determines which side of the surface is active.

Standard Mode

In the standard mode, when \(r_{\mathrm{extrap}} \le 0\), the potential energy is only computed on the active side. \(V(d)\) is evaluated in the same manner as when the mode is shift for the analogous pair potentials within the boundaries of the active space:

\[V(d) = V_{\mathrm{pair}}(d) - V_{\mathrm{pair}}(r_{\mathrm{cut}})\]

For open=True spaces:

\begin{eqnarray*} \vec{F} = & -\frac{\partial V}{\partial d}\hat{d} \,\,\, & 0 < d < r_{\mathrm{cut}} \\ = & 0 & d \ge r_{\mathrm{cut}} \\ = & 0 & d \le 0 \end{eqnarray*}

For open=False (closed) spaces:

\begin{eqnarray*} \vec{F} = & -\frac{\partial V}{\partial d}\hat{d} \,\,\, & 0 \le d < r_{\mathrm{cut}} \\ = & 0 & d \ge r_{\mathrm{cut}} \\ = & 0 & d < 0 \end{eqnarray*}

Below we show the potential for a hoomd.wall.Sphere with radius 5 in 2D, using the Gaussian potential with \(\epsilon=1, \sigma=1\) and inside=True.

_images/md-wall-potential.svg

When inside=False the potential becomes,

_images/md-wall-potential-outside.svg

The wall potential can be linearly extrapolated starting at \(d = r_{\mathrm{extrap}}\) on the active side and continuing to the inactive side. This can be useful to move particles from the inactive side to the active side.

The extrapolated potential has the following form:

\begin{eqnarray*} V_{\mathrm{extrap}}(d) =& V(d) \,\,\,& d > r_{\rm extrap} \\ =& V(r_{\rm extrap}) + (r_{\rm extrap}-r)\vec{F}(r_{\rm extrap}) \cdot \vec{n}& r \le r_{\rm extrap} \end{eqnarray*}

where \(\vec{n}\) is such that the force points towards the active space for repulsive potentials. This gives an effective force on the particle due to the wall:

\begin{eqnarray*} \vec{F}(r) =& \vec{F}(d) \,\,\,& d > r_{\rm extrap} \\ =& \vec{F}(r_{\rm extrap}) & r \le r_{\rm extrap} \end{eqnarray*}

Below is an example of extrapolation with r_extrap=1.1 for a LJ potential with \(\epsilon=1, \sigma=1\).

_images/md-wall-extrapolate.svg

To use extrapolated mode r_extrap must be set per particle type.

Attention

Walls are fixed in space and do not adjust with the box size. For example, NPT simulations may not behave as expected.

Note

  • The virial due to walls is computed, but the pressure computed and reported by hoomd.md.compute.ThermodynamicQuantities is not well defined. The volume (or area) of the box enters into the pressure computation, which is not correct in a confined system. It may not even be possible to define an appropriate volume with soft walls.

  • An effective use of wall forces requires considering the geometry of the system. Each wall is only evaluated in one simulation box and thus is not periodic. Forces will be evaluated and added to all particles from all walls. Additionally there are no safeguards requiring a wall to exist inside the box to have interactions. This means that an attractive force existing outside the simulation box would pull particles across the periodic boundary where they would immediately cease to have any interaction with that wall. It is therefore up to the user to use walls in a physically meaningful manner. This includes the geometry of the walls, their interactions, and as noted here their location.

  • When \(r_{\mathrm{cut}} \le 0\) or is set to False the particle type wall interaction is excluded.

  • While wall potentials are based on the same potential energy calculations as pair potentials, features of pair potentials such as specified neighborlists, and alternative force shifting modes are not supported.

Warning

WallPotential should not be used directly. It is a base class that provides features and documentation common to all standard wall potentials.

property walls

The walls associated with this wall potential.

Type

list [hoomd.wall.WallGeometry]

class hoomd.md.external.wall.Yukawa(walls)

Yukawa wall potential.

Parameters

walls (list [hoomd.wall.WallGeometry ]) – A list of wall definitions to use for the potential.

Wall force evaluated using the Yukawa potential. See hoomd.md.pair.Yukawa for force details and base parameters and WallPotential for generalized wall potential implementation.

Example:

walls = [hoomd.wall.Sphere(radius=4.0)]
yukawa_wall = hoomd.md.external.wall.Yukawa(walls=walls)
yukawa_wall.params['A'] = {
    "epsilon": 1.0, "kappa": 1.0, "r_cut": 3.0}
yukawa_wall.params[['A','B']] = {
    "epsilon": 0.5, "kappa": 3.0, "r_cut": 3.2}
walls=wall.group()
walls

A list of wall definitions to use for the potential.

Type

list [hoomd.wall.WallGeometry ]

params

The potential parameters per type. The dictionary has the following keys:

  • epsilon (float, required) - energy parameter \(\varepsilon\) \([\mathrm{energy}]\)

  • sigma (float, required) - particle size \(\sigma\) \([\mathrm{length}]\)

  • r_cut (float, required) - The cut off distance for the wall potential \([\mathrm{length}]\)

  • r_extrap (float, optional) - The distance to extrapolate the potential, defaults to 0 \([\mathrm{length}]\)

Type: TypeParameter [particle_types, dict]