md.pair¶

Overview

`md.pair.buckingham`	Buckingham pair potential.
`md.pair.dipole`	Screened dipole-dipole interactions.
`md.pair.dpd`	Dissipative Particle Dynamics.
`md.pair.dpdlj`	Dissipative Particle Dynamics with a LJ conservative force
`md.pair.dpd_conservative`	DPD Conservative pair force.
`md.pair.ewald`	Ewald pair potential.
`md.pair.force_shifted_lj`	Force-shifted Lennard-Jones pair potential.
`md.pair.fourier`	Fourier pair potential.
`md.pair.gauss`	Gaussian pair potential.
`md.pair.gb`	Gay-Berne anisotropic pair potential.
`md.pair.lj`	Lennard-Jones pair potential.
`md.pair.lj1208`	Lennard-Jones 12-8 pair potential.
`md.pair.mie`	Mie pair potential.
`md.pair.morse`	Morse pair potential.
`md.pair.moliere`	Moliere pair potential.
`md.pair.pair`	Common pair potential documentation.
`md.pair.reaction_field`	Onsager reaction field pair potential.
`md.pair.slj`	Shifted Lennard-Jones pair potential.
`md.pair.square_density`	Soft potential for simulating a van-der-Waals liquid
`md.pair.table`	Tabulated pair potential.
`md.pair.tersoff`	Tersoff Potential.
`md.pair.yukawa`	Yukawa pair potential.
`md.pair.zbl`	ZBL pair potential.

Details

Pair potentials.

Generally, pair forces are short range and are summed over all non-bonded particles within a certain cutoff radius of each particle. Any number of pair forces can be defined in a single simulation. The net force on each particle due to all types of pair forces is summed.

Pair forces require that parameters be set for each unique type pair. Coefficients are set through the aid of the coeff class. To set these coefficients, specify a pair force and save it in a variable:

my_force = pair.some_pair_force(arguments...)

Then the coefficients can be set using the saved variable:

my_force.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
my_force.pair_coeff.set('A', 'B', epsilon=1.0, sigma=2.0)
my_force.pair_coeff.set('B', 'B', epsilon=2.0, sigma=1.0)

This example set the parameters epsilon and sigma (which are used in lj). Different pair forces require that different coefficients are set. Check the documentation of each to see the definition of the coefficients.

class hoomd.md.pair.DLVO(r_cut, nlist, d_max=None, name=None)¶

DLVO colloidal interaction

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

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.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 evaluates the forces for the pair potential .. math:

   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)

where math:`a_i` is the radius of particle :math:`i`, :math:`\Delta = (d_i + d_j)/2` and
:math:`d_i` is the diameter of particle :math:`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.

Use pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in units of energy*distance)
\(\kappa\) - kappa (in units of 1/distance)
\(r_{\mathrm{cut}}\) - r_cut (in units of distance) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\) - r_on (in units of distance) - optional: defaults to the global r_cut specified in the pair command

New in version 2.2.

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)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.ai_pair(r_cut, nlist, name=None)¶

Generic anisotropic pair potential.

Users should not instantiate ai_pair directly. It is a base class that provides common features to all anisotropic pair forces. Rather than repeating all of that documentation in a dozen different places, it is collected here.

All anisotropic pair potential commands specify that a given potential energy, force and torque be computed on all non-excluded particle pairs in the system within a short range cutoff distance \(r_{\mathrm{cut}}\). The interaction energy, forces and torque depend on the inter-particle separation \(\vec r\) and on the orientations \(\vec q_i\), \(q_j\), of the particles.

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff

valid values for mode are: “none” (the default) and “shift”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")

shape¶

Get or set shape parameters per type.

In addition to any pair-specific parameters required to characterize a pair potential, individual particles that have anisotropic interactions may also have their own shapes that affect the potentials. General anisotropic pair potentials may set per-particle shapes using this method.

class hoomd.md.pair.buckingham(r_cut, nlist, name=None)¶

Buckingham pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(A\) - A (in energy units)
\(\rho\) - rho (in distance units)
\(C\) - C (in energy * distance**6 units )
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

New in version 2.2.

Changed in version 2.2.

Example:

nl = nlist.cell()
buck = pair.buckingham(r_cut=3.0, nlist=nl)
buck.pair_coeff.set('A', 'A', A=1.0, rho=1.0, C=1.0)
buck.pair_coeff.set('A', 'B', A=2.0, rho=1.0, C=1.0, r_cut=3.0, r_on=2.0);
buck.pair_coeff.set('B', 'B', A=1.0, rho=1.0, C=1.0, r_cut=2**(1.0/6.0), r_on=2.0);
buck.pair_coeff.set(['A', 'B'], ['C', 'D'], A=1.5, rho=2.0, C=1.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.coeff¶

Define pair coefficients

All pair forces use coeff to specify the coefficients between different pairs of particles indexed by type. The set of pair coefficients is a symmetric matrix defined over all possible pairs of particle types.

There are two ways to set the coefficients for a particular pair force. The first way is to save the pair force in a variable and call set() directly.

The second method is to build the coeff class first and then assign it to the pair force. There are some advantages to this method in that you could specify a complicated set of pair coefficients in a separate python file and import it into your job script.

Example (force_field.py):

from hoomd import md
my_coeffs = md.pair.coeff();
my_force.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
my_force.pair_coeff.set('A', 'B', epsilon=1.0, sigma=2.0)
my_force.pair_coeff.set('B', 'B', epsilon=2.0, sigma=1.0)

Example job script:

from hoomd import md
import force_field

.....
my_force = md.pair.some_pair_force(arguments...)
my_force.pair_coeff = force_field.my_coeffs

set(a, b, **coeffs)¶

Sets parameters for one type pair.

Parameters:	a (str) – First particle type in the pair (or a list of type names) b (str) – Second particle type in the pair (or a list of type names) coeffs – Named coefficients (see below for examples)

Calling set() results in one or more parameters being set for a single type pair or set of type pairs. Particle types are identified by name, and parameters are also added by name. Which parameters you need to specify depends on the pair force you are setting these coefficients for, see the corresponding documentation.

All possible type pairs as defined in the simulation box must be specified before executing hoomd.run(). You will receive an error if you fail to do so. It is not an error, however, to specify coefficients for particle types that do not exist in the simulation. This can be useful in defining a force field for many different types of particles even when some simulations only include a subset.

There is no need to specify coefficients for both pairs ‘A’, ‘B’ and ‘B’, ‘A’. Specifying only one is sufficient.

To set the same coefficients between many particle types, provide a list of type names instead of a single one. All pairs between the two lists will be set to the same parameters.

Examples:

coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
coeff.set('B', 'B', epsilon=2.0, sigma=1.0)
coeff.set('A', 'B', epsilon=1.5, sigma=1.0)
coeff.set(['A', 'B', 'C', 'D'], 'F', epsilon=2.0)
coeff.set(['A', 'B', 'C', 'D'], ['A', 'B', 'C', 'D'], epsilon=1.0)

system = init.read_xml('init.xml')
coeff.set(system.particles.types, system.particles.types, epsilon=2.0)
coeff.set('A', system.particles.types, epsilon=1.2)

Note

Single parameters can be updated. If both epsilon and sigma have already been set for a type pair, then executing coeff.set('A', 'B', epsilon=1.1) will update the value of epsilon and leave sigma as it was previously set.

Some pair potentials assign default values to certain parameters. If the default setting for a given coefficient (as documented in the respective pair command) is not set explicitly, the default will be used.

class hoomd.md.pair.dipole(r_cut, nlist, name=None)¶

Screened dipole-dipole interactions.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

dipole computes the (screened) interaction between pairs of particles with dipoles and electrostatic charges. The total energy computed is:

\[ \begin{align}\begin{aligned}U_{dipole} = 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} \]

Use pair_coeff.set to set potential coefficients. dipole does not implement and energy shift / smoothing modes due to the function of the force.

The following coefficients must be set per unique pair of particle types:

mu - magnitude of \(\vec{\mu} = \mu (1, 0, 0)\) in the particle local reference frame
A - electrostatic energy scale \(A\) (default value 1.0)
kappa - inverse screening length \(\kappa\)

Example:

# A/A interact only with screened electrostatics
dipole.pair_coeff.set('A', 'A', mu=0.0, A=1.0, kappa=1.0)
dipole.pair_coeff.set('A', 'B', mu=0.5, kappa=1.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(*args, **kwargs)¶: dipole has no energy shift modes

shape¶

Get or set shape parameters per type.

In addition to any pair-specific parameters required to characterize a pair potential, individual particles that have anisotropic interactions may also have their own shapes that affect the potentials. General anisotropic pair potentials may set per-particle shapes using this method.

class hoomd.md.pair.dpd(r_cut, nlist, kT, seed, name=None)¶

Dissipative Particle Dynamics.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list kT (`hoomd.variant` or `float`) – Temperature of thermostat (in energy units). seed (int) – seed for the PRNG in the DPD thermostat. name (str) – Name of the force instance.

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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(A\) - A (in force units)
\(\gamma\) - gamma (in units of force/velocity)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command

To use the DPD thermostat, an hoomd.md.integrate.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}\).

Example:

nl = nlist.cell()
dpd = pair.dpd(r_cut=1.0, nlist=nl, kT=1.0, seed=0)
dpd.pair_coeff.set('A', 'A', A=25.0, gamma = 4.5)
dpd.pair_coeff.set('A', 'B', A=40.0, gamma = 4.5)
dpd.pair_coeff.set('B', 'B', A=25.0, gamma = 4.5)
dpd.pair_coeff.set(['A', 'B'], ['C', 'D'], A=12.0, gamma = 1.2)
dpd.set_params(kT = 1.0)
integrate.mode_standard(dt=0.02)
integrate.nve(group=group.all())

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(kT=None)¶

Changes parameters.

Parameters:	kT (`hoomd.variant` or `float`) – Temperature of thermostat (in energy units).

Example:

dpd.set_params(kT=2.0)

class hoomd.md.pair.dpd_conservative(r_cut, nlist, name=None)¶

DPD Conservative pair force.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

dpd_conservative 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*}

dpd_conservative does not implement and energy shift / smoothing modes due to the function of the force. Use pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(A\) - A (in force units)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
dpdc = pair.dpd_conservative(r_cut=3.0, nlist=nl)
dpdc.pair_coeff.set('A', 'A', A=1.0)
dpdc.pair_coeff.set('A', 'B', A=2.0, r_cut = 1.0)
dpdc.pair_coeff.set('B', 'B', A=1.0)
dpdc.pair_coeff.set(['A', 'B'], ['C', 'D'], A=5.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(coeff)¶: dpd_conservative has no energy shift modes

class hoomd.md.pair.dpdlj(r_cut, nlist, kT, seed, name=None)¶

Dissipative Particle Dynamics with a LJ conservative force

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list kT (`hoomd.variant` or `float`) – Temperature of thermostat (in energy units). seed (int) – seed for the PRNG in the DPD thermostat. name (str) – Name of the force instance.

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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\sigma\) - sigma (in distance units)
\(\alpha\) - alpha (unitless) - optional: defaults to 1.0
\(\gamma\) - gamma (in units of force/velocity)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command

To use the DPD thermostat, an hoomd.md.integrate.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.

Example:

nl = nlist.cell()
dpdlj = pair.dpdlj(r_cut=2.5, nlist=nl, kT=1.0, seed=0)
dpdlj.pair_coeff.set('A', 'A', epsilon=1.0, sigma = 1.0, gamma = 4.5)
dpdlj.pair_coeff.set('A', 'B', epsilon=0.0, sigma = 1.0 gamma = 4.5)
dpdlj.pair_coeff.set('B', 'B', epsilon=1.0, sigma = 1.0 gamma = 4.5, r_cut = 2.0**(1.0/6.0))
dpdlj.pair_coeff.set(['A', 'B'], ['C', 'D'], epsilon = 3.0,sigma=1.0, gamma = 1.2)
dpdlj.set_params(T = 1.0)
integrate.mode_standard(dt=0.005)
integrate.nve(group=group.all())

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(kT=None, mode=None)¶

Changes parameters.

Parameters:	T (`hoomd.variant` or `float`) – Temperature (if set) (in energy units) mode (str) – energy shift/smoothing mode (default noshift).

Examples:

dpdlj.set_params(kT=variant.linear_interp(points = [(0, 1.0), (1e5, 2.0)]))
dpdlj.set_params(kT=2.0, mode="shift")

class hoomd.md.pair.ewald(r_cut, nlist, name=None)¶

Ewald pair potential.

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 hoomd.md.charge.pppm.

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

The following coefficients must be set per unique pair of particle types:

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

New in version 2.1.
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
ewald = pair.ewald(r_cut=3.0, nlist=nl)
ewald.pair_coeff.set('A', 'A', kappa=1.0)
ewald.pair_coeff.set('A', 'A', kappa=1.0, alpha=1.5)
ewald.pair_coeff.set('A', 'B', kappa=1.0, r_cut=3.0, r_on=2.0);

Warning

DO NOT use in conjunction with hoomd.md.charge.pppm. It automatically creates and configures ewald for you.

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(coeff)¶: ewald has no energy shift modes

class hoomd.md.pair.force_shifted_lj(r_cut, nlist, name=None)¶

Force-shifted Lennard-Jones pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

force_shifted_lj 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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\sigma\) - sigma (in distance units)
\(\alpha\) - alpha (unitless) - optional: defaults to 1.0
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
fslj = pair.force_shifted_lj(r_cut=1.5, nlist=nl)
fslj.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.fourier(r_cut, nlist, name=None)¶

Fourier pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

fourier specifies that a fourier series form potential.

\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 cos(\frac{n \pi r}{r_{cut}}) \end{eqnarray*} \begin{eqnarray*} b_1 = \sum_{n=2}^4 n (-1)^n b_n cos(\frac{n \pi r}{r_{cut}}) \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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(a\) - a (array of 3 values corresponding to a2, a3 and a4 in the Fourier series, unitless)
\(a\) - b (array of 3 values corresponding to b2, b3 and b4 in the Fourier series, unitless)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
fourier = pair.fourier(r_cut=3.0, nlist=nl)
fourier.pair_coeff.set('A', 'A', a=[a2,a3,a4], b=[b2,b3,b4])

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.gauss(r_cut, nlist, name=None)¶

Gaussian pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\sigma\) - sigma (in distance units)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

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

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.gb(r_cut, nlist, name=None)¶

Gay-Berne anisotropic pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

gb computes the Gay-Berne potential between anisotropic particles.

This version of the Gay-Berne potential supports identical pairs of uniaxial ellipsoids, with orientation-independent energy-well depth.

The interaction energy for this anisotropic pair potential is (Allen et. al. 2006):

\begin{eqnarray*} V_{\mathrm{GB}}(\vec r, \vec e_i, \vec e_j) = & 4 \varepsilon \left[ \zeta^{-12} - \zeta^{-6} \right] & \zeta < \zeta_{\mathrm{cut}} \\ = & 0 & \zeta \ge \zeta_{\mathrm{cut}} \\ \end{eqnarray*}

\[ \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} \]

with \(\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.

Use pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\ell_\perp\) - lperp (in distance units)
\(\ell_\parallel\) - lpar (in distance units)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
gb = pair.gb(r_cut=2.5, nlist=nl)
gb.pair_coeff.set('A', 'A', epsilon=1.0, lperp=0.45, lpar=0.5)
gb.pair_coeff.set('A', 'B', epsilon=2.0, lperp=0.45, lpar=0.5, r_cut=2**(1.0/6.0));

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Example

>>> my_gb.get_type_shapes()
[{'type': 'Ellipsoid', 'a': 1.0, 'b': 1.0, 'c': 1.5}]

Returns:	A list of dictionaries, one for each particle type in the system.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff

valid values for mode are: “none” (the default) and “shift”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")

shape¶

Get or set shape parameters per type.

In addition to any pair-specific parameters required to characterize a pair potential, individual particles that have anisotropic interactions may also have their own shapes that affect the potentials. General anisotropic pair potentials may set per-particle shapes using this method.

class hoomd.md.pair.lj(r_cut, nlist, name=None)¶

Lennard-Jones pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

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} - \alpha \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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\sigma\) - sigma (in distance units)
\(\alpha\) - alpha (unitless) - optional: defaults to 1.0
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
lj = pair.lj(r_cut=3.0, nlist=nl)
lj.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
lj.pair_coeff.set('A', 'B', epsilon=2.0, sigma=1.0, alpha=0.5, r_cut=3.0, r_on=2.0);
lj.pair_coeff.set('B', 'B', epsilon=1.0, sigma=1.0, r_cut=2**(1.0/6.0), r_on=2.0);
lj.pair_coeff.set(['A', 'B'], ['C', 'D'], epsilon=1.5, sigma=2.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.lj1208(r_cut, nlist, name=None)¶

Lennard-Jones 12-8 pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

lj1208 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} - \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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\sigma\) - sigma (in distance units)
\(\alpha\) - alpha (unitless) - optional: defaults to 1.0
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

New in version 2.2.

Changed in version 2.2.

Example:

nl = nlist.cell()
lj1208 = pair.lj1208(r_cut=3.0, nlist=nl)
lj1208.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
lj1208.pair_coeff.set('A', 'B', epsilon=2.0, sigma=1.0, alpha=0.5, r_cut=3.0, r_on=2.0);
lj1208.pair_coeff.set('B', 'B', epsilon=1.0, sigma=1.0, r_cut=2**(1.0/6.0), r_on=2.0);
lj1208.pair_coeff.set(['A', 'B'], ['C', 'D'], epsilon=1.5, sigma=2.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.mie(r_cut, nlist, name=None)¶

Mie pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

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*}

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

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\sigma\) - sigma (in distance units)
\(n\) - n (unitless)
\(m\) - m (unitless)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
mie = pair.mie(r_cut=3.0, nlist=nl)
mie.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0, n=12, m=6)
mie.pair_coeff.set('A', 'B', epsilon=2.0, sigma=1.0, n=14, m=7, r_cut=3.0, r_on=2.0);
mie.pair_coeff.set('B', 'B', epsilon=1.0, sigma=1.0, n=15.1, m=6.5, r_cut=2**(1.0/6.0), r_on=2.0);
mie.pair_coeff.set(['A', 'B'], ['C', 'D'], epsilon=1.5, sigma=2.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.moliere(r_cut, nlist, name=None)¶

Moliere pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

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*}

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

The following coefficients must be set per unique pair of particle types:

\(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_0\) - a_0 - The Bohr radius (in distance units)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
moliere = pair.moliere(r_cut = 3.0, nlist=nl)
moliere.pair_coeff.set('A', 'B', Z_i = 54.0, Z_j = 7.0, elementary_charge = 1.0, a_0 = 1.0);

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.morse(r_cut, nlist, name=None)¶

Morse pair potential.

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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(D_0\) - D0, depth of the potential at its minimum (in energy units)
\(\alpha\) - alpha, controls the width of the potential well (in units of 1/distance)
\(r_0\) - r0, position of the minimum (in distance units)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
morse = pair.morse(r_cut=3.0, nlist=nl)
morse.pair_coeff.set('A', 'A', D0=1.0, alpha=3.0, r0=1.0)
morse.pair_coeff.set('A', 'B', D0=1.0, alpha=3.0, r0=1.0, r_cut=3.0, r_on=2.0);
morse.pair_coeff.set(['A', 'B'], ['C', 'D'], D0=1.0, alpha=3.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.pair(r_cut, nlist, name=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_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\) - r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

When \(r_{\mathrm{cut}} \le 0\) or is set to False, the particle type pair interaction is excluded from the neighbor list. This mechanism can be used in conjunction with multiple neighbor lists to make efficient calculations in systems with large size disparity. Functionally, this is equivalent to setting \(r_{\mathrm{cut}} = 0\) in the pair force because negative \(r_{\mathrm{cut}}\) has no physical meaning.

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.reaction_field(r_cut, nlist, name=None)¶

Onsager reaction field pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

reaction_field 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: .. math:

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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in units of energy*distance)
\(\epsilon_{RF}\) - eps_rf (dimensionless)
\(r_{\mathrm{cut}}\) - r_cut (in units of distance) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\) - r_on (in units of distance) - optional: defaults to the global r_cut specified in the pair command
use_charge (boolean), evaluate potential using particle charges - optional: defaults to False

New in version 2.1.

Example:

nl = nlist.cell()
reaction_field = pair.reaction_field(r_cut=3.0, nlist=nl)
reaction_field.pair_coeff.set('A', 'A', epsilon=1.0, eps_rf=1.0)
reaction_field.pair_coeff.set('A', 'B', epsilon=-1.0, eps_rf=0.0)
reaction_field.pair_coeff.set('B', 'B', epsilon=1.0, eps_rf=0.0)
reaction_field.pair_coeff.set(system.particles.types, system.particles.types, epsilon=1.0, eps_rf=0.0, use_charge=True)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.slj(r_cut, nlist, d_max=None, name=None)¶

Shifted Lennard-Jones pair potential.

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

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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\sigma\) - sigma (in distance units) - optional: defaults to 1.0
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command

Attention

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

The actual cutoff radius for pair.slj is shifted by the diameter of two particles interacting. Thus to determine the maximum possible actual r_cut in simulation pair.slj must know the maximum diameter of all the particles over the entire run, d_max . This value is either determined automatically from the initialization or can be set by the user and can be modified between runs with hoomd.md.nlist.nlist.set_params(). In most cases, the correct value can be identified automatically.

The specified value of d_max will be used to properly determine the neighbor lists during the following hoomd.run() commands. If not specified, slj will set d_max to the largest diameter in particle data at the time it is initialized.

If particle diameters change after initialization, it is imperative that d_max be the largest diameter that any particle will attain at any time during the following hoomd.run() commands. If d_max is smaller than it should be, some particles will effectively have a smaller value of r_cut then was set and the simulation will be incorrect. d_max can be changed between runs by calling hoomd.md.nlist.nlist.set_params().

Example:

nl = nlist.cell()
slj = pair.slj(r_cut=3.0, nlist=nl, d_max = 2.0)
slj.pair_coeff.set('A', 'A', epsilon=1.0)
slj.pair_coeff.set('A', 'B', epsilon=2.0, r_cut=3.0);
slj.pair_coeff.set('B', 'B', epsilon=1.0, r_cut=2**(1.0/6.0));
slj.pair_coeff.set(['A', 'B'], ['C', 'D'], epsilon=2.0)

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

See pair.set_params().

Note

xplor is not a valid setting for slj.

class hoomd.md.pair.square_density(r_cut, nlist, name=None)¶

Soft potential for simulating a van-der-Waals liquid

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

square_density specifies that the three-body potential should be applied to every non-bonded particle pair in the simulation, that is harmonic in the local density.

The self energy per particle takes the form

\[\Psi^{ex} = B (\rho - A)^2\]

which gives a pair-wise additive, three-body force

\[\vec{f}_{ij} = \left( B (n_i - A) + B (n_j - A) \right) w'_{ij} \vec{e}_{ij}\]

Here, \(w_{ij}\) is a quadratic, normalized weighting function,

\[w(x) = \frac{15}{2 \pi r_{c,\mathrm{weight}}^3} (1-r/r_{c,\mathrm{weight}})^2\]

The local density at the location of particle i is defined as

\[n_i = \sum\limits_{j\neq i} w_{ij}\left(\big| \vec r_i - \vec r_j \big|\right)\]

The following coefficients must be set per unique pair of particle types:

\(A\) - A (in units of volume^-1) - mean density (default: 0)
\(B\) - B (in units of energy*volume^2) - coefficient of the harmonic density term

Example:

nl = nlist.cell()
sqd = pair.van_der_waals(r_cut=3.0, nlist=nl)
sqd.pair_coeff.set('A', 'A', A=0.1)
sqd.pair_coeff.set('A', 'A', B=1.0)

For further details regarding this multibody potential, see

Warning

Currently HOOMD does not support reverse force communication between MPI domains on the GPU. Since reverse force communication is required for the calculation of multi-body potentials, attempting to use the square_density potential on the GPU with MPI will result in an error.

[1] P. B. Warren, “Vapor-liquid coexistence in many-body dissipative particle dynamics” Phys. Rev. E. Stat. Nonlin. Soft Matter Phys., vol. 68, no. 6 Pt 2, p. 066702, 2003.

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.table(width, nlist, name=None)¶

Tabulated pair potential.

Parameters:	width (int) – Number of points to use to interpolate V and F. nlist (`hoomd.md.nlist`) – Neighbor list (default of None automatically creates a global cell-list based neighbor list) name (str) – Name of the force instance

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

The force \(\vec{F}\) is (in force units):

\begin{eqnarray*} \vec{F}(\vec{r}) = & 0 & r < r_{\mathrm{min}} \\ = & F_{\mathrm{user}}(r)\hat{r} & r_{\mathrm{min}} \le r < r_{\mathrm{max}} \\ = & 0 & r \ge r_{\mathrm{max}} \\ \end{eqnarray*}

and the potential \(V(r)\) is (in energy units)

\begin{eqnarray*} V(r) = & 0 & r < r_{\mathrm{min}} \\ = & V_{\mathrm{user}}(r) & r_{\mathrm{min}} \le r < r_{\mathrm{max}} \\ = & 0 & r \ge r_{\mathrm{max}} \\ \end{eqnarray*}

where \(\vec{r}\) is the vector pointing from one particle to the other in the pair.

\(F_{\mathrm{user}}(r)\) and \(V_{\mathrm{user}}(r)\) are evaluated on width grid points between \(r_{\mathrm{min}}\) and \(r_{\mathrm{max}}\). Values are interpolated linearly between grid points. For correctness, you must specify the force defined by: \(F = -\frac{\partial V}{\partial r}\).

The following coefficients must be set per unique pair of particle types:

\(V_{\mathrm{user}}(r)\) and \(F_{\mathrm{user}}(r)\) - evaluated by func (see example)
coefficients passed to func - coeff (see example)
\(_{\mathrm{min}}\) - rmin (in distance units)
\(_{\mathrm{max}}\) - rmax (in distance units)

Set table from a given function

When you have a functional form for V and F, you can enter that directly into python. table will evaluate the given function over width points between rmin and rmax and use the resulting values in the table:

def lj(r, rmin, rmax, epsilon, sigma):
    V = 4 * epsilon * ( (sigma / r)**12 - (sigma / r)**6);
    F = 4 * epsilon / r * ( 12 * (sigma / r)**12 - 6 * (sigma / r)**6);
    return (V, F)

nl = nlist.cell()
table = pair.table(width=1000, nlist=nl)
table.pair_coeff.set('A', 'A', func=lj, rmin=0.8, rmax=3.0, coeff=dict(epsilon=1.5, sigma=1.0))
table.pair_coeff.set('A', 'B', func=lj, rmin=0.8, rmax=3.0, coeff=dict(epsilon=2.0, sigma=1.2))
table.pair_coeff.set('B', 'B', func=lj, rmin=0.8, rmax=3.0, coeff=dict(epsilon=0.5, sigma=1.0))

Set a table from a file

When you have no function for for V or F, or you otherwise have the data listed in a file, table can use the given values directly. You must first specify the number of rows in your tables when initializing pair.table. Then use set_from_file() to read the file:

nl = nlist.cell()
table = pair.table(width=1000, nlist=nl)
table.set_from_file('A', 'A', filename='table_AA.dat')
table.set_from_file('A', 'B', filename='table_AB.dat')
table.set_from_file('B', 'B', filename='table_BB.dat')

Note

For potentials that diverge near r=0, make sure to set rmin to a reasonable value. If a potential does not diverge near r=0, then a setting of rmin=0 is valid.

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)

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)

set_from_file(a, b, filename)¶

Set a pair interaction from a file.

Parameters:	a (str) – Name of type A in pair b (str) – Name of type B in pair filename (str) – Name of the file to read

The provided file specifies V and F at equally spaced r values.

Example:

#r  V    F
0 2.0 -3.0
1 3.0 -4.0
2 2.0 -3.0
3 1.0 -2.0
4 0.0 -1.0
5 -1.0 0.0

The first r value sets rmin, the last sets rmax. Any line with # as the first non-whitespace character is is treated as a comment. The r values must monotonically increase and be equally spaced. The table is read directly into the grid points used to evaluate \(F_{\mathrm{user}}(r)\) and \(_{\mathrm{user}}(r)\).

class hoomd.md.pair.tersoff(r_cut, nlist, name=None)¶

Tersoff Potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

tersoff specifies that the Tersoff three-body potential should be applied to every non-bonded particle pair in the simulation. Despite the fact that the Tersoff potential accounts for the effects of third bodies, it is included in the pair potentials because the species of the third body is irrelevant. It can thus use type-pair parameters similar to those of the pair potentials.

The Tersoff potential is a bond-order potential based on the Morse potential that accounts for the weakening of individual bonds with increasing coordination number. It does this by computing a modifier to the attractive term of the potential. The modifier contains the effects of third-bodies on the bond energies. The potential also includes a smoothing function around the cutoff. The smoothing function used in this work is exponential in nature as opposed to the sinusoid used by Tersoff. The exponential function provides continuity up (I believe) the second derivative.

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.yukawa(r_cut, nlist, name=None)¶

Yukawa pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

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 pair_coeff.set to set potential coefficients.

The following coefficients must be set per unique pair of particle types:

\(\varepsilon\) - epsilon (in energy units)
\(\kappa\) - kappa (in units of 1/distance)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

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

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(mode=None)¶

Set parameters controlling the way forces are computed.

Parameters:	mode (str) – (if set) Set the mode with which potentials are handled at the cutoff.

Valid values for mode are: “none” (the default), “shift”, and “xplor”:

none - No shifting is performed and potentials are abruptly cut off
shift - A constant shift is applied to the entire potential so that it is 0 at the cutoff
xplor - A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.

See pair for the equations.

Examples:

mypair.set_params(mode="shift")
mypair.set_params(mode="no_shift")
mypair.set_params(mode="xplor")

class hoomd.md.pair.zbl(r_cut, nlist, name=None)¶

ZBL pair potential.

Parameters:	r_cut (float) – Default cutoff radius (in distance units). nlist (`hoomd.md.nlist`) – Neighbor list name (str) – Name of the force instance.

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*}

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

The following coefficients must be set per unique pair of particle types:

\(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_0\) - a_0 - The Bohr radius (in distance units)
\(r_{\mathrm{cut}}\) - r_cut (in distance units) - optional: defaults to the global r_cut specified in the pair command
\(r_{\mathrm{on}}\)- r_on (in distance units) - optional: defaults to the global r_cut specified in the pair command

Example:

nl = nlist.cell()
zbl = pair.zbl(r_cut = 3.0, nlist=nl)
zbl.pair_coeff.set('A', 'B', Z_i = 54.0, Z_j = 7.0, elementary_charge = 1.0, a_0 = 1.0);

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]))

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)

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)

get_type_shapes()¶

Get all the types of shapes in the current simulation.

Since this behaves differently for different types of shapes, the default behavior just raises an exception. Subclasses can override this to properly return.

set_params(coeff)¶: zbl has no energy shift modes