md.special_pair

Overview

md.special_pair.lj LJ special pair potential.
md.special_pair.coulomb Coulomb special pair potential.

Details

Potentials between special pairs of particles

Special pairs are used to implement interactions between designated pairs of particles. They act much like bonds, except that the interaction potential is typically a pair potential, such as LJ.

By themselves, special pairs that have been specified in an initial configuration do nothing. Only when you specify an force (i.e. special_pairs.lj), are forces actually calculated between the listed particles.

class hoomd.md.special_pair.coeff

Define special_pair coefficients.

The coefficients for all special pair potentials are specified using this class. Coefficients are specified per pair type.

There are two ways to set the coefficients for a particular special_pair potential. The first way is to save the special_pair potential in a variable and call set() directly. See below for an example of this.

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

Example:

my_coeffs = hoomd.md.special_pair.coeff();
special_pair_force.pair_coeff.set('pairtype1', epsilon=1, sigma=1)
special_pair_force.pair_coeff.set('backbone', epsilon=1.2, sigma=1)
set(type, **coeffs)

Sets parameters for special_pair types.

Parameters:
  • type (str) – Type of special_pair (or a list of type names)
  • coeffs – Named coefficients (see below for examples)

Calling set() results in one or more parameters being set for a special_pair type. Types are identified by name, and parameters are also added by name. Which parameters you need to specify depends on the special_pair potential you are setting these coefficients for, see the corresponding documentation.

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

Examples:

my_special_pair_force.special_pair_coeff.set('pair1', epsilon=1, sigma=1)
my_special_pair_force.pair_coeff.set('pair2', epsilon=0.5, sigma=0.7)
my_special_pair_force.pair_coeff.set(['special_pairA','special_pairB'], epsilon=0, sigma=1)

Note

Single parameters can be updated. If both k and r0 have already been set for a particle type, then executing coeff.set('polymer', r0=1.0) will update the value of r0 and leave the other parameters as they were previously set.

class hoomd.md.special_pair.coulomb(name=None)

Coulomb special pair potential.

Parameters:name (str) – Name of the special_pair instance.

coulomb specifies a Coulomb potential energy between the two particles in each defined pair.

This is useful for implementing e.g. special 1-4 interactions in all-atom force fields. It uses a standard Coulomb interaction with a scaling parameter. This allows for using this for scaled 1-4 interactions like in OPLS where both the 1-4 LJ and Coulomb interactions are scaled by 0.5.

\begin{eqnarray*} V_{\mathrm{Coulomb}}(r) = & \alpha \cdot \left[ \frac{q_{a}q_{b}}{r} \right] & 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 bond.

Coefficients:

  • \(\alpha\) - Coulomb scaling factor (defaults to 1.0)
  • \(q_{a}\) - charge of particle a (in hoomd charge units)
  • \(q_{b}\) - charge of particle b (in hoomd charge units)
  • \(r_{\mathrm{cut}}\) - r_cut (in distance units)

Example:

coul = special_pair.coulomb(name="myOPLS_style")
coul.pair_coeff.set('pairtype_1', alpha=0.5, r_cut=1.1)

Note

The energy of special pair interactions is reported in a log quantity special_pair_coul_energy, which is separate from those of other non-bonded interactions. Therefore, the total energy of non-bonded interactions is obtained by adding that of standard and special interactions.

New in version 2.2.

Changed in version 2.2.

disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

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

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
get_net_force(group)

Get the force of a particle group.

Parameters:group (hoomd.group) – The particle group to query the force for.
Returns:The last computed force for the members in the group.

Examples

g = group.all() force = force.get_net_force(g)

get_net_virial(group)

Get the virial of a particle group.

Parameters:group (hoomd.group) – The particle group to query the virial for.
Returns:The last computed virial for the members in the group.

Examples

g = group.all() virial = force.get_net_virial(g)

class hoomd.md.special_pair.lj(name=None)

LJ special pair potential.

Parameters:name (str) – Name of the special_pair instance.

lj specifies a Lennard-Jones potential energy between the two particles in each defined pair.

This is useful for implementing e.g. special 1-4 interactions in all-atom force fields.

The pair potential uses the standard LJ definition.

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

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

Coefficients:

  • \(\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)

Example:

lj = special_pair.lj(name="my_pair")
lj.pair_coeff.set('pairtype_1', epsilon=5.4, sigma=0.47, r_cut=1.1)

Note

The energy of special pair interactions is reported in a log quantity special_pair_lj_energy, which is separate from those of other non-bonded interactions. Therefore, the total energy of nonbonded interactions is obtained by adding that of standard and special interactions.

New in version 2.1.

disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

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

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
get_net_force(group)

Get the force of a particle group.

Parameters:group (hoomd.group) – The particle group to query the force for.
Returns:The last computed force for the members in the group.

Examples

g = group.all() force = force.get_net_force(g)

get_net_virial(group)

Get the virial of a particle group.

Parameters:group (hoomd.group) – The particle group to query the virial for.
Returns:The last computed virial for the members in the group.

Examples

g = group.all() virial = force.get_net_virial(g)