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 |
|---|---|---|---|
|
|
|
Truncated PNOs prevent a canonical CCSD(T) claim. |
Same entry, explicit |
Caller convention and cutoffs; molecular class default is |
Caller mode; wrapper overrides only internal localization to |
Explicit options do not inherit the retained recipe. |
Explicit |
Caller recipe |
T0, diagonal localized occupied Fock |
Full virtual/PNO/TNO spaces are insufficient when occupied Fock is not diagonal. |
Explicit |
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 |
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. |
|
|
|
Complete-space reference route, conditional on accepted source, ranks and converged amplitudes; no production qualification. |
Canonical entry with explicit truncated TNOs in |
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 |
No triples result is certified. |
Unconverged amplitudes, or triples requested but not executed |
Refused after the solve |
|
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.