vibe-qcDocumentation

Tensor engine implementation and migration tracker¶

Parent: TENS-00 (#793). The semantic proposal is the contract starting point, based on the completed tensor-engine-2026-11-02 library study. Status: proposed implementation programme, no engine delivered, no benchmarks run. Issue IDs below identify execution work, not accepted results. The programme is unscheduled and adds no release gate or dependency to #557.

First work and dependency order¶

Begin with TENS-01 (#794) inventory and semantic ADR, then TENS-02 (#795) descriptors and domain identities. TENS-03 (#796) IR and TENS-04 (#797) resource/provider lifecycle can develop against that shared contract. Deliver the molecular RI-J slice TENS-05 (#798) and complex selected-local factor slice TENS-06 (#799) using existing Eigen/BLAS and registered specialized paths. TENS-06 (#799) is a small local/periodic slice, not the full periodic migration or a production-correlation claim.

TENS-07 (#800) uses their measured costs to choose planning/backend crossovers; TENS-08 (#801) generalizes representation capabilities learned from actual sources; TENS-09 (#802) supplies coarse Python ownership/graph submission. A native migration does not wait for an unrelated Python or sparse capability. Optional GPU/MPI and compiler/compression issues start only at their particular capability and evidence prerequisites. There is no whole-umbrella closure dependency.

Package / issue	Deliverable and first claim	Specific dependencies
TENS-00 (#793)	Full-goal coverage and closure ledger	Children and existing scientific owners
TENS-01 (#794)	Enumerate every numerical tensor route and write semantic ADR; start with RI factors and selected-local complex factors	Current main, study, #472/#580/#617 and GPU/MPI records
TENS-02 (#795)	Runtime-rank descriptors, owners/borrows, leases, checked addressing and dependent index identities	TENS-01 (#794) initial ADR
TENS-03 (#796)	Checked indexed/einsum IR, explicit numerical effects and multi-expression DAG	TENS-02 (#795) schema
TENS-04 (#797)	Reservation ledger, provider protocol, sync executor and completion-safe lifetime/failure	TENS-02 (#795) owners; TENS-03 (#796) effects at executor boundary
TENS-05 (#798)	Molecular RI-J CPU slice over actual per-P factors, then one bounded AO transform	TENS-03 (#796) and TENS-04 (#797) minimal CPU capabilities
TENS-06 (#799)	Complex local/periodic panel and selected-pair contraction slice	TENS-03 (#796)/TENS-04 (#797); existing source-admitted factor/MP2 path
TENS-07 (#800)	Bounded planning, layout/packing choice, cache/rebinding and thread/NUMA policy; optional TBLIS measurement	TENS-05 (#798)/TENS-06 (#799) baseline traces; TENS-04 (#797) accounting
TENS-08 (#801)	Sparse assembly, ragged domains, packed symmetry, replay/stream and factor representations	TENS-02 (#795)/TENS-04 (#797) and lessons from TENS-06 (#799); per-format IR support
TENS-09 (#802)	Coarse Python graph/provider handles, buffer/future ownership and device handshakes	TENS-02 (#795)/TENS-04 (#797), one working CPU operation
TENS-10 (#803)	Optional GPU operation adapter and transfer/workspace qualification	TENS-04 (#797)/TENS-07 (#800) relevant contracts, GPU G0 measurements; #639 for MANTA qualification
TENS-11 (#804)	Optional MPI placement/execution adapter, communicator/progress/thread policy	TENS-04 (#797)/TENS-07 (#800) relevant contracts and existing MPI0/MPI1 substrate
TENS-12 (#805)	Integrals, AO-to-MO, RI/DF and SCF/DFT migrations	TENS-05 (#798); representation/Python capabilities only where needed; #472/#617 source/state interfaces
TENS-13 (#806)	MPn, CCD/CCSD/UCCSD, triples and implemented higher-excitation migrations	TENS-05 (#798), needed DAG/representations; #611 admitted references
TENS-14 (#807)	Molecular and periodic local-correlation migrations	TENS-06 (#799), needed TENS-08 (#801) domains; #580/#581 and existing bounded-resource admissions
TENS-15 (#808)	CI/CAS/MR perturbation/DMRG and other implemented active-space solver migrations	Needed TENS-08 (#801) sparse/factor and TENS-09 (#802) capabilities
TENS-16 (#809)	Response, EOM/TDDFT/stability and property migrations	Producer method migrated or a registered compatible kernel; existing #612 mathematical roles
TENS-17 (#810)	Gradients, Hessians, nuclear/cell derivatives and stress migrations	Relevant primal/response and derivative-provider capabilities; #636/#637 where applicable
TENS-18 (#811)	Periodic k/q/multi-k, GPW/GAPW, BIPOLE, AICCM/chi integration	Relevant native/provider operations; #577/#607/#617 and existing finite-source admission
TENS-19 (#812)	All implemented semiempirical tensor routes	Needed small-block/native/Python capabilities; #609/#610 state associations
TENS-20 (#813)	Later compiler/lowering experiment on a measured bottleneck	TENS-07 (#800) profile evidence and stable IR; optional dependency decision if needed
TENS-21 (#814)	Later compression/mixed-precision experiment with method-owned error contract	Exact baseline and explicit scientific scope; no default approximation change

Migration coverage and observed source entry points¶

This is a source navigation inventory, not an assertion that every route is qualified or fully implemented. At main 3ec1a4ae none of these families has been migrated to the proposed engine. TENS-01 (#794) must expand each family into route rows with exact call site, provider, dtype/layout, domain/source owner, resource behavior, implementation/qualification state, issue and evidence. Search C++ loops/Eigen operations and Python matmul/einsum/tensordot as well as arrays named tensor; wrappers alone miss native and callback work.

Family and package	Existing starting points	Required variants and complete-method observables
Integral generation, AO-to-MO, RI/DF; TENS-12 (#805)	`cpp/include/vibeqc/integrals.hpp`, `df.hpp`, `manta.hpp`; `cpp/src/df.cpp`, `integrals.cpp`; `python/vibeqc/correlation.py`	Direct/screened and stored ERIs; ECP/range/derivative sources where present; auxiliary metrics and three-index factors; actual strides/symmetries, factor/transform equality and an affected complete SCF/correlation case
SCF/HF/DFT, exchange and grids; TENS-12 (#805)	`cpp/src/rhf.cpp`, `uhf.cpp`, `rks.cpp`, `uks.cpp`; `cpp/include/vibeqc/jk_builder.hpp`; `python/vibeqc/fock_state.py`, `solvers/operators.py`	Restricted/independent-spin/restricted-open-shell, direct/DF/COSX, grid/XC, fractions/smearing, symmetry and source variants actually present; physical energy/density/Fock, stationarity/closure, iterations and unchanged thresholds
MPn and canonical CC; TENS-13 (#806)	`cpp/src/mp2.cpp`, `ump2.cpp`, `ccsd.cpp`, `uccsd.cpp`, `ccsd_triples.cpp`; `python/vibeqc/cc.py`, `solvers/_cc3.py`, `solvers/_ccsdt.py`	Inventory MP3/MP4/CCD entry points rather than assume their implementation from roadmap claims; canonical/DF, spin/frozen and triples variants; energies, amplitudes, raw residuals and benchmark-scale higher-excitation limits
Local correlation; TENS-14 (#807)	`python/vibeqc/dlpno/`; `cpp/src/dlpno_ccsd.cpp`, `dlpno_uccsd.cpp`; `cpp/include/vibeqc/periodic_correlation_resource.hpp`, `periodic_gaussian_local_orbital_factors.hpp`	PNO/PAO/local domains and independent spins; frozen spaces and translated pairs; staged pair/triple censuses, factor identities, raw residuals/energies and domain/threshold invariance
Multireference/CI/DMRG; TENS-15 (#808)	`python/vibeqc/solvers/_casci.py`, `_casscf.py`, `_cisd.py`, `_selected_ci.py`, `_mrci.py`, `_mrpt.py`, `_ms_caspt2.py`, `_v2rdm.py`, `_dmrg.py`, `_transcorrelated.py`; `cpp/src/casci.cpp`, `nevpt2_ops.cpp`	Determinant actions and sparse assembly, active/root/spin spaces, RDMs, MR intermediates and tensor-network bonds; energies/roots, normalization, RDM trace/symmetry and existing bond/truncation controls
Response and properties; TENS-16 (#809)	`python/vibeqc/tddft.py`, `mpi_tddft.py`, `properties.py`, `properties_casscf.py`, `periodic_gdf_properties.py`; `python/vibeqc/solvers/operators.py`	Matrix-free/batched actions, TDA/full response/EOM where implemented, real/complex and spin; eigenpair residuals, response symmetries, property tensors, sum rules/finite-field checks where applicable; do not cast non-Hermitian problems as Fock solves
Gradients/Hessians/stress; TENS-17 (#810)	`python/vibeqc/gradient/`, `hessian*.py`, `periodic_gapw_stress.py`; `cpp/src/casscf_gradient.cpp`, `hessian_integrals.cpp`; MANTA derivative providers	Every implemented primal method’s nuclear/cell derivatives and response contractions; analytic/finite-difference checks with fixed topology and thresholds, translation/rotation invariance, separate stress/cell normalization
Periodic/CCM overlays; TENS-18 (#811)	`python/vibeqc/periodic/ccm/`, `periodic/chi/`, `periodic_sr_mpi.py`, `mpi.py`; `cpp/include/vibeqc/periodic_correlation_local_factors.hpp`, `manta_periodic_ri.hpp`, `periodic_mean_field_state.hpp`	Gamma/complex multi-k, k/q/shifted mesh, GDF, grids/FFT/Poisson and augmentation, BIPOLE, neutral Bloch/real-Gamma/chi; actual weights/phases, source/support/q=0 conventions, cell-normalized energy and derivatives
Semiempirical; TENS-19 (#812)	`python/vibeqc/semiempirical/` including `methods/` and `seccm/`; `cpp/include/vibeqc/semiempirical/`; shared `python/vibeqc/correlation.py`	Inventory actual DFTB0/SCC-DFTB, GFN/xTB, PM/OM/MSINDO variants and supported molecular/periodic/SECCM routes; tiny irregular blocks, charges/multipoles, two/three-centre terms, method energies, SCC residuals, properties/derivatives and existing restrictions
Other tensor consumers; TENS-01 (#794) routes to existing family issue	Geometry/phonon/elasticity/transport, dispersion/solvation, density/property analysis, learned-model adapters and output transforms where present	Find remaining numerical arrays and assign an operation owner. External optional model internals retain their dependency-owned kernels; vibe-qc-owned tensor preprocessing/postprocessing uses the contract. File serialization and scalar control flow do not need an executor task

Periodic, derivative and property rows are overlays on producer families, not duplicate ownership. For example TENS-14 (#807) owns the local pair contraction; TENS-18 (#811) owns its k/q integration; TENS-17 (#810) owns the differentiated operation. Record one implementing issue per operation, link consumer rows and reuse its evidence. Unsupported/not-implemented variants are stated explicitly, without adding a new method to the scope by inference. Implemented deferred routes retain a concrete issue and next slice; permanent arbitrary bypasses are not an accepted full-engine completion state.

Route record and closure¶

Each route row records: method/variant and entry point; operation/kernels; axes/domain/source/frame identities; representation/layout/dtype; exact or approximate status; provider replay/assembly/workspace; owned/borrowed and external inventory; execution/backend/thread policy; focused source result; complete vq scientific result and actual source/native identity; measured cold/warm/full-method cost; old-path retirement; remaining capabilities. Keep raw operational records outside the product checkout. Repository summaries use portable commands, public references and public-safe evidence.

Use migration states with distinct meanings:

Inventoried: exact route and owner identified; still a legacy execution.
Source landed: common contract actually checks/adopts its execution; focused semantic/resource checks pass and source is on main.
Scientifically accepted: affected complete method passed through vq with matched reference or justified numerical evidence and limitations.
Retired: duplicate execution removed or retained as a registered, admitted specialized path; supported entry points use the common engine.
Unsupported/not implemented: explicit current capability, with no claim that a shared interface implements or qualifies missing physics.

The parent closes only when every implemented route is accepted and retired in this sense, including optional/experimental routes within their admitted scope. Registering specialized kernels is a valid end state; leaving an untracked implementation behind a wrapper is not. Optional compiler or new compression experiments are not prerequisites for the exact core/migration goal and do not keep an otherwise completed parent open. A new approximation does not repair a failed exact-refactoring check.

Checks and pickup¶

The design’s verification protocol and the study’s benchmark matrix supply the starting cases. Set tolerances and performance targets from existing route evidence and pilots before accepting new results. Test exact/below-budget boundaries and delayed async release, not just allocator totals after a successful call. No current result or release support is inferred from this plan.

Workers claim a bounded first increment and files on its issue, read latest main/notes and preserve shared edits and jobs. Specific missing capabilities block only dependent slices. Use existing #472/#594/#580/#581/#617/#639 and GPU/MPI work for their own interfaces and scientific acceptance; no duplicate Fock/provider/symmetry adapter or separate reviewer. Dev runs a focused source check and lands source on main with CI skipped, then completes own cleanup. Validator owns complete vq acceptance and issue closure and may be the same worker. Pending runtime delivery/science does not prolong a finished Dev task. New test files use the curated test-manifest generator. User-visible changes update manuals/citations/changelog as applicable; this internal design adds no runtime feature or changelog fragment.