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:
  • 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

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 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 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 and quat 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 and quat 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 in code.ll.

New in version 2.3.

compile_user(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.

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.

compile_user(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.

New in version 2.3.