hoomd.hpmc.pair.user#

Overview

CPPPotentialBase

Base class for interaction between pairs of particles given in C++.

CPPPotential

Define an energetic interaction between pairs of particles.

CPPPotentialUnion

Define an arbitrary energetic interaction between unions of particles.

Details

User-defined pair potentials for HPMC simulations.

Set \(U_{\mathrm{pair},ij}\) evaluated in hoomd.hpmc.integrate.HPMCIntegrator to a user-defined expression.

See also

Features explains the compile time options needed for user defined pair potentials.

class hoomd.hpmc.pair.user.CPPPotentialBase#

Base class for interaction between pairs of particles given in C++.

Pair potential energies define energetic interactions between pairs of particles in hoomd.hpmc.integrate.HPMCIntegrator. Particles within a cutoff distance interact with an energy that is a function the type and orientation of the particles and the vector pointing from the i particle to the j particle center.

Classes derived from CPPPotentialBase take C++ code, compile it at runtime, and execute the code natively in the MC loop.

Warning

CPPPotentialBase is experimental and subject to change in future minor releases.

C++ code

Classes derived from CPPPotentialBase will compile the code provided by the user and call it to evaluate the energy \(U_{\mathrm{pair},ij}\). The text provided is the body of a function with the following signature:

float eval(const vec3<float>& r_ij,
           unsigned int type_i,
           const quat<float>& q_i,
           float d_i,
           float charge_i,
           unsigned int type_j,
           const quat<float>& q_j,
           float d_j,
           float charge_j
)
  • r_ij is a vector pointing from the center of particle i to the center of particle j.

  • type_i is the integer type id of particle i

  • q_i is the quaternion orientation of particle i

  • d_i is the diameter of particle i

  • charge_i is the charge of particle i

  • type_j is the integer type id of particle j

  • q_j is the quaternion orientation of particle j

  • d_j is the diameter of particle j

  • charge_j is the charge of particle j

Note

vec3 and quat are defined in the file VectorMath.h in the HOOMD-blue source code.

Note

Your code must return a value.

Mixed precision

CPPPotentialBase uses 32-bit precision floating point arithmetic when computing energies in the local particle reference frame.

class hoomd.hpmc.pair.user.CPPPotential(r_cut, code, param_array)#

Bases: CPPPotentialBase

Define an energetic interaction between pairs of particles.

Adjust parameters within the code with the param_array attribute without requiring a recompile. These arrays are read-only during function evaluation.

Parameters:
  • r_cut (float) – Particle center to center distance cutoff beyond which all pair interactions are 0.

  • code (str) – C++ code defining the function body for pair interactions between particles.

  • param_array (list[float]) – Parameter values to make available in float *param_array in the compiled code. If no adjustable parameters are needed in the C++ code, pass an empty array.

See also

CPPPotentialBase for the documentation of the parent class.

Warning

CPPPotential is experimental and subject to change in future minor releases.

Example

See How to apply arbitrary pair potentials in HPMC.

code#

The C++ code that defines the body of the patch energy function. After running zero or more steps, this property cannot be changed.

Type:

str

param_array#

Numpy array containing dynamically adjustable elements in the potential energy function as defined by the user. After running zero or more steps, the array cannot be set, although individual values can still be changed.

Type:

(N, ) numpy.ndarray of float

energy#

The potential energy resulting from the interactions defind in the C++ code at the current timestep.

Type:

float

class hoomd.hpmc.pair.user.CPPPotentialUnion(r_cut_constituent, code_constituent, r_cut_isotropic, code_isotropic, param_array_constituent, param_array_isotropic)#

Bases: CPPPotentialBase

Define an arbitrary energetic interaction between unions of particles.

Parameters:
  • r_cut_constituent (float) – Constituent particle center to center distance cutoff beyond which all pair interactions are 0.

  • code_constituent (str) – C++ code defining the custom pair interactions between constituent particles.

  • r_cut_isotropic (float) – Cut-off for isotropic interaction between centers of union particles.

  • code_isotropic (str) – C++ code for isotropic part of the interaction. Must be '' when executing on a GPU.

  • param_array_constituent (list[float]) – Parameter values to make available in float *param_array_constituent in the compiled code. Pass an empty array if no adjustable parameters are needed for the constituent interactions.

  • param_array_isotropic (list[float]) – Parameter values to make available in float *param_array_isotropic in the compiled code. Pass an empty array if no adjustable parameters are needed for the isotropic interactions.

Note

Code passed into code_isotropic is not used when executing on the GPU. A RuntimeError is raised on attachment if the value of this argument is anything besides '' on the GPU.

Note

This class uses an internal OBB tree for fast interaction queries between constituents of interacting particles. Depending on the number of constituent particles per type in the tree, different values of the particles per leaf node may yield different optimal performance. The capacity of leaf nodes is configurable.

See also

CPPPotentialBase for the documentation of the parent class.

Warning

CPPPotentialUnion is experimental and subject to change in future minor releases.

Threading

CPPPotentialUnion uses threaded execution on multiple CPU cores.

Deprecated since version 4.6.0: num_cpu_threads >= 1 is deprecated. Set num_cpu_threads = 1.

positions#

The positions of the constituent particles.

Type: TypeParameter [particle type, list [tuple [float, float, float]]]

orientations#

The orientations of the constituent particles.

Type: TypeParameter [particle type, list [tuple [float, float, float, float]]]

diameters#

The diameters of the constituent particles.

Type:

TypeParameter [particle type, list [float]]

charges#

The charges of the constituent particles.

Type:

TypeParameter [particle type, list [float]]

typeids#

The integer types of the constituent particles.

Type:

TypeParameter [particle type, list [float]]

leaf_capacity#

The number of particles in a leaf of the internal tree data structure (default: 4).

Type:

int

code_constituent#

The C++ code that defines the body of the patch energy function between the constituent particles. This property cannot be modified after running for zero or more steps.

Type:

str

code_isotropic#

The C++ code that defines the body of the patch energy function between the centers of the particles. This property cannot be modified after running for zero or more steps.

Type:

str

param_array_isotropic#

Numpy array containing dynamically adjustable elements in the isotropic part of the potential as defined by the user. After running zero or more steps, the array cannot be set, although individual values can still be changed.

Type:

(N, ) numpy.ndarray of float

param_array_constituent#

Numpy array containing dynamically adjustable elements in the constituent part of the potential part of the potential as defined by the user. After running zero or more steps, the array cannot be set, although individual values can still be changed.

Type:

(N, ) numpy.ndarray of float

energy#

The potential energy resulting from the interactions defind in the C++ code at the current timestep.

Type:

float

Example without isotropic interactions:

square_well = '''float rsq = dot(r_ij, r_ij);
                    if (rsq < 1.21f)
                        return -1.0f;
                    else
                        return 0.0f;
              '''
patch = hoomd.hpmc.pair.user.CPPPotentialUnion(
    r_cut_constituent=1.1,
    r_cut_isotropic=0.0
    code_constituent=square_well,
    code_isotropic='',
    param_array_constituent=[],
    param_array_isotropic=[]
)
patch.positions['A'] = [
    (0, 0, -0.5),
    (0, 0, 0.5)
]
patch.diameters['A'] = [0, 0]
patch.typeids['A'] = [0, 0]
mc.pair_potential = patch

Example with added isotropic interactions:

# square well attraction on constituent spheres
square_well = '''float rsq = dot(r_ij, r_ij);
                      float r_cut = param_array_constituent[0];
                      if (rsq < r_cut*r_cut)
                          return param_array_constituent[1];
                      else
                          return 0.0f;
                '''

# soft repulsion between centers of unions
soft_repulsion = '''float rsq = dot(r_ij, r_ij);
                          float r_cut = param_array_isotropic[0];
                          if (rsq < r_cut*r_cut)
                            return param_array_isotropic[1];
                          else
                            return 0.0f;
                 '''

patch = hoomd.hpmc.pair.user.CPPPotentialUnion(
    r_cut_constituent=2.5,
    r_cut_isotropic=5.0,
    code_union=square_well,
    code_isotropic=soft_repulsion,
    param_array_constituent=[2.0, -5.0],
    param_array_isotropic=[2.5, 1.3],
)
patch.positions['A'] = [
    (0, 0, -0.5),
    (0, 0, 0.5)
]
patch.typeids['A'] = [0, 0]
patch.diameters['A'] = [0, 0]
mc.pair_potential = patch