QuanticsTCI: Migrate to TreeTCI backend + Pure Julia API compatibility + ComplexF64 support

[shinaoka]

Goals and Principles

Tensor4all.jl serves as:

1. A test harness for the Rust backend (tensor4all-rs): The Julia wrapper exercises Rust crate functionality, helping catch regressions and validate correctness.
2. An interoperability layer with the existing Julia ecosystem: Full API compatibility with existing Pure Julia libraries (QuanticsTCI.jl, TensorCrossInterpolation.jl, etc.) is not a goal. Instead, we provide data conversion functions that enable interoperability and gradual migration.
3. A tree-first architecture: Chain-specialized legacy code paths are eliminated in favor of tree-general implementations. Exceptions are made only for performance-critical operations (e.g., MPO-MPO contraction) where chain-specific algorithms have significant advantages.

---

Architecture Overview

Current Architecture

Tensor4all.jl (Rust C API wrapper)
├── C_API, Index, Tensor           ← tensor4all-core (foundation types)
├── SimpleTT                       ← tensor4all-simplett
├── TreeTN (MPS/MPO/TTN)           ← tensor4all-treetn
├── TreeTCI                        ← tensor4all-treetci
├── QuanticsGrids                  ← quanticsgrids-rs
├── QuanticsTCI                    ← tensor4all-quanticstci (tensor4all-tensorci backend)
├── QuanticsTransform              ← tensor4all-quanticstransform
└── ext/ITensorsExt                ← ITensorMPS.MPS ↔ TreeTN.MPS conversion

Target Architecture

Tensor4all.jl (Rust C API wrapper)
├── C_API, Index, Tensor           ← tensor4all-core (foundation types)
├── SimpleTT                       ← tensor4all-simplett
├── TreeTN (MPS/MPO/TTN)           ← tensor4all-treetn
├── TreeTCI                        ← tensor4all-treetci
├── QuanticsGrids                  ← quanticsgrids-rs
├── QuanticsTCI                    ← tensor4all-quanticstci (★ tensor4all-treetci backend)
├── QuanticsTransform              ← tensor4all-quanticstransform
├── ext/ITensorsExt                ← ITensorMPS.MPS ↔ TreeTN.MPS conversion (existing)
└── ext/TCIExt                     ← TCI.TensorTrain ↔ SimpleTT.SimpleTensorTrain conversion (★ new)

Key Changes

1. Migrate QuanticsTCI backend to TreeTCI ✅ DONE (feat: migrate QuanticsTCI backend from tensorci to treetci tensor4all-rs#388)

   • API: chain topology only (no user-facing change)
   • Backend: tensor4all-tensorci → tensor4all-treetci (auto-generates linear chain graph internally)
   • SimpleTreeTci renamed to TreeTCI2
   • QuanticsTensorCI2 stores TreeTCI2<V> state

2. C API design rules formalized ✅ DONE (docs+fix: Add mandatory C API rules and fix existing compliance issues tensor4all-rs#389)

   • Immutable (Box<Arc<T>>) vs Mutable (Box<T>) type classification
   • Lifecycle, thread safety, naming, complex number conventions

3. Systematic C API expansion (tensor4all-capi: Systematic C API expansion for Tensor4all.jl tensor4all-rs#390)

   • QuanticsTCI ComplexF64 support
   • QuanticsTCI full options + ranks/errors
   • SimpleTT from site tensors (TCI conversion bridge)
   • SimpleTT basic operations (add, scale, dot, reverse, fulltensor)

4. Julia wrapper updates (after C API expansion)

   • QuanticsTCI: Pure Julia API-compatible signatures, ComplexF64, (qtci, ranks, errors) tuple
   • TCI conversion bridge: ext/TCIExt

---

Work Plan

Phase 1: Rust crate — QuanticsTCI backend migration ✅ DONE

Tracking: tensor4all/tensor4all-rs#388 (MERGED)

Phase 2: Rust crate — C API design rules ✅ DONE

Tracking: tensor4all/tensor4all-rs#389 (MERGED)

Phase 3: Rust crate — Systematic C API expansion

Tracking: tensor4all/tensor4all-rs#390

• QuanticsTCI c64 variants (all functions)
• QuanticsTCI full QtciOptions + ranks/errors + initialpivots + max_bond_error/max_rank
• SimpleTT from_site_tensors (f64 + c64)
• SimpleTT basic operations: add, scale, dot, reverse, fulltensor (f64 + c64)

Phase 4: Julia wrapper — QuanticsTCI update

Target: Tensor4all.jl/src/QuanticsTCI.jl

• Make QuanticsTensorCI2{V} type-parametric
• Change return value to (qtci, ranks, errors) tuple
• Add overloads informed by Pure Julia version:

  quanticscrossinterpolate(::Type{V}, f, grid::DiscretizedGrid; kwargs...)
  quanticscrossinterpolate(::Type{V}, f, xvals::Vector{Vector{Float64}}; kwargs...)
  quanticscrossinterpolate(::Type{V}, f, size::NTuple{N,Int}; kwargs...)
  quanticscrossinterpolate(F::Array{V}; kwargs...)

• Keyword argument compatibility: tolerance, maxbonddim, maxiter, initialpivots, nrandominitpivot, verbosity, unfoldingscheme, ...
• Merge quanticscrossinterpolate_discrete into quanticscrossinterpolate(V, f, size::NTuple) (deprecate or alias old name)
• Add cachedata support

Phase 5: TCI conversion bridge

Target: Tensor4all.jl/ext/Tensor4allTCIExt.jl (new)

• Add TensorCrossInterpolation as a weak dependency (Project.toml)
• SimpleTT.SimpleTensorTrain(tt::TCI.TensorTrain) — convert via site tensors
• TCI.TensorTrain(stt::SimpleTT.SimpleTensorTrain) — extract via site_tensor() and construct
• Add tests

Phase 6: Tests & documentation

• Test all QuanticsTCI overloads (Float64 + ComplexF64)
• Regression tests with TreeTCI backend
• Round-trip tests for TCI ↔ SimpleTT conversion
• Update documentation

Future enhancement (not blocking)

• tensor4all-treetci: Add GlobalPivotFinder for error-driven pivot search tensor4all-rs#383 — TreeTCI: Add GlobalPivotFinder for error-driven pivot search. Evaluate effectiveness after initial migration is complete.

---

Upstream Issues (tensor4all-rs)

Issue	Description	Status
tensor4all/tensor4all-rs#388	QuanticsTCI: Migrate backend to treetci	✅ MERGED
tensor4all/tensor4all-rs#389	C API design rules + compliance fixes	✅ MERGED
tensor4all/tensor4all-rs#390	Systematic C API expansion	Open
tensor4all/tensor4all-rs#383	TreeTCI: GlobalPivotFinder (future)	Open

Design Decisions

• QuanticsGrids: Stays Rust-based (also serves as test for quanticsgrids-rs)
• TensorCrossInterpolation.jl: Not re-exported into Tensor4all.jl (avoids type system conflicts). Only a conversion bridge (ext) is provided.
• QuanticsTCI API: Chain topology only. Backend uses TreeTCI (tree-first principle).
• Chain-specialized code: Eliminated where possible. Exceptions for performance-critical operations (e.g., MPO-MPO contraction).
• For tree topology needs: Users combine QuanticsGrids + TreeTCI.crossinterpolate2 directly.
• ITensorMPS compatibility: Already handled by existing ext/ITensorsExt.
• GlobalPivotFinder: Deferred to post-migration. Effectiveness unclear; evaluate after initial migration.
• C API mutability: Immutable types use Box<Arc<T>>, Mutable types use Box<T>. See docs/CAPI_DESIGN.md.

Related Repositories

• Rust backend: https://github.com/tensor4all/tensor4all-rs
• Pure Julia QuanticsTCI: https://github.com/tensor4all/QuanticsTCI.jl (API reference)
• Pure Julia TCI: https://github.com/tensor4all/TensorCrossInterpolation.jl (conversion bridge target)