dhERI icon

Research2026

dhERI

An electron repulsion integral compiler that generates GPU compute kernels for Vulkan and Metal.

  • C++20
  • GLSL compute
  • Dahlia
  • Vulkan
  • Metal
  • Code generation
  • libint2
  • Double-float arithmetic
Real output from the dhERI test suite. Every Boys table is within 2.2e-15 relative error, and the reference matches libint2 to 1.7e-13.
3.0e-13 Max error vs libint2
5.3M Integrals validated
81 Kernels for L ≤ 2
2 Precisions (df64, fp64)

A code generator that turns the integral formulas of quantum chemistry into GPU compute kernels. They match libint2 to 3 × 10⁻¹³ on Apple GPUs, which have no native double precision.

dhERICompiler --lmax=N writes a self-contained CMake project. That project builds libdhERI, which computes contracted two-electron repulsion integrals (ab|cd) on the GPU through Dahlia compute shaders. It does what CUDA ERI codes do, on Vulkan and Metal.

Codes that already use libint2 can link it directly, because it follows libint2's conventions: shell normalisation, CCA Cartesian ordering, standard solid-harmonic order and [a][b][c][d] block layout.

./build/dhERI_TestBoysmaxM  0: xMax   37,  593 x  8 table, max relative error 2.22e-16 (m = 0, x = 50.2580) okmaxM  4: xMax   51,  817 x 12 table, max relative error 7.30e-16 (m = 4, x = 52.1600) okmaxM  8: xMax   61,  977 x 16 table, max relative error 1.18e-15 (m = 8, x = 121.5700) okmaxM 12: xMax   70, 1121 x 20 table, max relative error 1.85e-15 (m = 12, x = 121.9600) okmaxM 16: xMax   78, 1249 x 24 table, max relative error 2.16e-15 (m = 16, x = 121.9600) okPASS./build/dhERI_TestReferenceSolid harmonics l <= 4: max coefficient difference 0.00e+00 okTHO reference vs libint2, L <= 3 (Cartesian): 930560 integrals, max |error| 1.70e-13 okPASS
Real output from dhERI's test programs, run on an Apple M4 Pro.

How it works

The dhERI pipeline dhERICompiler generates a project of GLSL kernels and tables. CMake builds it into libdhERI. At run time the host engine dispatches the kernels on the GPU through Dahlia, then transforms and orders the integrals on the CPU. GENERATION TIME RUN TIME dhERICompiler --lmax=N THO expansion Boys table, 50 digits Generated project ERI_<abcd>.glsl df64 / fp64 wrappers CMake → libdhERI GPU kernels Dahlia compute Metal or Vulkan 1 thread per quartet × Cartesian component Host Cartesian → spherical libint2 ordering (ab|cd) blocks
  • Integral formula. The Taketa–Huzinaga–O-ohata (THO) expansion. For each angular momentum class, the compiler emits one fully unrolled B-array function per axis quadruple, with the binomial and factorial coefficients folded into constants.
  • Threads. One invocation computes one (contracted shell quartet, Cartesian component) pair. The component is gl_WorkGroupID.y, so the switch that picks B functions is uniform across a workgroup. Contraction happens in registers, so no atomics are needed.
  • Boys function. A 7th-order Taylor expansion about the nearest point of a table with a 1/16 step, built in 50-digit arithmetic at generation time. Beyond xMax it switches to the asymptotic form. The GPU needs only add, multiply, one divide and one square root, and never exp.
  • Host side. The Engine builds primitive pair data and groups quartets by class. It records every dispatch in one SubmitCompute, then applies the Cartesian → spherical transform and ordering on the CPU.

Double precision without doubles

Apple GPUs have no fp64 under either Metal or MoltenVK. Every kernel is therefore written against an abstract real type and compiled twice:

  • df64: pairs of floats using error-free transformations, accurate to about 10⁻¹⁴ relative. These compile with Dahlia's PreciseMath flag, so Metal's fast math can't optimise the error terms away.
  • fp64: native double on Vulkan devices that report shaderFloat64.
// B array of one axis for angular momenta (1 0 | 1 0), generated by dhERICompiler
void B_1010(real PA, real PB, real QC, real QD, real QP, real g1, real g2, real dl,
            inout real B[BSIZE])
{
    const real QP_2 = r_mul(QP, QP);
    const real dl_2 = r_mul(dl, dl);
    const real f1_0 = PA;
    const real f2_0 = QC;
    real b0 = RZERO, b1 = RZERO, b2 = RZERO;
    b0 = r_add(b0, r_mul(f1_0, f2_0));
    // …each term's coefficients are folded in at generation time
}

Accuracy

How close dhERI gets to the referenceMax error, log scale. Lower is better.
10-1610-1510-1410-1310-12 Boys function table (relative error): 2.2e-15 Boys function tablerelative error 2.2e-15 df64 arithmetic (relative, Metal & Vulkan): 2e-14 df64 arithmeticrelative, Metal & Vulkan 2e-14 CPU reference vs libint2 (max |error|, up to (FF|FF)): 1.7e-13 CPU reference vs libint2max |error|, up to (FF|FF) 1.7e-13 GPU kernels vs libint2 (max |error|, 5.3M integrals): 3.0e-13 GPU kernels vs libint2max |error|, 5.3M integrals 3.0e-13
Show as a table
CheckMeasureValue
Boys function tablerelative error2.2e-15
df64 arithmeticrelative, Metal & Vulkan2e-14
CPU reference vs libint2max |error|, up to (FF|FF)1.7e-13
GPU kernels vs libint2max |error|, 5.3M integrals3.0e-13

Measured on an Apple M4 Pro with L ≤ 2, Metal and df64. dhERI_Validate matches libint2 to a maximum |error| of 3.0 × 10⁻¹³ over 5.3 million integrals. That covers every class from (SS|SS) to (DD|DD), Cartesian and pure shells, 1–4 primitives, and exponents from 0.1 to 60.

Status: performance is the open problem

The numbers are right; the speed isn't there yet. The 5.3M-integral run takes 16 s on the GPU against 2.9 s for libint2 on one CPU thread. Each thread does the whole THO evaluation for a single Cartesian component, so the Boys function and B arrays are recomputed for every component: 1296 times per primitive quartet for (DD|DD). The first run on Metal also compiles 81 pipelines, which takes about seven minutes before the system shader cache takes over.

Next steps, in order of expected payoff:

  1. Share work across components. Compute the Boys values and pair-quartet scalars once per primitive quartet in threadgroup memory, or move to Rys quadrature or Head-Gordon–Pople recursion, which share intermediates by construction.
  2. Canonicalise permutationally equivalent classes. This roughly halves the shader count and compile time.
  3. Precompile .metallib files at build time.
  4. Do the spherical transform on the GPU, and screen shell pairs with Schwarz bounds.