vibe-qcDocumentation

Spin-resolved chi stationarity and the retained space

VibeQCAICCM/SpinStationarity.lean adds 15 kernel-checked claims to the pinned project. They extend the closed-shell finite-torus stationarity of the AICCM bridge to two independent spin densities on complex character blocks, and they state the stationarity condition of a truncated (reduced-rank) variational space. Chi remains experimental and D93 fitted/post-HF remains not-qualified. The claims are exact statements about supplied finite operators. They do not construct integrals, a fit or an SCF solution, and they bound no floating-point error.

Definitions and hypotheses

K is the finite set of characters of the complete unshifted mesh and Nc its size. A block family assigns one complex AO matrix to each character. The real pairing is T(F,V) = sum_k Re tr(F_k V_k)/Nc, as in the closed-shell tranche. Energies are per primitive cell in hartree.

A spin density is feasible when every block is Hermitian and is a metric projector, D S D = D, and when the mean count sum_k tr(D_k S_k)/Nc has its prescribed value (spinDomain). The two spins have separate counts. Only the Hermiticity of S is used by the spin-resolved claims; a positive metric is needed only where the closed-shell tranche already requires it.

The UHF ledger (uhfLedger) is

E = nn + T(h, Da+Db) + T(J[Da+Db], Da+Db)/2 - T(X[Da], Da)/2 - T(X[Db], Db)/2

for a Hermitian one-body family h and two continuous real-linear maps J and X. Reciprocity, T(J p, q) = T(J q, p) and the same for X on Hermitian families, is a hypothesis. It permits coupling between different characters. It is a property of the supplied operators, not something the theorems derive from integrals.

Claims

  • bvk_spin_rotation_feasible. For skew-Hermitian A and U = exp(t A S), the rotated block U D U^H is Hermitian, satisfies D S D = D and keeps its count.

  • bvk_uhf_quadratic_fock. With reciprocal J and X, the ledger has the real differential T(Fa, Va) + T(Fb, Vb) along Hermitian paths, where F_sigma = h + J[Da+Db] - X[D_sigma]. Each spin sees its own exchange.

  • bvk_uhf_orbital_stationary_iff. All slopes along independent rotations of the two spins vanish exactly when F_sigma D_sigma S = S D_sigma F_sigma in every block and for both spins. A rotation of one spin at fixed other spin is an allowed direction, so a common rotation of both spins is not enough.

  • bvk_uhf_stationary_iff and bvk_uhf_fock_iff. The same condition holds for every pair of differentiable feasible paths, and for the quadratic ledger with its physical operators. Differentiating D S D = D gives V S D + D S V = V, hence D S V S D = 0, and A = V S D - D S V regenerates V.

  • bvk_uhf_half_fock_ledger. The ledger equals nn + sum_sigma T(h + F_sigma, D_sigma)/2, the form the production rebuild sums.

  • bvk_seam_exchange_reciprocal and bvk_seam_shifted_exchange_reciprocal. The BvK zero-mode term S D S is reciprocal, and adding a real multiple of it to a reciprocal exchange map keeps reciprocity. The production exchange X[D] + eta S D S therefore satisfies the hypothesis whenever X does.

  • bvk_uhf_closed_shell_fock and bvk_uhf_closed_shell_ledger. Equal spin densities give the closed-shell operator h + (J - X/2)[D] and the closed-shell quadratic ledger at D = Da + Db.

Retained variational space

Canonical truncation of a nearly dependent overlap leaves an orthogonalizer x with fewer columns than AOs. The variational densities are x d x^H and the reduced metric is x^H S x.

  • bvk_retained_density. A reduced metric projector lifts to an AO metric projector with the same count.

  • bvk_retained_residual. x^H (F D S - S D F) x is the residual of the reduced problem with operators x^H F x and x^H S x.

  • bvk_uhf_retained_fock. The gradient of the reduced energy is x^H F x.

  • bvk_uhf_retained_stationary_iff. Stationarity over the retained space is the projected condition x^H (F D S - S D F) x = 0 for each spin. The reduced metric need not be the identity.

  • bvk_retained_unprojected_counterexample. With one retained orbital out of two and a Fock coupling to the removed direction, the projected residual vanishes while the AO commutator does not. The unprojected commutator is therefore not the Euler condition of a truncated space. This is the statement of Lowdin, Adv. Quantum Chem. 5, 185 (1970), doi:10.1016/S0065-3276(08)60339-1, already used by the native SCF residual.

Production correspondence

Mathematical object

Production

Ledger and half-Fock sum

_chi_rebuild_hf_acceptance in periodic_k_gdf.py: energy += w tr(d (h + h + j - k))/2 per spin and character

F_sigma

the returned spin_focks, h + j - k with k = K[D_sigma] + madelung S D_sigma S

Closed-shell collapse

the restricted call passes [D/2, D/2]

Spin residual

orbital_residual, the weighted Frobenius norm of F D S - S D F over spins and characters

Retained residual

the same norm of P^H (F D S - S D F) P with P^H = S x x^H when x has fewer columns than AOs

Uniform weights

complete unshifted chi meshes; the shared driver passes Brillouin-zone weights

The hypotheses are enforced only in part. Integer per-character occupations are required by _chi_require_integer_occupations. Reciprocity of the fitted J and K is not checked by the rebuild; it is measured by the operator diagnostics and by validator runs on the source in question, and it failed on a recorded short-range case (#453).

Finding and repair

The acceptance rebuild measured the unprojected AO commutator. At a stationary point of a truncated space that norm is of order one, so every reduced-rank explicit-support chi HF or KS state was refused after the SCF loop had converged on the correct retained residual. The refusal was fail-closed: no nonstationary state was accepted. The rebuild now projects the commutator onto the retained space when x is rectangular. At complete rank the reported value is unchanged bit for bit. The report records orbital_residual_space, retained_ranks and the former unprojected_orbital_residual as a diagnostic.

Correlation references on a truncated space

The same condition governs what a correlation consumer may assume (#1194). The canonical check _spin_state in periodic/chi/canonical_mp2.py measured F C - S C eps in complete AO coordinates. For orbitals with fewer columns than AOs it now measures the projection C^H (F C - S C eps), and only where the consumer asks for it.

Consumer

Truncated space

Canonical MP2 and UMP2 energy

admitted: the sum runs over the orbitals themselves

Canonical CCSD and triples energy

admitted: the equations use C^H F C and orbital-basis integrals only; unequal alpha and beta orbital dimensions were already supported

HF restart validation

admitted: projected canonical condition and projected commutator

Local MP2, MP2 and CC gradients

refused by name; not examined, and a derivative needs rank-boundary terms

Sealed real-torus and translation references (_admit_state)

refused by name: they diagonalize or audit the complete AO Fock

The orbitals must have one rank at every character. Complete-rank states are measured exactly as before. A departure from stationarity inside the kept space is refused at the unchanged 1e-9 tolerance.

Numerical check

formal/check_chi_uhf_stationarity.py runs the production rebuild on a synthetic three-character model: two characters form a complex conjugate pair, the metric is nonorthogonal, the Coulomb map couples all characters and the exchange map couples character pairs. It is not a material and uses no native integrals.

python formal/check_chi_uhf_stationarity.py
python formal/check_chi_uhf_stationarity.py --source python/vibeqc/periodic_k_gdf.py

The first form imports the installed runtime and records its version and native digest. The second reads the function from a source file. Central differences of the rebuilt energy on the steps 2e-2, 1e-2, 5e-3 and 2.5e-3 are extrapolated and compared with -w Re tr(R A) for 42 independent real and imaginary occupied-virtual generators, one spin and one character at a time, at a stationary open-shell state and at a displaced state.

Quantity

Measured

Tolerance

Slopes at the displaced state

1.2e-12

2e-9

Slopes at the stationary state

9.3e-13

2e-9

Central-difference error ratio on halved steps

3.99 to 4.00

3.5 to 4.5

Residual norm rebuilt from slopes against orbital_residual

2.7e-15

5e-8

Rebuilt energy against the independent ledger

0

5e-12

Retained stationary point: projected residual

4.2e-14

1e-11

Retained stationary point: unprojected commutator

1.15

must exceed 1e-3

Retained displaced state: slopes

5.1e-13

2e-9

Controls that must be detected: a spin-swapped exchange, a spin-averaged operator, a transposed operator, a missing metric, a missing cell weight, a reversed sign, real-only rotations and a nonreciprocal exchange map, whose operator is not the gradient of its own ledger. On unrepaired source the script fails at the retained stationary point with a residual of 1.15.

The zero-mode term is a deliberate non-control. On metric projectors S D S commutes with the density, so omitting it changes no orbital slope. It shifts the energy by -eta/2 per electron and each occupied level by -eta. Only the ledger and the spectrum can detect its omission, and both are checked.

Native check

formal/check_chi_uhf_native.py runs complete native chi calculations on explicit classic controls and then uses the executed fitted factors of each calculation. Submit it with its inputs.json and gates.json through vq; it exits nonzero unless every frozen gate holds.

One job ran on the dev runtime at source c48994c268c6 (native digest 17f3ccca02d5..., 3.5 s, 239 MB): a closed-shell hydrogen cell as RHF and as singlet UHF, a hydroxyl doublet and a hydrogen triplet, each on the three characters of a (3,1,1) mesh in STO-3G. That runtime predates the acceptance repair above; every case has complete rank, where the repair changes nothing.

Quantity

Worst value

Gate

Returned spin Fock against h + J - K - xi S D S with one scalar xi

2.8e-15 Ha

1e-10

Reported energy against the ledger and its half-Fock form

2.2e-16 Ha per cell

1e-10

Coulomb reciprocity on Hermitian families, generic and conjugation-symmetric

6.9e-16 Ha

1e-10

Exchange reciprocity, generic

6.7e-12 Ha

1e-10

Exchange reciprocity, conjugation-symmetric

1.7e-13 Ha

1e-10

Ledger slopes at a displaced state against the rebuilt Fock

1.4e-11 Ha

2e-9

Smallest slope signal

3.1e-2 Ha

at least 1e-4

Spin splitting of the open-shell Focks

0.89 Ha

at least 1e-3

UHF minus RHF energy on the same source

-2.2e-16 Ha per cell

1e-9

The slopes use eight directions per case: the real and the imaginary generator of one occupied-virtual pair, for each spin, at the real character and at one complex character. The displaced densities are generic complex Hermitian families, without the conjugation symmetry of a real lattice density, and separately with it. The hydrogen triplet has two orbitals per character, so one spin is completely full and the other empty: it has no occupied-virtual direction, and its slope gates are recorded as not applicable.

This is same-Hamiltonian finite algebra on small cells. It shows that the executed classic factors of these calculations satisfy the reciprocity hypothesis and that the returned operators are the gradient of the reported energy. It qualifies no accuracy, stability or convergence property, and it does not transfer to the short-range source, whose reciprocity failed on a recorded case (#453).

Runtime containing the repair, and a reduced-rank cell

A second job ran on the dev runtime at source a4c86bcfb8e7 (native digest 0fa0fb67c2b6..., 20 s, 292 MB), which contains the acceptance repair. The synthetic check passed there in import mode, on the installed function. The native check above passed again with all gates, its acceptance record now naming complete-ao and the ranks.

formal/check_chi_reduced_rank_native.py then ran two dense hydrogen cells in 6-31G whose diffuse functions are nearly the same Bloch function at the Gamma character, so canonical orthogonalization removes one AO direction there. They are not materials.

Cell

Ranks

Projected residual

Unprojected commutator

Slopes

H2 and He, 2.4 bohr, Gamma only

5 of 6

2.4e-11

1.25e-5

5.5e-11 Ha

H2, 2.3 bohr, (3,1,1)

3, 4, 4 of 4

6.3e-14

1.1e-12

2.6e-11 Ha

Both are accepted on the retained residual. The returned Fock is rebuilt to 1.7e-12 Ha and the ledger reproduces the energy to 1.6e-13 Ha per cell. The slopes are taken inside the retained space, in the frame of the returned orbitals, with steps from 0.16 to 0.02 because the small retained overlap eigenvalues amplify roundoff.

A control job ran the same input on a runtime without the repair (source b4f793452695). The helium cell was refused there after the loop had converged: unprojected residual 1.25e-5, correct fill to 6e-12, consistent energy, termination at the iteration limit. This is the defect on a real calculation and its repair.

The hydrogen-only cell does not discriminate, and the control accepts it. A homonuclear diatomic has inversion symmetry about its bond midpoint in any lattice; the occupied orbital is even and the removed direction is odd, so their Fock coupling vanishes. The helium atom removes that symmetry. A (3,1,1) variant of the helium cell failed in a local run before acceptance with a Hermiticity refusal of the eigenproblem; it is recorded separately and was not run on an identified runtime.

Reduced-rank MP2

formal/check_chi_reduced_rank_mp2_native.py seals native chi RHF references and compares the production canonical MP2 with an independent closed-shell sum over the executed AO factors and the returned orbitals. On the runtime at source a4c86bcfb8e7, which accepts the reduced-rank SCF but predates the projected correlation admission (#1194), its control mode ran as one job (11 s, 267 MB):

  • the complete-rank hydrogen fixture on (3,1,1): production MP2 -0.009542060743765108 Ha per cell, equal to the independent sum within 1e-17;

  • the helium cell with 5 of 6 retained directions: the returned orbitals are one array, canonical on the projected condition to 4.4e-11 while the unprojected product is 1.1e-4, and the MP2 admission refuses the reference as not stationary. The independent sum on those orbitals is -0.010360978553248 Ha per cell.

That refusal is the defect of #1194 on a real calculation.

The same script without --control, with byte-identical inputs and gates, then ran as one job (11 s, 287 MB, zero retries) on the runtime at source d54ee9fb20e7, which contains the admission change. All 15 frozen gates pass:

  • the complete-rank fixture is unchanged to the last digit;

  • the helium cell is admitted and the production MP2 is -0.010360978553245474 Ha per cell, 2.7e-15 from the independent sum, which is itself identical on both runtimes. The frozen limit is 1e-9.

The reduced-rank cell is Gamma only, so this run does not exercise a truncated space on complex characters. It covers restricted closed-shell MP2; unrestricted MP2 and CCSD on a reduced-rank reference have source-level regressions only.

Remaining obligations

  • Larger cells, other bases and the short-range source. The native checks cover small classic cells, and the reduced-rank cells are constructed dense hydrogen cells.

  • Near-dependent cells on complex characters that reach the eigenproblem Hermiticity refusal.

  • A native reduced-rank reference on complex characters with same-source MP2. The recorded native run (#1194) is Gamma only, and the synthetic regression uses an orthonormal metric and prescribed canonical Focks.

  • Native unrestricted MP2 and CCSD on a reduced-rank reference.

  • Truncated spaces for local MP2 and the gradients, each with its own examination.

  • The final acceptance of the direct four-centre route and the generalized ROHF gradient were not examined.

  • Stability, minimality, occupation selection and SCF convergence are separate properties. A vanishing residual proves none of them.

The route-by-route status is in the chi matrix.