vibe-qc/Documentation

Complex streamed tensor slice

Status: bounded source implementation for TENS-06 (#799), 2026-11-02. This extends the initial CPU contract; it does not close #793, #795-#799 or #801. Complete scientific acceptance is pending a runtime containing this source. The source commit and runtime pickup record are recorded on #799.

Subsequent source evidence: the bounded planner ADR records #800 RI-J lowering and structural schedule reuse, plus unchanged complex-kernel regression checks. The historical measurements and limitations below describe this earlier slice.

Actual consumers and authority

Entry point	Common-engine operation	Preserved method contract
build_periodic_gaussian_local_orbital_factor_panel	Checked logical coefficient product and AO-pair reduction into a rectangular complex [auxiliary,left,right] panel, one q/auxiliary slice at a time	Actual captured HF/context, gauge hash, local-basis certificate, occupied indices, virtual selection, q source and opposite-source receipts, principal whitener and actual native tile descriptors are validated before adaptation.
build_periodic_correlation_pair_integral_block	Checked G[a,b] += conj(VO[p,a]) * OV[p,b], independently built for every q and auxiliary slice	Existing admitted reference, private reader leases, factor-build/tile limits, source and whitener equality, finite-source receipts and independent orientations remain authoritative.

The first entry point feeds periodic_gaussian_real_local_provider.cpp and therefore the existing selected-pair MP2 workflow. That workflow still uses its separately certified real intermediates. Its projection/certification, PNO/denominator solver, energy normalization and scientific method are not changed. The second entry point is the existing complex selected-pair integral leaf; it is not falsely described as a direct call from that real MP2 driver. No new complex MP2 method is implemented.

#472 retains Fock/state authority, #580/#581 retain reference/factor authority, and #617 retains provider authority. Synthetic factor-stream v1 can exercise transport and refusals; it cannot certify a physical Gaussian producer.

Shared semantics and lowering

tensor/stream.hpp reuses core.hpp’s Budget, Allocation, BorrowScope, View, Space, Domain, leases and IndexProgram. The existing fixed-size Schema moved from ri_j.hpp into core.hpp; there is no second descriptor, allocator, domain system or generic planner.

Method adapters mint source/metric/frame tokens only after authenticating native owners. Tokens are scoped to that invocation, not a hash-to-identity registry or a cross-call cache. The frame binds the actual HF/gauge, ordered occupied placement, PAO domain/space and selection. Auxiliary domains depend on q/source/metric; left/right domains retain selection origins and dependent frame identities. Equal dimensions do not permit mixing different pair spaces or revisions. Source, metric, frame and partition are checked together.

The panel IR describes X[l,r,mu,nu]=conj(C[l,mu])*C[r,nu] and B[p,l,r]+=X[l,r,mu,nu]*A[p,mu,nu]. X and the full AO tensor are logical only. The registered lowering validates an ordered contiguous AO-pair tile map, then reduces that slice. The method’s bounded k/pair loops authenticate every returned tile’s exact range. The cursor checks source, sequence and visit count; it is not a replacement for that coverage/provenance proof.

Two registered CPU paths retain the predecessor arithmetic: cpu.complex.local_panel.compensated.v1 and cpu.complex.compensated_pair.v1. Their layout-specialized branches preserve loop order, multiplication association and independent real/imaginary compensation. Other admitted affine layouts use checked strided execution. Conjugation is explicit on input views, not inferred from matching domains. The panel retains its final (sum+correction) * (1/Nk)/sqrt(Nk) operation; the pair leaf retains its final compensated sum. There is no q/-q shortcut, real projection, reassociation, new screening or approximation in the engine.

Plans check input value revisions at execution. Synchronous leases reject expired borrows, overlapping outputs and conflicting writes. Exceptions leave a failed cursor that cannot resume or finalize. Accumulation is destructive inside a private unpublished native result; it is not transactional rollback. No result escapes the adapter after provider failure. Async completion, replay caches and generalized ragged enumeration remain future work.

Memory and work admission

BorrowScope can import an authoritative live-byte inventory once. Each borrowed allocation consumes credits within it, while multiple views of the same allocation retain that single charge. Credits cannot exceed the imported inventory and return when the allocation handle dies. This is an explicit adapter contract, not automatic deduplication of arbitrary pointer aliases. The native numerical owners and their existing lifetimes remain unchanged.

A conservative 65,536-byte per-worker control envelope admits the bounded views, IR, source tokens, cursor and leases. The panel adds this to its macro object inventory and propagates it into real-provider and density-Gram parent lower bounds. The pair leaf adds it for every rank/worker replica above its existing inner-factor node peak; tensor_control_bytes_per_worker exposes that component. Numerical payload caps remain separate. The panel imports its per-replica inventory, and the pair adapter imports its whole-node inventory with other workers reserved. Engine metadata must fit the added envelope.

Work accounting adds bounded planning/digest overhead before reads: 8,192 units per panel tile or pair factor build. Existing producer work, candidate, image, tile-call, reader and node/rank ceilings remain checked. The cursor stores only source and counters, not all-q keys. No all-q factors, full AO store, coefficient outer product or four-index tensor is allocated.

Tracked bytes are conservative reservations, not RSS. Allocator/runtime/OS costs outside the original CPU ledger boundary are not silently called a hard process-memory guarantee.

Focused evidence

Current C++17 source checks compile independently of an installed QC runtime:

.venv/bin/python -m pytest --noconftest tests/test_tensor_engine.py tests/test_tensor_stream.py -q

Eight cases pass. Four streamed cases also pass AddressSanitizer and UndefinedBehaviorSanitizer. They exercise skewed 3-by-5 pair domains and 2-by-5 panels, genuine imaginary lanes, Hermitian and bilinear products, bitwise predecessor panel parity, independent long-double explicit sums, compensation cancellation, source/metric/frame/q and dependent-domain revision mismatches, expired/conflicting leases, stale plans, provider failure and incomplete/out-of-order streams. Both kernels pass exact-peak admission and refuse one byte below it. Imported-owner overdraw and release are checked.

The bounded test streams 200,003 auxiliary rows in tiles of at most 31: 25,600,384 logical factor bytes with 8,464 tracked peak bytes. This proves bounded transport/execution for generated data, not Gaussian source accuracy. The four changed physical translation units and the dedicated pair binding unit compile with the checkout’s configured native compiler flags.

Existing physical tests remain the integration oracles: test_periodic_gaussian_local_orbital_factor_blocks.py compares rectangles against full panels and independent Gaussian transforms; test_periodic_correlation_pair_integrals.py compares all-q contractions with independent reciprocal sums and exact node/replica boundaries. Their accounting assertions include the new control envelope. They were not executed against an old native extension: collection currently refuses an incomplete basis overlay, and the previously identified installed extension is stale.

Measured cost and decision

The portable microbenchmark is benchmarks/tensor_stream.cpp, built with C++17, -O3 -DNDEBUG, Apple Clang 21 on Apple M5 Max, one caller thread. There is no BLAS call, extra packing or thread runtime in these kernels. Initial general-stride lowering cost 2.38-4.13 times the predecessor loops; this is why the registered layout-specialized loops remain.

Three subsequent process runs measured the following medians in microseconds. Planning constructs fresh IR without execution; repeated use keeps one plan. Fresh-plan execution includes planning and execution with already-adapted views. Provider generation, descriptor adaptation and whole-method cost are not included. Each operation visits one supplied tile and packs zero bytes.

Operation (aux,left,right)	Fresh planning	Reused execution	Fresh plan + execution	Predecessor	Tracked peak bytes
Pair (31,3,5)	0.134	0.961	1.072	0.975	9,336
Pair (48,7,13)	0.139	8.401	8.558	8.387	23,160
Panel (11,1,3), 31 AO pairs	0.305	2.752	2.908	3.127	16,936
Panel (11,7,13), 31 AO pairs	0.314	79.101	78.954	85.410	52,264

The peak includes benchmark inputs, outputs, compensation, views and two live plans during the fresh-plan measurement; predecessor comparison arrays are outside the engine ledger. Observed reused/legacy ratios ranged 0.86-1.38 across these runs. Thermal/order noise and small shapes preclude a general speedup claim. No mandatory external tensor package or benchmark target was introduced. Full HF/MP2 cost remains unmeasured.

Scientific acceptance and remaining work

No complete HF plus selected-pair MP2 calculation on this changed runtime has passed through vq yet. The available default vq inventory lists the QC program as scheduler-only, not as a verified native runtime containing this source. No stale-runtime override or speculative scientific PASS was used. Runtime delivery/Validator should execute the existing admitted finite-source HF/MP2 workflow and physical integration tests, recording source SHA, native module identity, actual gauges/domains/caps and energies. Use matched CRYSTAL only if its reference conventions match; otherwise retain the justified same-source/explicit-sum evidence and state its finite-source limitations. This source record establishes neither production periodic correlation nor infinite-image convergence. #799 remains open for that acceptance and broader stream capabilities; pending runtime delivery does not hold source landing.

The design reuses the library study’s TAMM III-IV (DOI 10.1063/5.0142433) dependent domains and CoRa sections 4-7/CoNST sections 2-5 bounded-iteration evidence. It implements a synchronous, fixed-memory CPU increment, not their distributed/compiler systems or fast-math performance claims. The preserved chemistry follows the existing Sun equations 3, 4, 13, 16, 21 (DOI 10.1063/1.4998644) and Nejad equations 2-10, 26-28 (DOI 10.1063/5.0290816); no scientific approximation is changed. Existing method citations remain in force.