md.pair¶
Overview
md.pair.dipole 
Screened dipoledipole interactions. 
md.pair.dpd 
Dissipative Particle Dynamics. 
md.pair.dpdlj 
Dissipative Particle Dynamics with a LJ conservative force 
md.pair.dpd_conservative 
DPD Conservative pair force. 
md.pair.ewald 
Ewald pair potential. 
md.pair.force_shifted_lj 
Forceshifted LennardJones pair potential. 
md.pair.gauss 
Gaussian pair potential. 
md.pair.gb 
GayBerne anisotropic pair potential. 
md.pair.lj 
LennardJones pair potential. 
md.pair.mie 
Mie pair potential. 
md.pair.morse 
Morse pair potential. 
md.pair.moliere 
Moliere pair potential. 
md.pair.pair 
Common pair potential documentation. 
md.pair.reaction_field 
Onsager reaction field pair potential. 
md.pair.slj 
Shifted LennardJones pair potential. 
md.pair.table 
Tabulated pair potential. 
md.pair.tersoff 
Tersoff Potential. 
md.pair.yukawa 
Yukawa pair potential. 
md.pair.zbl 
ZBL pair potential. 
Details
Pair potentials.
Generally, pair forces are short range and are summed over all 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 this 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.
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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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


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 list  name (str) – Name of the force instance.
dipole
computes the (screened) interaction between pairs of particles with dipoles and electrostatic charges. The total energy computed is:\[ \begin{align}\begin{aligned}U_{dipole} = U_{dd} + U_{de} + U_{ee}\\U_{dd} = A e^{\kappa r} \left(\frac{\vec{\mu_i}\cdot\vec{\mu_j}}{r^3}  3\frac{(\vec{\mu_i}\cdot \vec{r_{ji}})(\vec{\mu_j}\cdot \vec{r_{ji}})}{r^5}\right)\\U_{de} = A e^{\kappa r} \left(\frac{(\vec{\mu_j}\cdot \vec{r_{ji}})q_i}{r^3}  \frac{(\vec{\mu_i}\cdot \vec{r_{ji}})q_j}{r^3}\right)\\U_{ee} = A e^{\kappa r} \frac{q_i q_j}{r}\end{aligned}\end{align} \]Use
pair_coeff.set
to set potential coefficients.dipole
does not implement and energy shift / smoothing modes due to the function of the force.The following coefficients must be set per unique pair of particle types:
 mu  magnitude of \(\vec{\mu} = \mu (1, 0, 0)\) in the particle local reference frame
 A  electrostatic energy scale \(A\) (default value 1.0)
 kappa  inverse screening length \(\kappa\)
Example:
# A/A interact only with screened electrostatics dipole.pair_coeff.set('A', 'A', mu=0.0, A=1.0, kappa=1.0) dipole.pair_coeff.set('A', 'B', mu=0.5, kappa=1.0)

compute_energy
(tags1, tags2)¶ Compute the energy between two sets of particles.
Parameters:  tags1 (
ndarray<int32>
) – a numpy array of particle tags in the first group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

class
hoomd.md.pair.
dpd
(r_cut, nlist, kT, seed, name=None)¶ Dissipative Particle Dynamics.
Parameters:  r_cut (float) – Default cutoff radius (in distance units).
 nlist (
hoomd.md.nlist
) – Neighbor list  kT (
hoomd.variant
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 cthe urrent 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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 list  name (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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

set_params
(coeff)¶ dpd_conservative
has no energy shift modes

class
hoomd.md.pair.
dpdlj
(r_cut, nlist, kT, seed, name=None)¶ Dissipative Particle Dynamics with a LJ conservative force
Parameters:  r_cut (float) – Default cutoff radius (in distance units).
 nlist (
hoomd.md.nlist
) – Neighbor list  kT (
hoomd.variant
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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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

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) & 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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 list  name (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 efficency. 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

set_params
(mode=None)¶ Set parameters controlling the way forces are computed.
Parameters: mode (str) – (if set) Set the mode with which potentials are handled at the cutoff. Valid values for mode are: “none” (the default), “shift”, and “xplor”:
 none  No shifting is performed and potentials are abruptly cut off
 shift  A constant shift is applied to the entire potential so that it is 0 at the cutoff
 xplor  A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.
See
pair
for the equations.Examples:
mypair.set_params(mode="shift") mypair.set_params(mode="no_shift") mypair.set_params(mode="xplor")

class
hoomd.md.pair.
gauss
(r_cut, nlist, name=None)¶ Gaussian pair potential.
Parameters:  r_cut (float) – Default cutoff radius (in distance units).
 nlist (
hoomd.md.nlist
) – Neighbor list  name (str) – Name of the force instance.
gauss
specifies that a Gaussian pair potential should be applied between every 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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 list  name (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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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

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 list  name (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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

set_params
(mode=None)¶ Set parameters controlling the way forces are computed.
Parameters: mode (str) – (if set) Set the mode with which potentials are handled at the cutoff. Valid values for mode are: “none” (the default), “shift”, and “xplor”:
 none  No shifting is performed and potentials are abruptly cut off
 shift  A constant shift is applied to the entire potential so that it is 0 at the cutoff
 xplor  A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.
See
pair
for the equations.Examples:
mypair.set_params(mode="shift") mypair.set_params(mode="no_shift") mypair.set_params(mode="xplor")

class
hoomd.md.pair.
mie
(r_cut, nlist, name=None)¶ Mie pair potential.
Parameters:  r_cut (float) – Default cutoff radius (in distance units).
 nlist (
hoomd.md.nlist
) – Neighbor list  name (str) – Name of the force instance.
mie
specifies that a Mie pair potential should be applied between every 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

set_params
(mode=None)¶ Set parameters controlling the way forces are computed.
Parameters: mode (str) – (if set) Set the mode with which potentials are handled at the cutoff. Valid values for mode are: “none” (the default), “shift”, and “xplor”:
 none  No shifting is performed and potentials are abruptly cut off
 shift  A constant shift is applied to the entire potential so that it is 0 at the cutoff
 xplor  A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.
See
pair
for the equations.Examples:
mypair.set_params(mode="shift") mypair.set_params(mode="no_shift") mypair.set_params(mode="xplor")

class
hoomd.md.pair.
moliere
(r_cut, nlist, name=None)¶ Moliere pair potential.
Parameters:  r_cut (float) – Default cutoff radius (in distance units).
 nlist (
hoomd.md.nlist
) – Neighbor list  name (str) – Name of the force instance.
moliere
specifies that a Moliere type pair potential should be applied between every 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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 cuttoff.The following coefficients must be set per unique pair of particle types. See
hoomd.md.pair
for information on how to set coefficients: \(r_{\mathrm{cut}}\)  r_cut (in distance units)  optional: defaults to the global r_cut specified in the pair command
 \(r_{\mathrm{on}}\)  r_on (in distance units)  optional: defaults to the global r_cut specified in the pair command
When \(r_{\mathrm{cut}} \le 0\) or is set to False, the particle type pair interaction is excluded from the neighbor list. This mechanism can be used in conjunction with multiple neighbor lists to make efficient calculations in systems with large size disparity. Functionally, this is equivalent to setting \(r_{\mathrm{cut}} = 0\) in the pair force because negative \(r_{\mathrm{cut}}\) has no physical meaning.

compute_energy
(tags1, tags2)¶ Compute the energy between two sets of particles.
Parameters:  tags1 (
ndarray<int32>
) – a numpy array of particle tags in the first group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

set_params
(mode=None)¶ Set parameters controlling the way forces are computed.
Parameters: mode (str) – (if set) Set the mode with which potentials are handled at the cutoff. Valid values for mode are: “none” (the default), “shift”, and “xplor”:
 none  No shifting is performed and potentials are abruptly cut off
 shift  A constant shift is applied to the entire potential so that it is 0 at the cutoff
 xplor  A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.
See
pair
for the equations.Examples:
mypair.set_params(mode="shift") mypair.set_params(mode="no_shift") mypair.set_params(mode="xplor")

class
hoomd.md.pair.
reaction_field
(r_cut, nlist, name=None)¶ Onsager reaction field pair potential.
Parameters:  r_cut (float) – Default cutoff radius (in distance units).
 nlist (
hoomd.md.nlist
) – Neighbor list  name (str) – Name of the force instance.
reaction_field
specifies that an Onsager reaction field pair potential should be applied between every 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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 list  name (str) – Name of the force instance.
 d_max (float) – Maximum diameter particles in the simulation will have (in distance units)
slj
specifies that a shifted 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'], espilon=2.0)

compute_energy
(tags1, tags2)¶ Compute the energy between two sets of particles.
Parameters:  tags1 (
ndarray<int32>
) – a numpy array of particle tags in the first group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

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.
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) table = pair.table(width=1000) 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)

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 list  name (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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

set_params
(mode=None)¶ Set parameters controlling the way forces are computed.
Parameters: mode (str) – (if set) Set the mode with which potentials are handled at the cutoff. Valid values for mode are: “none” (the default), “shift”, and “xplor”:
 none  No shifting is performed and potentials are abruptly cut off
 shift  A constant shift is applied to the entire potential so that it is 0 at the cutoff
 xplor  A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.
See
pair
for the equations.Examples:
mypair.set_params(mode="shift") mypair.set_params(mode="no_shift") mypair.set_params(mode="xplor")

class
hoomd.md.pair.
yukawa
(r_cut, nlist, name=None)¶ Yukawa pair potential.
Parameters:  r_cut (float) – Default cutoff radius (in distance units).
 nlist (
hoomd.md.nlist
) – Neighbor list  name (str) – Name of the force instance.
yukawa
specifies that a Yukawa pair potential should be applied between every 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)

set_params
(mode=None)¶ Set parameters controlling the way forces are computed.
Parameters: mode (str) – (if set) Set the mode with which potentials are handled at the cutoff. Valid values for mode are: “none” (the default), “shift”, and “xplor”:
 none  No shifting is performed and potentials are abruptly cut off
 shift  A constant shift is applied to the entire potential so that it is 0 at the cutoff
 xplor  A smoothing function is applied to gradually decrease both the force and potential to 0 at the cutoff when ron < rcut, and shifts the potential to 0 at the cutoff when ron >= rcut.
See
pair
for the equations.Examples:
mypair.set_params(mode="shift") mypair.set_params(mode="no_shift") mypair.set_params(mode="xplor")

class
hoomd.md.pair.
zbl
(r_cut, nlist, name=None)¶ ZBL pair potential.
Parameters:  r_cut (float) – Default cutoff radius (in distance units).
 nlist (
hoomd.md.nlist
) – Neighbor list  name (str) – Name of the force instance.
zbl
specifies that a 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 group  tags2 (
ndarray<int32>
) – a numpy array of particle tags in the second group
\[U = \sum_{i \in \mathrm{tags1}, j \in \mathrm{tags2}} V_{ij}(r)\]where \(V_{ij}(r)\) is the pairwise energy between two particles \(i\) and \(j\).
Assumed properties of the sets tags1 and tags2 are:
 tags1 and tags2 are disjoint
 all elements in tags1 and tags2 are unique
 tags1 and tags2 are contiguous numpy arrays of dtype int32
None of these properties are validated.
Examples:
tags=numpy.linspace(0,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]))
 tags1 (

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)