jit.patch¶
Overview
jit.patch.user |
Define an arbitrary patch energy. |
jit.patch.user_union |
Define an arbitrary patch energy on a union of particles |
Details
-
class
hoomd.jit.patch.
user
(mc, r_cut, code=None, llvm_ir_file=None, clang_exec=None)¶ Define an arbitrary patch energy.
Parameters: Patch energies define energetic interactions between pairs of shapes in
hpmc
integrators. Shapes within a cutoff distance of r_cut are potentially interacting and the energy of interaction is a function the type and orientation of the particles and the vector pointing from the i particle to the j particle center.The
user
patch energy 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 patch energies. 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 vec3<float>& r_ij, unsigned int type_i, const quat<float>& q_i, float d_i, float charge_i, unsigned int type_j, const quat<float>& q_j, float d_j, float charge_j)
vec3
andquat
are defined in HOOMDMath.h.- r_ij is a vector pointing from the center of particle i to the center of particle j.
- type_i is the integer type of particle i
- q_i is the quaternion orientation of particle i
- d_i is the diameter of particle i
- charge_i is the charge of particle i
- type_j is the integer type of particle j
- q_j is the quaternion orientation of particle j
- d_j is the diameter of particle j
- charge_j is the charge of particle j
- Your code must return a value.
- When |r_ij| is greater than r_cut, the energy must be 0. This r_cut is applied between the centers of the two particles: compute it accordingly based on the maximum range of the anisotropic interaction that you implement.
Example:
square_well = """float rsq = dot(r_ij, r_ij); if (rsq < 1.21f) return -1.0f; else return 0.0f; """ patch = hoomd.jit.patch.user(mc=mc, r_cut=1.1, code=square_well)
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 vec3<float>& r_ij, unsigned int type_i, const quat<float>& q_i, float d_i, float charge_i, unsigned int type_j, const quat<float>& q_j, float d_j, float charge_j)
vec3
andquat
are 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.3.
-
class
hoomd.jit.patch.
user_union
(mc, r_cut, code=None, llvm_ir_file=None, r_cut_iso=None, code_iso=None, llvm_ir_file_iso=None, clang_exec=None)¶ Define an arbitrary patch energy on a union of particles
Parameters: - r_cut (float) – Constituent particle center to center distance cutoff beyond which all pair interactions are assumed 0.
- r_cut_iso (float, optional) – Cut-off for isotropic interaction between centers of union particles
- code (str) – C++ code to compile
- code_iso (str, optional) – C++ code for isotropic part
- llvm_ir_fname (str) – File name of the llvm IR file to load.
- llvm_ir_fname_iso (str, optional) – File name of the llvm IR file to load for isotropic interaction
Example:
square_well = """float rsq = dot(r_ij, r_ij); if (rsq < 1.21f) return -1.0f; else return 0.0f; """ patch = hoomd.jit.patch.user_union(r_cut=1.1, code=square_well) patch.set_params('A',positions=[(0,0,-5.),(0,0,.5)], typeids=[0,0])
Example with added isotropic interactions:
# square well attraction on constituent spheres square_well = """float rsq = dot(r_ij, r_ij); if (rsq < 1.21f) return -1.0f; else return 0.0f; """ # soft repulsion between centers of unions soft_repulsion = """float rsq = dot(r_ij, r_ij); if (rsq < 6.25f) return 1.0f; else return 0.0f; """ patch = hoomd.jit.patch.user_union(r_cut=1.1, code=square_well, r_cut_iso=5, code_iso=soft_repulsion) patch.set_params('A',positions=[(0,0,-5.),(0,0,.5)], typeids=[0,0])
New in version 2.3.