Fock, evaluated-state and eigensolver route matrix¶
Parent #472. Audited from source at main 3b4fb9e0 on 2026-11-12. This page
states what each route does today. The programme plan
orders the work and the validation ledger
holds the measured evidence. The source decides where this page and the
consumer inventory disagree.
Four states are tracked separately and none implies the next:
Source: the code is on main.
Science: a complete calculation through
vqon a containing runtime agreed with a matched reference, or with a stated same-source control.Performance: timings exist for a named workload and hardware.
Production:
run_joborrun_periodic_jobdelivers the capability.
Abbreviations: ES is an evaluated state, an immutable FockBuild that
binds the physical Fock, the density that built it, the energy record, the
frame and a source receipt. Solvers lists what the route executes.
Molecular SCF¶
All molecular HF and KS drivers diagonalise through the native
solve_fock_matrix boundary or, for ROHF and ROKS, FockDiagonalizer.
Every route runs dense or block Davidson. run_job records how the solver
was selected in the run manifest.
Route |
ES through the driver API |
Science |
ES through |
Notes |
|---|---|---|---|---|
RHF, libint conventional |
yes |
accepted, |
on request, manifest record |
first native capture slice |
RHF, libint direct, fixed Schwarz |
yes, final build on the full density |
accepted, ledger |
on request, manifest record |
an incremental final build is refused |
RHF, libint RI-JK |
yes, aux basis hash and rank in the receipt |
accepted, ledger |
on request, manifest record |
|
RHF, COSX |
refused |
n/a |
no |
terminal COSX correction is a separate energy surface |
RHF, ECP, +U, embedding, non-native optimizer |
refused |
n/a |
no |
named refusal |
RHF, MANTA exact direct |
yes, with terminal J/K receipts |
accepted, |
no |
#616 |
RHF, MANTA RI or screened |
refused |
n/a |
no |
#616 |
UHF, libint conventional, direct, RI-JK |
yes |
accepted, |
on request, manifest record |
targeted-spin options refused |
UHF, MANTA |
refused |
n/a |
no |
the refusal names only libint |
RKS and UKS, libint conventional, LDA and PBE |
yes, joint XC energy and potential |
accepted, |
on request, manifest record |
|
RKS and UKS, direct, RI, hybrid, meta-GGA, MANTA |
refused |
n/a |
no |
#596, #616 |
ROHF, libint direct or MANTA exact, integer shells |
yes, physical spin Focks and effective operator |
accepted, ledger, ORCA |
no |
full retained spectrum required |
ROKS, LDA and PBE, libint direct or MANTA |
yes |
accepted, same-source and cross-provider controls |
no |
no independent external energy for the fractional ensemble |
ROHF and ROKS, DF, COSX, ECP |
refused |
n/a |
no |
|
Point-group reduction, RHF and UHF |
yes, Python |
source checks |
yes |
the only molecular route whose identities reach the manifest |
Smearing |
not implemented |
n/a |
refused |
the Mermin estimate is post hoc |
Open molecular gaps, most important first:
run_jobrecords the evaluated state in the manifest only when the options request capture, and records a refusal for an unadmitted source. The returned result carries no state object, capture is not the default, and ROHF, ROKS and MANTA are not wired through the runner (#613).Partial-root Davidson in RHF, UHF, RKS and UKS bounds its root tolerance by the commutator threshold once the energy has converged. RKS then needs up to ten iterations more than dense at the default tolerance, and a degenerate frontier shell (OH with PBE) can still stop at the cap at the default tolerance. A stop is reported, never accepted (#1142).
Native RHF, UHF, RKS and UKS count their dense solves, Davidson solves and dense fallbacks, and
run_jobwrites them to the manifest. ROHF and ROKS, the QVF settings record and the output text do not carry them yet (#1142).FockDiagonalizercomparesdavidson_min_dimwith the AO count and the native drivers compare it with the retained rank (#1142).The partial-root stagnation repair of #1064 exists only in RHF (#895).
ROHF and ROKS libint receipts state the Schwarz threshold from code constants instead of witnessing the builder (#597).
Periodic SCF¶
Route |
ES |
Returned-state relation |
Solvers |
|
|---|---|---|---|---|
Gamma Ewald 3D and slab, RHF/RKS/UHF/UKS |
yes |
terminal build on the returned density, Rayleigh quotients |
dense, real Davidson |
runs |
Gamma Ewald ROHF |
yes, with effective operator |
evaluated |
dense |
refused |
Multi-k Ewald, all six methods (reached through the slab and BIPOLE routes) |
yes, one frame per k |
density-defining orbitals, Rayleigh quotients; |
dense, complex |
refused |
Gamma GDF, exact driver, RHF/RKS/UHF/UKS |
no |
n/a |
dense, real Davidson |
runs |
Bulk Gamma GDF on the k-mesh engine at |
yes |
as k-point GDF |
dense |
refused |
Gamma GDF, legacy driver, dimension below 3 |
yes |
evaluated |
dense |
reported as not executed |
k-point GDF, RHF/RKS/UHF/UKS, incl. slab, ECP, +U, IBZ |
yes |
density-defining orbitals with Rayleigh quotients since |
dense, complex |
refused |
GDF ROHF |
yes |
effective Fock, canonical orbitals |
dense |
refused |
RIJCOSX, Gamma and multi-k |
no |
n/a |
dense |
refused |
Gamma GPW RHF/RKS |
yes |
evaluated |
dense, real Davidson |
runs |
Gamma GPW UHF/UKS/ROHF/ROKS |
yes |
evaluated |
dense |
refused |
Multi-k GPW RKS, built-in XC, no +U |
yes |
density-defining orbitals, Rayleigh quotients |
dense, complex Davidson, full spectrum |
runs |
Multi-k GPW UKS/ROKS |
no |
n/a |
dense |
refused |
GAPW Gamma RHF, no +U, no smearing |
yes |
evaluated |
dense |
refused |
GAPW, other Gamma methods and multi-k |
no |
n/a |
dense |
refused |
BIPOLE, all methods |
private build object, no |
terminal rebuild on the returned density |
dense |
refused |
MANTA selected periodic RHF |
native snapshot, no |
evaluated density distinct from the next orbital density |
bounded Jacobi |
|
Scientific acceptance on the periodic rows is recorded per slice in the validation ledger. The multi-k Ewald, k-GDF and multi-k GPW landings of November 2026 are source landed with acceptance pending.
Open periodic gaps:
Multi-k Ewald, GPW and, since
50f9951e, k-GDF return density-defining orbitals whose energies are Rayleigh quotients; mixed and COSX-corrected returns keep canonical orbitals. No consumer readsreturned_state_relation(#1143).Exact Gamma GDF, RIJCOSX, most GAPW routes, multi-k open-shell GPW and BIPOLE have no public evaluated state (#599, #600, #604, #605, #606).
Fractional occupations always see the full retained spectrum through the runner. The exact Gamma GDF UHF and UKS drivers refuse a partial
davidson.n_eigwhen smearing is on, since the occupation tail needs every retained root (#1142).
Model Hamiltonians and experimental methods¶
Family |
Diagonalisation |
Shared operator contract |
Status |
|---|---|---|---|
DFTB0, UDFTB0 |
native generalized solve, strict Cholesky metric |
eigensolve only |
#609 |
SCC-DFTB, GFN2-xTB, PM6, OM1 to OM3, MSINDO |
dense, method-owned |
none |
#609, #610 |
k-point DFTB0 and SCC-DFTB |
dense per k |
shared multi-k helper |
#609 |
SECCM |
dense, method-owned |
none |
experimental |
AICCM four-center, real-Gamma, neutral-Bloch |
|
real-Gamma |
experimental, #519 |
chi |
BIPOLE or k-GDF drivers |
none of its own |
experimental, #614 |
These methods accept solver="dense" and solver="auto" and refuse
solver="davidson". Their Hamiltonians are effective models. A shared
operator object does not equate them with a Gaussian Fock operator.
Consumers¶
A consumer must use the reference operator and density it was given and must admit or refuse a stopped reference. Both runners refuse an unconverged SCF before any post-SCF stage, so the gaps below concern direct API callers and the meaning of the arrays.
Consumer |
Reads |
Stopped reference |
Own operator rebuild |
|---|---|---|---|
MP2, RI-MP2, UMP2, ROHF-MP2 |
orbitals, orbital energies, spin Focks |
refused |
RI factors from the MP2 options |
CCSD, CCSD(T), UCCSD, ROHF-CCSD, FNO-CCSD |
orbitals, AO Fock |
refused |
none |
Brueckner CCD |
starting orbitals |
refused |
rebuilds |
Double hybrids |
KS result |
refused |
none |
DLPNO-MP2 and UMP2 |
Fock, orbitals, bound source |
refused, also natural orbitals |
caller’s DF object |
DLPNO-CCSD and UCCSD pilots |
Fock, orbitals |
refused |
none |
Evaluated DLPNO sources, symmetry CCD |
|
refused, identity checked |
none; the reference implementation of the contract |
Periodic DLPNO |
per-k Fock and orbitals, re-diagonalised |
refused |
requires the SCF’s retained fit |
Toroidal MP2 |
canonical orbitals |
refused |
builds a separate Gamma density fit; agrees with the SCF fit in the occupied and occupied-virtual blocks, differs in the virtual-virtual block |
Gradients, molecular |
orbitals, energies, density |
refused |
route mirrored from the SCF options |
Gradients, periodic multi-k |
orbitals and energies |
refused |
relation read; non-canonical occupied orbitals made block-canonical, a state that does not define its density admitted only under a residual bound |
Analytic Hessians, CPHF |
orbitals, energies, density |
refused |
exact four-index integrals; fitted, COSX, +U and embedded references refused from the result flags |
Molecular TDA and TDDFT |
arrays |
runner gate only |
exact ERIs |
Periodic TDA |
orbitals and energies |
refused |
relation read (Rayleigh-quotient energies admitted under a residual bound); molecular ERI kernel |
READ restart, in memory and QVF |
density or orbitals |
admitted, source status recorded (molecular and periodic) |
n/a |
GPW restart archive |
densities |
admitted, source status written to |
n/a |
QVF, |
run fields |
run status |
periodic |
Open consumer gaps, tracked under #1143 unless another issue is named:
Periodic TDA refuses an unconverged reference and reads the relation. It still uses a molecular ERI kernel instead of the periodic reference operator (#612).
Periodic multi-k RHF, RKS and UKS gradients read the returned-state relation (
gradient_referenceinperiodic_multi_k_state.py). The BIPOLE and GPW gradient routes do not.Native molecular results state their two-electron source and added operators (
density_fit_applied,cosx_applied,dft_plus_u_applied,embedding.applied). Analytic Hessians refuse a fitted, COSX, +U or embedded reference. The polarizability entry points refuse a fitted or COSX reference when they build the exact kernel themselves, and a +U reference always. Brueckner CCD refuses +U and embedding. It admits a fitted reference, because it re-optimises the orbitals with the exact Hamiltonian. The low-level CPHF solvers take the caller’s integrals and check only convergence. ROHF, ROKS and Python-built references carry no flags and are admitted unchecked.A READ or GPW restart states the stopped status of its source. A capped legacy RHF archive still stores next-iterate orbitals, so the density that built its stored Fock matrix is not restored (#613).
Toroidal MP2 builds its own fit. Rebuilding J and the bare K of the SCF density from it (local runs, H2 chain and LiH, sto-3g and def2-SVP) gives the SCF Coulomb energy to 4e-7 Eh for H2 and 4e-5 Eh for LiH, an occupied-virtual Fock block below 1e-5 Ha and no measurable singles energy. The virtual-virtual block differs by up to 3e-3 Ha (def2-SVP). The effect on the correlation energy is not measured, because the MP2 cannot yet be run with the SCF’s retained fit.
Eigensolvers¶
Solver |
Reachable from |
Role |
|---|---|---|
dense |
every route |
production default and the selection oracle |
block Davidson, real |
molecular SCF; Gamma Ewald, GDF and GPW |
production, user selected |
block Davidson, complex Hermitian |
multi-k GPW RKS |
production, user selected, full spectrum |
LOBPCG |
|
production for explicit problems, no SCF route |
Chebyshev filter |
|
experimental, partial spectrum |
PRIMME |
|
experimental comparator |
Jacobi-Davidson |
|
experimental, interior |
harmonic-Davidson ( |
|
experimental, interior; not the published GPLHR recurrence |
Lanczos |
|
experimental reference |
bounded Jacobi |
periodic MANTA RHF kernel |
specialized, memory bounded |
solver="auto" selects dense on every route. The measured cases are listed
in the benchmark design. Complete SCF runs
from retained rank 24 to 472 favour dense or show no difference. Offline
replays up to rank 1888 favour recycled iterative solvers only on the last
Fock matrices of a sequence. No measurement supports a size threshold.
A later automatic rule needs all of the following before it can select an iterative solver on a route:
complete converged SCF runs on that route that beat dense, with failed attempts and fallbacks charged;
a decision input available before each solve, such as the retained Fock displacement from the previous build, not a window chosen afterwards;
a bounded, recorded fallback and an unchanged terminal dense confirmation;
a guard-root rule for fractional occupations that bounds the omitted charge.
Restricted open-shell routes keep the full retained spectrum.