vibe-qcDocumentation

Retained chi CC recipes and exact-limit audit

Explicit fitted-support RHF transport

The retained restricted CCSD and CCSD(T) wrappers accept a sealed ChiHFReference from the classic or the range-separated finite-contract producer; a classic reference may come from a checkpoint reload. The caller names the executed source of its reference in fit_source ("classic" or "sr"); a name that differs from the reference is refused, and no other fit is built (issue 1188). The adapter validates the original physical request, executed controls and factor descriptor, then derives a distinct real-torus CorrelationSource. The producer’s source, support, state, factor, metric-rank and runtime identities, plus each transfer’s retained metric projector, remain in the transformation record; none is renamed to the older canonical-modrho frame. The accepted terminal Fock, overlap, density and occupations are used as returned. No SCF or fit is repeated.

Auxiliary admission compares the consumer’s requested basis with the sealed physical request, resolving an omitted request with the usual default. The executed auxiliary descriptor can carry the producer’s transformed label, such as def2-universal-jkfit-modrho for a def2-universal-jkfit request. Its label, content fingerprint, factors and metric projectors remain sealed; the adapter neither strips the suffix nor rebuilds or renames that source. The transformation record retains requested, resolved and executed auxiliary identities separately. A changed consumer request or executed identity is still refused.

For N complete unshifted characters with chi_i(R)=exp(ik_i R), the AO operator home row is A[0,T]=N^-1 sum_i chi_i(T)^* A_i and the corresponding real auxiliary factor is B[tP,Ru,Sv]=N^-2 sum_ij chi_i(R-t) chi_j(S-t)^* L[ij,Pu v]. The complex finite-source Gram contracts each canonical factor with the adjoint of the factor at the same transfer. The real provider sums over all translated auxiliary cells and the wrapper divides the supercell CC and triples energies by N once. This is the unitary finite Fourier convention of Nejad et al., JCP 163, 214107 (2025), Sec. II, Eqs. (2)-(10). The adapter checks inverse factor transforms, real symmetry, overlap/Fock round trips, accepted-density and occupied-projector preservation, and the full real generalized Fock eigenproblem. A representation change receives its own identity; it does not change the sealed producer identity.

The admitted mathematical domain is neutral 3D classic or range-separated RI-RHF with integer Aufbau occupations, a complete uniform unshifted character mesh, positive retained metric modes in a common canonical auxiliary frame, no frozen core, and a real finite-torus Hamiltonian. A complex factor gauge that has no real translation representation is refused. The current implementation uses the complete dense torus orbital space and home auxiliary tensor; overlap-reduced orbitals, ECPs, tailed or screened support, SR fitting, and active frozen-core selection remain outside this adapter. These are implementation restrictions, except the complete character/weight and common-frame conditions required by the stated transform. Numerical CCSD(T) agreement, PNO truncation error, physical accuracy and scaling remain unqualified. Chi stays experimental and D93 fitted/post-HF stays not-qualified.

formal/check_chi_retained_cc.py is the single-job native continuation for the frozen Paper 2 H2 packet. It checks the packet hashes, handles an authentic accepted checkpoint, records loaded Python/native identity, runs canonical and localized complete-space CCSD(T), reconstructs the same MO Hamiltonian for independent PySCF RCCSD(T), checks full-space residuals, applies a fixed occupied rotation and a diagonal-triples shortcut control, and enforces the unchanged energy and per-cell gates. It must run in a vq allocation on a qualified runtime containing this adapter, audit 3a417ebb and triples fix 11687db, and bounded snapshot prerequisite dcebecec. No native numerical verdict is claimed by the source checks.

The library entries in periodic/chi/posthf.py retain the historical real-torus DLPNO recipe. They are separate from both translation-pair run_chi_local_mp2 and the sealed complex spin-orbital run_chi_ccsd route described in chi CCSD. No threshold conversion or PNO normalization unification is performed. Chi remains experimental; D93 fitted/post-HF remains not-qualified.

Route matrix

All retained real-torus routes use supercell amplitudes and integrals. The wrapper divides HF, correlation, triples and total energies by n_cyclic_cells once. fit_source="classic" consumes the retained fit; historical auto can refit and must be read with reference_execution and same_source.

Request

Executed PNO recipe

Triples and occupied treatment

Exact-limit eligibility

run_aiccm2026dev_b_dlpno_ccsd_t, no options

legacy, PNO 1e-7, diagonal scale 1, MKN/pair/radius 0, PNO correction off

t1 compatibility, occupied Jacobi rotation; default TNO 0

Truncated PNOs prevent a canonical CCSD(T) claim.

Same entry, explicit LocalCCSDOptions

Caller convention and cutoffs; molecular class default is mp2

Caller mode; wrapper overrides only internal localization to none after preparing orbitals and the method’s triples request

Explicit options do not inherit the retained recipe.

Explicit triples_mode="local"

Caller recipe

T0, diagonal localized occupied Fock

Full virtual/PNO/TNO spaces are insufficient when occupied Fock is not diagonal.

Explicit triples_mode="t1"

Caller recipe

Jacobi-diagonalized occupied Fock, both occupied amplitude legs and occupied integral legs rotated

Full spaces and successful occupied diagonalization are required; this is the compatibility rotation, not iterative local T1 equations.

Explicit triples_mode="exact"

Caller recipe

Full-virtual expansion, occupied and virtual Fock diagonalization, all amplitude and integral legs transformed

Exact canonical (T) on the supplied converged amplitudes. Truncated CCSD amplitudes do not become canonical CCSD. TNO cutoff is inactive.

run_aiccm2026dev_b_ccsd_t, no options

mp2, complete PNO/PAO/pair/coupling spaces, no localization, full residual domain

exact

Complete-space reference route, conditional on accepted source, ranks and converged amplitudes; no production qualification.

Canonical entry with explicit truncated TNOs in local or t1 mode

Refused before reference work

Does not execute

A canonical backend label cannot conceal a nonzero active TNO cutoff.

CCSD without triples

Requested density retained

Executed triples metadata says none

No triples result is certified.

Unconverged amplitudes, or triples requested but not executed

Refused after the solve

RuntimeError; the capped iterate is attached as solver_result for diagnosis

No energy is returned from unconverged amplitudes, and no total carries a triples label without a triples energy (#1180).

Three refusals apply to every library route, with or without a sealed reference. Unconverged coupled-cluster amplitudes raise, for the restricted, canonical and unrestricted entries. Truncated domains (tcut_mkn > 0) require domain_criterion="mulliken", because the DOI criterion integrates on an open-boundary molecular grid that is not defined on the torus (#1184); tcut_mkn = 0 keeps complete domains under either criterion. On the default path, where the route runs its own SCF and takes the lowest orbitals of the supercell Fock, the reference must have integer, character-independent occupations and a gap above 1e-12 Ha between the occupied and virtual levels of the returned Fock across all characters (#1193). That floor is the chi canonical denominator tolerance. Nothing is reordered or regularized.

AICCM2026DevBDLPNOCCSDResult.recipe_metadata records the entry point, default versus explicit selection, requested and solver option snapshots, resolved executed pno_norm, threshold provenance, active cutoff settings, requested and executed triples, algorithm description and per-cell divisor. The existing triples_mode field remains the requested mode for compatibility; consult recipe_metadata["triples_mode"] and triples_executed for execution. The record explicitly retains qualification="not-qualified".

Density, selection and labels

For real amplitudes the retained legacy density is (T T^T + T^T T)/(1+delta). The mp2 convention instead uses Ttilde=(4T-2T^T)/(1+delta) and D=Ttilde T^T+Ttilde^T T. For off-diagonal T=[[1,2],[0,0]], these give [[6,2],[2,4]] and [[20,4],[4,16]]; diagonal normalization halves each. The tests exercise the resolved recipe returned by chi dispatch, including the MP2Norm alias and caller-option preservation. This is not a scalar conversion of cutoffs.

The shared CC solver loops over complete active supercell orbital indices, not only home-cell band indices. Its delta=(i==j) therefore compares full placed orbitals: equal bands in different cells are off-diagonal. The optional translation-orbit census is diagnostic; it does not replace this solver loop. After sorting occupations, positive thresholds use strict > (ties excluded), an empty selection retains the leading direction, and zero cutoff retains null directions. Diagonal effective cutoff is tcut_pno*tcut_pno_diag_scale. These shared selection branches were source-inspected without editing them. The existing dense-versus-translation tests in test_dlpno_mp2.py cover placed labels and strict/fallback selection; new generic null-space and spin-adapted coverage remains with the chi MP2 owner. This audit does not claim those MP2 checks qualify the CCSD residual or energy.

Exact triples transformation

ccsd_local_solver.run_local_dlpno_ccsd dispatches triples only after convergence. For exact, triples_local.exact_triples_correction expands each pair as U_ij T_ij U_ij^T, fills the reversed occupied pair by transpose, and expands diagonal-pair singles. It diagonalizes C_act^T F C_act and the full virtual Fock, producing C_can=C_act R_o, C_vcan=C_vir R_v and U_o=C_can^T S C_loc. It then forms t1c=U_o t1f R_v and applies both U_o and both R_v legs to doubles. DF transforms are recomputed in the same coordinates for oo, ov and vv; _blocks forms ovvv, ooov and ovov. cs_triples_correction sums ordered occupied triples using those eigenvalues. Frozen orbitals are excluded from the occupied diagonalization. The returned supercell correction is divided only in the chi wrapper.

The existing seeded gauge fixture has three active occupieds, four virtuals, one frozen orbital and a nonorthogonal AO metric. Its independently canonical Python contraction agrees with the exact path under occupied-only, virtual-only and simultaneous rotations (absolute tolerance 1e-13 Ha, relative 1e-10). A new negative control reuses the same fixture with full pair spaces but diagonal localized occupied gaps:

Contraction

Energy (Ha, synthetic fixture)

Canonical/exact rotated-source result

-1.2726922894245602e-5

Diagonal localized shortcut

-1.2798557974971221e-5

Shortcut minus exact

-7.163508072561974e-8

The negative-control requirement is abs(difference)>1e-9 Ha. No SCF, CCSD iteration, native triples kernel, LiH job or new full calculation was run.

Evidence and limits

The focused chi dispatch and existing gauge/default tests passed: 16 tests. Twelve existing density-convention checks also passed; the two new TNO-refusal cases fail against the unmodified source with no exception raised. The retained default test already existed; this increment adds explicit recipe, execution-state, per-cell, negative-shortcut and TNO-label admission checks. Two demonstrated defects are fixed: absent complete recipe/executed-triples provenance, and a canonical wrapper accepting active TNO truncation. Shared solver/triples algorithms, BIPOLE work and molecular reproducibility work are unchanged. Source/module/native identities and the exact test selection are in the audit identity record.

The occupied rotation and CC energy statements remain source-inspected and Python-tested behavior outside the local-MP2 Lean coverage. Remaining obligations include matched external CCSD(T) evidence, full residual convergence and space limits, general-domain control, native acceptance and broader production qualification. A zero threshold or the word exact is not a numerical verdict.

Bounded final-amplitude evidence

The explicit same-source chi adapter supports pair_snapshot_max_bytes for complete-space RHF with full residual domains, zero frozen core and all truncation cutoffs zero. Set release_df_tensors=False. The existing immutable pair snapshot records the final singles, doubles, pair coefficients, occupied and virtual frames, factor hashes and source identity. Its numerical payload is checked against the requested cap before iteration and at capture. No snapshot is returned for an unconverged solve. Molecular factor leases are not admitted by this chi extension. Capturing operands is not numerical qualification; the independent harness must evaluate the returned solution.

Frozen qualification harness

The qualification harness persists result.json atomically before execution and after each stage. Every required stage begins as UNEXERCISED; exceptions are recorded as FAIL, while a numerically insensitive control remains UNEXERCISED. The global outcome cannot be PASS with an unexecuted stage. Existing execution records are never overwritten. The immutable original chi blocks, accepted Fock and metric metadata, final A/B pair snapshots, canonical amplitudes and fixed-rotation operands have bounded, hashed archives.

The CC transformation copies only the validated small metric vectors into JSON-safe provenance values. This also supports chunk-backed metric metadata restored from an accepted checkpoint. The producer’s support chunks, metric projectors, factors, sealed identities and auxiliary labels remain unchanged; the shared source serializer continues to refuse unsupported object types.

The independent integral oracle uses explicit finite Fourier sums of the original factor blocks. It does not call the production factor transform. PySCF receives that finite normal-ordered Hamiltonian without running SCF. Its converged solution is only arm C. Separate evaluations of the unpreconditioned singles and doubles residual numerators use reconstructed A/B amplitudes as explicit arguments. Each arm also has separate singles and doubles perturbation controls, with the oracle solution held unchanged. These results are distinct from the production preconditioned pre-DIIS iteration residual.

The fixed angle is 0.31 radians between the first and last canonical occupied orbitals (indices 0 and nocc-1), declared before the native calculation. All occupied amplitude legs, orbital coefficients and integral legs are transformed without any CC iteration. Exact and diagonal-localized triples consume these same saved operands. Native spatial triples provide an additional contraction check. Only these fixed-amplitude comparisons use the frozen rotation tolerance; separately converged A/B energies use the frozen energy agreement gates. A vanishing occupied-Fock mixing or unresolved shortcut difference is not a pass. No post-result rotation search or tolerance relaxation is allowed.

Runtime admission accepts either an authenticated portable runtime bundle or an existing qualified immutable vq source slot. For a source slot, supply --runtime-receipt with the runtime owner’s private JSON receipt containing qualified: true, source_revision, native_core_sha256, immutable_root and nonempty build_provenance. The harness verifies the loaded module and native identities, source ancestry, clean source-slot identity and loaded-path containment. The receipt must come from actual runtime qualification; writing these fields is not itself qualification. The source repository argument is used for read-only ancestry and exact module-byte comparisons. PySCF is a harness dependency, never a product solver dependency.

Within the single authorized vq allocation, run:

python -B check_chi_retained_cc.py --packet frozen-packet \
  --output results --source-repository "$SOURCE_REPOSITORY" \
  --runtime-source "$QUALIFIED_SOURCE" --runtime-receipt runtime-receipt.json \
  --build-checkpoint

Omit --build-checkpoint only when an authentic matching results/reference.vqr has been restored before execution. Portable bundles use their qualified artifact pin instead of the source-slot receipt. The allocation remains 2 CPUs, 4096 MiB, 7200 seconds and zero retries. Operational receipts and operands stay outside the product checkout. Source tests do not establish native H2 acceptance.