jit.external¶
Overview
jit.external.user |
Details
-
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.
Parameters: 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. Theuser
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 recentclang
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
andquat
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
Example:
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
andquat
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 incode.ll
.New in version 2.5.
-
compile_user
(code, clang_exec, fn=None)¶ Helper function to compile the provided code into an executable
Parameters: New in version 2.3.
-
disable
()¶ Disables the compute.
Examples:
c.disable()
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 withhoomd.analyze.log
.A disabled compute can be re-enabled with
enable()
.
-
restore_state
()¶ Restore the state information from the file used to initialize the simulations