md.pair.aniso
Overview
Anistropic LJ force. |
|
Base class anisotropic pair force. |
|
Screened dipole-dipole pair forces. |
|
Gay-Berne anisotropic pair force. |
Details
Anisotropic pair forces.
Anisotropic pair force classes apply a force, torque, and virial on every particle in the simulation state commensurate with the potential energy:
AnisotropicPair
applies cuttoffs, exclusions, and assigns per particle
energies and virials in the same manner as hoomd.md.pair.Pair
AnisotropicPair
does not support 'xplor'
shifting mode or the r_on
parameter.
- class hoomd.md.pair.aniso.ALJ(nlist, default_r_cut=None, mode='none')
Bases:
AnisotropicPair
Anistropic LJ force.
- Parameters
nlist (hoomd.md.nlist.NeighborList) – Neighbor list
default_r_cut (float) – Default cutoff radius \([length]\).
mode (
str
, optional) – the energy shifting mode, defaults to “none”.
ALJ
computes the Lennard-Jones force between anisotropic particles as described in Ramasubramani, V. et. al. 2020. Specifically we implement the formula:\[U(r, r_c) = 4 \varepsilon \left[ \left( \frac{\sigma}{r} \right)^{12} - \left( \frac{\sigma}{r} \right)^{6} \right] + 4 \varepsilon_c \left[ \left( \frac{\sigma_c}{r_c} \right)^{12} - \left( \frac{\sigma_c}{r_c} \right)^{6} \right]\]The first term is the standard center-center interaction between two Lennard-Jones spheres. The second term is a contact interaction computed based on the smallest distance between the surfaces of the two shapes, \(r_c\). The total potential energy can thus be viewed as the sum of two interactions, a central Lennard-Jones potential and a shifted Lennard-Jones potential where the shift is anisotropic and depends on the extent of the shape in each direction.
Like a standard LJ potential, each term has an independent cutoff beyond which it decays to zero the behavior of these cutoffs is dependent on whether a user requires LJ or Weeks-Chandler-Anderson (WCA)-like (repulsive-only) behavior. This behavior is controlled using the
alpha
parameter, which can take on the following values:0: All interactions are WCA (no attraction).
1: Center-center interactions include attraction, contact-contact interactions are solely repulsive.
2: Center-center interactions are solely repulsive, contact-contact interactions include attraction.
3: All interactions include attractive and repulsive components.
For polytopes, computing interactions using a single contact point leads to significant instabilities in the torques because the contact point can jump from one end of a face to another in an arbitrarily small time interval. To ameliorate this, the ALJ potential performs a local averaging over all the features associated with the closest simplices on two polytopes. This averaging can be turned off by setting the
average_simplices
key for the type pair toFalse
.Specifying only
rounding_radii
creates an ellipsoid, while specifying onlyvertices
creates a convex polytope (setvertices
andfaces
to empty list to create the ellipsoid).Example:
nl = hoomd.md.nlist.Cell() alj = hoomd.md.pair.aniso.ALJ(nl, r_cut=2.5) cube_verts = [(-0.5, -0.5, -0.5), (-0.5, -0.5, 0.5), (-0.5, 0.5, -0.5), (-0.5, 0.5, 0.5), (0.5, -0.5, -0.5), (0.5, -0.5, 0.5), (0.5, 0.5, -0.5), (0.5, 0.5, 0.5)]; cube_faces = [[0, 2, 6], [6, 4, 0], [5, 0, 4], [5,1,0], [5,4,6], [5,6,7], [3,2,0], [3,0,1], [3,6,2], [3,7,6], [3,1,5], [3,5,7]] alj.params[("A", "A")] = dict(epsilon=2.0, sigma_i=1.0, sigma_j=1.0, alpha=1, ) alj.shape["A"] = dict(vertices=cube_verts, faces=cube_faces, rounding_radii=1)
The following example shows how to easily get the faces, with vertex indices properly ordered, for a shape with known vertices by using the coxeter package:
Example:
import coxeter nl = hoomd.md.nlist.Cell() alj = hoomd.md.pair.aniso.ALJ(nl, r_cut=2.5) cube_verts = [[-0.5, -0.5, -0.5], [-0.5, -0.5, 0.5], [-0.5, 0.5, -0.5], [-0.5, 0.5, 0.5], [0.5, -0.5, -0.5], [0.5, -0.5, 0.5], [0.5, 0.5, -0.5], [0.5, 0.5, 0.5]] cube = coxeter.shapes.ConvexPolyhedron(cube_verts) alj.params[("A", "A")] = dict(epsilon=2.0, sigma_i=1.0, sigma_j=1.0, alpha=1, ) alj.shape["A"] = dict(vertices=cube.vertices, faces=cube.faces, rounding_radii=1)
Warning
Changing dimension in a simulation will invalidate this force and will lead to error or unrealistic behavior.
- params
The ALJ potential parameters. The dictionary has the following keys:
epsilon
(float
, required) - base energy scale \(\varepsilon\) \([energy]\).sigma_i
(float
, required) - the insphere radius of the first particle type, \([length]\).sigma_j
(float
, required) - the insphere radius of the second particle type, \([length]\).alpha
(int
, required) - Integer 0-3 indicating whether or not to include the attractive component of the interaction (see above for details).contact_ratio_i
(float
, optional) - the ratio of the contact sphere radius of the first type withsigma_i
. Defaults to 0.15.contact_ratio_j
(float
, optional) - the ratio of the contact sphere radius of the second type withsigma_j
. Defaults to 0.15.average_simplices
(bool
, optional) - Whether to average over simplices. Defaults toTrue
. See class documentation for more information.
Type:
hoomd.data.typeparam.TypeParameter
[tuple
[particle_types
,particle_types
],dict
]
- shape
The shape of a given type. The dictionary has the following keys per type:
vertices
(list
[tuple
[float
,float
,float
]], required) - The vertices of a convex polytope in 2 or 3 dimensions. The third dimension in 2D is ignored.rounding_radii
(tuple
[float
,float
,float
] orfloat
, required) - The semimajor axes of a rounding ellipsoid. If a single value is specified, the rounding ellipsoid is a sphere.faces
(list
[list
[int
]], required) - The faces of the polyhedron specified as a list of list of integers. The indices corresponding to the vertices must be ordered counterclockwise with respect to the face normal vector pointing outward from the origin.
Type:
hoomd.data.typeparam.TypeParameter
[particle_types
,dict
]
- property type_shapes
The shape specification for use with GSD files for visualization.
This is not meant to be used for access to shape information in Python. See the attribute
shape
for programatic assess. Use this property to log shape for visualization and storage through the GSD file type.(
Loggable
: category=”object”)
- class hoomd.md.pair.aniso.AnisotropicPair(nlist, default_r_cut=None, mode='none')
Bases:
Pair
Base class anisotropic pair force.
Note
AnisotropicPair
is the base class for all anisotropic pair forces. Users not not instantiate this class directly.- Parameters
nlist (hoomd.md.nlist.NeighborList) – The neighbor list.
default_r_cut (
float
, optional) – The default cutoff for the potential, defaults toNone
which means no cutoff \([\mathrm{length}]\).mode (
str
, optional) – the energy shifting mode, defaults to “none”.
- class hoomd.md.pair.aniso.Dipole(nlist, default_r_cut=None, mode='none')
Bases:
AnisotropicPair
Screened dipole-dipole pair forces.
- Parameters
nlist (
hoomd.md.nlist.NeighborList
) – Neighbor listdefault_r_cut (float) – Default cutoff radius \([\mathrm{length}]\).
mode (str) – energy shifting/smoothing mode
Dipole
computes the (screened) interaction between pairs of particles with dipoles and electrostatic charges:\[ \begin{align}\begin{aligned}U &= U_{dd} + U_{de} + U_{ee}\\U_{dd} &= A e^{-\kappa r} \left(\frac{\vec{\mu_i}\cdot\vec{\mu_j}}{r^3} - 3\frac{(\vec{\mu_i}\cdot \vec{r_{ji}}) (\vec{\mu_j}\cdot \vec{r_{ji}})} {r^5} \right)\\U_{de} &= A e^{-\kappa r} \left(\frac{(\vec{\mu_j}\cdot \vec{r_{ji}})q_i}{r^3} - \frac{(\vec{\mu_i}\cdot \vec{r_{ji}})q_j}{r^3} \right)\\U_{ee} &= A e^{-\kappa r} \frac{q_i q_j}{r}\end{aligned}\end{align} \]Note
All units are documented electronic dipole moments. However,
Dipole
can also be used to represent magnetic dipoles.Example:
nl = nlist.Cell() dipole = md.pair.Dipole(nl, default_r_cut=3.0) dipole.params[('A', 'B')] = dict(A=1.0, kappa=4.0) dipole.mu['A'] = (4.0, 1.0, 0.0)
- params
The dipole potential parameters. The dictionary has the following keys:
A
(float
, required) - \(A\) - electrostatic energy scale (default: 1.0) \([\mathrm{energy} \cdot \mathrm{length} \cdot \mathrm{charge}^{-2}]\)kappa
(float
, required) - \(\kappa\) - inverse screening length \([\mathrm{length}^{-1}]\)
Type:
TypeParameter
[tuple
[particle_type
,particle_type
],dict
]
- class hoomd.md.pair.aniso.GayBerne(nlist, default_r_cut=None, mode='none')
Bases:
AnisotropicPair
Gay-Berne anisotropic pair force.
- Parameters
nlist (
hoomd.md.nlist.NeighborList
) – Neighbor listdefault_r_cut (float) – Default cutoff radius \([\mathrm{length}]\).
mode (str) – energy shifting/smoothing mode.
GayBerne
computes the Gay-Berne anisotropic pair force on every particle in the simulation state. This version of the Gay-Berne force supports identical pairs of uniaxial ellipsoids, with orientation-independent energy-well depth. The potential comes from the following paper Allen et. al. 2006.\[\begin{split}U(\vec r, \vec e_i, \vec e_j) = \begin{cases} 4 \varepsilon \left[ \zeta^{-12} - \zeta^{-6} \right] & \zeta < \zeta_{\mathrm{cut}} \\ 0 & \zeta \ge \zeta_{\mathrm{cut}} \\ \end{cases}\end{split}\]where
\[ \begin{align}\begin{aligned}\zeta &= \left(\frac{r-\sigma+\sigma_{\mathrm{min}}} {\sigma_{\mathrm{min}}}\right),\\\sigma^{-2} &= \frac{1}{2} \hat{\vec{r}} \cdot \vec{H^{-1}} \cdot \hat{\vec{r}},\\\vec{H} &= 2 \ell_\perp^2 \vec{1} + (\ell_\parallel^2 - \ell_\perp^2) (\vec{e_i} \otimes \vec{e_i} + \vec{e_j} \otimes \vec{e_j}),\end{aligned}\end{align} \]and \(\sigma_{\mathrm{min}} = 2 \min(\ell_\perp, \ell_\parallel)\).
The cut-off parameter \(r_{\mathrm{cut}}\) is defined for two particles oriented parallel along the long axis, i.e. \(\zeta_{\mathrm{cut}} = \left(\frac{r-\sigma_{\mathrm{max}} + \sigma_{\mathrm{min}}}{\sigma_{\mathrm{min}}}\right)\) where \(\sigma_{\mathrm{max}} = 2 \max(\ell_\perp, \ell_\parallel)\) .
The quantities \(\ell_\parallel\) and \(\ell_\perp\) denote the semi-axis lengths parallel and perpendicular to particle orientation.
Example:
nl = nlist.Cell() gay_berne = md.pair.GayBerne(nlist=nl, default_r_cut=2.5) gay_berne.params[('A', 'A')] = dict(epsilon=1.0, lperp=0.45, lpar=0.5) gay_berne.r_cut[('A', 'B')] = 2 ** (1.0 / 6.0)
- params
The Gay-Berne potential parameters. The dictionary has the following keys:
epsilon
(float
, required) - \(\varepsilon\) \([\mathrm{energy}]\)lperp
(float
, required) - \(\ell_\perp\) \([\mathrm{length}]\)lpar
(float
, required) - \(\ell_\parallel\) \([\mathrm{length}]\)
Type:
TypeParameter
[tuple
[particle_type
,particle_type
],dict
]