hoomd.hpmc.external.user#

Overview

CPPExternalPotential

Define an external potential energy field imposed on all particles in the system.

Details

User-defined external fields for HPMC simulations.

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

See also

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

class hoomd.hpmc.external.user.CPPExternalPotential(code, param_array=[])#

Bases: ExternalField

Define an external potential energy field imposed on all particles in the system.

Parameters:

  • code (str) – C++ function body to compile.

  • 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.

Potentials added using CPPExternalPotential are added to the total energy calculation in hoomd.hpmc.integrate.HPMCIntegrator. CPPExternalPotential takes C++ code, compiles it at runtime, and executes the code natively in the MC loop with full performance. It enables researchers to quickly and easily implement custom energetic field intractions without the need to modify and recompile HOOMD.

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

C++ code

Supply C++ code to the code argument and CPPExternalPotential will compile the code and call it to evaluate the energy. The text provided in code is the body of a function with the following signature:

float eval(const BoxDim& box,
           unsigned int type_i,
           const vec3<Scalar>& r_i,
           const quat<Scalar>& q_i
           Scalar diameter,
           Scalar charge
)

  • box is the system box.

  • type_i is the (integer) particle type.

  • r_i is the particle position

  • q_i the quaternion representing the particle orientation.

  • diameter the particle diameter.

  • charge the particle charge.

Note

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

Note

Your code must return a value.

Example:

gravity_code = '''
    float gravity_constant = param_array[0];
    return gravity_constant * (r_i.z + box.getL().z/2);
'''
cpp_external_potential = hoomd.hpmc.external.user.CPPExternalPotential(
    code=gravity_code, param_array=[9.8])
hpmc_integrator.external_potential = cpp_external_potential

Note

CPPExternalPotential does not support execution on GPUs.

Warning

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

code#

The code of the body of the external field energy function. After running zero or more steps, this property cannot be modified.

Example

code = cpp_external_potential.code
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.

Example

cpp_external_potential.param_array[0] = 10.0
Type:

(N, ) numpy.ndarray of float

property energy#

Total field energy of the system in the current state.

\[U = \sum_{i=0}^\mathrm{N_particles-1} U_{\mathrm{external},i}\]

Example:

logger.add(cpp_external_potential, quantities=['energy'])

Returns None when the patch object and integrator are not attached.

(Loggable: category=”scalar”)

Type:

float