vibe-qcDocumentation

UHF mathematical specification¶

This extension proves selected real, integer-occupation UHF identities. Implementation and independent-reference checks passed for the case below. It does not claim spin purity, SCF convergence or a minimum-energy solution.

Spin densities and energy¶

Use separate occupied coefficient matrices with \(C_\sigma^TSC_\sigma=I\). The single-spin density is \(P_\sigma=C_\sigma C_\sigma^T\), with no factor two. Cycling the trace gives \(\mathrm{Tr}(P_\sigma S)=N_\sigma\); multiplication through the occupied metric gives \(P_\sigma S P_\sigma=P_\sigma\). These are spin_density_count and spin_density_metric in Extensions.lean. The two occupied index sets can have different cardinalities.

With the RHF integral conventions, let \(P=P_\alpha+P_\beta\). Opposite spins contribute Coulomb interaction but no exchange. Thus

\[F_\alpha=h+J[P]-K[P_\alpha],\qquad F_\beta=h+J[P]-K[P_\beta],\]

\[E_{\rm el}=\langle P,h\rangle+\tfrac12\langle P,J[P]\rangle -\tfrac12\{\langle P_\alpha,K[P_\alpha]\rangle+ \langle P_\beta,K[P_\beta]\rangle\}.\]

Distributing the contractions proves the implemented energy expression

\[E_{\rm el}=\tfrac12\sum_{\sigma=\alpha,\beta} \langle P_\sigma,h+F_\sigma\rangle.\]

uhf_half_fock_energy proves this identity for arbitrary finite real arrays. uhf_closed_shell_fock proves reduction to the RHF Fock matrix when \(P_\alpha=P_\beta=D/2\). The separate spin stationarity conditions are \(F_\sigma P_\sigma S=SP_\sigma F_\sigma\). Their orbital variational origin and the UHF energy derivative remain to be formalized.

Implementation correspondence¶

cpp/src/uhf.cpp constructs each occupied density without a factor two, builds the common Coulomb matrix from the total density, subtracts each spin’s full exchange, and computes the half-Fock energy above. check_extensions.py tests an OH doublet/STO-3G calculation at O=(0,0,0), H=(0,0,1.8), in bohr, with five alpha and four beta electrons. It independently reconstructs both Fock matrices, densities, metric projectors, counts and energy, and checks the two metric commutators. A deliberately halved exchange must fail. Absolute molecular tolerances are \(2\times10^{-8}\) atomic units.

Reference: Helgaker, Jorgensen and Olsen, Molecular Electronic-Structure Theory, Sections 5.4.3 and 10.6, DOI. UHF permits different spatial orbitals for each spin; it need not be an eigenstate of total spin. Formal spin-contamination analysis is outstanding.

Measured acceptance¶

On 1 November 2026, vibe-qc 0.18.5 at source 006069bd8c005aa32ca60c60814f7cf50ef1b25e gave -74.36040547332445 hartree; ORCA 6.1.1 gave -74.360405473220 hartree. The absolute difference was \(1.045\times10^{-10}\) hartree, within the preset \(10^{-8}\) tolerance. The largest spin-density residual was \(1.556\times10^{-13}\); the energy contraction residual was zero at the reported precision. These are measured residuals, not general error bounds. The matched input is reference_oh_uhf.inp.