Notebooks · lib/hf/integrals
The integral stages on one page, what each promises and who checks it
A Hartree-Fock energy needs four kinds of numbers from the basis: the
contracted coefficients, the one-electron matrices S, T and V, the
electron repulsion integrals (ij|kl), and, for a spherical basis, the same
things moved from Cartesian to spherical functions. Each of these has two or
more implementations in lib/hf that share no algebra. This page lists them
as registries, one per stage, and gives each stage one contract def.
A contract def runs every member of its registry on the same input and
requires them to agree (lib/hf/sweep); the agreed value is returned. Under
release_mode() it runs member 0, the production member, and nothing else.
The tolerance is written next to the def. Agreement is measured as
abs(v - median) / (1 + abs(median)), per entry.
This page is the verification layer around the integrals, not the way a calculation reaches them: the production path calls each production member by name (lib/hf/ao for a molecule's integrals, lib/hf/jk for J and K), and the registries, the masked drivers and the contract defs here run the same members side by side. The cross-checked pipeline of lib/hf/hf, the lock ladder (scf/lock_*.viv) and the tests in lib/hf/tests use them.
| Stage | Registry | Members (production first) | Tolerance |
|---|---|---|---|
| 1 contraction | int_contract_methods | closed form, numeric via md1_s, numeric via os_overlap | 10−13 |
| 3 overlap | int_overlap_methods | md1_s, os_overlap, gh_overlap | 10−12 |
| 3 kinetic | int_kinetic_methods | md1_t, os_kinetic, gh_kinetic | 10−12 |
| 3 nuclear | int_nuclear_methods | md1_v, os_nuclear | 10−12 |
| 4 ERI | int_eri_methods | mdg_screened, mderi_screened, mderi_full, hgp_eri, rys_eri | 10−12 |
| 5 c2s block | int_c2s_methods | c2s_closed, c2s_general | 10−14 |
| 5 one-electron transform | int_tr2_methods | tr2_blocks, tr2_dense | 10−13 |
| 5 density back-transform | int_tr2_back_methods | tr2_back_blocks, tr2_back_dense | 10−13 |
| 5 ERI transform | int_tr4_methods | tr4_blocks, tr4_quarter (n <= 30) | 10−13 |
| 4+5 spherical ERIs | int_eri_sph_methods | mdg_sph, mderi_sph, tr4_two_pass | 10−14 |
| 8 J/K | int_jk_methods | jk_packed, jk_pairs, jk_dense, int_jk_direct, int_jk_direct_full | 10−12 |
Stage 2 (Boys) is boys_methods() in lib/hf/boys, stage 6
(orthogonalizer) is orth_methods() and stage 7 (eigen) is eig_methods();
their contracts live with them.
Choosing members. The ERI registry holds one member that costs far more
than the others (Rys, about 7x MD on water cc-pVDZ in the interpreter), so
the ERI and ERI-transform contracts take a member mask: bit k set means
member k runs. Mask 0 means every member. ScfOptions.eri_members carries
the ERI mask through the pipeline in lib/hf/hf, where 0 means the default
pair INT_ERI_PAIR = MD on the generated kernels (lib/hf/mdg_eri) and HGP,
two families that share no recurrence. The generated kernels are held to the
general MD code they were generated from (lib/hf/md_eri) by
lib/hf/tests/mdg_eri and by every sweep with mask 0. The masked driver int_sweep3 reports the blamed member by its
index in the full registry, not in the mask.
The numeric contraction. bas_contract normalizes a contracted shell
with the closed form for the overlap of two primitives,
(2 sqrt(ab)/(a+b))^(l+3/2). bas_contract_numeric gets the same overlaps
from an integral code instead: each primitive becomes a one-primitive shell
at the origin, md1_s (or os_overlap) gives their overlap matrix, and the
contraction is scaled so that sum_pq c_p c_q S_pq = 1. A one-primitive shell
is normalized by the closed form evaluated at a = b, where it is exactly 1,
so the two strategies share only the radial factor Nr(a, l).
Direct J/K. The direct members int_jk_direct (density-screened) and
int_jk_direct_full (lib/hf/jk_direct) read a basis blob instead of packed
integrals. A sweep over
int_jk_methods() passes the packed vector in slot 1 and the blob in slots
2 and 3, so the in-core members and the direct one see the same density.
Used with import hf.integrals.
Look inside this program
- Atlas
The program’s map: every function and which calls which.
There’s no recorded run of this program yet.
Shift+Enter in a cell runs it and moves to the next. Running a cell runs every cell above it too, as one program.