vibe-qcDocumentation

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:

  1. Source: the code is on main.

  2. Science: a complete calculation through vq on a containing runtime agreed with a matched reference, or with a stated same-source control.

  3. Performance: timings exist for a named workload and hardware.

  4. Production: run_job or run_periodic_job delivers 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 run_job

Notes

RHF, libint conventional

yes

accepted, ddcdf9ad, ORCA

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, ebb64a16, ORCA

no

#616

RHF, MANTA RI or screened

refused

n/a

no

#616

UHF, libint conventional, direct, RI-JK

yes

accepted, 9588b923, ORCA

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, 9588b923, ORCA

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 FockBuild

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_job records 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_job writes them to the manifest. ROHF and ROKS, the QVF settings record and the output text do not carry them yet (#1142).

  • FockDiagonalizer compares davidson_min_dim with 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

solver="davidson"

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; mixed under ODA

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 (1, 1, 1), the usual bulk Gamma route

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 50f9951e; canonical orbitals for damped, mixed, density-guess and COSX returns

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 FockBuild

terminal rebuild on the returned density

dense

refused

MANTA selected periodic RHF

native snapshot, no FockBuild

evaluated density distinct from the next orbital density

bounded Jacobi

solver refused

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 reads returned_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_eig when 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

numpy.linalg.eigh or the k-GDF drivers

real-Gamma FockBuild only

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 T + V and exact ERIs; the SCF source is not carried

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

fock_build

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

n/a

QVF, .system and .out

run fields

run status

periodic .out states relation, residual, stop reason and build identity where the result records them; identities reach the manifest on few routes

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_reference in periodic_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

solve_operator, explicit real problems

production for explicit problems, no SCF route

Chebyshev filter

solve_operator

experimental, partial spectrum

PRIMME

solve_operator, optional dependency

experimental comparator

Jacobi-Davidson

solve_operator

experimental, interior

harmonic-Davidson (gplhr alias)

solve_operator

experimental, interior; not the published GPLHR recurrence

Lanczos

solve_operator

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.