Feature proposal: selected-index tensor utilities for multi-axis QTT workflows

[shinaoka]

Summary

This is an umbrella feature request for general tensor-network and quantics utilities that would make downstream multi-axis QTT applications easier to implement without writing ad hoc glue code. The motivating use cases are generic: time-dependent kernels, two-point functions, Green's functions, covariance/density matrices, spectral transforms, weighted integrations, and black-box function compression on quantics bit domains.

The common pattern is a tensor network with several semantic groups of external indices, for example time_left, time_right, imag_time, frequency, momentum, or component. Downstream code often needs to apply an operator to only one or a few of these groups, multiply two networks pointwise, sum/integrate out selected groups with weights, or fit a function defined directly on quantics bits. These are general operations and should not require each downstream crate to reinvent index mapping, diagonal embedding, or dense diagnostic materialization.

A key constraint for these workflows is that production implementations should remain tensor-network based. Downstream crates should not need to implement TT -> dense -> operation -> TT workarounds just to express common operations.

Proposed upstream work, in suggested order

Priority	Area	Proposal
P0	tensor4all-tensorci / tensor4all-quanticstci	Bit-level TCI entry point based on tensor-train TCI2
P0	tensor4all-treetn	Bind/apply LinearOperator to explicit external indices
P0	tensor4all-treetn / tensor4all-itensorlike	Hadamard product for compatible external index sets
P1	tensor4all-treetn	Weighted partial sum / integration over selected indices
P1	tensor4all-treetn / tensor4all-core	Group swap/relabel helpers
P1	tensor4all-quanticstransform	Quantics transform constructors bound to user indices
P1	tensor4all-quanticstci	True-error estimators and richer fit reports
P2	tensor4all-hdf5	HDF5 support for TreeTN, LinearOperator, mappings, and metadata

1. Bit-level TCI entry point

Need

High-level QTCI grid interfaces are useful when a function naturally lives on a physical coordinate grid. Some quantics algorithms instead define the target function directly on the local quantics coordinates, for example a closure f(bits: &[usize]) -> Complex64 that splits interleaved bits into multiple logical variables and evaluates a kernel.

Examples:

• a function on mixed bit domains such as r_time + r_tau, where the axes do not have equal length;
• a function on an interleaved pair of variables where the bit order is semantically meaningful;
• fitting exp(F(x) - F(y)), window masks, triangular constraints, or other functions whose natural input is already quantics bits;
• reproducing lower-level TCI workflows that operate on local dimensions rather than a DiscretizedGrid.

This should be based on tensor4all-tensorci, not tensor4all-treetci. tensor4all-tensorci is the maintained tensor-train TCI2 implementation and already matches the desired output type. tensor4all-treetci is appropriate when the desired approximation is a general tree tensor network; using a linear-chain TreeTCI path just to convert back to a tensor train adds an unnecessary layer and is less faithful to tensor-train TCI workflows.

Without this API, downstream code is pushed toward artificial grid wrappers or dense sampling before factorization. Both obscure the intended algorithm and make it harder to expose TCI bugs.

Sketch

pub fn crossinterpolate_bits<V, F>(
    local_dims: &[usize],
    f: F,
    initial_pivots: Option<Vec<Vec<usize>>>,
    options: TCI2Options,
) -> Result<BitTciResult<V>>
where
    V: TTScalar,
    F: Fn(&[usize]) -> V;

pub struct BitTciResult<V: TTScalar> {
    pub tensor_ci: TensorCI2<V>,
    pub tensor_train: TensorTrain<V>,
    pub ranks: Vec<usize>,
    pub errors: Vec<f64>,
    pub cache_size: usize,
}

tensor4all-quanticstci can then expose a quantics-oriented wrapper around this bit-level tensorci API, preserving its 1-indexed grid conventions at the high-level boundary while using 0-indexed tensorci local coordinates internally.

Acceptance tests

• Fit a separable function on local_dims = [2; r] and verify exact values at selected bit strings.
• Fit a mixed-domain function on local_dims = [2; r_time + r_tau] and verify it does not require equal physical axis sizes.
• Fit a complex-valued function and check rank/error reporting.
• Verify initial pivots are interpreted in the same local-coordinate convention used by f.

2. Bind/apply LinearOperator to explicit external indices

Need

LinearOperator already supports partial and non-contiguous application, which is the right abstraction. The remaining friction is binding an operator's internal input/output indices to a state's true external indices. Downstream applications frequently apply an operator to just one semantic axis inside a larger tensor network.

Examples:

• apply a QFT to only time_left while preserving time_right and momentum;
• apply a shift/flip to an imaginary-time axis inside a mixed real/imaginary tensor;
• apply a two-input affine transform to selected time groups while leaving spectator groups untouched;
• multiply by a one-time diagonal operator on the left or right leg of a two-time kernel.

Manual IndexMapping construction is repetitive and convention-sensitive. A small binding helper would reduce bugs around input/output direction, temporary indices, and spectator preservation.

Sketch

pub fn bind_operator_to_indices<T, V>(
    op: LinearOperator<T, V>,
    input_indices: &[T::Index],
    output_indices: Option<&[T::Index]>,
) -> Result<LinearOperator<T, V>>;

pub fn apply_operator_to_indices<T, V>(
    op: &LinearOperator<T, V>,
    state: &TreeTN<T, V>,
    target_indices: &[T::Index],
    options: ApplyOptions,
) -> Result<TreeTN<T, V>>;

Acceptance tests

• Apply a one-axis QFT to one axis of a two-axis state and compare with a small dense reference.
• Apply a flip operator to a non-contiguous subset of a chain/tree state.
• Apply an affine multi-index operator while verifying spectator indices are preserved exactly.
• Verify input/output index IDs and dimensions are validated before contraction.

3. Hadamard product for compatible external index sets

Need

Pointwise multiplication is a core tensor-network operation in many quantics applications:

• elementwise products of two kernels;
• applying masks/windows;
• products of two fitted functions;
• bubble-like contractions in many-body workflows;
• multiplying probability/amplitude fields by indicator functions.

There are regression tests in the codebase using diagonal embedding patterns for elementwise behavior. Exposing a public Hadamard API would let downstream crates use a tested tensor-network implementation instead of duplicating that pattern.

Sketch

pub fn hadamard<T, V>(
    lhs: &TreeTN<T, V>,
    rhs: &TreeTN<T, V>,
    external_indices: &[T::Index],
    options: ContractionOptions,
) -> Result<TreeTN<T, V>>;

Requirements

• No dense materialization in the implementation.
• Validate that external index sets and dimensions match.
• Preserve intended output external indices.
• Support exact/local mode and approximate fit/zipup modes with truncation.

Acceptance tests

• Product of two rank-1 functions remains correct.
• Product of a function and a binary mask matches a small dense reference.
• Complex-valued product preserves conjugation-free pointwise semantics.
• Bond dimensions remain controlled under truncation options.

4. Weighted partial sum / integration over selected indices

Need

Many tensor-network algorithms need to sum out selected external indices, optionally with weights:

• numerical quadrature along one axis of a kernel;
• marginalization of probability-like tensors;
• expectation values with a diagonal weight function;
• contractions such as sum_z w(z) A(x,z) B(z,y) after the product/contraction step;
• sums over momentum, frequency, or component axes.

This is not domain-specific. It is a group-aware contraction/reduction primitive.

Sketch

pub fn weighted_sum_over_indices<T, V>(
    state: &TreeTN<T, V>,
    sum_indices: &[T::Index],
    weights: Option<&TreeTN<T, V>>,
    options: ContractionOptions,
) -> Result<TreeTN<T, V>>;

Acceptance tests

• Unweighted sum over one axis matches a small dense reference.
• Weighted sum with a diagonal/rank-1 weight matches a quadrature reference.
• Summing multiple non-contiguous axes preserves the remaining external indices in a deterministic order.

5. Group swap/relabel helpers

Need

Downstream codes often need to transpose or reinterpret two semantic groups of external indices. Examples include two-point kernels K(x,y) -> K(y,x), covariance/density matrices, and changing between left/right time legs.

Raw loops over replaceind, tag-like metadata, and site order are easy to get wrong. A tested helper would make these operations safer and easier to review.

Sketch

pub fn swap_external_index_groups<T, V>(
    state: &TreeTN<T, V>,
    left: &[T::Index],
    right: &[T::Index],
    options: SwapOptions,
) -> Result<TreeTN<T, V>>;

pub fn relabel_external_indices<T, V>(
    state: &TreeTN<T, V>,
    old: &[T::Index],
    new: &[T::Index],
) -> Result<TreeTN<T, V>>;

Acceptance tests

• Square two-axis transpose preserves values under f(i,j) -> f(j,i).
• Rectangular group swap changes output index groups correctly.
• Relabel rejects dimension mismatches.

6. Quantics transform constructors bound to user indices

Need

tensor4all-quanticstransform constructors return LinearOperators with their own internal indices. This is correct, but downstream code repeatedly needs to bind those operators to existing state indices.

Helpers such as qft_on_indices, shift_on_indices, or affine_on_index_groups would reduce convention errors around bit order, action direction, and input/output mapping.

Sketch

pub fn shift_on_indices(
    indices: &[DynIndex],
    offset: i64,
    bc: BoundaryCondition,
) -> Result<LinearOperator<TensorDynLen, usize>>;

pub fn qft_on_indices(
    indices: &[DynIndex],
    options: FourierOptions,
) -> Result<LinearOperator<TensorDynLen, usize>>;

pub fn affine_on_index_groups(
    input_groups: &[&[DynIndex]],
    output_groups: &[&[DynIndex]],
    params: AffineParams,
    bc: &[BoundaryCondition],
) -> Result<LinearOperator<TensorDynLen, usize>>;

Acceptance tests

• Bound shift/flip/QFT operators match unbound operator + explicit binding.
• QFT normalization and bit-reversed output order are documented and tested.
• Affine transform preserves spectator groups when applied through apply_operator_to_indices.

7. QTCI true-error diagnostics and richer fit reports

Need

TCI convergence errors alone are not always enough. Downstream users need stable diagnostics such as sampled true error, rank history, cache size, and underfit detection, especially when fitting discontinuous masks, triangular constraints, or oscillatory functions.

Sketch

pub fn estimate_true_error_bits<V, F>(
    tt: &TensorTrain<V>,
    f: F,
    local_dims: &[usize],
    options: TrueErrorOptions,
) -> Result<f64>
where
    V: TTScalar,
    F: Fn(&[usize]) -> V;

pub struct TrueErrorOptions {
    pub sample_bits: usize,
    pub mode: TrueErrorSamplingMode,
}

pub enum TrueErrorSamplingMode {
    LinearStride,
    UniformGrid,
    Random { seed: u64, n_samples: usize },
}

Acceptance tests

• A deliberately underfit function reports a larger sampled true error.
• Linear-stride sampling is deterministic.
• Random sampling is reproducible with a seed.
• Complex-valued errors use a documented norm.

8. HDF5 support for tensor-network metadata

Need

Complex downstream workflows need reproducible bug reports and restartable calculations. It is useful to persist not just raw tensor data, but also operator mappings and semantic index metadata.

Proposed coverage

• TreeTN.
• LinearOperator.
• IndexMapping input/output maps.
• Optional named index groups.
• Transform/operator metadata needed to reconstruct convention-sensitive objects.

Acceptance tests

• Round-trip a TreeTN with external index metadata.
• Round-trip a LinearOperator and verify applying it before/after serialization gives the same result.
• Reject or warn on schema version mismatch.

Notes

This umbrella issue is intentionally phrased in general tensor-network terms. The requested APIs are not specific to any one downstream physics code. They cover common workflows for multi-axis QTT tensors: selected-index transforms, pointwise products, weighted reductions, low-level tensor-train TCI fitting, diagnostics, and reproducible serialization.

[shinaoka]

I think this is worth addressing as a cohesive selected-index API effort, not as downstream-specific glue.

The key constraint is that the new surface should stay aligned with existing tensor4all-rs primitives:

• TreeTN remains the main selected-index tensor-network object.
• LinearOperator + IndexMapping + apply_linear_operator remains the operator application path.
• partial_contract / PartialContractionSpec remains the substrate for Hadamard-style diagonal pairing and selected contractions.
• Production paths stay tensor-network based, with dense materialization only for explicitly bounded reference/diagnostic paths.

Primary scope for this issue:

1. Generalize/broaden LinearOperator binding so it can be bound to explicit external index pairs, including multi-index nodes. The current align_to_state helper is useful but too narrow because it assumes one site index per node.

2. Add selected-index apply helpers as thin wrappers over the existing LinearOperator machinery. These should validate full Index identity and dimensions, not rely on index IDs or fragile ordering conventions.

3. Add public Hadamard and weighted selected-sum helpers as wrappers over partial_contract, using diagonal/copy structure rather than dense materialization. This avoids downstream duplication of the diagonal embedding pattern.

4. Add quantics transform constructors bound to user indices as ergonomic wrappers around the generalized binding layer, not as separate operator semantics.

Explicitly out of scope / backlog for this issue:

• A dedicated bit-level QTCI entry point. The cleaner model is quanticsgrids for coordinate/bit-domain mapping plus tensorci::crossinterpolate2 for local-dimension TCI. If discoverability is the problem, this should be addressed with documentation/examples first rather than a second wrapper API with another indexing convention.
• HDF5 persistence for TreeTN, LinearOperator, mappings, semantic groups, and metadata. This is useful, but it is a serialization/schema issue and should be tracked separately.
• Richer QTCI fit reports and true-error estimators. These are useful diagnostics, but they are orthogonal to selected-index tensor-network operations.
• Standalone group-swap/relabel APIs beyond what falls out naturally from replaceinds, swap_site_indices, or restructure_to. If a concrete gap remains after the primary selected-index APIs land, it should be specified separately.

The main API-design question is whether LinearOperator should move from node-to-single-mapping storage toward node-to-multiple-mappings, e.g. conceptually HashMap<V, Vec<IndexMapping<I>>>. Since this project is still in early development and backward compatibility is not required, this may be the right time to make that abstraction match multi-axis TreeTN use cases directly.

So my preference is: keep this issue open and handle it as one coordinated selected-index API effort, starting from the LinearOperator mapping generalization and then layering the apply/Hadamard/reduction APIs on top, while explicitly leaving bit-domain fitting wrappers, persistence, and diagnostic-reporting work out of this issue unless a concrete gap remains after documentation/examples.

[shinaoka]

Implemented the selected-index/tag binding path without adding per-operation *_on_indices APIs.

• Added generic TreeTN helpers for exact tag lookup and numbered tags (x=1, x=2, ...).
• Added generic operator application APIs: bind_linear_operator_indices, apply_linear_operator_to_indices, and apply_linear_operator_to_numbered_tags.
• Kept quanticstransform operator constructors focused on building operators; callers now resolve tags on the target TreeTN and apply through the shared TreeTN path.
• Documented the flow in the Quantics guide, with one tutorial note: use apply_linear_operator_to_numbered_tags if and only if numbered tags are the intended operator binding.

Deferred: no per-operator tag-specific wrappers such as shift_operator_on_indices; the generic TreeTN binding API covers the intended use without expanding the quanticstransform API surface.

[shinaoka]

Merged in #508.

Completed in this pass:

• Generic selected-index operator binding/application in tensor4all-treetn.
• Numbered-tag selection for quantics-style tags such as x=1, x=2, ... .
• Selected-index contraction utilities: Hadamard/product-style helpers and weighted/summed selected-index reductions.
• Documentation for the generic tag-resolution + apply flow.

Explicitly not added in this pass:

• Per-operation quanticstransform wrappers such as shift_operator_on_indices or qft_on_indices; the shared TreeTN binding API covers this without expanding every transform API.
• Bit-level TCI entry points, group swap/relabel helpers, richer QTCI diagnostics, and HDF5 metadata serialization; those are broader follow-up features and should be handled as separate issues if still needed.