vibe-qc/Documentation

Molecular GPU operation contracts

Status: conventions recorded; numerical admission thresholds remain open. This is the real molecular G0 contract for later fixed-density G1 replay. It does not enable a GPU backend or add a dependency. The complete CPU route remains the default. G0 is not complete: the remaining n-hexadecane DFT noise, containing-runtime B3 acceptance, construction-memory evidence and scientific error budgets are still required. See the delivery plan and measured CPU noise.

Indices and physical storage

Let n be the number of real AOs, m the auxiliary dimension, and p = mu*n + nu the logical AO-pair index. Strides below are in FP64 elements, not bytes. Logical symmetry does not imply a storage order.

Object	Logical indices	Physical offset or strides
Raw Eri3D::data	(P, mu, nu)	P*n*n + mu*n + nu; strides (n*n, n, 1)
Constructor-local T_flat	(P, p)	Column-major (m, n*n); P + p*m; strides (1, m)
Temporary B_flat	(P, p)	Same column-major layout as T_flat
Resident B_per_P_[P]	(mu, nu)	Each matrix is column-major (n, n); mu + nu*n; strides (1, n)
Cholesky L	(P, Q)	Column-major (m, m); P + Q*m; lower triangle defines the solve

The per-P matrices own separate allocations. There is no constant physical stride between P blocks and no resident flat B allocation. A mathematical row of T-flat or B-flat is strided. A backend must declare its leading dimensions, transpose flags, ownership and lifetime explicitly; it cannot reinterpret raw T or a per-P matrix as a contiguous flat row.

The factorization is V = L L^T, B_flat = L^-1 T_flat, with the full auxiliary dimension in each triangular solve. Pair-column blocking preserves that dimension. Independent auxiliary-row solves do not implement this factorization. The Coulomb-metric construction follows Weigend 2002, section 2, equations (2)-(4). The DF implementation retains the existing density-form exchange route; an occupied-orbital implementation is a separate experiment.

Every new pack/unpack route must round-trip unequal dimensions and an asymmetric index sentinel. Physical ERIs alone cannot detect all transpose errors because their AO pairs are symmetric. Tests must include C-contiguous, Fortran-contiguous, transposed and sliced Python inputs where those inputs are accepted; conversion must preserve logical entries. The existing storage tests check contraction layouts, the half-transform and the corrected Gram helper. They do not qualify a future device packer.

Density, spin and energy

AO densities are expressed in the nonorthogonal AO basis. Electron number is Tr(D S), where S is the overlap matrix. Operators and energy contractions use that same basis and ordering; inserting an extra S in Tr(D J) or Tr(D K) changes the definition.

For a restricted closed shell, D = 2 C_occ C_occ^T. The builders return unscaled J and K of the supplied spin-summed D:

gamma[P] = sum(mu,nu) B[P,mu,nu] D[mu,nu]
J[mu,nu] = sum(P) B[P,mu,nu] gamma[P]
K[mu,nu] = sum(P,lambda,sigma) B[P,mu,lambda] D[lambda,sigma] B[P,sigma,nu]
F = H + J - (a_x/2) K + Vxc
E_J = Tr(D J)/2
E_K = -a_x Tr(D K)/4

RHF has a_x = 1, PBE0 has a_x = 1/4, and PBE has a_x = 0. RHF has no Vxc operation; PBE has no K operation. Missing physical operations are not zero-cost measurements. The PBE0 K energy coefficient is -1/16, not -1/4.

For unrestricted densities, each spin density uses unit occupations: D_total = D_alpha + D_beta, J = J[D_total], and K_sigma = K[D_sigma]. Then F_sigma = H + J - a_x K_sigma + Vxc_sigma, E_J = Tr(D_total J)/2, and E_K = -a_x sum(sigma) Tr(D_sigma K_sigma)/2. These factors are conventions, not a claim that the restricted G0 campaign qualifies unrestricted replay.

For fractional occupations, D = C diag(f) C^T uses the occupations actually requested by the driver. X = C sqrt(f) may replace D only when D = X X^T is the actual density passed to the builder. Driver orbitals do not generally factor a damped, mixed or extrapolated density. Preserve the density route for indefinite inputs and preserve fractional/MOM policies; do not project a signed fixture onto a positive-semidefinite density.

Vxc is the functional derivative of the implemented nonlinear XC energy. Tr(D delta Vxc) is an operator diagnostic, not an XC energy difference. Compare the separately evaluated E_xc[D] as well. The direct restricted fixed-density XC interface accepts signed perturbations while retaining the production pointwise density cutoffs and functional/grid settings.

Complex arithmetic needs conjugate transposes, Hermitian metrics and separate k-point/spin conventions. None of these real molecular tests qualifies periodic or complex data.

Frozen inputs and replay scope

The noise harness exports SAD, mid-SCF and converged densities plus opposite small symmetric signed perturbations. The perturbation scale is 1e-7 relative Frobenius norm with the harness’s unit floor, and the perturbation preserves Tr(D S). Archive and matrix hashes identify the exact inputs. Density preparation, convergence and electron-count checks are part of fixture qualification.

Hold geometry, orbital and auxiliary basis content, AO ordering, density, grid points/weights, functional, screens and resolved route fixed. Direct replay disables incremental caching. The measured COSX replay is FITTED final-grid iterated K with the one-center correction excluded. It is not a measurement of the entire staged SCF algorithm. AUTO is resolved explicitly; deduplication requires identical resolved settings.

Repeat each operation at least three times at OMP=1 and OMP=N, with the granted physical-core allocation recorded and BLAS=1 for the current baseline. Record observed teams as well as requested settings. Compare all repeat pairs within a thread setting and all cross-thread pairs; use OMP=1 as the cross-thread reference. Never pool different frozen densities or runtime identities to manufacture a complete cell.

Source SHA, native digest, clean-tree state, bundle identity and fixture hashes must pass before and after replay. Sleep invalidates timing evidence. A timeout, refused operation or missing observation remains incomplete. Raw paths and deployment details stay outside the repository. Public summaries contain only verified, redacted measurements.

Error metrics and admission

For candidate A, reference R and delta = A-R, record each observable separately:

Metric	Definition
Maximum absolute matrix error	max(abs(delta[i,j])), in Hartree
Relative Frobenius error	norm(delta, F) / norm(R, F)
Symmetry defect	max(abs(A-A^T)); CPU pair floors retain the larger defect of both matrices
J energy error	abs(Tr(D delta J)/2)
Restricted K energy error	abs(-a_x Tr(D delta K)/4)
Vxc contraction diagnostic	abs(Tr(D delta Vxc))
Nonlinear XC energy error	abs(E_xc_candidate[D] - E_xc_reference[D])

If the reference Frobenius norm is zero, relative error is zero only if the difference also vanishes; otherwise it is undefined (null in the summary). Undefined or nonfinite metrics cannot silently pass a numerical admission test. Absolute error remains meaningful. Matrix, energy and symmetry checks are complementary; an energy cancellation cannot excuse a matrix failure.

The current machine-readable floors contain complete H2O and naphthalene restricted RHF/PBE/PBE0 coverage and partial n-hexadecane RHF coverage. Each row records repeat and OMP=1-versus-N floors, density/basis/grid hashes and its runtime. Those floors measure CPU repeatability within one approximation. Direct-versus-DF or COSX errors are approximation errors and must not be folded into an arithmetic noise floor. An observed zero is not a guarantee of exact arithmetic on other inputs.

The optional DF rounding study establishes conditional two-stage Coulomb bounds for supplied B and D. Its finite-instance native certificates do not certify every BLAS reduction order or assign a scientific admission budget. They can support a justified roundoff estimate within their stated premises.

For each future operation and metric, take the CPU floor n as the larger repeat and cross-thread floor for the matched fixture and route. Record a justified roundoff estimate r for that operation/shape/conditioning and an independent scientific budget b before inspecting candidate results. The plan’s proposed strict rule requires both error <= 10*max(n,r) and error <= b. If max(n,r) > b, admission is unresolved; it does not increase the budget. A universal absolute threshold, including 1e-10 Hartree, is not inferred from these measurements.

No numerical G1 admission thresholds are assigned here yet. The remaining n-hexadecane DFT measurements, per-operation roundoff justification and predeclared scientific budgets must be added with their evidence. Subsequent full SCF comparisons must also match convergence and approximation settings against ORCA or CRYSTAL where available. Passing fixed-density arithmetic alone is not scientific SCF acceptance or completion of G0.