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.

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 hpmc integrators. 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 patch energies. 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: hoomd.hpmc.pair.user.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 assumed 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.

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

ndarray<float>

energy

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

Type

float

Examples

sq_well = '''float rsq = dot(r_ij, r_ij);
                    if (rsq < 1.21f)
                        return -1.0f;
                    else
                        return 0.0f;
            '''
patch = hoomd.hpmc.pair.user.CPPPotential(r_cut=1.1, code=sq_well,
                                          param_array=[])
mc.pair_potential = patch
sim.run(1000)
class hoomd.hpmc.pair.user.CPPPotentialUnion(r_cut_constituent, code_constituent, r_cut_isotropic, code_isotropic, param_array_constituent, param_array_isotropic)

Bases: hoomd.hpmc.pair.user.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 assumed 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.

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

ndarray<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

ndarray<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