md.wall

Geometry

md.wall.cylinder Cylinder wall.
md.wall.group Defines a wall group.
md.wall.plane Plane wall.
md.wall.sphere Sphere wall.

Overview

md.wall.force_shifted_lj Force-shifted Lennard-Jones wall potential.
md.wall.gauss Gaussian wall potential.
md.wall.lj Lennard-Jones wall potential.
md.wall.mie Mie potential wall potential.
md.wall.morse Morse wall potential.
md.wall.slj Shifted Lennard-Jones wall potential
md.wall.wallpotential Generic wall potential.
md.wall.yukawa Yukawa wall potential.

Details

Wall potentials.

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

Wall geometries are used to specify half-spaces. There are two half spaces for each of the possible geometries included and each can be selected using the inside parameter. In order to fully specify space, it is necessary that one half space be closed and one open. Setting inside=True for closed half-spaces and inside=False for open ones. See wallpotential for more information on how the concept of half-spaces are used in implementing wall forces.

Attention

The current wall force implementation does not support NPT integrators.

Wall groups (group) are used to pass wall geometries to wall forces. By themselves, wall groups do nothing. Only when you specify a wall force (i.e. lj), are forces actually applied between the wall and the

class hoomd.md.wall.cylinder(r=0.0, origin=(0.0, 0.0, 0.0), axis=(0.0, 0.0, 1.0), inside=True)

Cylinder wall.

Parameters:
  • r (float) – Cylinder radius (in distance units)
  • origin (tuple) – Cylinder origin (in x,y,z coordinates)
  • axis (tuple) – Cylinder axis vector (in x,y,z coordinates)
  • inside (bool) – Selects the half-space to be used (bool)

Define a cylindrical half-space:

  • inside = True selects the space inside the radius of the cylinder and includes the cylinder surface.
  • inside = False selects the space outside the radius of the cylinder.

Use in function calls or by reference in the creation or modification of wall groups.

For an example see sphere.

class hoomd.md.wall.force_shifted_lj(walls, r_cut=False, name='')

Force-shifted Lennard-Jones wall potential.

Parameters:
  • walls (group) – Wall group containing half-space geometries for the force to act in.
  • r_cut (float) – The global r_cut value for the force. Defaults to False or 0 if not specified.
  • name (str) – The force name which will be used in the metadata and log files.

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

Example:

walls=wall.group()
# add walls to interact with
wall_force_fslj=wall.force_shifted_lj(walls, r_cut=3.0)
wall_force_fslj.force_coeff.set('A', epsilon=1.0, sigma=1.0)
wall_force_fslj.force_coeff.set('B', epsilon=1.5, sigma=3.0, r_cut = 8.0)
wall_force_fslj.force_coeff.set(['C','D'], epsilon=1.0, sigma=1.0, alpha = 1.5)
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
class hoomd.md.wall.gauss(walls, r_cut=False, name='')

Gaussian wall potential.

Parameters:
  • walls (group) – Wall group containing half-space geometries for the force to act in.
  • r_cut (float) – The global r_cut value for the force. Defaults to False or 0 if not specified.
  • name (str) – The force name which will be used in the metadata and log files.

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=wall.group()
# add walls to interact with
wall_force_gauss=wall.gauss(walls, r_cut=3.0)
wall_force_gauss.force_coeff.set('A', epsilon=1.0, sigma=1.0)
wall_force_gauss.force_coeff.set('A', epsilon=2.0, sigma=1.0, r_cut=3.0)
wall_force_gauss.force_coeff.set(['C', 'D'], epsilon=3.0, sigma=0.5)
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
class hoomd.md.wall.group(*walls)

Defines a wall group.

Parameters:walls (list) – Wall objects to be included in the group.

All wall forces use a wall group as an input so it is necessary to create a wall group object before any wall force can be created. Modifications of the created wall group may occur at any time before hoomd.run() is invoked. Current supported geometries are spheres, cylinder, and planes. The maximum number of each type of wall is 20, 20, and 60 respectively.

The inside parameter used in each wall geometry is used to specify the half-space that is to be used for the force implementation. See wallpotential for more general details and sphere cylinder, and plane for the definition of inside for each geometry.

An effective use of wall forces requires considering the geometry of the system. Walls are only evaluated in one simulation box and are not periodic. It is therefore important to ensure that the walls that intersect with a periodic boundary meet.

Note

The entire structure can easily be viewed by printing the group object.

Note

While all x,y,z coordinates can be given as a list or tuple, only origin parameters are points in x,y,z space. Normal and axis parameters are vectors and must have a nonzero magnitude.

Note

Wall structure modifications between hoomd.run() calls will be implemented in the next run. However, modifications must be done carefully since moving the wall can result in particles moving to a relative position which causes exceptionally high forces resulting in particles moving many times the box length in one move.

Example:

In[0]:
# Creating wall geometry defintions using convenience functions
wallstructure=wall.group()
wallstructure.add_sphere(r=1.0,origin=(0,1,3))
wallstructure.add_sphere(1.0,[0,-1,3],inside=False)
wallstructure.add_cylinder(r=1.0,origin=(1,1,1),axis=(0,0,3),inside=True)
wallstructure.add_cylinder(4.0,[0,0,0],(1,0,1))
wallstructure.add_cylinder(5.5,(1,1,1),(3,-1,1),False)
wallstructure.add_plane(origin=(3,2,1),normal=(2,1,4))
wallstructure.add_plane((0,0,0),(10,2,1))
wallstructure.add_plane((0,0,0),(0,2,1))
print(wallstructure)

Out[0]:
Wall_Data_Sturucture:
spheres:2{
[0:   Radius=1.0  Origin=(0.0, 1.0, 3.0)  Inside=True]
[1:   Radius=1.0  Origin=(0.0, -1.0, 3.0) Inside=False]}
cylinders:3{
[0:   Radius=1.0  Origin=(1.0, 1.0, 1.0)  Axis=(0.0, 0.0, 3.0)    Inside=True]
[1:   Radius=4.0  Origin=(0.0, 0.0, 0.0)  Axis=(1.0, 0.0, 1.0)    Inside=True]
[2:   Radius=5.5  Origin=(1.0, 1.0, 1.0)  Axis=(3.0, -1.0, 1.0)   Inside=False]}
planes:3{
[0:   Origin=(3.0, 2.0, 1.0)  Normal=(2.0, 1.0, 4.0)]
[1:   Origin=(0.0, 0.0, 0.0)  Normal=(10.0, 2.0, 1.0)]
[2:   Origin=(0.0, 0.0, 0.0)  Normal=(0.0, 2.0, 1.0)]}

In[1]:
# Deleting wall geometry defintions using convenience functions in all accepted types
wallstructure.del_plane(range(3))
wallstructure.del_cylinder([0,2])
wallstructure.del_sphere(1)
print(wallstructure)

Out[1]:
Wall_Data_Sturucture:
spheres:1{
[0:   Radius=1.0  Origin=(0.0, 1.0, 3.0)  Inside=True]}
cylinders:1{
[0:   Radius=4.0  Origin=(0.0, 0.0, 0.0)  Axis=(1.0, 0.0, 1.0)    Inside=True]}
planes:0{}

In[2]:
# Modifying wall geometry defintions using convenience functions
wallstructure.spheres[0].r=2.0
wallstructure.cylinders[0].origin=[1,2,1]
wallstructure.cylinders[0].axis=(0,0,1)
print(wallstructure)

Out[2]:
Wall_Data_Sturucture:
spheres:1{
[0:   Radius=2.0  Origin=(0.0, 1.0, 3.0)  Inside=True]}
cylinders:1{
[0:   Radius=4.0  Origin=(1.0, 2.0, 1.0)  Axis=(0.0, 0.0, 1.0)    Inside=True]}
planes:0{}
add(wall)

Generic wall add for wall objects.

Generic convenience function to add any wall object to the group. Accepts sphere, cylinder, plane, and lists of any combination of these.

add_cylinder(r, origin, axis, inside=True)

Adds a cylinder to the wall group.

Parameters:
  • r (float) – Cylinder radius (in distance units)
  • origin (tuple) – Cylinder origin (in x,y,z coordinates)
  • axis (tuple) – Cylinder axis vector (in x,y,z coordinates)
  • inside (bool) – Selects the half-space to be used (bool)

Adds a cylinder with the specified parameters to the group.

add_plane(origin, normal, inside=True)

Adds a plane to the wall group.

Parameters:
  • origin (tuple) – Plane origin (in x,y,z coordinates)
  • normal (tuple) – Plane normal vector (in x,y,z coordinates)
  • inside (bool) – Selects the half-space to be used (bool)

Adds a plane with the specified parameters to the wallgroup.planes list.

add_sphere(r, origin, inside=True)

Adds a sphere to the wall group.

Parameters:
  • r (float) – Sphere radius (in distance units)
  • origin (tuple) – Sphere origin (in x,y,z coordinates)
  • inside (bool) – Selects the half-space to be used (bool)

Adds a sphere with the specified parameters to the group.

del_cylinder(*indexs)

Deletes the cylinder or cylinders in index.

Parameters:index (list) – The index of cylinder(s) desired to delete. Accepts int, range, and lists.

Removes the specified cylinder or cylinders from the wallgroup.cylinders list.

del_plane(*indexs)

Deletes the plane or planes in index.

Parameters:index (list) – The index of plane(s) desired to delete. Accepts int, range, and lists.

Removes the specified plane or planes from the wallgroup.planes list.

del_sphere(*indexs)

Deletes the sphere or spheres in index.

Parameters:index (list) – The index of sphere(s) desired to delete. Accepts int, range, and lists.

Removes the specified sphere or spheres from the wallgroup.spheres list.

class hoomd.md.wall.lj(walls, r_cut=False, name='')

Lennard-Jones wall potential.

Parameters:
  • walls (group) – Wall group containing half-space geometries for the force to act in.
  • r_cut (float) – The global r_cut value for the force. Defaults to False or 0 if not specified.
  • name (str) – The force name which will be used in the metadata and log files.

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

Standard mode:

walls=wall.group()
#add walls
lj=wall.lj(walls, r_cut=3.0)
lj.force_coeff.set('A', sigma=1.0,epsilon=1.0)  #plotted below in red
lj.force_coeff.set('B', sigma=1.0,epsilon=1.0, r_cut=2.0**(1.0/2.0))
lj.force_coeff.set(['A','B'], epsilon=2.0, sigma=1.0, alpha=1.0, r_cut=3.0)

Extrapolated mode:

walls=wall.group()
#add walls
lj_extrap=wall.lj(walls, r_cut=3.0)
lj_extrap.force_coeff.set('A', sigma=1.0,epsilon=1.0, r_extrap=1.1) #plotted in blue below

V(r) plot:

_images/wall_extrap.png
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
class hoomd.md.wall.mie(walls, r_cut=False, name='')

Mie potential wall potential.

Parameters:
  • walls (group) – Wall group containing half-space geometries for the force to act in.
  • r_cut (float) – The global r_cut value for the force. Defaults to False or 0 if not specified.
  • name (str) – The force name which will be used in the metadata and log files.

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=wall.group()
# add walls to interact with
wall_force_mie=wall.mie(walls, r_cut=3.0)
wall_force_mie.force_coeff.set('A', epsilon=1.0, sigma=1.0, n=12, m=6)
wall_force_mie.force_coeff.set('A', epsilon=2.0, sigma=1.0, n=14, m=7, r_cut=3.0)
wall_force_mie.force_coeff.set('B', epsilon=1.0, sigma=1.0, n=15.1, m=6.5, r_cut=2**(1.0/6.0))
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
class hoomd.md.wall.morse(walls, r_cut=False, name='')

Morse wall potential.

Parameters:
  • walls (group) – Wall group containing half-space geometries for the force to act in.
  • r_cut (float) – The global r_cut value for the force. Defaults to False or 0 if not specified.
  • name (str) – The force name which will be used in the metadata and log files.

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=wall.group()
# add walls to interact with
wall_force_morse=wall.morse(walls, r_cut=3.0)
wall_force_morse.force_coeff.set('A', D0=1.0, alpha=3.0, r0=1.0)
wall_force_morse.force_coeff.set('A', D0=1.0, alpha=3.0, r0=1.0, r_cut=3.0)
wall_force_morse.force_coeff.set(['C', 'D'], D0=1.0, alpha=3.0)
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
class hoomd.md.wall.plane(origin=(0.0, 0.0, 0.0), normal=(0.0, 0.0, 1.0), inside=True)

Plane wall.

Parameters:
  • origin (tuple) – Plane origin (in x,y,z coordinates)n <i>Default : (0.0, 0.0, 0.0)</i>
  • normal (tuple) – Plane normal vector (in x,y,z coordinates)n <i>Default : (0.0, 0.0, 1.0)</i>
  • inside (bool) – Selects the half-space to be used (bool)n <i>Default : True</i>

Define a planar half space.

  • inside = True selects the space on the side of the plane to which the normal vector points and includes the plane surface.
  • inside = False selects the space on the side of the plane opposite the normal vector.

Use in function calls or by reference in the creation or modification of wall groups.

For an example see sphere.

class hoomd.md.wall.slj(walls, r_cut=False, d_max=None, name='')

Shifted Lennard-Jones wall potential

Parameters:
  • walls (group) – Wall group containing half-space geometries for the force to act in.
  • r_cut (float) – The global r_cut value for the force. Defaults to False or 0 if not specified.
  • name (str) – The force name which will be used in the metadata and log files.

Wall force evaluated using the Shifted Lennard-Jones potential. Note that because slj is dependent upon particle diameters the following correction is necessary to the force details in the hoomd.md.pair.slj description.

\(\Delta = d_i/2 - 1\) where \(d_i\) is the diameter of particle \(i\). See hoomd.md.pair.slj for force details and base parameters and wallpotential for generalized wall potential implementation

Example:

walls=wall.group()
# add walls to interact with
wall_force_slj=wall.slj(walls, r_cut=3.0)
wall_force_slj.force_coeff.set('A', epsilon=1.0, sigma=1.0)
wall_force_slj.force_coeff.set('A', epsilon=2.0, sigma=1.0, r_cut=3.0)
wall_force_slj.force_coeff.set('B', epsilon=1.0, sigma=1.0, r_cut=2**(1.0/6.0))
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
class hoomd.md.wall.sphere(r=0.0, origin=(0.0, 0.0, 0.0), inside=True)

Sphere wall.

Parameters:
  • r (float) – Sphere radius (in distance units)
  • origin (tuple) – Sphere origin (in x,y,z coordinates)
  • inside (bool) – Selects the half-space to be used

Define a spherical half-space:

  • inside = True selects the space inside the radius of the sphere and includes the sphere surface.
  • inside = False selects the space outside the radius of the sphere.

Use in function calls or by reference in the creation or modification of wall groups.

The following example is intended to demonstrate cylinders and planes as well. Note that the distinction between points and vectors is reflected in the default parameters.

Examples:

In[0]:
# One line initialization
one_line_walls=wall.group(wall.sphere(r=3,origin=(0,0,0)),wall.cylinder(r=2.5,axis=(0,0,1),inside=True), wall.plane(normal=(1,0,0)))
print(one_line_walls)
full_wall_object=wall.group([wall.sphere()]*20,[wall.cylinder()]*20,[wall.plane()]*60)
# Sharing wall group elements and access by reference
common_sphere=wall.sphere()
linked_walls1=wall.group(common_sphere,wall.plane(origin=(3,0,0),normal=(-1,0,0)))
linked_walls2=wall.group(common_sphere,wall.plane(origin=(-3,0,0),normal=(1,0,0)))
common_sphere.r=5.0
linked_walls1.spheres[0].origin=(0,0,1)
print(linked_walls1)
print(linked_walls2)

Out[0]:
Wall_Data_Sturucture:
spheres:1{
[0:   Radius=3    Origin=(0.0, 0.0, 0.0)  Inside=True]}
cylinders:1{
[0:   Radius=2.5  Origin=(0.0, 0.0, 0.0)  Axis=(0.0, 0.0, 1.0)    Inside=True]}
planes:1{
[0:   Origin=(0.0, 0.0, 0.0)  Normal=(1.0, 0.0, 0.0)]}
Wall_Data_Sturucture:
spheres:1{
[0:   Radius=5.0  Origin=(0.0, 0.0, 1.0)  Inside=True]}
cylinders:0{}
planes:1{
[0:   Origin=(3.0, 0.0, 0.0)  Normal=(-1.0, 0.0, 0.0)]}
Wall_Data_Sturucture:
spheres:1{
[0:   Radius=5.0  Origin=(0.0, 0.0, 1.0)  Inside=True]}
cylinders:0{}
planes:1{
[0:   Origin=(-3.0, 0.0, 0.0) Normal=(1.0, 0.0, 0.0)]}
class hoomd.md.wall.wallpotential(walls, r_cut, name='')

Generic wall potential.

wallpotential should not be used directly. It is a base class that provides common features to all standard wall potentials. Rather than repeating all of that documentation in many different places, it is collected here.

All wall potential commands specify that a given potential energy and potential be computed on all particles in the system within a cutoff distance, \(r_{\mathrm{cut}}\), from each wall in the given wall group. The force \(\vec{F}\) is in the direction of \(\vec{r}\), the vector pointing from the particle to the wall or half-space boundary and \(V_{\mathrm{pair}}(r)\) is the specific pair potential chosen by the respective command. Wall forces are implemented with the concept of half-spaces in mind. There are two modes which are allowed currently in wall potentials: standard and extrapolated.

Standard Mode.

In the standard mode, when \(r_{\mathrm{extrap}} \le 0\), the potential energy is only applied to the half-space specified in the wall group. \(V(r)\) is evaluated in the same manner as when the mode is shift for the analogous pair potentials within the boundaries of the half-space.

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

For inside=True (closed) half-spaces:

\[\begin{eqnarray*} \vec{F} = & -\nabla V(r) & 0 \le r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ = & 0 & r < 0 \end{eqnarray*}\]

For inside=False (open) half-spaces:

\[\begin{eqnarray*} \vec{F} = & -\nabla V(r) & 0 < r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ = & 0 & r \le 0 \end{eqnarray*}\]

The wall potential can be linearly extrapolated beyond a minimum separation from the wall \(r_{\mathrm{extrap}}\) in the active half-space. This can be useful for bringing particles outside the half-space into the active half-space. It also useful for pushing particles off the wall by effectively limiting the maximum force experienced by the particle. The potential is extrapolated into both half-spaces and the cutoff \(r_{\mathrm{cut}}\) only applies in the active half-space. The user should then be careful using this mode with multiple nested walls. It is intended to be used primarily for equilibration.

The extrapolated potential has the following form:

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

where \(\vec{n}\) is the normal into the active half-space. This gives an effective force on the particle due to the wall:

where \(\vec{F}_{\rm pair}\) is given by the gradient of the pair force

\[\begin{eqnarray*} \vec{F}_{\rm pair} =& -\nabla V_{\rm pair}(r) &, r < r_{\rm cut} \\ =& 0 &, r \ge r_{\mathrm{cut}} \end{eqnarray*}\]

In other words, if \(r_{\rm extrap}\) is chosen so that the pair force would point into the active half-space, the extrapolated potential will push all particles into the active half-space. See lj for a pictorial example.

To use extrapolated mode, the following coefficients must be set per unique particle types:

  • All parameters required by the pair potential base for the wall potential
  • \(r_{\mathrm{cut}}\) - r_cut (in distance units) - Optional: Defaults to global r_cut for the force if given or 0.0 if not
  • \(r_{\mathrm{extrap}}\) - r_extrap (in distance units) - Optional: Defaults to 0.0

Generic Example

Note that the walls object below must be created before it is given as an argument to the force object. However, walls can be modified at any time before hoomd.run() is called and it will update itself appropriately. See group for more details about specifying the walls to be used:

walls=wall.group()
# Edit walls
my_force=wall.pairpotential(walls)
my_force.force_coeff.set('A', all required arguments)
my_force.force_coeff.set(['B','C'],r_cut=0.3, all required arguments)
my_force.force_coeff.set(['B','C'],r_extrap=0.3, all required arguments)

A specific example can be found in lj

Attention

The current wall force implementation does not support NPT integrators.

Note

The virial due to walls is computed, but the pressure and reported by hoomd.analyze.log is not well defined. The volume (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 appopriate volume with soft walls.

Note

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 in the wall group. 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.

Note

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

Note

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.

disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
class hoomd.md.wall.yukawa(walls, r_cut=False, name='')

Yukawa wall potential.

Parameters:
  • walls (group) – Wall group containing half-space geometries for the force to act in.
  • r_cut (float) – The global r_cut value for the force. Defaults to False or 0 if not specified.
  • name (str) – The force name which will be used in the metadata and log files.

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=wall.group()
# add walls to interact with
wall_force_yukawa=wall.yukawa(walls, r_cut=3.0)
wall_force_yukawa.force_coeff.set('A', epsilon=1.0, kappa=1.0)
wall_force_yukawa.force_coeff.set('A', epsilon=2.0, kappa=0.5, r_cut=3.0)
wall_force_yukawa.force_coeff.set(['C', 'D'], epsilon=0.5, kappa=3.0)
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)