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: 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: Wall force evaluated using the Force-shifted Lennard-Jones potential. See
hoomd.md.pair.force_shifted_lj
for force details and base parameters andwallpotential
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 withenable()
.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.
-
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)
-
get_net_force
(group)¶ Get the force of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the force for.Returns: The last computed force for the members in the group. Examples
g = group.all() force = force.get_net_force(g)
-
get_net_virial
(group)¶ Get the virial of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the virial for.Returns: The last computed virial for the members in the group. Examples
g = group.all() virial = force.get_net_virial(g)
-
-
class
hoomd.md.wall.
gauss
(walls, r_cut=False, name='')¶ Gaussian wall potential.
Parameters: Wall force evaluated using the Gaussian potential. See
hoomd.md.pair.gauss
for force details and base parameters andwallpotential
for generalized wall potential implementationExample:
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 withenable()
.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.
-
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)
-
get_net_force
(group)¶ Get the force of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the force for.Returns: The last computed force for the members in the group. Examples
g = group.all() force = force.get_net_force(g)
-
get_net_virial
(group)¶ Get the virial of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the virial for.Returns: The last computed virial for the members in the group. Examples
g = group.all() virial = force.get_net_virial(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 andsphere
cylinder
, andplane
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 definitions 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_Structure: 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 definitions 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_Structure: 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 definitions 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_Structure: 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: Adds a cylinder with the specified parameters to the group.
-
add_plane
(origin, normal, inside=True)¶ Adds a plane to the wall group.
Parameters: 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: 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.
-
-
class
hoomd.md.wall.
lj
(walls, r_cut=False, name='')¶ Lennard-Jones wall potential.
Parameters: Wall force evaluated using the Lennard-Jones potential. See
hoomd.md.pair.lj
for force details and base parameters andwallpotential
for generalized wall potential implementationStandard 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:
-
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 withenable()
.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.
-
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)
-
get_net_force
(group)¶ Get the force of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the force for.Returns: The last computed force for the members in the group. Examples
g = group.all() force = force.get_net_force(g)
-
get_net_virial
(group)¶ Get the virial of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the virial for.Returns: The last computed virial for the members in the group. Examples
g = group.all() virial = force.get_net_virial(g)
-
-
class
hoomd.md.wall.
mie
(walls, r_cut=False, name='')¶ Mie potential wall potential.
Parameters: Wall force evaluated using the Mie potential. See
hoomd.md.pair.mie
for force details and base parameters andwallpotential
for generalized wall potential implementationExample:
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 withenable()
.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.
-
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)
-
get_net_force
(group)¶ Get the force of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the force for.Returns: The last computed force for the members in the group. Examples
g = group.all() force = force.get_net_force(g)
-
get_net_virial
(group)¶ Get the virial of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the virial for.Returns: The last computed virial for the members in the group. Examples
g = group.all() virial = force.get_net_virial(g)
-
-
class
hoomd.md.wall.
morse
(walls, r_cut=False, name='')¶ Morse wall potential.
Parameters: Wall force evaluated using the Morse potential. See
hoomd.md.pair.morse
for force details and base parameters andwallpotential
for generalized wall potential implementationExample:
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 withenable()
.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.
-
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)
-
get_net_force
(group)¶ Get the force of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the force for.Returns: The last computed force for the members in the group. Examples
g = group.all() force = force.get_net_force(g)
-
get_net_virial
(group)¶ Get the virial of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the virial for.Returns: The last computed virial for the members in the group. Examples
g = group.all() virial = force.get_net_virial(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: 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: 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 andwallpotential
for generalized wall potential implementationExample:
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 withenable()
.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.
-
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)
-
get_net_force
(group)¶ Get the force of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the force for.Returns: The last computed force for the members in the group. Examples
g = group.all() force = force.get_net_force(g)
-
get_net_virial
(group)¶ Get the virial of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the virial for.Returns: The last computed virial for the members in the group. Examples
g = group.all() virial = force.get_net_virial(g)
-
-
class
hoomd.md.wall.
sphere
(r=0.0, origin=(0.0, 0.0, 0.0), inside=True)¶ Sphere wall.
Parameters: 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_Structure: 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_Structure: 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_Structure: 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 can also be useful for typical wall force usages by effectively limiting the maximum force experienced by the particle due to the wall. 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 initialization.
The extrapolated potential has the following form:
\begin{eqnarray*} V_{\mathrm{extrap}}(r) =& V(r) &, r > 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 the normal into the active half-space. This gives an effective force on the particle due to the wall:
\begin{eqnarray*} \vec{F}(r) =& \vec{F}_{\rm pair}(r) &, r > r_{\rm extrap} \\ =& \vec{F}_{\rm pair}(r_{\rm extrap}) &, r \le r_{\rm extrap} \end{eqnarray*}where \(\vec{F}_{\rm pair}\) is given by the gradient of the pair force
\begin{eqnarray*} \vec{F}_{\rm pair}(r) =& -\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. Seegroup
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 appropriate 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 withenable()
.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.
-
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)
-
get_net_force
(group)¶ Get the force of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the force for.Returns: The last computed force for the members in the group. Examples
g = group.all() force = force.get_net_force(g)
-
get_net_virial
(group)¶ Get the virial of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the virial for.Returns: The last computed virial for the members in the group. Examples
g = group.all() virial = force.get_net_virial(g)
-
class
hoomd.md.wall.
yukawa
(walls, r_cut=False, name='')¶ Yukawa wall potential.
Parameters: Wall force evaluated using the Yukawa potential. See
hoomd.md.pair.yukawa
for force details and base parameters andwallpotential
for generalized wall potential implementationExample:
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 withenable()
.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.
-
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)
-
get_net_force
(group)¶ Get the force of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the force for.Returns: The last computed force for the members in the group. Examples
g = group.all() force = force.get_net_force(g)
-
get_net_virial
(group)¶ Get the virial of a particle group.
Parameters: group ( hoomd.group
) – The particle group to query the virial for.Returns: The last computed virial for the members in the group. Examples
g = group.all() virial = force.get_net_virial(g)
-