md.pair¶
Overview
Buckingham pair potential. 

Screened dipoledipole interactions. 

Dissipative Particle Dynamics. 

Dissipative Particle Dynamics with a LJ conservative force 

DPD Conservative pair force. 

Ewald pair potential. 

Forceshifted LennardJones pair potential. 

Fourier pair potential. 

Gaussian pair potential. 

GayBerne anisotropic pair potential. 

LennardJones pair potential. 

LennardJones 128 pair potential. 

Mie pair potential. 

Morse pair potential. 

Moliere pair potential. 

Common pair potential documentation. 

Onsager reaction field pair potential. 

Reversible crosslinker threebody potential to model bond swaps. 

Shifted LennardJones pair potential. 

Soft potential for simulating a vanderWaals liquid 

Tabulated pair potential. 

Tersoff Potential. 

Yukawa pair potential. 

ZBL pair potential. 
Details
Pair potentials.
Generally, pair forces are short range and are summed over all nonbonded 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 nonexcluded particle pair in the simulation. Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (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_1a_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 doublelayer 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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 nonexcluded particle pairs in the system within a short range cutoff distance \(r_{\mathrm{cut}}\). The interaction energy, forces and torque depend on the interparticle 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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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

property
shape
¶ Get or set shape parameters per type.
In addition to any pairspecific 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 perparticle 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 listname (str) – Name of the force instance.
buckingham
specifies that a Buckingham pair potential should be applied between every nonexcluded 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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
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 dipoledipole interactions.
 Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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.

property
shape
¶ Get or set shape parameters per type.
In addition to any pairspecific 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 perparticle 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 listkT (
hoomd.variant
orfloat
) – 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 nonexcluded 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 HOOMDblue. 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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
orfloat
) – 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 listname (str) – Name of the force instance.
dpd_conservative
specifies the conservative part of the DPD pair potential should be applied between every nonexcluded particle pair in the simulation. No thermostat (e.g. Drag Force and Random Force) is applied, as is indpd
.\begin{eqnarray*} V_{\mathrm{DPDC}}(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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 listkT (
hoomd.variant
orfloat
) – 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 LennardJones pair potential should be applied between every nonexcluded particle pair in the simulation.C. L. Phillips et. al. 2011 describes the DPD implementation details in HOOMDblue. 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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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
orfloat
) – 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 nonexcluded 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. Usepair_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 configuresewald
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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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.

class
hoomd.md.pair.
force_shifted_lj
(r_cut, nlist, name=None)¶ Forceshifted LennardJones pair potential.
 Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (str) – Name of the force instance.
force_shifted_lj
specifies that a modified LennardJones pair force should be applied between nonexcluded particle pair in the simulation. The force differs from the one calculated bylj
by the subtraction of the value of the force at \(r_{\mathrm{cut}}\), such that the force smoothly goes to zero at the cutoff. The potential is modified by a linear function. This potential can be used as a substitute forlj
, when the exact analytical form of the latter is not required but a smaller cutoff 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 listname (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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 listname (str) – Name of the force instance.
gauss
specifies that a Gaussian pair potential should be applied between every nonexcluded 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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)¶ GayBerne anisotropic pair potential.
 Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (str) – Name of the force instance.
gb
computes the GayBerne potential between anisotropic particles.This version of the GayBerne potential supports identical pairs of uniaxial ellipsoids, with orientationindependent energywell 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 cutoff 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 semiaxis 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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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

property
shape
¶ Get or set shape parameters per type.
In addition to any pairspecific 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 perparticle shapes using this method.

class
hoomd.md.pair.
lj
(r_cut, nlist, name=None)¶ LennardJones pair potential.
 Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (str) – Name of the force instance.
lj
specifies that a LennardJones pair potential should be applied between every nonexcluded 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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)¶ LennardJones 128 pair potential.
 Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (str) – Name of the force instance.
lj1208
specifies that a LennardJones pair potential should be applied between every nonexcluded 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 listname (str) – Name of the force instance.
mie
specifies that a Mie pair potential should be applied between every nonexcluded particle pair in the simulation.\begin{eqnarray*} V_{\mathrm{mie}}(r) = & \left( \frac{n}{nm} \right) {\left( \frac{n}{m} \right)}^{\frac{m}{nm}} \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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 listname (str) – Name of the force instance.
moliere
specifies that a Moliere type pair potential should be applied between every nonexcluded 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 nonexcluded particle pair in the simulation.\begin{eqnarray*} V_{\mathrm{morse}}(r) = & D_0 \left[ \exp \left(2\alpha\left(rr_0\right)\right) 2\exp \left(\alpha\left(rr_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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 nonexcluded 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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 listname (str) – Name of the force instance.
reaction_field
specifies that an Onsager reaction field pair potential should be applied between every nonexcluded 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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.
revcross
(r_cut, nlist, name=None)¶ Reversible crosslinker threebody potential to model bond swaps.
 Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (str) – Name of the force instance.
revcross
specifies that the revcross threebody potential should be applied to every nonbonded particle pair in the simulation. Despite the fact that the revcross potential accounts for the effects of third bodies, it is included in the pair potentials because its is actually just a combination of two body potential terms. It can thus use typepair parameters similar to those of the pair potentials.The revcross potential has been described in detail in S. Ciarella and W.G. Ellenbroek 2019. It is based on a generalizedLennardJones pairwise attraction to form bonds between interacting particless:
\begin{eqnarray*} V_{ij}(r) = 4 \varepsilon \left[ \left( \dfrac{ \sigma}{r_{ij}} \right) ^{2n} \left( \dfrac{ \sigma}{r_{ij}} \right)^{n} \right] \qquad r<r_{cut} \end{eqnarray*}with the following coefficients:
\(\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
Then an additional threebody repulsion is evaluated to compensate the bond energies imposing single bond per particle condition:
\begin{eqnarray*} v^{\left( 3b \right)}_{ijk}=\lambda \epsilon\,\hat{v}^{ \left( 2b \right)}_{ij}\left(\vec{r}_{ij}\right) \cdot \hat{v}^{ \left( 2b \right)}_{ik}\left(\vec{r}_{ik}\right)~,\\ \end{eqnarray*}where the two body potential is rewritten as:
\begin{eqnarray*} \hat{v}^{ \left( 2b \right)}_{ij}\left(\vec{r}_{ij}\right) = \begin{cases} & 1 \qquad \qquad \; \; \qquad r\le r_{min}\\ &  \dfrac{v_{ij}\left(\vec{r}_{ij}\right)}{\epsilon} \qquad r > r_{min}~.\\ \end{cases} \end{eqnarray*}Attention
The revcross potential models an asymmetric interaction between two different chemical moieties that can form a reversible bond. This requires the definition of (at least) two different types of particles. A reversible bond is only possible between two different species, otherwise \(v^{\left( 3b \right)}_{ijk}\), would prevent any bond. In our example we then set the interactions for types A and B with
potRevC.pair_coeff.set(['A','B'],['A','B'],sigma=0.0,n=0,epsilon=0,lambda3=0)
and the only nonzero energy only between the different typespotRevC.pair_coeff.set('A','B',sigma=1,n=100,epsilon=100,lambda3=1)
. Notice that the number of the minoritary species corresponds to the maximum number of bonds.This threebody term also tunes the energy required for a bond swap through the coefficient:  \(\lambda\)  lambda3 (unitless) in S. Ciarella and W.G. Ellenbroek 2019 is explained that setting \(\lambda=1\) corresponds to no energy requirement to initiate bond swap, while this energy barrier scales roughly as \(\beta \Delta E_\text{sw} =\beta \varepsilon(\lambda1)\).
Note
Choosing \(\lambda=1\) pushes the system towards clusterization because the threebody term is not enough to compensate the energy of multiple bonds, so it may cause unphysical situations.
Example:
nl = md.nlist.cell() potBondSwap = md.pair.revcross(r_cut=1.3,nlist=nl) potBondSwap.pair_coeff.set(['A','B'],['A','B'],sigma=0,n=0,epsilon=0,lambda3=0) # a bond can be made only between AB and not AA or BB potBondSwap.pair_coeff.set('A','B',sigma=1,n=100,epsilon=10,lambda3=1)

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

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 LennardJones pair potential.
 Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (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 LennardJones type pair potential should be applied between every nonexcluded 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. Usepair_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 callinghoomd.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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 vanderWaals liquid
 Parameters
r_cut (float) – Default cutoff radius (in distance units).
nlist (
hoomd.md.nlist
) – Neighbor listname (str) – Name of the force instance.
square_density
specifies that the threebody potential should be applied to every nonbonded 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 pairwise additive, threebody 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} (1r/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 multibody potentials, attempting to use the square_density potential on the GPU with MPI will result in an error.
[1] P. B. Warren, “Vaporliquid coexistence in manybody 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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 celllist based neighbor list)name (str) – Name of the force instance
table
specifies that a tabulated pair potential should be applied between every nonexcluded 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 useset_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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

set_from_file
(a, b, filename)¶ Set a pair interaction from a file.
 Parameters
The provided file specifies V and F at equally spaced r values.
Example:
#r V F 1.0 2.0 3.0 1.1 3.0 4.0 1.2 2.0 3.0 1.3 1.0 2.0 1.4 0.0 1.0 1.5 1.0 0.0
The first r value sets rmin, the last sets rmax. Any line with # as the first nonwhitespace 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 listname (str) – Name of the force instance.
tersoff
specifies that the Tersoff threebody potential should be applied to every nonbonded 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 typepair parameters similar to those of the pair potentials.The Tersoff potential is a bondorder 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 thirdbodies 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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 listname (str) – Name of the force instance.
yukawa
specifies that a Yukawa pair potential should be applied between every nonexcluded 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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 listname (str) – Name of the force instance.
zbl
specifies that a ZieglerBiersackLittmark pair potential should be applied between every nonexcluded 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. Usepair_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 grouptags2 (
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,N1,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 reenabled withenable()
.By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

get_energy
(group)¶ Get the energy of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the energy for. Returns
The last computed energy for the members in the group.
Examples:
g = group.all() energy = force.get_energy(g)

get_net_force
(group)¶ Get the force of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the force for. Returns
The last computed force for the members in the group.
Examples
g = group.all() force = force.get_net_force(g)

get_net_virial
(group)¶ Get the virial of a particle group.
 Parameters
group (
hoomd.group
) – The particle group to query the virial for. Returns
The last computed virial for the members in the group.
Examples
g = group.all() virial = force.get_net_virial(g)

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.