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. These arrays are read-only during function evaluation.

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.

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

wrap_gpu_code(code)

Helper function to compile the provided code into a device function

Parameters

code (str) – C++ code to compile

New in version 3.0.

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.

set_params(type, positions, typeids, orientations=None, charges=None, diameters=None, leaf_capacity=4)

Set the union shape parameters for a given particle type

Parameters
  • type (str) – The type to set the interactions for

  • positions (list) – The positions of the constituent particles (list of vectors)

  • orientations (list) – The orientations of the constituent particles (list of four-vectors)

  • diameters (list) – The diameters of the constituent particles (list of floats)

  • charges (list) – The charges of the constituent particles (list of floats)

  • leaf_capacity (int) – The number of particles in a leaf of the internal tree data structure

wrap_gpu_code(code)

Helper function to compile the provided code into a device function

Parameters

code (str) – C++ code to compile

New in version 3.0.