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


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.


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.


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.


Your code must return a value.


gravity_code = "return r_i.z + box.getL().z/2;"
gravity = hoomd.hpmc.external.user.CPPExternalPotential(
mc.external_potential = gravity


CPPExternalPotential does not support execution on GPUs.


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


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



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”)