md.external.wall

Overview

ForceShiftedLJ

Force-shifted Lennard-Jones wall force.

Gaussian

Gaussian wall force.

LJ

Lennard-Jones wall force.

Mie

Mie wall force.

Morse

Morse wall force.

Yukawa

Yukawa wall force.

WallPotential

Base class wall force.

Details

Wall forces.

Wall potential classes compute forces, virials, and energies between all particles and the given walls consistent with the energy:

\[U_\mathrm{wall} = \sum_{i=0}^{\mathrm{N_particles-1}} \sum_{w \in walls} U_w(d_i),\]

where \(d_i\) is the signed distance between particle \(i\) and the wall \(w\).

The potential \(U_w(d)\) is a function of the signed cutoff distance between the particle and a 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. \(U_w(d)\) is related to a pair potential \(U_{\mathrm{pair}}\) as defined below and each subclass of WallPotential implements a different functional form of \(U_{\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. \(U(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:

\[U(d) = U_{\mathrm{pair}}(d) - U_{\mathrm{pair}}(r_{\mathrm{cut}})\]

For open=True spaces:

\[\begin{split}\vec{F} = \begin{cases} -\frac{\partial U}{\partial d}\hat{d} & 0 < d < r_{\mathrm{cut}} \\ 0 & d \ge r_{\mathrm{cut}} \\ 0 & d \le 0 \end{cases}\end{split}\]

For open=False (closed) spaces:

\[\begin{split}\vec{F} = \begin{cases} -\frac{\partial U}{\partial d}\hat{d} & 0 \le d < r_{\mathrm{cut}} \\ 0 & d \ge r_{\mathrm{cut}} \\ 0 & d < 0 \end{cases}\end{split}\]

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:

Example plot of wall potential.

When inside=False, the potential becomes:

Example plot of an outside wall potential.

Extrapolated Mode:

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{split}V_{\mathrm{extrap}}(d) = \begin{cases} U(d) & d > r_{\rm extrap} \\ U(r_{\rm extrap}) + (r_{\rm extrap}-r)\vec{F}(r_{\rm extrap}) \cdot \vec{n} & d \le r_{\rm extrap} \end{cases}\end{split}\]

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{split}\vec{F}(d) = \begin{cases} \vec{F}(d) & d > r_{\rm extrap} \\ \vec{F}(r_{\rm extrap}) & d \le r_{\rm extrap} \end{cases}\end{split}\]

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

Example plot demonstrating potential extrapolation.

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.

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

Force-shifted Lennard-Jones wall force.

Parameters:

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

Wall force evaluated using the Force-shifted Lennard-Jones force. See hoomd.md.pair.ForceShiftedLJ for the functional form of the force and parameter definitions.

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 force.

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.Gaussian(walls)

Gaussian wall force.

Parameters:

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

Wall force evaluated using the Gaussian force. See hoomd.md.pair.Gaussian for the functional form of the force and parameter definitions.

Example:

walls = [hoomd.wall.Sphere(radius=4.0)]
gaussian_wall = hoomd.md.external.wall.Gaussian(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 force.

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 force.

Parameters:

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

Wall force evaluated using the Lennard-Jones force. See hoomd.md.pair.LJ for the functional form of the force and parameter definitions.

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, defaults to 0 \([\mathrm{length}]\).

Type: TypeParameter [particle_types, dict]

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

Mie wall force.

Parameters:

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

Wall force evaluated using the Mie force. See hoomd.md.pair.Mie for the functional form of the force and parameter definitions.

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 force.

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 force.

Parameters:

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

Wall force evaluated using the Morse force. See hoomd.md.pair.Morse for the functional form of the force and parameter definitions.

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 force.

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)

Base class wall force.

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 force.

Parameters:

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

Wall force evaluated using the Yukawa force. See hoomd.md.pair.Yukawa for the functional form of the force and parameter definitions.

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

A list of wall definitions to use for the force.

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]