vibe-qc/Documentation

From a neutral finite torus to local correlation in crystals

This roadmap starts at source f50255a1. The Li UKS row includes validation landed in 8019668d. It covers energies. An experimental method can be usable for a specified system class without becoming the default or acquiring a general accuracy guarantee. Issue numbers below refer to development work. See the real-Gamma increment ledger, the route matrix, the MANTA operator contract, and local-correlation parity for the underlying implementations.

What is already known

Object	Executed behavior and evidence	Limit
Gamma-CCM in Paper 1 (also called Gamma-AICCM in planning)	A neutral finite Born-von Karman torus with the zero Fourier component removed. The real-Gamma supercell and commensurate full-mesh neutral-Bloch representations are Fourier partners for one translation-invariant operator and compatible state. Select the variant explicitly.	Equal mesh dimensions alone do not match the Hamiltonian. The bare Wigner-Seitz four-centre construction and chi-CCM are different objects. Four-centre differences do not measure a representation error.
Real-Gamma HF	Direct RHF/UHF, block factors, evaluated Fock and explicit spin-sector records exist. On the Li doublet two-cell control, real/Bloch UHF differed by 2.61e-13 Ha/cell and independent UHF by 3.3e-12 Ha/cell (#519).	Same multiplicity need not select the same determinant. MgO can reach a second stationary state (#442). The large classic fit tail on the one-cell polarized MgO case has hit admission limits (#761).
KS and hybrids	RKS/UKS and global hybrid paths exist. The Li PBE/UKS representation energy difference was 2.65e-13 Ha/cell. With complete XC support throughout SCF, real-Gamma and independent PySCF differ by 1.951e-10 Ha/cell; the largest spin Fock difference is 1.097e-9 Ha (#519).	This accepts one two-cell Li spin sector on the matched grid, not every basis, mesh, or the default finite XC support. Screened K needs a range-aware backend; an unscreened fitted K cannot implement HSE. External full-grid providers have separate restrictions.
MANTA	Optional native Gaussian integral and contraction provider. RG-8 can supply the fit, one-electron and XC operands; standalone periodic RI-RHF can retain its terminal factors. BUPO supplies Coulomb, not exchange.	Identifying a provider is insufficient: two calculations must bind the same support, ranks, one-electron, nuclear and exchange conventions to assert identity. Independent fits belong on separate error rows.
Post-HF	Canonical finite-cell MP2 and CCSD controls and folded local drivers exist. Standalone three-cell MANTA H2 has full-space, PAO-only, PNO-only, joint and pair-screen controls; the pair-only retained solve differs by 3.47e-18 Ha/cell from its matched control (#582). Molecular water frozen-core fit error reached 89 microhartree despite full-space solver agreement near roundoff.	The signed-transfer H2 oracle has one occupied and one virtual band per character (#1001). Neither the fit error nor the small pair-control difference establishes bulk accuracy. A folded molecular solve has different memory costs from translation-native iteration.
CC and triples	The translation residual shares the compiled molecular equations; complete strong-pair residuals and raw energies can be checked at arbitrary amplitudes. #888 joined selected molecular TNOs to an occupied-coupled solve.	Neither establishes converged translation-native CCSD(T). The molecular compatibility triples path, local T0 and iterative local triples are different algorithms. ORCA repeated-label TNO ranks can disagree (#889).

Initial physical scope: neutral, three-dimensionally periodic, gapped, integer-occupation cells with an explicit diagonal supercell, matched lattice convention, basis, fit and charge. Molecular calculations serve as isolated limits and independent local-correlation controls. Complex full-mesh Bloch amplitudes may enter a real torus only with the required conjugate partners, real gauge and projector checks. Record restricted and independent alpha/beta states separately. Fractional occupations, genuinely complex magnetic states, spinors, arbitrary twists, metallic thermodynamic limits, charged cells, isolated low-dimensional kernels, gradients and arbitrary ECPs need independent contracts. An insulating chain with transverse vacuum is still a three-dimensional boundary condition. A selected scalar ECP requires matching effective electron counts and an independently qualified operator.

Release sequence and decision points

These are scoped increments that may span releases. Numbers are proposed budgets unless attributed to an existing gate. Failed or unsupported rows stay visible.

1. Finite operator and state. Under #519/#632 bind S, h, nuclear energy, fit factors and retained metric, full mesh/weights, q=0 treatment, XC support, spin and occupations. For a block-circulant operator, compare each Fourier block and its action on a test density, then compare final projectors in the overlap metric. For restricted HF use F=h+J[D]-K[D]/2 with spin-summed D; for UHF use J of the total density and K of each spin. Check electron traces, per-cell energy, achieved energy step and FDS-SDF. Reuse Li controls. Expand to asymmetric mesh LiH and polarized MgO; cross-start or cross-evaluate stationary states before attributing a discrepancy to representation. Keep #761’s physical cutoff and resource guard; a refused row is not zero error.

2. DFT and hybrid energy. Integrate the same density and, for GGA, its gradient on the same weighted points; potential must differentiate the discretized energy. Janetzko et al., Eqs. 27-32, treat image functions and the atomic partition; adopting this for a fitted torus still requires numerical proof. Hold D fixed while varying grid and image support independently, then rerun both SCFs on matched supports; measure both spin potentials. Start PBE, then PBE0 with its full-range exact-exchange fraction and matching Madelung seam. For screened exchange explicitly evaluate the short-range operator, match omega and the exchange fractions, and test the appropriate zero-range-parameter limit. Reject incompatible backends. Exit for a same-source row: 1e-10 Ha/cell representation energy (existing #519 budget), with achieved residual <=1e-9 and a common-frame Fock/projector comparison. An unmatched physical grid remains a named error term. Double hybrids, meta-GGA ingredients and other XC providers require separate admission.

3. Independent canonical MP2. Use #1001 before drawing any multiband local conclusions. In a fixed finite RHF Hamiltonian compare the momentum-conserving ordered occupied-virtual sum of conjugated direct times (twice direct minus exchange), divided by orbital-energy denominators, to the explicit supercell sum per primitive cell. Retain the physical occupied Fock including its declared exchange seam; freeze a projector, not a band index inferred independently on each side. Zero all local thresholds. Require the raw result, not a canonical correction masking an error. Reject singular denominators and unverifiable carried factors. Test odd/even transfers and deliberately wrong multiplicity. A dense reference is for capped verification only.

4. Controlled local MP2. Nejad et al., Secs. II and IV A, exploit translated home-cell occupied pairs and PAOs. Do not equate the present seed/metric construction with their localized orbitals or local fit. Under #582 compare cyclic translations, active/frozen metric projectors and boundary-wrapping occupied orbitals. Project AO domains out of occupied space, remove linear dependence, diagonalize the pair density and solve coupled pair amplitudes in retained PNOs. Report domain cutoff, overlap cutoff, pair-energy cutoff, PNO occupation cutoff, strong/weak/distant policy and named corrections independently. Enlarge each space alone before crossing cutoffs; errors can cancel. Full space must recover the raw canonical energy within 2e-9 Ha/cell, residual <=1e-11 and energy change <=1e-13 Ha (#591 controls). Test size additivity on separated neutral replicas and invariance of the full-space energy to allowed orbital rotations. Truncated results may depend on localization; quantify it. Independent-spin UMP2 requires aa/ab/bb orbital spaces, occupancies and denominators (#588); no ROHF/QRO or KS substitution.

5. Restricted CCSD. Feed the accepted source, domains and translation transports to the existing compiled residual; solve projected exp(-T) H exp(T) singles/doubles equations (#586). First iterate only the complete strong-pair inventory; compare raw residual blocks at nonzero amplitudes, converged energy and amplitude changes to a capped unreduced solve. Then define each weak-pair approximation and restoration term separately. Check translation stabilizers, non-diagonal occupied Fock and size extensivity. Never emit triples from unconverged CCSD. Broader UCCSD and spin-adapted open-shell CC are separate increments.

6. Triples. First derive orbit weights for full, repeated and self-inverse translated labels, then verify a nonzero canonical triples limit. For local T0 construct each triple space from normalized strong-pair densities and evaluate semicanonical diagonal denominators (Riplinger et al., triples-space and energy equations). For local T1 restore occupied-Fock coupling by transporting neighboring triple amplitudes between distinct TNO frames (Guo et al., Eqs. 1-3 and SI). Keep TNO occupations, weak-pair treatment and energy corrections explicit. #587 owns the periodic adaptation: neither the molecular papers nor #888 derive cyclic multiplicities. Test diagonal-Fock reduction to T0 and full-rank recovery against canonical (T) with off-diagonal occupied coupling; do not require T0 alone to recover canonical (T) in an arbitrary localized gauge. Stop a parity claim on an unresolved #889 rank discrepancy. Report finite-Hamiltonian and local-approximation errors separately.

7. Whole-method cost and external science. Measure the current path before changing it. The historical LiH 6.6-bohr radius ceiling occurred while the old implementation formed dense factors and all pairs before truncation. Target an insulating sequence beyond that radius with compact factors and translation-unique pairs. Record source preparation, SCF, localization, pair selection, MP2, CC iterations and triples separately and end-to-end, plus peak RSS, thread counts, compiler/build, repeated timings and errors. Keep problem, machine, thread placement and thresholds fixed in paired runs; separate backend, screening and representation ablations. Compare against the best applicable Bloch/canonical and existing local approach, not just the oldest dense path. Claim a gain only where repeat variability is smaller than the improvement and both runs meet the same accuracy budget. Derive any empirical exponent from a size range spanning several local domains and publish the range/crossover. Stop at a memory ceiling with an explicit censored result.

What would support a paper

Proposed claim	Evidence, ablation and independent comparator	Artifact and limit
A single finite functional gives consistent energies in both representations	H2 and gapped LiH/MgO; vary representation only, then intentionally mismatch spin, fit or XC support. Fixed-density derivatives separate operator errors from SCF roots.	Archive operators or reproducible recipes, projectors, raw components and SCF residuals. No proof of accuracy at infinite mesh.
Accuracy survives the finite-size and local approximations	LiH, MgO, diamond in polarized bases; vary mesh/radius, basis/auxiliary rank and PAO/pair/PNO/TNO thresholds independently. Match CRYSTAL23 mean field; for correlation use periodic KMP2, method-matched CRYSCOR or published periodic reference with justified remaining differences. Compare molecular frozen-core/direct and fitted variants to matched ORCA 6.1.1 recipes.	Per-cell raw energies, cohesive or relative energy with matching fragment references, error components and uncertainty. Define a target for the observable before running (proposed 1 kJ/mol per formula unit for a relative energy, not a universal total-energy tolerance). No extrapolation unless successive rungs and model sensitivity support it.
MANTA makes a previously inaccessible calculation useful	Hold locality fixed, change producer only on matched finite support; then hold producer fixed, change locality. Include preparation, more than one orbital band, a difficult small-gap or ill-conditioned case and at least one size past the previous ceiling.	Reproducible decks, hardware and resource records, failed runs and matched-accuracy frontier. A kernel speedup, a faster but different fit or a toy H2 result cannot establish this.
Periodic CCSD(T) adds predictive information	Nonzero triples for a chemically discriminating relative energy; compare CCSD alone, T0 and iterative triples at fixed geometry and domains. Test against finite canonical controls and an independent method where applicable.	Report the CC and triples increments and uncertainty at each level. Without an external matched solid reference, state exactly which component is only internally verified.

The Fourier equivalence and periodic local MP2 both have precedents. The research question is whether representation-controlled local correlation, including a verified triples correction and an identifiable native source, extends attainable accuracy or size for a meaningful crystal observable. A null cost result or a poorly converged property narrows the paper. It does not justify a novelty, production, or journal-readiness claim.

Development ends at checked source on main. Scientific acceptance requires the affected calculation through vq, actual Python and native identities, inputs, convergence history, reference version/settings and units. Reuse accepted rows at their recorded scope. Performance and article acceptance are distinct. Keep all AICCM selectors experimental; method validation, changing defaults and publication are separate decisions.