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
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
How it works
- 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 theswitchthat 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
xMaxit switches to the asymptotic form. The GPU needs only add, multiply, one divide and one square root, and neverexp. - Host side. The
Enginebuilds primitive pair data and groups quartets by class. It records every dispatch in oneSubmitCompute, 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
PreciseMathflag, so Metal's fast math can't optimise the error terms away. - fp64: native
doubleon Vulkan devices that reportshaderFloat64.
// 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
Show as a table
| Check | Measure | Value |
|---|---|---|
| Boys function table | relative error | 2.2e-15 |
| df64 arithmetic | relative, Metal & Vulkan | 2e-14 |
| CPU reference vs libint2 | max |error|, up to (FF|FF) | 1.7e-13 |
| GPU kernels vs libint2 | max |error|, 5.3M integrals | 3.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:
- 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.
- Canonicalise permutationally equivalent classes. This roughly halves the shader count and compile time.
- Precompile
.metallibfiles at build time. - Do the spherical transform on the GPU, and screen shell pairs with Schwarz bounds.