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, array_size=1, code=None, llvm_ir_file=None, clang_exec=None)¶ Define an arbitrary patch energy.
Parameters: - r_cut (float) – Particle center to center distance cutoff beyond which all pair interactions are assumed 0.
- 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
- array_size (int) – Size of array with adjustable elements. (added in version 2.8)
-
alpha_iso
¶ Length array_size numpy array containing dynamically adjustable elements defined by the user (added in version 2.8)
Type: numpy.ndarray, float
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 with full performance. It enables researchers to quickly and easily implement custom energetic interactions without the need to modify and recompile HOOMD. Additionally,user
provides a mechanism, through the alpha_iso attribute (numpy array), to adjust user defined potential parameters without the need to recompile the patch energy code.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.
Examples:
Static potential parameters
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) hoomd.run(1000)
Dynamic potential parameters
square_well = """float rsq = dot(r_ij, r_ij); float r_cut = alpha_iso[0]; if (rsq < r_cut*r_cut) return alpha_iso[1]; else return 0.0f; """ patch = hoomd.jit.patch.user(mc=mc, r_cut=1.1, array_size=2, code=square_well) patch.alpha_iso[:] = [1.1, 1.5] # [rcut, epsilon] hoomd.run(1000) patch.alpha_iso[1] = 2.0 hoomd.run(1000)
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.
-
compile_user
(array_size_iso, array_size_union, code, clang_exec, fn=None)¶ Helper function to compile the provided code into an executable
Parameters: - 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.
- array_size_iso (int) – Size of array with adjustable elements for the isotropic part. (added in version 2.8)
- array_size_union (int) – Size of array with adjustable elements for unions of shapes. (added in version 2.8)
New in version 2.3.
-
class
hoomd.jit.patch.
user_union
(mc, r_cut, array_size=1, code=None, llvm_ir_file=None, r_cut_iso=None, code_iso=None, llvm_ir_file_iso=None, array_size_iso=1, 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
- array_size (int) – Size of array with adjustable elements. (added in version 2.8)
- array_size_iso (int) – Size of array with adjustable elements for the isotropic part. (added in version 2.8)
-
alpha_union
¶ Length array_size numpy array containing dynamically adjustable elements defined by the user for unions of shapes (added in version 2.8)
Type: numpy.ndarray, float
-
alpha_iso
¶ Length array_size_iso numpy array containing dynamically adjustable elements defined by the user for the isotropic part. (added in version 2.8)
Type: numpy.ndarray, float
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); float r_cut = alpha_union[0]; if (rsq < r_cut*r_cut) return alpha_union[1]; else return 0.0f; """ # soft repulsion between centers of unions soft_repulsion = """float rsq = dot(r_ij, r_ij); float r_cut = alpha_iso[0]; if (rsq < r_cut*r_cut) return alpha_iso[1]; else return 0.0f; """ patch = hoomd.jit.patch.user_union(r_cut=2.5, code=square_well, array_size=2, \ r_cut_iso=5, code_iso=soft_repulsion, array_size_iso=2) patch.set_params('A',positions=[(0,0,-5.),(0,0,.5)], typeids=[0,0]) # [r_cut, epsilon] patch.alpha_iso[:] = [2.5, 1.3]; patch.alpha_union[:] = [2.5, -1.7];
New in version 2.3.
-
compile_user
(array_size_iso, array_size_union, code, clang_exec, fn=None)¶ Helper function to compile the provided code into an executable
Parameters: - 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.
- array_size_iso (int) – Size of array with adjustable elements for the isotropic part. (added in version 2.8)
- array_size_union (int) – Size of array with adjustable elements for unions of shapes. (added in version 2.8)
New in version 2.3.