md.pair¶

Overview

`Pair`	Common pair potential documentation.
`Buckingham`	Buckingham pair potential.
`DLVO`	DLVO colloidal interaction
`DPD`	Dissipative Particle Dynamics.
`DPDLJ`	Dissipative Particle Dynamics with a LJ conservative force.
`DPDConservative`	DPD Conservative pair force.
`Ewald`	Ewald pair potential.
`ForceShiftedLJ`	Force-shifted Lennard-Jones pair potential.
`Fourier`	Fourier pair potential.
`Gauss`	Gaussian pair potential.
`LJ`	Lennard-Jones pair potential.
`LJ1208`	Lennard-Jones 12-8 pair potential.
`Mie`	Mie pair potential.
`Morse`	Morse pair potential.
`Moliere`	Moliere pair potential.
`ReactionField`	Onsager reaction field pair potential.
`SLJ`	Shifted Lennard-Jones pair potential.
`Yukawa`	Yukawa pair potential.
`ZBL`	ZBL pair potential.

Details

class hoomd.md.pair.Buckingham(nlist, r_cut=None, r_on=0.0, mode='none')¶

Buckingham pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode

Buckingham specifies that a Buckingham pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{Buckingham}}(r) = & A \exp\left(-\frac{r}{\rho}\right) - \frac{C}{r^6} & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use the params dictionary to set potential coefficients.

params¶

The potential parameters. The dictionary has the following keys:

A (float, required) - \(A\) (in energy units)
rho (float, required) - \(\rho\) (in distance units)
C (float, required) - \(C\) (in energy units)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
buck = pair.Buckingham(nl, r_cut=3.0)
buck.params[('A', 'A')] = {'A': 2.0, 'rho'=0.5, 'C': 1.0}
buck.params[('A', 'B')] = dict(A=1.0, rho=1.0, C=1.0)
buck.params[('B', 'B')] = dict(A=2.0, rho=2.0, C=2.0)

class hoomd.md.pair.DLVO(nlist, r_cut=None, r_on=0.0, mode='none')¶

DLVO colloidal interaction

Parameters

r_cut (float) – Default cutoff radius (in distance units).
nlist (hoomd.md.nlist.NList) – Neighbor list
name (str) – Name of the force instance.
d_max (float) – Maximum diameter particles in the simulation will have (in distance units)

DLVO specifies that a DLVO dispersion and electrostatic interaction should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{DLVO}}(r) = & - \frac{A}{6} \left[ \frac{2a_1a_2}{r^2 - (a_1+a_2)^2} + \frac{2a_1a_2}{r^2 - (a_1-a_2)^2} \\ + \log \left( \frac{r^2 - (a_1+a_2)^2}{r^2 - (a_1-a_2)^2} \right) \right] & \\ & + \frac{a_1 a_2}{a_1+a_2} Z e^{-\kappa(r - (a_1+a_2))} & r < (r_{\mathrm{cut}} + \Delta) \\ = & 0 & r \ge (r_{\mathrm{cut}} + \Delta) \end{eqnarray*}

where \(a_i\) is the radius of particle \(i\), \(\Delta = (d_i + d_j)/2\) and \(d_i\) is the diameter of particle \(i\).

The first term corresponds to the attractive van der Waals interaction with \(A\) being the Hamaker constant, the second term to the repulsive double-layer interaction between two spherical surfaces with Z proportional to the surface electric potential. See Israelachvili 2011, pp. 317.

The DLVO potential does not need charge, but does need diameter. See SLJ for an explanation on how diameters are handled in the neighbor lists.

Due to the way that DLVO modifies the cutoff condition, it will not function properly with the xplor shifting mode. See Pair for details on how forces are calculated and the available energy shifting and smoothing modes.

params¶

The potential parameters. The dictionary has the following keys:

epsilon (float, required) - \(\varepsilon\) (in units of energy)
kappa (float, required) - scaling parameter \(\kappa\) (in units of 1/distance)
Z (float, required) - \(Z\) (in units of 1/distance)
A (float, required) - \(A\) (in units of energy)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.cell()
DLVO.pair_coeff.set('A', 'A', epsilon=1.0, kappa=1.0)
DLVO.pair_coeff.set('A', 'B', epsilon=2.0, kappa=0.5, r_cut=3.0, r_on=2.0);
DLVO.pair_coeff.set(['A', 'B'], ['C', 'D'], epsilon=0.5, kappa=3.0)

class hoomd.md.pair.DPD(nlist, kT, seed=3, r_cut=None, r_on=0.0, mode='none')¶

Dissipative Particle Dynamics.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
kT (hoomd.variant or float) – Temperature of thermostat (in energy units).
seed (int) – seed for the PRNG in the DPD thermostat.
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).

DPD specifies that a DPD pair force should be applied between every non-excluded particle pair in the simulation, including an interaction potential, pairwise drag force, and pairwise random force. See Groot and Warren 1997.

\begin{eqnarray*} F = F_{\mathrm{C}}(r) + F_{\mathrm{R,ij}}(r_{ij}) + F_{\mathrm{D,ij}}(v_{ij}) \\ \end{eqnarray*}

\begin{eqnarray*} F_{\mathrm{C}}(r) = & A \cdot w(r_{ij}) \\ F_{\mathrm{R, ij}}(r_{ij}) = & - \theta_{ij}\sqrt{3} \sqrt{\frac{2k_b\gamma T}{\Delta t}}\cdot w(r_{ij}) \\ F_{\mathrm{D, ij}}(r_{ij}) = & - \gamma w^2(r_{ij})\left( \hat r_{ij} \circ v_{ij} \right) \\ \end{eqnarray*}

\begin{eqnarray*} w(r_{ij}) = &\left( 1 - r/r_{\mathrm{cut}} \right) & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

where \(\hat r_{ij}\) is a normalized vector from particle i to particle j, \(v_{ij} = v_i - v_j\), and \(\theta_{ij}\) is a uniformly distributed random number in the range [-1, 1].

DPD generates random numbers by hashing together the particle tags in the pair, the user seed, and the current time step index.

Attention

Change the seed if you reset the simulation time step to 0. If you keep the same seed, the simulation will continue with the same sequence of random numbers used previously and may cause unphysical correlations.

For MPI runs: all ranks other than 0 ignore the seed input and use the value of rank 0.

C. L. Phillips et. al. 2011 describes the DPD implementation details in HOOMD-blue. Cite it if you utilize the DPD functionality in your work.

DPD does not implement and energy shift / smoothing modes due to the function of the force. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

To use the DPD thermostat, an hoomd.md.methods.NVE integrator must be applied to the system and the user must specify a temperature. Use of the dpd thermostat pair force with other integrators will result in unphysical behavior. To use pair.dpd with a different conservative potential than \(F_C\), set A to zero and define the conservative pair potential separately. Note that DPD thermostats are often defined in terms of \(\sigma\) where \(\sigma = \sqrt{2k_b\gamma T}\).

params¶

The force parameters. The dictionary has the following keys:

A (float, required) - \(A\) (in force units)
gamma (float, required) - \(\gamma\) (in units of force/velocity)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
dpd = pair.DPD(nlist=nl, kT=1.0, seed=0, r_cut=1.0)
dpd.params[('A', 'A')] = dict(A=25.0, gamma=4.5)
dpd.params[('A', 'B')] = dict(A=40.0, gamma=4.5)
dpd.params[('B', 'B')] = dict(A=25.0, gamma=4.5)
dpd.params[(['A', 'B'], ['C', 'D'])] = dict(A=40.0, gamma=4.5)

class hoomd.md.pair.DPDConservative(nlist, r_cut=None, r_on=0.0, mode='none')¶

DPD Conservative pair force.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).

DPDConservative specifies the conservative part of the DPD pair potential should be applied between every non-excluded particle pair in the simulation. No thermostat (e.g. Drag Force and Random Force) is applied, as is in DPD.

\begin{eqnarray*} V_{\mathrm{DPD-C}}(r) = & A \cdot \left( r_{\mathrm{cut}} - r \right) - \frac{1}{2} \cdot \frac{A}{r_{\mathrm{cut}}} \cdot \left(r_{\mathrm{cut}}^2 - r^2 \right) & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

DPDConservative does not implement and energy shift / smoothing modes due to the function of the force. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The potential parameters. The dictionary has the following keys:

A (float, required) - \(A\) (in force units)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
dpdc = pair.DPDConservative(nlist=nl, r_cut=3.0)
dpdc.params[('A', 'A')] = dict(A=1.0)
dpdc.params[('A', 'B')] = dict(A=2.0, r_cut = 1.0)
dpdc.params[(['A', 'B'], ['C', 'D'])] = dict(A=3.0)

class hoomd.md.pair.DPDLJ(nlist, kT, seed=3, r_cut=None, r_on=0.0, mode='none')¶

Dissipative Particle Dynamics with a LJ conservative force.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
kT (hoomd.variant or float) – Temperature of thermostat (in energy units).
seed (int) – seed for the PRNG in the DPD thermostat.
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).

DPDLJ specifies that a DPD thermostat and a Lennard-Jones pair potential should be applied between every non-excluded particle pair in the simulation.

C. L. Phillips et. al. 2011 describes the DPD implementation details in HOOMD-blue. Cite it if you utilize the DPD functionality in your work.

\begin{eqnarray*} F = F_{\mathrm{C}}(r) + F_{\mathrm{R,ij}}(r_{ij}) + F_{\mathrm{D,ij}}(v_{ij}) \\ \end{eqnarray*}

\begin{eqnarray*} F_{\mathrm{C}}(r) = & \partial V_{\mathrm{LJ}} / \partial r \\ F_{\mathrm{R, ij}}(r_{ij}) = & - \theta_{ij}\sqrt{3} \sqrt{\frac{2k_b\gamma T}{\Delta t}}\cdot w(r_{ij}) \\ F_{\mathrm{D, ij}}(r_{ij}) = & - \gamma w^2(r_{ij}) \left( \hat r_{ij} \circ v_{ij} \right) \\ \end{eqnarray*}

\begin{eqnarray*} V_{\mathrm{LJ}}(r) = & 4 \varepsilon \left[ \left( \frac{\sigma}{r} \right)^{12} - \alpha \left( \frac{\sigma}{r} \right)^{6} \right] & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

\begin{eqnarray*} w(r_{ij}) = &\left( 1 - r/r_{\mathrm{cut}} \right) & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

where \(\hat r_{ij}\) is a normalized vector from particle i to particle j, \(v_{ij} = v_i - v_j\), and \(\theta_{ij}\) is a uniformly distributed random number in the range [-1, 1].

Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

To use the DPD thermostat, an hoomd.md.methods.NVE integrator must be applied to the system and the user must specify a temperature. Use of the dpd thermostat pair force with other integrators will result in unphysical behavior.

params¶

The DPDLJ potential parameters. The dictionary has the following keys:

epsilon (float, required) - \(\varepsilon\) (in energy units)
sigma (float, required) - \(\sigma\) (in distance units)
alpha (float, optional, defaults to 1.0) - \(\alpha\) (unitless)
gamma (float, required) - \(\gamma\) (in units of force/velocity)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
dpdlj = pair.DPDLJ(nlist=nl, kT=1.0, seed=0, r_cut=2.5)
dpdlj.params[('A', 'A')] = dict(epsilon=1.0, sigma=1.0, gamma=4.5)
dpdlj.params[(['A', 'B'], ['C', 'D'])] = dict(epsilon=3.0, sigma=1.0, gamma=1.2)
dpdlj.r_cut[('B', 'B')] = 2.0**(1.0/6.0)

class hoomd.md.pair.Ewald(nlist, r_cut=None, r_on=0.0, mode='none')¶

Ewald pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – Energy shifting mode.

Ewald specifies that a Ewald pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{ewald}}(r) = & q_i q_j \left[\mathrm{erfc}\left(\kappa r + \frac{\alpha}{2\kappa}\right) \exp(\alpha r) \\ + \mathrm{erfc}\left(\kappa r - \frac{\alpha}{2 \kappa}\right) \exp(-\alpha r)\right] & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

The Ewald potential is designed to be used in conjunction with PPPM.

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use the params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The Ewald potential parameters. The dictionary has the following keys:

kappa (float, required) - Splitting parameter \(\kappa\) (in units of 1/distance)
alpha (float, required) - Debye screening length \(\alpha\) (in units of 1/distance)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
ewald = pair.Ewald(r_cut=3.0, nlist=nl)
ewald.params[('A', 'A')] = dict(kappa=1.0, alpha=1.5)
ewald.r_cut[('A', 'B')] = 3.0

class hoomd.md.pair.ForceShiftedLJ(nlist, r_cut=None, r_on=0.0, mode='none')¶

Force-shifted Lennard-Jones pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode.

ForceShiftedLJ specifies that a modified Lennard-Jones pair force should be applied between non-excluded particle pair in the simulation. The force differs from the one calculated by LJ by the subtraction of the value of the force at \(r_{\mathrm{cut}}\), such that the force smoothly goes to zero at the cut-off. The potential is modified by a linear function. This potential can be used as a substitute for LJ, when the exact analytical form of the latter is not required but a smaller cut-off radius is desired for computational efficiency. See Toxvaerd et. al. 2011 for a discussion of this potential.

\begin{eqnarray*} V(r) = & 4 \varepsilon \left[ \left( \frac{\sigma}{r} \right)^{12} - \alpha \left( \frac{\sigma}{r} \right)^{6} \right] + \Delta V(r) & r < r_{\mathrm{cut}}\\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

\[\Delta V(r) = -(r - r_{\mathrm{cut}}) \frac{\partial V_{\mathrm{LJ}}}{\partial r}(r_{\mathrm{cut}})\]

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The potential parameters. The dictionary has the following keys:

epsilon (float, required) - \(\varepsilon\) (in energy units)
sigma (float, required) - \(\sigma\) (in distance units)
alpha (float, optional, defaults to 1.0) - \(\alpha\) (unitless)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
fslj = pair.ForceShiftedLJ(nlist=nl, r_cut=1.5)
fslj.params[('A', 'A')] = dict(epsilon=1.0, sigma=1.0)

class hoomd.md.pair.Fourier(nlist, r_cut=None, r_on=0.0, mode='none')¶

Fourier pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – Energy shifting mode.

Fourier specifies that a Fourier pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{Fourier}}(r) = & \frac{1}{r^{12}} + \frac{1}{r^2}\sum_{n=1}^4 [a_n cos(\frac{n \pi r}{r_{cut}}) + b_n sin(\frac{n \pi r}{r_{cut}})] & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*} where: \begin{eqnarray*} a_1 = \sum_{n=2}^4 (-1)^n a_n \end{eqnarray*} \begin{eqnarray*} b_1 = \sum_{n=2}^4 n (-1)^n b_n \end{eqnarray*} is calculated to enforce close to zero value at r_cut.

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The Fourier potential parameters. The dictionary has the following keys:

a (float, required) - array of 3 values corresponding to a2, a3 and a4 in the Fourier series, unitless)
b (float, required) - array of 3 values corresponding to b2, b3 and b4 in the Fourier series, unitless)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
fourier = pair.Fourier(r_cut=3.0, nlist=nl)
fourier.params[('A', 'A')] = dict(a=[a2,a3,a4], b=[b2,b3,b4])

class hoomd.md.pair.Gauss(nlist, r_cut=None, r_on=0.0, mode='none')¶

Gaussian pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode.

Gauss specifies that a Gaussian pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{gauss}}(r) = & \varepsilon \exp \left[ -\frac{1}{2} \left( \frac{r}{\sigma} \right)^2 \right] & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The Gauss potential parameters. The dictionary has the following keys:

epsilon (float, required) - energy parameter \(\varepsilon\) (in energy units)
sigma (float, required) - particle size \(\sigma\) (in distance units)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
gauss = pair.Gauss(r_cut=3.0, nlist=nl)
gauss.params[('A', 'A')] = dict(epsilon=1.0, sigma=1.0)
gauss.r_cut[('A', 'B')] = 3.0

class hoomd.md.pair.LJ(nlist, r_cut=None, r_on=0.0, mode='none')¶

Lennard-Jones pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode

LJ specifies that a Lennard-Jones pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{LJ}}(r) = & 4 \varepsilon \left[ \left( \frac{\sigma}{r} \right)^{12} - \left( \frac{\sigma}{r} \right)^{6} \right] & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The LJ potential parameters. The dictionary has the following keys:

epsilon (float, required) - energy parameter \(\varepsilon\) (in energy units)
sigma (float, required) - particle size \(\sigma\) (in distance units)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
lj = pair.LJ(nl, r_cut=3.0)
lj.params[('A', 'A')] = {'sigma': 1.0, 'epsilon': 1.0}
lj.r_cut[('A', 'B')] = 3.0

class hoomd.md.pair.LJ1208(nlist, r_cut=None, r_on=0.0, mode='none')¶

Lennard-Jones 12-8 pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode

LJ1208 specifies that a Lennard-Jones 12-8 pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{LJ}}(r) = & 4 \varepsilon \left[ \left( \frac{\sigma}{r} \right)^{12} - \alpha \left( \frac{\sigma}{r} \right)^{8} \right] & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use the params dictionary to set potential coefficients.

params¶

The potential parameters. The dictionary has the following keys:

epsilon (float, required) - energy parameter \(\varepsilon\) (in energy units)
sigma (float, required) - particle size \(\sigma\) (in distance units)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
lj1208 = pair.LJ1208(nl, r_cut=3.0)
lj1208.params[('A', 'A')] = {'sigma': 1.0, 'epsilon': 1.0}
lj1208.params[('A', 'B')] = dict(epsilon=2.0, sigma=1.0)

class hoomd.md.pair.Mie(nlist, r_cut=None, r_on=0.0, mode='none')¶

Mie pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode.

Mie specifies that a Mie pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{mie}}(r) = & \left( \frac{n}{n-m} \right) {\left( \frac{n}{m} \right)}^{\frac{m}{n-m}} \varepsilon \left[ \left( \frac{\sigma}{r} \right)^{n} - \left( \frac{\sigma}{r} \right)^{m} \right] & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use the params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The potential parameters. The dictionary has the following keys:

epsilon (float, required) - \(\varepsilon\) (in units of energy)
sigma (float, required) - \(\sigma\) (in distance units)
n (float, required) - \(n\) (unitless)
m (float, required) - \(m\) (unitless)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
mie = pair.Mie(nlist=nl, r_cut=3.0)
mie.params[('A', 'A')] = dict(epsilon=1.0, sigma=1.0, n=12, m=6)
mie.r_cut[('A', 'A')] = 2**(1.0/6.0)
mie.r_on[('A', 'A')] = 2.0
mie.params[(['A', 'B'], ['C', 'D'])] = dict(epsilon=1.5, sigma=2.0)

class hoomd.md.pair.Moliere(nlist, r_cut=None, r_on=0.0, mode='none')¶

Moliere pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode.

Moliere specifies that a Moliere type pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{Moliere}}(r) = & \frac{Z_i Z_j e^2}{4 \pi \epsilon_0 r_{ij}} \left[ 0.35 \exp \left( -0.3 \frac{r_{ij}}{a_F} \right) + \\ 0.55 \exp \left( -1.2 \frac{r_{ij}}{a_F} \right) + 0.10 \exp \left( -6.0 \frac{r_{ij}}{a_F} \right) \right] & r < r_{\mathrm{cut}} \\ = & 0 & r > r_{\mathrm{cut}} \\ \end{eqnarray*}

Where each parameter is defined as:

\(Z_i\) - Z_i - Atomic number of species i (unitless)
\(Z_j\) - Z_j - Atomic number of species j (unitless)
\(e\) - elementary_charge - The elementary charge (in charge units)
\(a_F = \frac{0.8853 a_0}{\left( \sqrt{Z_i} + \sqrt{Z_j} \right)^{2/3}}\), where \(a_0\) is the Bohr radius (in distance units)

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The potential parameters. The dictionary has the following keys:

qi (float, required) - \(q_i = Z_i \frac{e}{\sqrt{4 \pi \epsilon_0}}\) (in charge units)
qj (float, required) - \(q_j = Z_j \frac{e}{\sqrt{4 \pi \epsilon_0}}\) (in charge units)
aF (float, required) - \(a_F = \frac{0.8853 a_0}{\left( \sqrt{Z_i} + \sqrt{Z_j} \right)^{2/3}}\)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
moliere = pair.Moliere(r_cut = 3.0, nlist=nl)

Zi = 54
Zj = 7
e = 1
a0 = 1
aF = 0.8853 * a0 / (np.sqrt(Zi) + np.sqrt(Zj))**(2/3)

moliere.params[('A', 'B')] = dict(qi=Zi*e, qj=Zj*e, aF=aF)

class hoomd.md.pair.Morse(nlist, r_cut=None, r_on=0.0, mode='none')¶

Morse pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode.

Morse specifies that a Morse pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{morse}}(r) = & D_0 \left[ \exp \left(-2\alpha\left( r-r_0\right)\right) -2\exp \left(-\alpha\left(r-r_0\right) \right) \right] & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The potential parameters. The dictionary has the following keys:

D0 (float, required) - depth of the potential at its minimum \(D_0\) (in energy units)
alpha (float, required) - the width of the potential well \(\alpha\) (in units of 1/distance)
r0 (float, required) - position of the minimum \(r_0\) (in distance units)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
morse = pair.Morse(r_cut=3.0, nlist=nl)
morse.params[('A', 'A')] = dict(D0=1.0, alpha=3.0, r0=1.0)
morse.r_cut[('A', 'B')] = 3.0

class hoomd.md.pair.Pair(nlist, r_cut=None, r_on=0.0, mode='none')¶

Common pair potential documentation.

Users should not invoke Pair directly. It is a base command that provides common features to all standard pair forces. Common documentation for all pair potentials is documented here.

All pair force commands specify that a given potential energy and force be computed on all non-excluded particle pairs in the system within a short range cutoff distance \(r_{\mathrm{cut}}\).

The force \(\vec{F}\) applied between each pair of particles is:

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

where \(\vec{r}\) is the vector pointing from one particle to the other in the pair, and \(V(r)\) is chosen by a mode switch (see set_params()):

\begin{eqnarray*} V(r) = & V_{\mathrm{pair}}(r) & \mathrm{mode\ is\ no\_shift} \\ = & V_{\mathrm{pair}}(r) - V_{\mathrm{pair}}(r_{\mathrm{cut}}) & \mathrm{mode\ is\ shift} \\ = & S(r) \cdot V_{\mathrm{pair}}(r) & \mathrm{mode\ is\ xplor\ and\ } r_{\mathrm{on}} < r_{\mathrm{cut}} \\ = & V_{\mathrm{pair}}(r) - V_{\mathrm{pair}}(r_{\mathrm{cut}}) & \mathrm{mode\ is\ xplor\ and\ } r_{\mathrm{on}} \ge r_{\mathrm{cut}} \end{eqnarray*}

\(S(r)\) is the XPLOR smoothing function:

\begin{eqnarray*} S(r) = & 1 & r < r_{\mathrm{on}} \\ = & \frac{(r_{\mathrm{cut}}^2 - r^2)^2 \cdot (r_{\mathrm{cut}}^2 + 2r^2 - 3r_{\mathrm{on}}^2)}{(r_{\mathrm{cut}}^2 - r_{\mathrm{on}}^2)^3} & r_{\mathrm{on}} \le r \le r_{\mathrm{cut}} \\ = & 0 & r > r_{\mathrm{cut}} \\ \end{eqnarray*}

and \(V_{\mathrm{pair}}(r)\) is the specific pair potential chosen by the respective command.

Enabling the XPLOR smoothing function \(S(r)\) results in both the potential energy and the force going smoothly to 0 at \(r = r_{\mathrm{cut}}\), reducing the rate of energy drift in long simulations. \(r_{\mathrm{on}}\) controls the point at which the smoothing starts, so it can be set to only slightly modify the tail of the potential. It is suggested that you plot your potentials with various values of \(r_{\mathrm{on}}\) in order to find a good balance between a smooth potential function and minimal modification of the original \(V_{\mathrm{pair}}(r)\). A good value for the LJ potential is \(r_{\mathrm{on}} = 2 \cdot \sigma\).

The split smoothing / shifting of the potential when the mode is xplor is designed for use in mixed WCA / LJ systems. The WCA potential and it’s first derivative already go smoothly to 0 at the cutoff, so there is no need to apply the smoothing function. In such mixed systems, set \(r_{\mathrm{on}}\) to a value greater than \(r_{\mathrm{cut}}\) for those pairs that interact via WCA in order to enable shifting of the WCA potential to 0 at the cutoff.

The following coefficients must be set per unique pair of particle types. See hoomd.md.pair for information on how to set coefficients.

r_cut¶

r_cut (in distance units), optional: defaults to the value r_cut specificied on construction

Type: TypeParameter [ tuple [particle_type, particle_type], float]

r_on¶

r_on (in distance units), optional: defaults to the value r_on specified on construction

Type: TypeParameter [ tuple [particle_type, particle_type], float]

compute_energy(tags1, tags2)¶

Compute the energy between two sets of particles.

Parameters

tags1 (ndarray<int32>) – a numpy array of particle tags in the first group
tags2 (ndarray<int32>) – a numpy array of particle tags in the second group

\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]

where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).

Assumed properties of the sets tags1 and tags2 are:

tags1 and tags2 are disjoint
all elements in tags1 and tags2 are unique
tags1 and tags2 are contiguous numpy arrays of dtype int32

None of these properties are validated.

Examples:

tags=numpy.linspace(0,N-1,1, dtype=numpy.int32)
# computes the energy between even and odd particles
U = mypair.compute_energy(tags1=numpy.array(tags[0:N:2]),
                          tags2=numpy.array(tags[1:N:2]))

class hoomd.md.pair.ReactionField(nlist, r_cut=None, r_on=0.0, mode='none')¶

Onsager reaction field pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode

ReactionField specifies that an Onsager reaction field pair potential should be applied between every non-excluded particle pair in the simulation.

Reaction field electrostatics is an approximation to the screened electrostatic interaction, which assumes that the medium can be treated as an electrostatic continuum of dielectric constant \(\epsilon_{RF}\) outside the cutoff sphere of radius \(r_{\mathrm{cut}}\). See: Barker et. al. 1973.

\[V_{\mathrm{RF}}(r) = \varepsilon \left[ \frac{1}{r} + \frac{(\epsilon_{RF}-1) r^2}{(2 \epsilon_{RF} + 1) r_c^3} \right]\]

By default, the reaction field potential does not require charge or diameter to be set. Two parameters, \(\varepsilon\) and \(\epsilon_{RF}\) are needed. If \(\epsilon_{RF}\) is specified as zero, it will represent infinity.

If use_charge is set to True, the following formula is evaluated instead:

\[V_{\mathrm{RF}}(r) = q_i q_j \varepsilon \left[ \frac{1}{r} + \frac{(\epsilon_{RF}-1) r^2}{(2 \epsilon_{RF} + 1) r_c^3} \right]\]

where \(q_i\) and \(q_j\) are the charges of the particle pair.

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use the params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The potential parameters. The dictionary has the following keys:

epsilon (float, required) - \(\varepsilon\) (in units of energy*distance)
eps_rf (float, required) - \(\epsilon_{RF}\) (dimensionless)
use_charge (Boolean Operations — and, or, not, optional) - evaluate pair potntial using particle charges (default: False)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
reaction_field = pair.reaction_field(nl, r_cut=3.0)
reaction_field.params[('A', 'B')] = dict(epsilon=1.0, eps_rf=1.0)
reaction_field.params[('B', 'B')] = dict(epsilon=1.0, eps_rf=0.0, use_charge=True)

class hoomd.md.pair.SLJ(nlist, r_cut=None, r_on=0.0, mode='none')¶

Shifted Lennard-Jones pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – Energy shifting/smoothing mode

SLJ specifies that a shifted Lennard-Jones type pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{SLJ}}(r) = & 4 \varepsilon \left[ \left( \frac{\sigma}{r - \Delta} \right)^{12} - \left( \frac{\sigma}{r - \Delta} \right)^{6} \right] & r < (r_{\mathrm{cut}} + \Delta) \\ = & 0 & r \ge (r_{\mathrm{cut}} + \Delta) \\ \end{eqnarray*}

where \(\Delta = (d_i + d_j)/2 - 1\) and \(d_i\) is the diameter of particle \(i\).

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

Attention

Due to the way that SLJ modifies the cutoff criteria, a shift_mode of xplor is not supported.

Set the max_diameter property of the neighbor list object to the largest particle diameter in the system (where diameter is a per-particle property of the same name in hoomd.State).

Warning

Failure to set max_diameter will result in missing pair interactions.

params¶

The potential parameters. The dictionary has the following keys:

epsilon (float, required) - energy parameter \(\varepsilon\) (in energy units)
sigma (float, required) - particle size \(\sigma\) (in distance units)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
nl.max_diameter = 2.0
slj = pair.SLJ(r_cut=3.0, nlist=nl)
slj.params[('A', 'B')] = dict(epsilon=2.0, r_cut=3.0)
slj.r_cut[('B', 'B')] = 2**(1.0/6.0)

class hoomd.md.pair.Yukawa(nlist, r_cut=None, r_on=0.0, mode='none')¶

Yukawa pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – Energy shifting mode.

Yukawa specifies that a Yukawa pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{yukawa}}(r) = & \varepsilon \frac{ \exp \left( -\kappa r \right) }{r} & r < r_{\mathrm{cut}} \\ = & 0 & r \ge r_{\mathrm{cut}} \\ \end{eqnarray*}

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients. The coefficients must be set per unique pair of particle types.

params¶

The Yukawa potential parameters. The dictionary has the following keys:

epsilon (float, required) - energy parameter \(\varepsilon\) (in energy units)
kappa (float, required) - scaling parameter \(\kappa\) (in units of 1/distance)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
yukawa = pair.Yukawa(r_cut=3.0, nlist=nl)
yukawa.params[('A', 'A')] = dict(epsilon=1.0, kappa=1.0)
yukawa.r_cut[('A', 'B')] = 3.0

class hoomd.md.pair.ZBL(nlist, r_cut=None, r_on=0.0, mode='none')¶

ZBL pair potential.

Parameters

nlist (hoomd.md.nlist.NList) – Neighbor list
r_cut (float) – Default cutoff radius (in distance units).
r_on (float) – Default turn-on radius (in distance units).
mode (str) – energy shifting/smoothing mode.

ZBL specifies that a Ziegler-Biersack-Littmark pair potential should be applied between every non-excluded particle pair in the simulation.

\begin{eqnarray*} V_{\mathrm{ZBL}}(r) = & \frac{Z_i Z_j e^2}{4 \pi \epsilon_0 r_{ij}} \left[ 0.1818 \exp \left( -3.2 \frac{r_{ij}}{a_F} \right) \\ + 0.5099 \exp \left( -0.9423 \frac{r_{ij}}{a_F} \right) \\ + 0.2802 \exp \left( -0.4029 \frac{r_{ij}}{a_F} \right) \\ + 0.02817 \exp \left( -0.2016 \frac{r_{ij}}{a_F} \right) \right], & r < r_{\mathrm{cut}} \\ = & 0, & r > r_{\mathrm{cut}} \\ \end{eqnarray*}

Where each parameter is defined as:

\(Z_i\) - Z_i - Atomic number of species i (unitless)
\(Z_j\) - Z_j - Atomic number of species j (unitless)
\(e\) - elementary_charge - The elementary charge (in charge units)
\(a_F = \frac{0.8853 a_0}{ Z_i^{0.23} + Z_j^{0.23} }\), where \(a_0\) is the Bohr radius (in distance units)

See Pair for details on how forces are calculated and the available energy shifting and smoothing modes. Use params dictionary to set potential coefficients.

params¶

The ZBL potential parameters. The dictionary has the following keys:

q_i (float, required) - \(q_i=Z_i \frac{e}{\sqrt{4 \pi \epsilon_0}}\) (in charge units)
q_j (float, required) - \(q_j=Z_j \frac{e}{\sqrt{4 \pi \epsilon_0}}\) (in charge units)
a_F (float, required) - \(a_F = \frac{0.8853 a_0}{ Z_i^{0.23} + Z_j^{0.23} }\)

Type: TypeParameter [ tuple [particle_type, particle_type], dict]

Example:

nl = nlist.Cell()
zbl = pair.ZBL(r_cut = 3.0, nlist=nl)

Zi = 54
Zj = 7
e = 1
a0 = 1
aF = 0.8853 * a0 / (Zi**(0.23) + Zj**(0.23))

zbl.params[('A', 'B')] = dict(qi=Zi*e, qj=Zj*e, aF=aF)