md.external.wall¶
Overview
Force-shifted Lennard-Jones wall force. |
|
Gaussian wall force. |
|
Lennard-Jones wall force. |
|
Mie wall force. |
|
Morse wall force. |
|
Yukawa wall force. |
|
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:
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:
For open=True
spaces:
For open=False
(closed) spaces:
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
:
When inside=False
, the potential becomes:
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:
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:
Below is an example of extrapolation with r_extrap=1.1
for a LJ
potential with \(\epsilon=1, \sigma=1\).
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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
]