class hoomd.jit.external.user(mc, code=None, llvm_ir_file=None, clang_exec=None)

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

  • code (str) – C++ code to compile
  • llvm_ir_fname (str) – File name of the llvm IR file to load.
  • clang_exec (str) – The Clang executable to use

Potentials in jit.external behave similarly to external fields assigned via hpmc.field.callback. Potentials added using external.user are added to the total energy calculation in hpmc integrators. The user external field takes C++ code, JIT compiles it at run time and executes the code natively in the MC loop at with full performance. It enables researchers to quickly and easily implement custom energetic interactions without the need to modify and recompile HOOMD.

C++ code

Supply C++ code to the code argument and user will compile the code and call it to evaluate forces. Compilation assumes that a recent clang installation is on your PATH. This is convenient when the energy evaluation is simple or needs to be modified in python. More complex code (i.e. code that requires auxiliary functions or initialization of static data arrays) should be compiled outside of HOOMD and provided via the llvm_ir_file input (see below).

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
  • vec3 and quat are is defined in HOOMDMath.h.
  • box is the system box.
  • type_i is the particle type.
  • r_i is the particle position
  • q_i the particle orientation.
  • diameter the particle diameter.
  • charge the particle charge.
  • Your code must return a value.

Once initialized, the following log quantities are provided to analyze.log:

  • external_field_jit – total energy of the field


gravity = """return r_i.z + box.getL().z/2;"""
external = hoomd.jit.external.user(mc=mc, code=gravity)

LLVM IR code

You can compile outside of HOOMD and provide a direct link to the LLVM IR file in llvm_ir_file. A compatible file contains an extern “C” eval function with this signature:

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

vec3 and quat is defined in HOOMDMath.h.

Compile the file with clang: clang -O3 --std=c++11 -DHOOMD_LLVMJIT_BUILD -I /path/to/hoomd/include -S -emit-llvm code.cc to produce the LLVM IR in code.ll.

New in version 2.5.

compile_user(code, clang_exec, fn=None)

Helper function to compile the provided code into an executable

  • code (str) – C++ code to compile
  • clang_exec (str) – The Clang executable to use
  • fn (str) – If provided, the code will be written to a file.

New in version 2.3.


Disables the compute.



Executing the disable command will remove the compute from the system. Any hoomd.run() command executed after disabling a compute will not be able to log computed values with hoomd.analyze.log.

A disabled compute can be re-enabled with enable().


Enables the compute.



See disable().


Restore the state information from the file used to initialize the simulations