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)

Bases: ExternalField

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

Parameters

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

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.

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 = "return r_i.z + box.getL().z/2;"
gravity = hoomd.hpmc.external.user.CPPExternalPotential(
    code=gravity_code)
mc.external_potential = gravity

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.

Type

str

property energy

Total field energy of the system in the current state.

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

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

(Loggable: category=”scalar”)

Type

float