hoomd.hpmc.pair.user#
Overview
Base class for interaction between pairs of particles given in C++. |
|
Define an energetic interaction between pairs of particles. |
|
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 iq_i
is the quaternion orientation of particle id_i
is the diameter of particle icharge_i
is the charge of particle itype_j
is the integer type id of particle jq_j
is the quaternion orientation of particle jd_j
is the diameter of particle jcharge_j
is the charge of particle j
Note
vec3
andquat
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:
- 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
offloat
- 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. ARuntimeError
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.4.0:
num_cpu_threads >= 1
is deprecated. Setnum_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:
- 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:
- 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:
- 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
offloat
- 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
offloat
- energy#
The potential energy resulting from the interactions defind in the C++ code at the current timestep.
- Type:
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