Skip to main content

tensor4all_core/
tensor_like.rs

1//! TensorLike trait for unifying tensor types.
2//!
3//! This module provides a fully generic trait for tensor-like objects that expose
4//! external indices and support contraction operations.
5//!
6//! # Design
7//!
8//! The trait is **fully generic** (monomorphic), meaning:
9//! - No trait objects (`dyn TensorLike`)
10//! - Uses associated type for `Index`
11//! - All methods return `Self` instead of concrete types
12//!
13//! For heterogeneous tensor collections, use an enum wrapper.
14
15use crate::any_scalar::AnyScalar;
16use crate::index_like::IndexLike;
17use crate::tensor_index::TensorIndex;
18use crate::truncation::{
19    validate_svd_truncation_options, SvdTruncationOptionsError, SvdTruncationPolicy,
20};
21use crate::TensorElement;
22use num_complex::Complex64;
23use std::collections::HashSet;
24use std::fmt::Debug;
25use std::sync::Arc;
26
27// ============================================================================
28// Factorization types (non-generic, algorithm-specific)
29// ============================================================================
30
31use thiserror::Error;
32
33/// Error type for factorize operations.
34///
35/// # Examples
36///
37/// ```
38/// use tensor4all_core::{
39///     factorize, Canonical, DynIndex, FactorizeOptions, TensorContractionLike, IdxTensor,
40/// };
41///
42/// let i = DynIndex::new_dyn(3);
43/// let j = DynIndex::new_dyn(3);
44/// let data: Vec<f64> = (0..9).map(|x| x as f64).collect();
45/// let tensor = IdxTensor::from_dense(vec![i.clone(), j.clone()], data).unwrap();
46///
47/// // QR with Canonical::Right is not supported
48/// let result = factorize(
49///     &tensor,
50///     &[i],
51///     &FactorizeOptions::qr().with_canonical(Canonical::Right),
52/// );
53/// assert!(result.is_err());
54/// ```
55#[derive(Debug, Error)]
56pub enum FactorizeError {
57    /// RSVD cannot certify a threshold-based truncation policy.
58    #[error("RSVD does not support truncation policy {0:?}; specify a fixed max_bond_dim, or select deterministic SVD for rtol/cutoff")]
59    UnsupportedTruncationPolicy(
60        /// The rejected policy; no deterministic fallback was attempted.
61        SvdTruncationPolicy,
62    ),
63    /// Factorization computation failed.
64    ///
65    /// The underlying error is preserved as an `anyhow` source, so a typed
66    /// cause such as
67    /// [`IdxTensorError::UnsupportedExecutionContext`](crate::IdxTensorError::UnsupportedExecutionContext)
68    /// stays reachable through `downcast_ref`.
69    #[error("Factorization failed: {0}")]
70    ComputationError(
71        /// The underlying error
72        #[from]
73        anyhow::Error,
74    ),
75    /// Invalid relative tolerance value (must be finite and non-negative).
76    #[error("Invalid rtol value: {0}. rtol must be finite and non-negative.")]
77    InvalidRtol(
78        /// The invalid rtol value
79        f64,
80    ),
81    /// Invalid algorithm-specific option combination.
82    #[error("Invalid factorize options: {0}")]
83    InvalidOptions(
84        /// Description of the invalid option combination
85        &'static str,
86    ),
87    /// The storage type is not supported for this operation.
88    #[error("Unsupported storage type: {0}")]
89    UnsupportedStorage(
90        /// Description of the unsupported storage type
91        &'static str,
92    ),
93    /// The canonical direction is not supported for this algorithm.
94    #[error("Unsupported canonical direction for this algorithm: {0}")]
95    UnsupportedCanonical(
96        /// Description of the unsupported canonical direction
97        &'static str,
98    ),
99    /// Error from SVD operation.
100    #[error("SVD error: {0}")]
101    SvdError(
102        /// The underlying SVD error
103        #[from]
104        crate::svd::SvdError,
105    ),
106    /// Error from QR operation.
107    #[error("QR error: {0}")]
108    QrError(
109        /// The underlying QR error
110        #[from]
111        crate::qr::QrError,
112    ),
113    /// Error from matrix CI operation.
114    #[error("Matrix CI error: {0}")]
115    MatrixCIError(
116        /// The underlying matrix CI error
117        #[from]
118        crate::MatrixCIError,
119    ),
120}
121
122/// Factorization algorithm.
123///
124/// Determines which matrix decomposition is used by [`TensorFactorizationLike::factorize`].
125///
126/// # Examples
127///
128/// ```
129/// use tensor4all_core::FactorizeAlg;
130///
131/// // Default is SVD
132/// assert_eq!(FactorizeAlg::default(), FactorizeAlg::SVD);
133/// ```
134#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
135pub enum FactorizeAlg {
136    /// Singular Value Decomposition.
137    #[default]
138    SVD,
139    /// Fixed-rank randomized SVD; requires a positive rank cap and dense
140    /// `f64`/`Complex64`. `f32`/`Complex32` are unsupported.
141    RSVD,
142    /// QR decomposition.
143    QR,
144    /// Rank-revealing LU decomposition.
145    LU,
146    /// Cross Interpolation (LU-based).
147    CI,
148}
149
150/// Canonical direction for factorization.
151///
152/// This determines which factor is "canonical" (orthogonal for SVD/QR,
153/// or unit-diagonal for LU/CI).
154///
155/// # Examples
156///
157/// ```
158/// use tensor4all_core::{
159///     factorize, Canonical, DynIndex, FactorizeOptions, TensorContractionLike, IdxTensor,
160/// };
161///
162/// let i = DynIndex::new_dyn(3);
163/// let j = DynIndex::new_dyn(3);
164/// let data: Vec<f64> = (0..9).map(|x| x as f64).collect();
165/// let tensor = IdxTensor::from_dense(vec![i.clone(), j.clone()], data).unwrap();
166///
167/// // Left canonical: left factor has orthonormal columns
168/// let left_result = factorize(
169///     &tensor,
170///     &[i.clone()],
171///     &FactorizeOptions::svd().with_canonical(Canonical::Left),
172/// ).unwrap();
173///
174/// // Right canonical: right factor has orthonormal rows
175/// let right_result = factorize(
176///     &tensor,
177///     &[i.clone()],
178///     &FactorizeOptions::svd().with_canonical(Canonical::Right),
179/// ).unwrap();
180///
181/// // Both recover the same tensor
182/// let recovered_left = left_result.left.contract_pair(&left_result.right).unwrap();
183/// let recovered_right = right_result.left.contract_pair(&right_result.right).unwrap();
184/// assert!(recovered_left.distance(&recovered_right).unwrap() < 1e-12);
185/// ```
186#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
187pub enum Canonical {
188    /// Left factor is canonical.
189    /// - SVD: L=U (orthogonal), R=S*V
190    /// - QR: L=Q (orthogonal), R=R
191    /// - LU/CI: L has unit diagonal
192    #[default]
193    Left,
194    /// Right factor is canonical.
195    /// - SVD: L=U*S, R=V (orthogonal)
196    /// - QR: Not supported (would need LQ)
197    /// - LU/CI: U has unit diagonal
198    Right,
199}
200
201/// Options for tensor factorization.
202///
203/// Controls the algorithm, canonical direction, and truncation parameters
204/// for [`TensorFactorizationLike::factorize`].
205///
206/// # Defaults
207///
208/// - Algorithm: SVD
209/// - Canonical: Left (left factor is orthogonal)
210/// - max_bond_dim: `None` (no rank limit)
211/// - svd_policy: `None` (uses the SVD global default policy)
212/// - qr_rtol: `None` (uses the QR global default tolerance)
213///
214/// # Field Interactions
215///
216/// - `svd_policy` is only valid for `FactorizeAlg::SVD`.
217/// - `qr_rtol` is only valid for `FactorizeAlg::QR`.
218/// - `max_bond_dim` is independent of the algorithm-specific tolerance settings.
219///
220/// # Examples
221///
222/// ```
223/// use tensor4all_core::{
224///     factorize, Canonical, DynIndex, FactorizeOptions, IdxTensor,
225/// };
226///
227/// let i = DynIndex::new_dyn(4);
228/// let j = DynIndex::new_dyn(4);
229/// let mut data = vec![0.0_f64; 16];
230/// data[0] = 1.0;  // rank-1 matrix
231/// let tensor = IdxTensor::from_dense(vec![i.clone(), j.clone()], data).unwrap();
232///
233/// // SVD with an explicit policy
234/// let opts = FactorizeOptions::svd()
235///     .with_svd_policy(tensor4all_core::SvdTruncationPolicy::new(1e-10));
236/// let result = factorize(&tensor, &[i.clone()], &opts).unwrap();
237/// assert_eq!(result.rank, 1);
238///
239/// // QR with max-rank truncation
240/// let opts = FactorizeOptions::qr().with_qr_rtol(1e-8).with_max_bond_dim(2);
241/// let result = factorize(&tensor, &[i.clone()], &opts).unwrap();
242/// assert!(result.rank <= 2);
243/// ```
244#[derive(Debug, Clone)]
245pub struct FactorizeOptions {
246    /// Factorization algorithm to use.
247    pub alg: FactorizeAlg,
248    /// Canonical direction.
249    pub canonical: Canonical,
250    /// Maximum rank for truncation.
251    /// If `None`, no rank limit is applied to deterministic methods; RSVD
252    /// requires a positive rank cap.
253    pub max_bond_dim: Option<usize>,
254    /// SVD truncation policy.
255    /// If `None`, deterministic SVD uses its global default. RSVD ignores
256    /// global defaults and rejects every explicit threshold policy.
257    pub svd_policy: Option<SvdTruncationPolicy>,
258    /// QR-specific relative tolerance.
259    /// If `None`, uses the QR global default.
260    pub qr_rtol: Option<f64>,
261    /// Gaussian sketch options for RSVD; ignored by deterministic algorithms.
262    pub randomized: crate::RangeOptions,
263    /// Seed for convenience RSVD calls. Caller-RNG entries ignore this field.
264    pub rsvd_seed: u64,
265}
266
267impl Default for FactorizeOptions {
268    fn default() -> Self {
269        Self {
270            alg: FactorizeAlg::SVD,
271            canonical: Canonical::Left,
272            max_bond_dim: None,
273            svd_policy: None,
274            qr_rtol: None,
275            randomized: crate::RangeOptions::default(),
276            rsvd_seed: 0,
277        }
278    }
279}
280
281impl FactorizeOptions {
282    /// Create fixed-rank RSVD options with the default sketch and seed zero.
283    ///
284    /// `max_bond_dim` must be positive. Global truncation defaults are ignored;
285    /// an explicit `svd_policy` or `qr_rtol` is rejected.
286    /// Only dense `f64`/`Complex64` inputs are supported, not `f32`/`Complex32`.
287    ///
288    /// # Examples
289    /// ```
290    /// use tensor4all_core::{FactorizeAlg, FactorizeOptions};
291    /// let options = FactorizeOptions::rsvd(3);
292    /// assert_eq!(options.alg, FactorizeAlg::RSVD);
293    /// assert_eq!(options.max_bond_dim, Some(3));
294    /// ```
295    pub fn rsvd(max_bond_dim: usize) -> Self {
296        Self {
297            alg: FactorizeAlg::RSVD,
298            max_bond_dim: Some(max_bond_dim),
299            ..Self::default()
300        }
301    }
302
303    /// Create options for SVD factorization.
304    ///
305    /// # Examples
306    ///
307    /// ```
308    /// use tensor4all_core::{FactorizeAlg, FactorizeOptions};
309    ///
310    /// let opts = FactorizeOptions::svd();
311    /// assert_eq!(opts.alg, FactorizeAlg::SVD);
312    /// ```
313    pub fn svd() -> Self {
314        Self {
315            alg: FactorizeAlg::SVD,
316            ..Default::default()
317        }
318    }
319
320    /// Create options for QR factorization.
321    ///
322    /// # Examples
323    ///
324    /// ```
325    /// use tensor4all_core::{FactorizeAlg, FactorizeOptions};
326    ///
327    /// let opts = FactorizeOptions::qr();
328    /// assert_eq!(opts.alg, FactorizeAlg::QR);
329    /// ```
330    pub fn qr() -> Self {
331        Self {
332            alg: FactorizeAlg::QR,
333            ..Default::default()
334        }
335    }
336
337    /// Create options for LU factorization.
338    ///
339    /// # Examples
340    ///
341    /// ```
342    /// use tensor4all_core::{FactorizeAlg, FactorizeOptions};
343    ///
344    /// let opts = FactorizeOptions::lu();
345    /// assert_eq!(opts.alg, FactorizeAlg::LU);
346    /// ```
347    pub fn lu() -> Self {
348        Self {
349            alg: FactorizeAlg::LU,
350            ..Default::default()
351        }
352    }
353
354    /// Create options for CI factorization.
355    ///
356    /// # Examples
357    ///
358    /// ```
359    /// use tensor4all_core::{FactorizeAlg, FactorizeOptions};
360    ///
361    /// let opts = FactorizeOptions::ci();
362    /// assert_eq!(opts.alg, FactorizeAlg::CI);
363    /// ```
364    pub fn ci() -> Self {
365        Self {
366            alg: FactorizeAlg::CI,
367            ..Default::default()
368        }
369    }
370
371    /// Set canonical direction.
372    ///
373    /// # Examples
374    ///
375    /// ```
376    /// use tensor4all_core::{Canonical, FactorizeOptions};
377    ///
378    /// let opts = FactorizeOptions::svd().with_canonical(Canonical::Right);
379    /// assert_eq!(opts.canonical, Canonical::Right);
380    /// ```
381    pub fn with_canonical(mut self, canonical: Canonical) -> Self {
382        self.canonical = canonical;
383        self
384    }
385
386    /// Set the SVD truncation policy.
387    ///
388    /// # Examples
389    ///
390    /// ```
391    /// use tensor4all_core::{FactorizeOptions, SvdTruncationPolicy};
392    ///
393    /// let opts = FactorizeOptions::svd().with_svd_policy(SvdTruncationPolicy::new(1e-8));
394    /// assert_eq!(opts.svd_policy, Some(SvdTruncationPolicy::new(1e-8)));
395    /// ```
396    pub fn with_svd_policy(mut self, policy: SvdTruncationPolicy) -> Self {
397        self.svd_policy = Some(policy);
398        self
399    }
400
401    /// Set the QR-specific relative tolerance.
402    ///
403    /// # Examples
404    ///
405    /// ```
406    /// use tensor4all_core::FactorizeOptions;
407    ///
408    /// let opts = FactorizeOptions::qr().with_qr_rtol(1e-8);
409    /// assert_eq!(opts.qr_rtol, Some(1e-8));
410    /// ```
411    pub fn with_qr_rtol(mut self, rtol: f64) -> Self {
412        self.qr_rtol = Some(rtol);
413        self
414    }
415
416    /// Set maximum rank.
417    ///
418    /// # Examples
419    ///
420    /// ```
421    /// use tensor4all_core::FactorizeOptions;
422    ///
423    /// let opts = FactorizeOptions::svd().with_max_bond_dim(10);
424    /// assert_eq!(opts.max_bond_dim, Some(10));
425    /// ```
426    pub fn with_max_bond_dim(mut self, max_bond_dim: usize) -> Self {
427        self.max_bond_dim = Some(max_bond_dim);
428        self
429    }
430
431    /// Validate that the selected fields make sense for the chosen algorithm.
432    ///
433    /// Validates max bond dimension and explicit SVD policy thresholds through
434    /// the shared [`validate_svd_truncation_options`] seam, then checks the
435    /// algorithm/option compatibility rules.
436    ///
437    /// # Errors
438    ///
439    /// Returns [`FactorizeError::InvalidOptions`] if an algorithm is paired with
440    /// unsupported algorithm-specific truncation settings, or if `max_bond_dim`
441    /// is zero or an SVD policy threshold is non-finite/negative. Returns
442    /// [`FactorizeError::UnsupportedTruncationPolicy`] for every RSVD threshold
443    /// policy; specify a fixed rank or select deterministic SVD instead.
444    pub fn validate(&self) -> std::result::Result<(), FactorizeError> {
445        if self.alg == FactorizeAlg::RSVD {
446            if let Some(policy) = self.svd_policy {
447                return Err(FactorizeError::UnsupportedTruncationPolicy(policy));
448            }
449        }
450        validate_svd_truncation_options(self.max_bond_dim, self.svd_policy).map_err(|error| {
451            FactorizeError::InvalidOptions(match error {
452                SvdTruncationOptionsError::ZeroMaxBondDim => "max_bond_dim must be at least 1",
453                SvdTruncationOptionsError::InvalidThreshold(_) => {
454                    "SVD truncation threshold must be finite and non-negative"
455                }
456            })
457        })?;
458
459        match self.alg {
460            FactorizeAlg::RSVD => {
461                if self.max_bond_dim.is_none() {
462                    return Err(FactorizeError::InvalidOptions("RSVD requires max_bond_dim"));
463                }
464                if self.qr_rtol.is_some() {
465                    return Err(FactorizeError::InvalidOptions(
466                        "RSVD does not accept qr_rtol; specify a fixed max_bond_dim",
467                    ));
468                }
469                self.max_bond_dim
470                    .and_then(|rank| rank.checked_add(self.randomized.oversampling))
471                    .ok_or(FactorizeError::InvalidOptions(
472                        "rank + oversampling overflows usize",
473                    ))?;
474            }
475            FactorizeAlg::SVD => {
476                if self.qr_rtol.is_some() {
477                    return Err(FactorizeError::InvalidOptions(
478                        "SVD factorization does not accept qr_rtol",
479                    ));
480                }
481            }
482            FactorizeAlg::QR => {
483                if self.svd_policy.is_some() {
484                    return Err(FactorizeError::InvalidOptions(
485                        "QR factorization does not accept svd_policy",
486                    ));
487                }
488            }
489            FactorizeAlg::LU | FactorizeAlg::CI => {
490                if self.svd_policy.is_some() {
491                    return Err(FactorizeError::InvalidOptions(
492                        "LU/CI factorization does not accept svd_policy",
493                    ));
494                }
495                if self.qr_rtol.is_some() {
496                    return Err(FactorizeError::InvalidOptions(
497                        "LU/CI factorization does not accept qr_rtol",
498                    ));
499                }
500            }
501        }
502
503        Ok(())
504    }
505}
506
507/// Result of tensor factorization.
508///
509/// Contains the two factors, the bond index connecting them, and metadata
510/// about the decomposition. The original tensor can be recovered (up to
511/// truncation error) by contracting `left` and `right` along `bond_index`.
512///
513/// # Examples
514///
515/// ```
516/// use tensor4all_core::{
517///     factorize, DynIndex, FactorizeOptions, TensorContractionLike, IdxTensor,
518/// };
519///
520/// let i = DynIndex::new_dyn(3);
521/// let j = DynIndex::new_dyn(4);
522/// let data: Vec<f64> = (0..12).map(|x| x as f64).collect();
523/// let tensor = IdxTensor::from_dense(vec![i.clone(), j.clone()], data).unwrap();
524///
525/// let result = factorize(&tensor, &[i.clone()], &FactorizeOptions::svd()).unwrap();
526///
527/// // Contracting left * right recovers the original tensor
528/// let recovered = result.left.contract_pair(&result.right).unwrap();
529/// assert!(tensor.distance(&recovered).unwrap() < 1e-12);
530///
531/// // SVD provides singular values
532/// assert!(result.singular_values.is_some());
533/// assert_eq!(result.singular_values.as_ref().unwrap().len(), result.rank);
534/// ```
535///
536/// This struct is `#[non_exhaustive]`: it carries a private
537/// algorithm-internal field (`incremental_qr_state`) that downstream crates
538/// cannot see or set, so external construction always goes through
539/// [`FactorizeResult::new`] rather than struct-literal syntax.
540#[derive(Debug, Clone)]
541#[non_exhaustive]
542pub struct FactorizeResult<T: TensorIndex> {
543    /// Left factor tensor.
544    pub left: T,
545    /// Right factor tensor.
546    pub right: T,
547    /// Bond index connecting left and right factors.
548    pub bond_index: T::Index,
549    /// Retained singular values (SVD or the projected matrix for RSVD).
550    pub singular_values: Option<Vec<f64>>,
551    /// Retained bond dimension of the factorization.
552    ///
553    /// Tensor LU/CI factorization represents a rank-zero matrix selection
554    /// with a dimension-one bond and an exactly zero product. The selected
555    /// canonical factor keeps its unit diagonal; the other factor is zero.
556    pub rank: usize,
557    incremental_qr_state: Option<IncrementalQrState>,
558}
559
560#[derive(Debug, Clone)]
561pub(crate) enum IncrementalQrState {
562    F64(tensor4all_tensorbackend::IncrementalQr<f64>),
563    C64(tensor4all_tensorbackend::IncrementalQr<Complex64>),
564}
565
566impl<T: TensorIndex> FactorizeResult<T> {
567    /// Construct a factorization result without an algorithm-private update
568    /// state.
569    ///
570    /// # Arguments
571    /// * `left` - Left factor tensor.
572    /// * `right` - Right factor tensor.
573    /// * `bond_index` - Index connecting the two factors.
574    /// * `singular_values` - Singular values when the result came from SVD.
575    /// * `rank` - Number of columns in the factorization.
576    ///
577    /// # Returns
578    /// A factorization result suitable for public factorization APIs. Native
579    /// incremental QR callers attach their private update state afterward.
580    ///
581    /// # Examples
582    ///
583    /// ```
584    /// use tensor4all_core::{DynIndex, FactorizeResult, IdxTensor};
585    ///
586    /// let left_index = DynIndex::new_dyn(1);
587    /// let bond = DynIndex::new_bond(1).unwrap();
588    /// let left = IdxTensor::from_dense(vec![left_index.clone(), bond.clone()], vec![1.0]).unwrap();
589    /// let right = IdxTensor::from_dense(vec![bond.clone()], vec![2.0]).unwrap();
590    /// let result = FactorizeResult::new(left, right, bond, None, 1);
591    /// assert_eq!(result.rank, 1);
592    /// ```
593    pub fn new(
594        left: T,
595        right: T,
596        bond_index: T::Index,
597        singular_values: Option<Vec<f64>>,
598        rank: usize,
599    ) -> Self {
600        Self {
601            left,
602            right,
603            bond_index,
604            singular_values,
605            rank,
606            incremental_qr_state: None,
607        }
608    }
609
610    pub(crate) fn with_incremental_qr_state(mut self, state: IncrementalQrState) -> Self {
611        self.incremental_qr_state = Some(state);
612        self
613    }
614
615    pub(crate) fn incremental_qr_state(&self) -> Option<&IncrementalQrState> {
616        self.incremental_qr_state.as_ref()
617    }
618}
619
620// ============================================================================
621// Contraction types
622// ============================================================================
623
624/// Linearization order used when fusing or unfusing multiple logical indices
625/// into one physical index.
626///
627/// This matters for exact reshape-style operations such as replacing one fused
628/// index with several unfused indices.
629///
630/// # Examples
631///
632/// ```
633/// use tensor4all_core::LinearizationOrder;
634///
635/// assert_eq!(LinearizationOrder::ColumnMajor.as_str(), "column-major");
636/// assert_eq!(LinearizationOrder::RowMajor.as_str(), "row-major");
637/// ```
638#[derive(Debug, Clone, Copy, PartialEq, Eq)]
639pub enum LinearizationOrder {
640    /// First index changes fastest.
641    ColumnMajor,
642    /// Last index changes fastest.
643    RowMajor,
644}
645
646impl LinearizationOrder {
647    /// Return a short human-readable description.
648    ///
649    /// # Examples
650    ///
651    /// ```
652    /// use tensor4all_core::LinearizationOrder;
653    ///
654    /// assert_eq!(LinearizationOrder::ColumnMajor.as_str(), "column-major");
655    /// ```
656    pub fn as_str(self) -> &'static str {
657        match self {
658            Self::ColumnMajor => "column-major",
659            Self::RowMajor => "row-major",
660        }
661    }
662}
663
664// ============================================================================
665// Capability traits (fully generic)
666// ============================================================================
667
668/// Generic adapter error used by vector-space implementations whose concrete
669/// backend error is not part of their public API.
670///
671/// # Examples
672///
673/// ```
674/// use tensor4all_core::TensorVectorSpaceError;
675///
676/// let error = TensorVectorSpaceError::from(anyhow::anyhow!("backend failed"));
677/// assert!(error.to_string().contains("backend failed"));
678/// ```
679#[derive(Debug, thiserror::Error)]
680#[error("tensor vector-space operation failed: {source}")]
681pub struct TensorVectorSpaceError {
682    #[source]
683    source: Arc<dyn std::error::Error + Send + Sync + 'static>,
684}
685
686impl From<anyhow::Error> for TensorVectorSpaceError {
687    fn from(source: anyhow::Error) -> Self {
688        Self {
689            source: Arc::from(source.into_boxed_dyn_error()),
690        }
691    }
692}
693
694/// Vector-space operations for iterative linear algebra over tensor-like values.
695///
696/// This trait intentionally does not require tensor contraction/einsum,
697/// factorization, or tensor-network construction. Krylov solvers should depend
698/// on this trait instead of [`TensorLike`] so block vectors and other abstract
699/// state types do not have to provide unrelated tensor-network operations.
700pub trait TensorVectorSpace: TensorIndex {
701    /// Compute the squared Frobenius norm of the tensor.
702    ///
703    /// # Errors
704    ///
705    /// Returns `Self::Error` when the norm cannot be evaluated (a materialization
706    /// or backend failure).
707    ///
708    /// # Examples
709    /// ```
710    /// # fn main() -> anyhow::Result<()> {
711    /// use tensor4all_core::{DynIndex, IdxTensor, TensorVectorSpace};
712    ///
713    /// let index = DynIndex::new_dyn(2);
714    /// let tensor = IdxTensor::from_dense(vec![index], vec![3.0_f64, 4.0])?;
715    /// assert!((TensorVectorSpace::norm_squared(&tensor)? - 25.0).abs() < 1e-12);
716    /// # Ok(())
717    /// # }
718    /// ```
719    fn norm_squared(&self) -> std::result::Result<f64, Self::Error>;
720
721    /// Compute a linear combination: `a * self + b * other`.
722    ///
723    /// # Errors
724    ///
725    /// Returns `Self::Error` when the operands have incompatible index spaces
726    /// (an index-space mismatch) or the underlying arithmetic or backend
727    /// computation reports a failure.
728    fn axpby(
729        &self,
730        a: AnyScalar,
731        other: &Self,
732        b: AnyScalar,
733    ) -> std::result::Result<Self, Self::Error>;
734
735    /// Scalar multiplication.
736    ///
737    /// # Errors
738    ///
739    /// Returns `Self::Error` when the scalar coefficient is invalid for the
740    /// tensor's scalar type or the underlying backend computation reports a
741    /// failure.
742    fn scale(&self, scalar: AnyScalar) -> std::result::Result<Self, Self::Error>;
743
744    /// Real scalar multiplication in a caller-owned execution context.
745    ///
746    /// Context-scoped counterpart of [`Self::scale`] for real factors: the
747    /// scalar is constructed in the tensor's owning runtime (explicit upload
748    /// for CUDA), so explicit-context tensors never enter the process-global
749    /// default context.
750    ///
751    /// # Errors
752    ///
753    /// Returns `Self::Error` with an `UnsupportedStorage` failure when scoped
754    /// scaling is unsupported for this tensor type; other failures report a
755    /// missing tensor context, an invalid payload, or a backend failure.
756    fn scale_in(
757        &self,
758        _factor: f64,
759        _context: &tensor4all_tensorbackend::ExecutionContext,
760    ) -> std::result::Result<Self, Self::Error> {
761        Err(anyhow::anyhow!("context-scoped scaling is not supported for this tensor type").into())
762    }
763
764    /// Inner product (dot product) of two tensors.
765    ///
766    /// Computes `⟨self, other⟩ = Σ conj(self)_i * other_i`.
767    ///
768    /// # Errors
769    ///
770    /// Returns `Self::Error` when the operands have incompatible index spaces
771    /// (an index-space mismatch) or the underlying contraction or backend
772    /// computation reports a failure.
773    fn inner_product(&self, other: &Self) -> std::result::Result<AnyScalar, Self::Error>;
774
775    /// Returns whether entries are stored in single precision (`f32` or
776    /// `Complex32`).
777    ///
778    /// [`scale`](Self::scale) converts its scalar to the storage precision,
779    /// so a scalar component outside the `f32` range becomes zero or infinite
780    /// before the multiplication. Callers that apply `f64` factors check them
781    /// with [`AnyScalar::is_in_single_precision_range`] when this is `true`.
782    /// A container reports `true` when any of its parts is single precision.
783    ///
784    /// # Examples
785    ///
786    /// ```
787    /// use tensor4all_core::{DynIndex, IdxTensor, TensorVectorSpace};
788    ///
789    /// let i = DynIndex::new_dyn(2);
790    /// let single = IdxTensor::from_dense(vec![i.clone()], vec![1.0_f32, 2.0]).unwrap();
791    /// let double = IdxTensor::from_dense(vec![i], vec![1.0_f64, 2.0]).unwrap();
792    /// assert!(single.is_single_precision());
793    /// assert!(!double.is_single_precision());
794    /// ```
795    fn is_single_precision(&self) -> bool;
796
797    /// Returns whether entries are stored as complex numbers (`Complex32` or
798    /// `Complex64`).
799    ///
800    /// Code that builds new tensors to combine with existing ones, such as
801    /// identity factors, uses this to choose a matching scalar type: scaling a
802    /// real tensor by a complex one with [`scale`](Self::scale) makes it
803    /// complex. A container reports `true` when any of its parts is complex.
804    ///
805    /// # Examples
806    ///
807    /// ```
808    /// use num_complex::Complex64;
809    /// use tensor4all_core::{DynIndex, IdxTensor, TensorVectorSpace};
810    ///
811    /// let i = DynIndex::new_dyn(2);
812    /// let real = IdxTensor::from_dense(vec![i.clone()], vec![1.0_f64, 2.0]).unwrap();
813    /// let complex =
814    ///     IdxTensor::from_dense(vec![i], vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 1.0)])
815    ///         .unwrap();
816    /// assert!(!real.is_complex());
817    /// assert!(complex.is_complex());
818    /// ```
819    fn is_complex(&self) -> bool;
820
821    /// Compute the Frobenius norm of the tensor.
822    ///
823    /// The default takes the square root of [`Self::norm_squared`]. Override
824    /// it with scaled accumulation when a representable norm must survive
825    /// underflow or overflow of its square, as `IdxTensor` and `BlockTensor` do.
826    ///
827    /// # Errors
828    ///
829    /// Returns `Self::Error` when the norm cannot be evaluated (a materialization
830    /// or backend failure).
831    ///
832    /// # Examples
833    /// ```
834    /// # fn main() -> anyhow::Result<()> {
835    /// use tensor4all_core::{DynIndex, IdxTensor, TensorVectorSpace};
836    ///
837    /// let index = DynIndex::new_dyn(2);
838    /// let tensor = IdxTensor::from_dense(vec![index], vec![3.0_f64, 4.0])?;
839    /// assert!((TensorVectorSpace::norm(&tensor)? - 5.0).abs() < 1e-12);
840    /// # Ok(())
841    /// # }
842    /// ```
843    fn norm(&self) -> std::result::Result<f64, Self::Error> {
844        Ok(self.norm_squared()?.sqrt())
845    }
846
847    /// Frobenius norm in a caller-owned execution context.
848    ///
849    /// Context-scoped counterpart of [`Self::norm`]: reductions run in the
850    /// tensor's owning runtime and only the scalar result crosses the
851    /// explicit readback boundary on CUDA. CPU contexts delegate to
852    /// [`Self::norm`] unchanged.
853    ///
854    /// # Errors
855    ///
856    /// Returns `Self::Error` with an `UnsupportedStorage` failure when scoped
857    /// norm evaluation is unsupported for this tensor type; other failures
858    /// report a missing tensor context or a backend failure.
859    fn norm_in(
860        &self,
861        _context: &tensor4all_tensorbackend::ExecutionContext,
862    ) -> std::result::Result<f64, Self::Error> {
863        Err(anyhow::anyhow!("context-scoped norm is not supported for this tensor type").into())
864    }
865
866    /// Compute the maximum absolute value of all tensor elements.
867    ///
868    /// # Errors
869    ///
870    /// Returns `Self::Error` when the maximum cannot be evaluated (a
871    /// materialization or backend failure).
872    ///
873    /// # Examples
874    /// ```
875    /// # fn main() -> anyhow::Result<()> {
876    /// use tensor4all_core::{DynIndex, IdxTensor, TensorVectorSpace};
877    ///
878    /// let index = DynIndex::new_dyn(2);
879    /// let tensor = IdxTensor::from_dense(vec![index], vec![-3.0_f64, 2.0])?;
880    /// assert!((TensorVectorSpace::maxabs(&tensor)? - 3.0).abs() < 1e-12);
881    /// # Ok(())
882    /// # }
883    /// ```
884    fn maxabs(&self) -> std::result::Result<f64, Self::Error>;
885
886    /// Smallest modulus among the nonzero elements, or `None` when every
887    /// element is zero. With [`maxabs`](Self::maxabs) it gives the dynamic
888    /// range of the elements, which decides whether one power-of-two
889    /// rescaling can keep every nonzero element a normal `f64`. Implementors
890    /// return the exact modulus of a real element; for a complex element
891    /// they may return a lower bound within a few ulps (`hypot` rounds), but
892    /// never a value above the true modulus, so `floor(log2)` of the result
893    /// never exceeds that of the true smallest modulus.
894    ///
895    /// The provided implementation reports an unsupported operation; dense
896    /// implementors such as [`IdxTensor`](crate::IdxTensor) override it.
897    ///
898    /// # Errors
899    ///
900    /// - The provided implementation always returns an unsupported-operation
901    ///   error (message `min_nonzero_abs is not supported by this tensor
902    ///   type`), for types without element-wise access.
903    /// - [`IdxTensor`](crate::IdxTensor) returns `IdxTensorError::NaNInput`
904    ///   when an element is NaN, and `IdxTensorError::Storage` or a
905    ///   materialization error when its storage cannot be read.
906    /// - `BlockTensor` propagates the first error of its blocks.
907    ///
908    /// # Examples
909    /// ```
910    /// # fn main() -> anyhow::Result<()> {
911    /// use tensor4all_core::{DynIndex, IdxTensor, TensorVectorSpace};
912    ///
913    /// let index = DynIndex::new_dyn(3);
914    /// let tensor = IdxTensor::from_dense(vec![index.clone()], vec![-3.0_f64, 0.0, 0.5])?;
915    /// assert_eq!(TensorVectorSpace::min_nonzero_abs(&tensor)?, Some(0.5));
916    /// let zero = IdxTensor::from_dense(vec![index], vec![0.0_f64; 3])?;
917    /// assert_eq!(TensorVectorSpace::min_nonzero_abs(&zero)?, None);
918    /// # Ok(())
919    /// # }
920    /// ```
921    fn min_nonzero_abs(&self) -> std::result::Result<Option<f64>, Self::Error> {
922        Err(anyhow::anyhow!("min_nonzero_abs is not supported by this tensor type").into())
923    }
924
925    /// Returns whether every stored real and imaginary component is finite,
926    /// with neither NaN nor infinity.
927    ///
928    /// Use it to tell a non-finite value, such as an operator image that
929    /// overflowed (including an `inf - inf = NaN` formed by the overflow),
930    /// from a backend failure: a NaN entry gives `Ok(false)`, not an error.
931    /// The default derives the answer from [`Self::maxabs`], which takes the
932    /// modulus of a complex entry (so finite components whose modulus
933    /// overflows count as non-finite) and may report a NaN entry as an error;
934    /// `IdxTensor` and `BlockTensor` check each component instead.
935    ///
936    /// # Errors
937    ///
938    /// Returns `Self::Error` when the entries cannot be inspected (a
939    /// materialization or backend failure), or, for the default
940    /// implementation, whatever [`Self::maxabs`] reports.
941    ///
942    /// # Examples
943    /// ```
944    /// # fn main() -> anyhow::Result<()> {
945    /// use num_complex::Complex64;
946    /// use tensor4all_core::{DynIndex, IdxTensor, TensorVectorSpace};
947    ///
948    /// let index = DynIndex::new_dyn(2);
949    /// let finite = IdxTensor::from_dense(vec![index.clone()], vec![f64::MAX, -1.0])?;
950    /// assert!(finite.is_all_finite()?);
951    /// let nan = IdxTensor::from_dense(vec![index.clone()], vec![f64::NAN, 1.0])?;
952    /// assert!(!nan.is_all_finite()?);
953    /// // Both components are finite although the modulus overflows.
954    /// let big = 0.75 * f64::MAX;
955    /// let complex = IdxTensor::from_dense(
956    ///     vec![index],
957    ///     vec![Complex64::new(big, big), Complex64::new(0.0, 0.0)],
958    /// )?;
959    /// assert!(complex.is_all_finite()?);
960    /// # Ok(())
961    /// # }
962    /// ```
963    fn is_all_finite(&self) -> std::result::Result<bool, Self::Error> {
964        Ok(self.maxabs()?.is_finite())
965    }
966
967    /// Element-wise subtraction: `self - other`.
968    ///
969    /// # Errors
970    ///
971    /// Returns `Self::Error` when the operand index spaces are incompatible
972    /// (an index-space mismatch) or the underlying arithmetic or backend
973    /// computation reports a failure; propagates failures from [`Self::axpby`].
974    fn sub(&self, other: &Self) -> std::result::Result<Self, Self::Error> {
975        self.axpby(AnyScalar::new_real(1.0), other, AnyScalar::new_real(-1.0))
976    }
977
978    /// Negate all elements: `-self`.
979    ///
980    /// # Errors
981    ///
982    /// Returns `Self::Error` when scaling reports a failure (an invalid
983    /// scalar coefficient or a backend computation failure); propagates
984    /// failures from [`Self::scale`].
985    fn neg(&self) -> std::result::Result<Self, Self::Error> {
986        self.scale(AnyScalar::new_real(-1.0))
987    }
988
989    /// Approximate equality check (Julia `isapprox` semantics).
990    ///
991    /// # Errors
992    /// Returns `Self::Error` when the operands have incompatible index spaces
993    /// (an index-space mismatch) or when norm evaluation reports a failure;
994    /// propagates failures from subtraction and norm evaluation.
995    fn isapprox(
996        &self,
997        other: &Self,
998        atol: f64,
999        rtol: f64,
1000    ) -> std::result::Result<bool, Self::Error> {
1001        let diff = self.sub(other)?;
1002        let diff_norm = diff.norm()?;
1003        let self_norm = self.norm()?;
1004        let other_norm = other.norm()?;
1005        Ok(diff_norm <= atol.max(rtol * self_norm.max(other_norm)))
1006    }
1007
1008    /// Validate structural consistency of this tensor-like vector.
1009    ///
1010    /// # Errors
1011    ///
1012    /// Returns `Self::Error` when the tensor's index space or shape is
1013    /// structurally inconsistent (for example index-space or dimension
1014    /// mismatches, or an invalid internal state). The default implementation
1015    /// always returns `Ok(())`.
1016    fn validate(&self) -> std::result::Result<(), Self::Error> {
1017        Ok(())
1018    }
1019}
1020
1021/// Contraction/einsum-style operations for tensor-like values.
1022///
1023/// Types that only need vector-space algebra should not implement or require
1024/// this trait. Tree tensor-network algorithms should use this trait when they
1025/// truly need index-based contraction.
1026pub trait TensorContractionLike: TensorIndex {
1027    /// Tensor conjugate operation.
1028    fn conj(&self) -> Self;
1029
1030    /// Direct sum of two tensors along specified index pairs.
1031    ///
1032    /// Each pair `(a_index, b_index)` becomes one new index of dimension
1033    /// `dim(a_index) + dim(b_index)`; `self` occupies the first block and
1034    /// `other` the second. For more than two operands use
1035    /// [`direct_sum_many`](Self::direct_sum_many).
1036    ///
1037    /// # Errors
1038    ///
1039    /// Returns `Self::Error` when the summed index spaces are incompatible
1040    /// (an index-space mismatch) or the underlying construction reports a
1041    /// failure.
1042    fn direct_sum(
1043        &self,
1044        other: &Self,
1045        pairs: &[(<Self as TensorIndex>::Index, <Self as TensorIndex>::Index)],
1046    ) -> std::result::Result<DirectSumResult<Self>, Self::Error>;
1047
1048    /// Direct sum of any number of tensors.
1049    ///
1050    /// Each entry of `groups` lists one index per operand, in operand order,
1051    /// and becomes one new index whose dimension is the sum of the group's
1052    /// dimensions. Operand `i` occupies its own diagonal block, after the
1053    /// blocks of operands `0..i`; all other entries are zero. The indices that
1054    /// belong to no group must be the same for every operand. The result
1055    /// lists those common indices in `operands[0]`'s order, followed by the
1056    /// new indices in `groups` order.
1057    ///
1058    /// The provided implementation folds [`direct_sum`](Self::direct_sum)
1059    /// from the left, `((t0 (+) t1) (+) t2) ...`, which copies the growing
1060    /// partial result at every step. Implementors with a dense layout should
1061    /// override it with a one-pass construction, as `IdxTensor` does.
1062    ///
1063    /// # Errors
1064    ///
1065    /// Returns `Self::Error` when `operands` or `groups` is empty, when a
1066    /// group does not have one index per operand, when the index spaces are
1067    /// incompatible (an index-space mismatch), or when the underlying
1068    /// construction reports a failure. Types without a block construction
1069    /// return an unsupported-operation error.
1070    ///
1071    /// # Examples
1072    ///
1073    /// ```
1074    /// use tensor4all_core::{DynIndex, IdxTensor, IndexLike, TensorContractionLike};
1075    ///
1076    /// let (b0, b1, b2) = (DynIndex::new_dyn(1), DynIndex::new_dyn(1), DynIndex::new_dyn(2));
1077    /// let t0 = IdxTensor::from_dense(vec![b0.clone()], vec![1.0_f64]).unwrap();
1078    /// let t1 = IdxTensor::from_dense(vec![b1.clone()], vec![2.0_f64]).unwrap();
1079    /// let t2 = IdxTensor::from_dense(vec![b2.clone()], vec![3.0_f64, 4.0]).unwrap();
1080    ///
1081    /// let result = IdxTensor::direct_sum_many(&[&t0, &t1, &t2], &[vec![b0, b1, b2]]).unwrap();
1082    ///
1083    /// assert_eq!(result.new_indices[0].dim(), 4);
1084    /// assert_eq!(result.tensor.to_vec::<f64>().unwrap(), vec![1.0, 2.0, 3.0, 4.0]);
1085    /// ```
1086    fn direct_sum_many(
1087        operands: &[&Self],
1088        groups: &[Vec<<Self as TensorIndex>::Index>],
1089    ) -> std::result::Result<DirectSumResult<Self>, Self::Error> {
1090        let (first, rest) = operands
1091            .split_first()
1092            .ok_or_else(|| anyhow::anyhow!("direct_sum_many requires at least one operand"))?;
1093        if groups.is_empty() {
1094            return Err(
1095                anyhow::anyhow!("direct_sum_many requires at least one index group").into(),
1096            );
1097        }
1098        if let Some((g, group)) = groups
1099            .iter()
1100            .enumerate()
1101            .find(|(_, group)| group.len() != operands.len())
1102        {
1103            return Err(anyhow::anyhow!(
1104                "index group {g} has {} entries, expected one per operand ({})",
1105                group.len(),
1106                operands.len()
1107            )
1108            .into());
1109        }
1110        let Some((second, later)) = rest.split_first() else {
1111            // One operand: rename each grouped index to a fresh link and move
1112            // the new indices after the common ones.
1113            let old: Vec<<Self as TensorIndex>::Index> =
1114                groups.iter().map(|group| group[0].clone()).collect();
1115            let new_indices = old
1116                .iter()
1117                .map(|index| <<Self as TensorIndex>::Index as IndexLike>::new_link(index.dim()))
1118                .collect::<anyhow::Result<Vec<_>>>()?;
1119            let mut order: Vec<<Self as TensorIndex>::Index> = first
1120                .external_indices()
1121                .into_iter()
1122                .filter(|index| !old.contains(index))
1123                .collect();
1124            order.extend(new_indices.iter().cloned());
1125            let tensor = first
1126                .replace_indices(&old, &new_indices)?
1127                .permuteinds(&order)?;
1128            return Ok(DirectSumResult {
1129                tensor,
1130                new_indices,
1131            });
1132        };
1133        let pairs: Vec<_> = groups
1134            .iter()
1135            .map(|group| (group[0].clone(), group[1].clone()))
1136            .collect();
1137        let mut sum = first.direct_sum(second, &pairs)?;
1138        for (offset, operand) in later.iter().enumerate() {
1139            let pairs: Vec<_> = sum
1140                .new_indices
1141                .iter()
1142                .cloned()
1143                .zip(groups.iter().map(|group| group[offset + 2].clone()))
1144                .collect();
1145            sum = sum.tensor.direct_sum(operand, &pairs)?;
1146        }
1147        Ok(sum)
1148    }
1149
1150    /// Outer product (tensor product) of two tensors.
1151    ///
1152    /// # Errors
1153    ///
1154    /// Returns `Self::Error` when the two tensors share contractable indices
1155    /// (a shared-index mismatch) or the underlying construction reports a
1156    /// failure.
1157    fn outer_product(&self, other: &Self) -> std::result::Result<Self, Self::Error>;
1158
1159    /// Permute tensor indices to match the specified order.
1160    ///
1161    /// # Errors
1162    ///
1163    /// Returns `Self::Error` when `new_order` does not contain exactly the
1164    /// tensor's external indices (an index-set mismatch or a missing-index
1165    /// failure).
1166    fn permuteinds(
1167        &self,
1168        new_order: &[<Self as TensorIndex>::Index],
1169    ) -> std::result::Result<Self, Self::Error>;
1170
1171    /// Fuse local tensor indices into one replacement index.
1172    ///
1173    /// # Errors
1174    ///
1175    /// Returns `Self::Error` when `old_indices` is not a subset of the
1176    /// tensor's external indices (a missing-index failure) or the fused
1177    /// dimension product overflows (an overflow failure).
1178    fn fuse_indices(
1179        &self,
1180        old_indices: &[<Self as TensorIndex>::Index],
1181        new_index: <Self as TensorIndex>::Index,
1182        order: LinearizationOrder,
1183    ) -> std::result::Result<Self, Self::Error>;
1184
1185    /// Contract a connected tensor network over its contractable indices.
1186    ///
1187    /// # Errors
1188    ///
1189    /// Returns `Self::Error` when the network is disconnected (a
1190    /// disconnected-network failure), when indices are incompatible (an
1191    /// index-space mismatch), or when the underlying contraction reports a
1192    /// failure.
1193    fn contract(tensors: &[&Self]) -> std::result::Result<Self, Self::Error>;
1194
1195    /// Contract tensors while preserving selected shared indices as batch axes.
1196    ///
1197    /// This seam was introduced for the batched SRC sketch. The paper basis is
1198    /// Algorithm 1's independent probe columns; the retained-index execution
1199    /// and fallback contract are tensor4all-specific `[AI-Supplied]` plumbing.
1200    ///
1201    /// A retained index is matched elementwise across operands instead of being
1202    /// summed. This is useful for evaluating several independent contractions
1203    /// in one backend call, such as a batch of SRC probe columns. Implementations
1204    /// that do not support retained batch axes may return an operation error.
1205    ///
1206    /// # Arguments
1207    /// * `tensors` - Connected tensor operands to contract.
1208    /// * `retained_indices` - Shared indices to preserve as output batch axes.
1209    ///
1210    /// # Returns
1211    /// The contracted tensor with each retained index present once in its output
1212    /// index list. An empty `retained_indices` list has the same meaning as
1213    /// [`Self::contract`].
1214    ///
1215    /// # Errors
1216    ///
1217    /// Returns `Self::Error` when the operands are disconnected, an operand
1218    /// index is missing or incompatible, or the retained-index operation is
1219    /// unsupported by the tensor type.
1220    ///
1221    /// # Examples
1222    ///
1223    /// ```
1224    /// use tensor4all_core::{DynIndex, IdxTensor, TensorContractionLike};
1225    ///
1226    /// let batch = DynIndex::new_dyn(2);
1227    /// let contracted = DynIndex::new_dyn(2);
1228    /// let left = IdxTensor::from_dense(
1229    ///     vec![batch.clone(), contracted.clone()],
1230    ///     vec![1.0_f64, 2.0, 3.0, 4.0],
1231    /// )
1232    /// .unwrap();
1233    /// let right = IdxTensor::from_dense(
1234    ///     vec![batch.clone(), contracted],
1235    ///     vec![2.0_f64, 3.0, 4.0, 5.0],
1236    /// )
1237    /// .unwrap();
1238    /// let result = IdxTensor::contract_retaining_indices(&[&left, &right], &[batch]).unwrap();
1239    /// assert_eq!(result.dims(), vec![2]);
1240    /// assert_eq!(result.to_vec::<f64>().unwrap(), vec![14.0, 26.0]);
1241    /// ```
1242    fn contract_retaining_indices(
1243        tensors: &[&Self],
1244        retained_indices: &[<Self as TensorIndex>::Index],
1245    ) -> std::result::Result<Self, Self::Error> {
1246        if retained_indices.is_empty() {
1247            return Self::contract(tensors);
1248        }
1249        Err(anyhow::anyhow!(
1250            "{} does not support retained contraction indices",
1251            std::any::type_name::<Self>()
1252        )
1253        .into())
1254    }
1255
1256    /// Contract this tensor with one other tensor using default pairwise semantics.
1257    ///
1258    /// # Errors
1259    ///
1260    /// Returns `Self::Error` when the pair is disconnected or has
1261    /// incompatible indices (an index-space mismatch); propagates failures
1262    /// from [`Self::contract`].
1263    fn contract_pair(&self, other: &Self) -> std::result::Result<Self, Self::Error> {
1264        Self::contract(&[self, other])
1265    }
1266
1267    /// Validate structural consistency of this tensor.
1268    ///
1269    /// # Errors
1270    ///
1271    /// Returns `Self::Error` when the tensor's index space or shape is
1272    /// structurally inconsistent (an index-space mismatch or an invalid
1273    /// internal state). The default implementation always returns `Ok(())`.
1274    fn validate(&self) -> std::result::Result<(), Self::Error> {
1275        Ok(())
1276    }
1277}
1278
1279/// Factorization operations for tensor-like values.
1280pub trait TensorFactorizationLike: TensorIndex {
1281    /// Factorize this tensor into left and right factors.
1282    /// # Errors
1283    ///
1284    /// Returns `FactorizeError` when the factorization fails (a non-convergence,
1285    /// singular, or unsupported-storage failure).
1286    ///
1287    fn factorize(
1288        &self,
1289        left_inds: &[<Self as TensorIndex>::Index],
1290        options: &FactorizeOptions,
1291    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError>;
1292
1293    /// Factorize using a caller-owned RNG consumed directly by randomized algorithms.
1294    ///
1295    /// Deterministic algorithms leave `rng` untouched. The default refuses RSVD;
1296    /// concrete tensor implementations can override it without exposing storage.
1297    ///
1298    /// # Errors
1299    /// Returns [`FactorizeError`] for unsupported randomized factorization,
1300    /// invalid options, or an underlying factorization failure.
1301    ///
1302    /// # Examples
1303    /// ```
1304    /// use rand::SeedableRng;
1305    /// use rand_chacha::ChaCha8Rng;
1306    /// use tensor4all_core::{DynIndex, FactorizeOptions, IdxTensor, TensorContractionLike, TensorFactorizationLike};
1307    /// let i = DynIndex::new_dyn(2);
1308    /// let j = DynIndex::new_dyn(2);
1309    /// let a = IdxTensor::from_dense(vec![i.clone(), j], vec![3., 0., 0., 0.])?;
1310    /// let mut rng = ChaCha8Rng::seed_from_u64(11);
1311    /// let result = a.factorize_with_rng(&[i], &FactorizeOptions::rsvd(1), &mut rng)?;
1312    /// assert!(a.sub(&result.left.contract_pair(&result.right)?)?.maxabs()? < 1e-12);
1313    /// # Ok::<(), Box<dyn std::error::Error>>(())
1314    /// ```
1315    fn factorize_with_rng(
1316        &self,
1317        left_inds: &[<Self as TensorIndex>::Index],
1318        options: &FactorizeOptions,
1319        rng: &mut dyn rand::RngCore,
1320    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError> {
1321        let _ = rng;
1322        if options.alg == FactorizeAlg::RSVD {
1323            return Err(FactorizeError::UnsupportedStorage(
1324                "this tensor type does not support randomized factorization",
1325            ));
1326        }
1327        self.factorize(left_inds, options)
1328    }
1329
1330    /// Factorize this tensor in a caller-owned execution context.
1331    ///
1332    /// Context-scoped counterpart of [`Self::factorize`]: the input must
1333    /// belong to `context`, and factors, truncation, and results stay in
1334    /// `context` with only bounded decision payloads crossing the explicit
1335    /// readback boundary on device-resident inputs.
1336    ///
1337    /// # Errors
1338    ///
1339    /// Returns `FactorizeError` when scoped factorization is unsupported for
1340    /// this tensor type, when the tensor does not belong to `context`, or
1341    /// when the factorization fails.
1342    fn factorize_in(
1343        &self,
1344        _left_inds: &[<Self as TensorIndex>::Index],
1345        _options: &FactorizeOptions,
1346        _context: &tensor4all_tensorbackend::ExecutionContext,
1347    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError> {
1348        Err(FactorizeError::UnsupportedStorage(
1349            "context-scoped factorization is not supported for this tensor type",
1350        ))
1351    }
1352
1353    /// Factorize this tensor using policy-aware automatic SVD/eigen selection.
1354    ///
1355    /// Implementations may use Hermitian Gram eigendecomposition when the
1356    /// requested SVD policy is numerically suitable. The default delegates to
1357    /// [`Self::factorize`], preserving the existing behavior for tensor types
1358    /// without an automatic eigendecomposition path.
1359    ///
1360    /// # Arguments
1361    /// * `left_inds` - Indices to place on the left side of the split.
1362    /// * `options` - Ordinary SVD factorization options, including canonical
1363    ///   direction, truncation policy, and maximum bond dimension.
1364    ///
1365    /// # Returns
1366    /// The same factorization result as [`Self::factorize`], with singular
1367    /// values populated for SVD-compatible implementations.
1368    ///
1369    /// # Errors
1370    /// Returns [`FactorizeError::InvalidOptions`] when `options.alg` is not
1371    /// [`FactorizeAlg::SVD`], or another [`FactorizeError`] when factorization
1372    /// fails.
1373    ///
1374    /// # Examples
1375    ///
1376    /// ```
1377    /// use tensor4all_core::{
1378    ///     DynIndex, FactorizeOptions, IdxTensor, SvdTruncationPolicy,
1379    ///     TensorFactorizationLike,
1380    /// };
1381    ///
1382    /// let left = DynIndex::new_dyn(2);
1383    /// let right = DynIndex::new_dyn(2);
1384    /// let tensor = IdxTensor::from_dense(
1385    ///     vec![left.clone(), right],
1386    ///     vec![1.0_f64, 0.0, 0.0, 1.0e-3],
1387    /// )?;
1388    /// let options = FactorizeOptions::svd()
1389    ///     .with_svd_policy(SvdTruncationPolicy::new(1.0e-2));
1390    /// let result = tensor.factorize_auto(&[left], &options)?;
1391    /// assert_eq!(result.rank, 1);
1392    /// # Ok::<(), Box<dyn std::error::Error>>(())
1393    /// ```
1394    fn factorize_auto(
1395        &self,
1396        left_inds: &[<Self as TensorIndex>::Index],
1397        options: &FactorizeOptions,
1398    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError> {
1399        if options.alg != FactorizeAlg::SVD {
1400            return Err(FactorizeError::InvalidOptions(
1401                "automatic factorization only supports SVD options",
1402            ));
1403        }
1404        self.factorize(left_inds, options)
1405    }
1406
1407    /// Factorize this tensor without applying truncation controls.
1408    /// # Errors
1409    ///
1410    /// Returns `FactorizeError` when the factorization fails (a non-convergence,
1411    /// singular, or unsupported-storage failure).
1412    ///
1413    fn factorize_full_rank(
1414        &self,
1415        left_inds: &[<Self as TensorIndex>::Index],
1416        alg: FactorizeAlg,
1417        canonical: Canonical,
1418    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError>;
1419
1420    /// Full-rank factorization in a caller-owned execution context.
1421    ///
1422    /// Context-scoped counterpart of [`Self::factorize_full_rank`] with the
1423    /// same algorithm coverage as the scoped free functions: QR and SVD
1424    /// execute in `context`; other algorithms return a typed error.
1425    ///
1426    /// # Errors
1427    ///
1428    /// Returns `FactorizeError` when scoped factorization is unsupported for
1429    /// this tensor type, when the tensor does not belong to `context`, or
1430    /// when the factorization fails.
1431    fn factorize_full_rank_in(
1432        &self,
1433        _left_inds: &[<Self as TensorIndex>::Index],
1434        _alg: FactorizeAlg,
1435        _canonical: Canonical,
1436        _context: &tensor4all_tensorbackend::ExecutionContext,
1437    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError> {
1438        Err(FactorizeError::UnsupportedStorage(
1439            "context-scoped full-rank factorization is not supported for this tensor type",
1440        ))
1441    }
1442
1443    /// Factorize a probe prefix, optionally extending an existing QR prefix.
1444    ///
1445    /// The append semantics are based on Appendix C of
1446    /// Camaño--Epperly--Tropp and the author's `IncrementalQR.append`; the
1447    /// generic trait/default implementation is repository plumbing and is
1448    /// labelled `[AI-Supplied]` in the audit.
1449    ///
1450    /// `all_columns` contains the complete prefix requested by the caller;
1451    /// `appended_columns` contains only the newly added columns when
1452    /// `previous` is present. Native dense implementations may use the
1453    /// previous factors and append only the new block. The default is a
1454    /// correctness fallback that factorizes the complete prefix from scratch.
1455    ///
1456    /// # Arguments
1457    /// * `previous` - Factors for the preceding prefix, or `None` for the first
1458    ///   prefix.
1459    /// * `all_columns` - All probe-column tensors in the new prefix.
1460    /// * `appended_columns` - Only the columns appended since `previous`.
1461    /// * `left_inds` - Tensor indices that form the matrix rows.
1462    ///
1463    /// # Returns
1464    /// A full-rank left-canonical QR factorization of the requested prefix.
1465    ///
1466    /// # Errors
1467    /// Returns [`FactorizeError`] when the prefix cannot be stacked or QR
1468    /// factorized.
1469    ///
1470    /// # Examples
1471    ///
1472    /// ```
1473    /// use tensor4all_core::{DynIndex, IdxTensor, TensorFactorizationLike};
1474    ///
1475    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
1476    /// let row = DynIndex::new_dyn(2);
1477    /// let first = IdxTensor::from_dense(
1478    ///     vec![row.clone()],
1479    ///     vec![1.0, 0.0],
1480    /// )?;
1481    /// let second = IdxTensor::from_dense(
1482    ///     vec![row.clone()],
1483    ///     vec![0.0, 1.0],
1484    /// )?;
1485    /// let result = <IdxTensor as TensorFactorizationLike>::factorize_probe_columns_incremental(
1486    ///     None,
1487    ///     &[&first, &second],
1488    ///     &[&first, &second],
1489    ///     &[row],
1490    /// )?;
1491    /// assert_eq!(result.rank, 2);
1492    /// assert_eq!(result.left.indices().len(), 2);
1493    /// # Ok(())
1494    /// # }
1495    /// ```
1496    fn factorize_probe_columns_incremental(
1497        _previous: Option<&FactorizeResult<Self>>,
1498        all_columns: &[&Self],
1499        _appended_columns: &[&Self],
1500        left_inds: &[<Self as TensorIndex>::Index],
1501    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError>
1502    where
1503        Self: TensorVectorSpace + TensorConstructionLike,
1504    {
1505        let batch = <Self as TensorIndex>::Index::new_link(all_columns.len())
1506            .map_err(FactorizeError::ComputationError)?;
1507        let sketch = Self::stack_along_new_index(all_columns, batch, -1)
1508            .map_err(|error| FactorizeError::ComputationError(anyhow::Error::new(error)))?;
1509        sketch.factorize_full_rank(left_inds, FactorizeAlg::QR, Canonical::Left)
1510    }
1511
1512    /// Batch-native variant of [`Self::factorize_probe_columns_incremental`]:
1513    /// `batch_tensor` carries a batch axis (`batch_index`) instead of being
1514    /// split into separate column tensors, letting an implementation avoid
1515    /// splitting an already-computed batch into columns and re-stacking them
1516    /// only to feed this call.
1517    ///
1518    /// The default implementation only supports the from-scratch case
1519    /// (`previous.is_none()`); it returns
1520    /// [`FactorizeError::UnsupportedStorage`] when asked to extend a
1521    /// previous factorization, exactly like this trait's
1522    /// [`Self::src_error_estimate`] default does for a capability a generic
1523    /// implementation cannot provide. `IdxTensor` overrides this with a true
1524    /// incremental implementation.
1525    ///
1526    /// Unlike [`Self::factorize_probe_columns_incremental`], whose default
1527    /// can always fall back to re-stacking `all_columns` and factorizing
1528    /// from scratch, this method's default has no such fallback once growth
1529    /// is needed: `tensor4all-treetn`'s adaptive SRC path
1530    /// (`factorize_probe_batches` in
1531    /// `crates/tensor4all-treetn/src/treetn/contraction/src_probe.rs`) calls
1532    /// this method with `previous.is_some()` on every growth step after the
1533    /// first, and always passes only the newly appended batch slice, never
1534    /// the cumulative range from the start. A backend that does not override
1535    /// this method therefore cannot use adaptive SRC at all once a second
1536    /// growth step is needed, even though the column-based path would have
1537    /// kept working (just less efficiently). This is a deliberate trade-off
1538    /// of the batch interface, not an oversight: a correct from-scratch
1539    /// re-derivation is not possible from an appended-only slice, so no
1540    /// generic default can close this gap.
1541    ///
1542    /// # Errors
1543    /// Returns [`FactorizeError`] when the batch cannot be factorized, or
1544    /// (default implementation only) when asked to extend a previous
1545    /// factorization.
1546    fn factorize_probe_batch_incremental(
1547        previous: Option<&FactorizeResult<Self>>,
1548        batch_tensor: &Self,
1549        batch_index: &<Self as TensorIndex>::Index,
1550        left_inds: &[<Self as TensorIndex>::Index],
1551    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError>
1552    where
1553        Self: TensorVectorSpace + TensorConstructionLike,
1554    {
1555        if previous.is_some() {
1556            return Err(FactorizeError::UnsupportedStorage(
1557                "incremental probe-batch growth is not supported for this tensor type",
1558            ));
1559        }
1560        let _ = batch_index;
1561        batch_tensor.factorize_full_rank(left_inds, FactorizeAlg::QR, Canonical::Left)
1562    }
1563
1564    /// Evaluate the SRC adaptive stopping estimator for a small QR factor.
1565    ///
1566    /// The tensor must represent a square upper-triangular `R` matrix in
1567    /// column-major order. Implementations that do not expose their small
1568    /// matrix storage return an unsupported-storage error.
1569    ///
1570    /// # Errors
1571    ///
1572    /// Returns [`FactorizeError`] when the tensor is not a supported QR factor,
1573    /// when its storage cannot be read as a dense matrix, or when the backend
1574    /// estimator rejects the matrix.
1575    ///
1576    /// # Examples
1577    ///
1578    /// ```
1579    /// use tensor4all_core::{DynIndex, IdxTensor, TensorFactorizationLike};
1580    ///
1581    /// let row = DynIndex::new_dyn(2);
1582    /// let column = DynIndex::new_dyn(2);
1583    /// let r = IdxTensor::from_dense(
1584    ///     vec![row, column],
1585    ///     vec![2.0_f64, 0.0, 1.0, 3.0],
1586    /// ).unwrap();
1587    /// let estimate = r.src_error_estimate().unwrap();
1588    /// assert!(estimate.error.is_finite());
1589    /// assert!(estimate.norm.is_finite());
1590    /// ```
1591    fn src_error_estimate(
1592        &self,
1593    ) -> std::result::Result<tensor4all_tensorbackend::SrcErrorEstimate, FactorizeError> {
1594        Err(FactorizeError::UnsupportedStorage(
1595            "SRC adaptive estimation is not supported for this tensor type",
1596        ))
1597    }
1598
1599    /// Evaluate the Appendix-C adaptive SRC error estimate in a caller-owned
1600    /// execution context.
1601    ///
1602    /// Context-scoped counterpart of [`Self::src_error_estimate`]: all
1603    /// arithmetic executes in `context`, with only bounded decision scalars
1604    /// crossing the explicit readback boundary on device-resident inputs.
1605    ///
1606    /// # Examples
1607    ///
1608    /// ```
1609    /// use std::sync::Arc;
1610    /// use tensor4all_core::{DynIndex, ExecutionContext, IdxTensor, TensorFactorizationLike};
1611    /// use tensor4all_tensorbackend::CpuExecutionContext;
1612    /// use tensor4all_tensorbackend::CpuBackend;
1613    ///
1614    /// let context = ExecutionContext::Cpu(Arc::new(
1615    ///     CpuExecutionContext::from_backend(CpuBackend::new()),
1616    /// ));
1617    /// let cap = DynIndex::new_dyn(2);
1618    /// let batch = DynIndex::new_dyn(2);
1619    /// let r = IdxTensor::from_dense_in(
1620    ///     &context,
1621    ///     vec![cap, batch],
1622    ///     vec![2.0_f64, 0.0, 0.0, 3.0],
1623    /// )?;
1624    /// let estimate = r.src_error_estimate_in(&context)?;
1625    /// // error = sqrt(mean(1/||x_col||^2)) with x = R^{-T}: (4 + 9)/2 -> sqrt.
1626    /// let expected = ((4.0_f64 + 9.0) / 2.0).sqrt();
1627    /// assert!((estimate.error - expected).abs() < 1e-12, "got {}", estimate.error);
1628    /// assert!((estimate.norm - (13.0_f64 / 2.0).sqrt()).abs() < 1e-12);
1629    /// # Ok::<(), Box<dyn std::error::Error>>(())
1630    /// ```
1631    ///
1632    /// # Errors
1633    ///
1634    /// Returns `FactorizeError` when the estimate is unsupported for this
1635    /// tensor type, when the factor does not belong to `context`, or when the
1636    /// solve, reductions, or explicit decision readback fail.
1637    fn src_error_estimate_in(
1638        &self,
1639        _context: &tensor4all_tensorbackend::ExecutionContext,
1640    ) -> std::result::Result<tensor4all_tensorbackend::SrcErrorEstimate, FactorizeError> {
1641        Err(FactorizeError::UnsupportedStorage(
1642            "context-scoped SRC adaptive estimation is not supported for this tensor type",
1643        ))
1644    }
1645
1646    /// Batch-native incremental probe factorization in a caller-owned context.
1647    ///
1648    /// Context-scoped counterpart of
1649    /// [`Self::factorize_probe_batch_incremental`]: sketch columns, QR factors,
1650    /// and results all stay in `context` with no host round-trip.
1651    ///
1652    /// # Errors
1653    ///
1654    /// Returns `FactorizeError` when the factorization is unsupported for this
1655    /// tensor type, when an input does not belong to `context`, or when the
1656    /// resident factorization fails.
1657    fn factorize_probe_batch_incremental_in(
1658        _previous: Option<&FactorizeResult<Self>>,
1659        _batch_tensor: &Self,
1660        _batch_index: &<Self as TensorIndex>::Index,
1661        _left_inds: &[<Self as TensorIndex>::Index],
1662        _context: &tensor4all_tensorbackend::ExecutionContext,
1663    ) -> std::result::Result<FactorizeResult<Self>, FactorizeError>
1664    where
1665        Self: TensorVectorSpace + TensorConstructionLike,
1666    {
1667        Err(FactorizeError::UnsupportedStorage(
1668            "context-scoped incremental probe factorization is not supported for this tensor type",
1669        ))
1670    }
1671}
1672
1673/// Constructors and selection helpers for index-labelled tensors.
1674pub trait TensorConstructionLike: TensorContractionLike {
1675    /// Create a diagonal (Kronecker delta) tensor for a single index pair.
1676    ///
1677    /// # Errors
1678    ///
1679    /// Returns `Self::Error` when the input and output indices have unequal
1680    /// dimensions (a shape mismatch) or the underlying construction
1681    /// reports a failure.
1682    fn diagonal(
1683        input_index: &<Self as TensorIndex>::Index,
1684        output_index: &<Self as TensorIndex>::Index,
1685    ) -> std::result::Result<Self, Self::Error>;
1686
1687    /// Create a delta (identity) tensor as outer product of diagonals.
1688    ///
1689    /// # Errors
1690    ///
1691    /// Returns `Self::Error` when the input and output index lists differ in
1692    /// length (a length mismatch) or when a constituent diagonal or outer
1693    /// product reports a failure; propagates failures from [`Self::diagonal`],
1694    /// [`Self::scalar_one`], and [`TensorContractionLike::outer_product`].
1695    fn delta(
1696        input_indices: &[<Self as TensorIndex>::Index],
1697        output_indices: &[<Self as TensorIndex>::Index],
1698    ) -> std::result::Result<Self, Self::Error> {
1699        if input_indices.len() != output_indices.len() {
1700            return Err(anyhow::anyhow!(
1701                "Number of input indices ({}) must match output indices ({})",
1702                input_indices.len(),
1703                output_indices.len()
1704            )
1705            .into());
1706        }
1707
1708        if input_indices.is_empty() {
1709            return Self::scalar_one();
1710        }
1711
1712        let mut result = Self::diagonal(&input_indices[0], &output_indices[0])?;
1713        for (inp, out) in input_indices[1..].iter().zip(output_indices[1..].iter()) {
1714            let diag = Self::diagonal(inp, out)?;
1715            result = result.outer_product(&diag)?;
1716        }
1717        Ok(result)
1718    }
1719
1720    /// Create a scalar tensor with value 1.0.
1721    ///
1722    /// # Errors
1723    ///
1724    /// Returns `Self::Error` when the scalar type does not support the
1725    /// required construction (an invalid scalar dtype or a backend
1726    /// construction failure).
1727    fn scalar_one() -> std::result::Result<Self, Self::Error>;
1728
1729    /// Create a tensor filled with 1.0 for the given indices.
1730    ///
1731    /// # Errors
1732    ///
1733    /// Returns `Self::Error` when an index dimension product overflows (an
1734    /// overflow failure) or the underlying construction reports a failure.
1735    fn ones(indices: &[<Self as TensorIndex>::Index]) -> std::result::Result<Self, Self::Error>;
1736
1737    /// Create an all-ones tensor in a caller-owned execution context.
1738    ///
1739    /// Context-scoped counterpart of [`Self::ones`]: the result belongs to
1740    /// `context`, with an explicit host-to-device transfer for CUDA contexts.
1741    ///
1742    /// # Examples
1743    ///
1744    /// ```
1745    /// use std::sync::Arc;
1746    /// use tensor4all_core::{DynIndex, ExecutionContext, TensorConstructionLike};
1747    /// use tensor4all_core::IdxTensor;
1748    /// use tensor4all_tensorbackend::CpuExecutionContext;
1749    /// use tensor4all_tensorbackend::CpuBackend;
1750    ///
1751    /// let context = ExecutionContext::Cpu(Arc::new(
1752    ///     CpuExecutionContext::from_backend(CpuBackend::new()),
1753    /// ));
1754    /// let tensor = <IdxTensor as TensorConstructionLike>::ones_in(
1755    ///     &context,
1756    ///     &[DynIndex::new_dyn(2)],
1757    /// )?;
1758    /// assert_eq!(tensor.to_vec::<f64>()?, vec![1.0, 1.0]);
1759    /// # Ok::<(), Box<dyn std::error::Error>>(())
1760    /// ```
1761    ///
1762    /// # Errors
1763    ///
1764    /// Returns `Self::Error` with an `UnsupportedStorage` failure when
1765    /// construction is unsupported for this tensor type; other failures
1766    /// report an invalid payload or a backend transfer failure.
1767    fn ones_in(
1768        _context: &tensor4all_tensorbackend::ExecutionContext,
1769        _indices: &[<Self as TensorIndex>::Index],
1770    ) -> std::result::Result<Self, Self::Error> {
1771        Err(anyhow::anyhow!(
1772            "context-scoped ones construction is not supported for this tensor type"
1773        )
1774        .into())
1775    }
1776
1777    /// Validate that this tensor belongs to the supplied execution context.
1778    ///
1779    /// Generic SRC entries call this on every input tensor before RNG
1780    /// advancement or contraction, so mixed host/CUDA inputs and foreign CUDA
1781    /// contexts fail at the boundary with typed errors.
1782    ///
1783    /// # Errors
1784    ///
1785    /// Returns `Self::Error` with an `UnsupportedStorage` failure when
1786    /// validation is unsupported for this tensor type, or a backend failure
1787    /// when tensor placement does not belong to `context`.
1788    fn validate_context(
1789        &self,
1790        _context: &tensor4all_tensorbackend::ExecutionContext,
1791    ) -> std::result::Result<(), Self::Error> {
1792        Err(anyhow::anyhow!("context validation is not supported for this tensor type").into())
1793    }
1794
1795    /// Re-publish this tensor in a caller-owned execution context.
1796    ///
1797    /// Context-scoped algorithms that take a whole tensor network adopt every
1798    /// input tensor this way; the context-scoped truncation entry does, so a
1799    /// network loaded from disk or materialised by TCI works without a
1800    /// caller-side rebuild.
1801    ///
1802    /// # Errors
1803    ///
1804    /// Returns `Self::Error` with an `UnsupportedStorage` failure when adoption
1805    /// is unsupported for this tensor type, and a backend failure when the
1806    /// stored payload cannot be re-published or the tensor already belongs to a
1807    /// *different* execution context than `context`.
1808    fn adopt_into(
1809        &self,
1810        _context: &tensor4all_tensorbackend::ExecutionContext,
1811    ) -> std::result::Result<Self, Self::Error> {
1812        Err(anyhow::anyhow!("context adoption is not supported for this tensor type").into())
1813    }
1814
1815    /// Construct a tensor from a column-major dense payload.
1816    ///
1817    /// Implementations with a native dense storage path should override this
1818    /// method. The default preserves compatibility for tensor types that only
1819    /// expose one-hot construction, at the cost of constructing a sparse sum
1820    /// of one-hot tensors.
1821    ///
1822    /// # Arguments
1823    /// * `indices` - External indices in the intended column-major axis order.
1824    /// * `data` - Dense values in column-major order; its length must equal the
1825    ///   product of the index dimensions.
1826    ///
1827    /// # Errors
1828    ///
1829    /// Returns `Self::Error` when the input payload length does not match the
1830    /// product of the index dimensions, that index-dimension product would
1831    /// overflow `usize`, or an underlying tensor construction operation fails.
1832    ///
1833    /// # Examples
1834    ///
1835    /// ```
1836    /// use tensor4all_core::{AnyScalar, DynIndex, IdxTensor, TensorConstructionLike};
1837    ///
1838    /// let index = DynIndex::new_dyn(2);
1839    /// let tensor = <IdxTensor as TensorConstructionLike>::from_dense_any(
1840    ///     vec![index],
1841    ///     vec![AnyScalar::new_real(2.0), AnyScalar::new_real(3.0)],
1842    /// )
1843    /// .unwrap();
1844    /// assert_eq!(tensor.to_vec::<f64>().unwrap(), vec![2.0, 3.0]);
1845    /// ```
1846    fn from_dense_any(
1847        indices: Vec<<Self as TensorIndex>::Index>,
1848        data: Vec<AnyScalar>,
1849    ) -> std::result::Result<Self, Self::Error>
1850    where
1851        Self: TensorVectorSpace,
1852    {
1853        let expected_len = indices.iter().try_fold(1usize, |size, index| {
1854            size.checked_mul(index.dim())
1855                .ok_or_else(|| anyhow::anyhow!("dense tensor shape product overflows usize"))
1856        })?;
1857        if data.len() != expected_len {
1858            return Err(anyhow::anyhow!(
1859                "dense tensor payload has length {}, expected {}",
1860                data.len(),
1861                expected_len
1862            )
1863            .into());
1864        }
1865
1866        let mut result = Self::ones(&indices)?.scale(AnyScalar::new_real(0.0))?;
1867        let one = AnyScalar::new_real(1.0);
1868        for (linear, value) in data.into_iter().enumerate() {
1869            if value.is_zero() {
1870                continue;
1871            }
1872            let mut remainder = linear;
1873            let mut index_vals = Vec::with_capacity(indices.len());
1874            for index in &indices {
1875                let dim = index.dim();
1876                let position = remainder % dim;
1877                remainder /= dim;
1878                index_vals.push((index.clone(), position));
1879            }
1880            let basis = Self::onehot(&index_vals)?;
1881            let term = basis.scale(value)?;
1882            result = result.axpby(one.clone(), &term, one.clone())?;
1883        }
1884        Ok(result)
1885    }
1886
1887    /// Construct a tensor directly from a typed column-major dense payload.
1888    ///
1889    /// Implementations with native typed storage should override this method to
1890    /// avoid converting every element through [`AnyScalar`].
1891    ///
1892    /// # Arguments
1893    ///
1894    /// * `indices` - External indices in the intended column-major axis order.
1895    /// * `data` - Typed dense values in column-major order; its length must equal
1896    ///   the product of the index dimensions.
1897    ///
1898    /// # Returns
1899    ///
1900    /// A tensor whose dtype is selected from `T` by the implementation.
1901    ///
1902    /// # Errors
1903    ///
1904    /// Returns `Self::Error` when the index-dimension product overflows, the
1905    /// data length does not match that product, the scalar dtype is unsupported,
1906    /// or [`Self::from_dense_any`] otherwise rejects construction.
1907    ///
1908    /// # Examples
1909    ///
1910    /// ```
1911    /// use tensor4all_core::{DynIndex, IdxTensor, TensorConstructionLike};
1912    ///
1913    /// let index = DynIndex::new_dyn(2);
1914    /// let tensor = <IdxTensor as TensorConstructionLike>::from_dense(
1915    ///     vec![index],
1916    ///     vec![2.0_f64, 3.0],
1917    /// )
1918    /// .unwrap();
1919    /// assert_eq!(tensor.to_vec::<f64>().unwrap(), vec![2.0, 3.0]);
1920    /// ```
1921    fn from_dense<T>(
1922        indices: Vec<<Self as TensorIndex>::Index>,
1923        data: Vec<T>,
1924    ) -> std::result::Result<Self, Self::Error>
1925    where
1926        Self: TensorVectorSpace,
1927        T: TensorElement + Into<AnyScalar>,
1928    {
1929        Self::from_dense_any(indices, data.into_iter().map(Into::into).collect())
1930    }
1931
1932    /// Construct a tensor from a column-major dense payload in a caller-owned
1933    /// execution context.
1934    ///
1935    /// Context-scoped counterpart of [`Self::from_dense`]: host-originated
1936    /// data takes one explicit construction transfer for CUDA contexts, and
1937    /// the result belongs to `context`.
1938    ///
1939    /// # Examples
1940    ///
1941    /// ```
1942    /// use std::sync::Arc;
1943    /// use tensor4all_core::{DynIndex, ExecutionContext, TensorConstructionLike};
1944    /// use tensor4all_core::IdxTensor;
1945    /// use tensor4all_tensorbackend::CpuExecutionContext;
1946    /// use tensor4all_tensorbackend::CpuBackend;
1947    ///
1948    /// let context = ExecutionContext::Cpu(Arc::new(
1949    ///     CpuExecutionContext::from_backend(CpuBackend::new()),
1950    /// ));
1951    /// let tensor = <IdxTensor as TensorConstructionLike>::from_dense_in(
1952    ///     &context,
1953    ///     vec![DynIndex::new_dyn(2)],
1954    ///     vec![2.0_f64, 3.0],
1955    /// )?;
1956    /// assert_eq!(tensor.to_vec::<f64>()?, vec![2.0, 3.0]);
1957    /// # Ok::<(), Box<dyn std::error::Error>>(())
1958    /// ```
1959    ///
1960    /// # Errors
1961    ///
1962    /// Returns `Self::Error` with an `UnsupportedStorage` failure when
1963    /// construction is unsupported for this tensor type; other failures
1964    /// report an invalid payload or a backend transfer failure.
1965    fn from_dense_in<T>(
1966        _context: &tensor4all_tensorbackend::ExecutionContext,
1967        _indices: Vec<<Self as TensorIndex>::Index>,
1968        _data: Vec<T>,
1969    ) -> std::result::Result<Self, Self::Error>
1970    where
1971        Self: TensorVectorSpace,
1972        T: TensorElement + Into<AnyScalar>,
1973    {
1974        Err(anyhow::anyhow!(
1975            "context-scoped dense construction is not supported for this tensor type"
1976        )
1977        .into())
1978    }
1979
1980    /// Stack tensors along a newly created batch index.
1981    ///
1982    /// Implementations with a native batch stack should override this method.
1983    /// The default constructs the batch by outer products with one-hot batch
1984    /// vectors, which is correct but intended only as a compatibility path.
1985    ///
1986    /// # Arguments
1987    /// * `tensors` - Non-empty tensors with identical external index order.
1988    /// * `new_index` - Fresh index whose dimension equals `tensors.len()`.
1989    /// * `axis` - Insertion axis; negative axes count from the end, so `-1`
1990    ///   appends the batch axis.
1991    ///
1992    /// # Errors
1993    /// Returns `Self::Error` when tensors are empty, their index orders differ,
1994    /// the batch dimension is wrong, the axis is invalid, or construction
1995    /// fails.
1996    ///
1997    /// # Examples
1998    ///
1999    /// ```
2000    /// use tensor4all_core::{DynIndex, IdxTensor, TensorConstructionLike};
2001    ///
2002    /// let index = DynIndex::new_dyn(2);
2003    /// let batch = DynIndex::new_dyn(2);
2004    /// let first = IdxTensor::from_dense(vec![index.clone()], vec![1.0, 2.0]).unwrap();
2005    /// let second = IdxTensor::from_dense(vec![index.clone()], vec![3.0, 4.0]).unwrap();
2006    /// let stacked = <IdxTensor as TensorConstructionLike>::stack_along_new_index(
2007    ///     &[&first, &second],
2008    ///     batch.clone(),
2009    ///     -1,
2010    /// )
2011    /// .unwrap();
2012    /// assert_eq!(stacked.indices(), &[index, batch]);
2013    /// assert_eq!(stacked.to_vec::<f64>().unwrap(), vec![1.0, 2.0, 3.0, 4.0]);
2014    /// ```
2015    fn stack_along_new_index(
2016        tensors: &[&Self],
2017        new_index: <Self as TensorIndex>::Index,
2018        axis: isize,
2019    ) -> std::result::Result<Self, Self::Error>
2020    where
2021        Self: TensorVectorSpace,
2022    {
2023        let first = tensors
2024            .first()
2025            .ok_or_else(|| anyhow::anyhow!("stack_along_new_index requires at least one tensor"))?;
2026        if new_index.dim() != tensors.len() {
2027            return Err(anyhow::anyhow!(
2028                "stack_along_new_index batch dimension {} does not match tensor count {}",
2029                new_index.dim(),
2030                tensors.len()
2031            )
2032            .into());
2033        }
2034        let base_indices = first.external_indices();
2035        for tensor in tensors.iter().skip(1) {
2036            if tensor.external_indices() != base_indices {
2037                return Err(anyhow::anyhow!(
2038                    "stack_along_new_index tensors must have identical index order"
2039                )
2040                .into());
2041            }
2042        }
2043
2044        let result_rank = base_indices.len() + 1;
2045        let insertion_axis = if axis < 0 {
2046            result_rank as isize + axis
2047        } else {
2048            axis
2049        };
2050        if !(0..=base_indices.len() as isize).contains(&insertion_axis) {
2051            return Err(anyhow::anyhow!(
2052                "stack_along_new_index axis {} is invalid for rank {}",
2053                axis,
2054                base_indices.len()
2055            )
2056            .into());
2057        }
2058
2059        let batch_one = AnyScalar::new_real(1.0);
2060        let mut result: Option<Self> = None;
2061        for (position, tensor) in tensors.iter().enumerate() {
2062            let batch = Self::onehot(&[(new_index.clone(), position)])?;
2063            let term = tensor.outer_product(&batch)?;
2064            result = Some(match result {
2065                Some(current) => current.axpby(batch_one.clone(), &term, batch_one.clone())?,
2066                None => term,
2067            });
2068        }
2069        let mut desired = base_indices;
2070        desired.insert(insertion_axis as usize, new_index);
2071        let result = result
2072            .ok_or_else(|| anyhow::anyhow!("stack_along_new_index requires at least one tensor"))?;
2073        if result.external_indices() == desired {
2074            Ok(result)
2075        } else {
2076            result.permuteinds(&desired)
2077        }
2078    }
2079
2080    /// Concatenate tensors whose selected axes are replaced by one new index.
2081    ///
2082    /// The tensors must have the same index order away from the selected axis.
2083    /// Each tensor may use a distinct source index at that axis; the source
2084    /// axes are copied in tensor order into `new_index`. This is the batched
2085    /// counterpart to appending column blocks without recomputing the old
2086    /// columns.
2087    ///
2088    /// # Arguments
2089    /// * `tensors` - Non-empty tensors with matching non-concatenated axes.
2090    /// * `source_indices` - One axis to concatenate for each tensor.
2091    /// * `new_index` - Fresh output axis whose dimension is the sum of source
2092    ///   dimensions.
2093    ///
2094    /// # Errors
2095    ///
2096    /// Returns `Self::Error` when the input list is empty; the tensor and
2097    /// source-index counts do not match; a source index is missing; source axes
2098    /// occupy incompatible positions; non-concatenated indices are
2099    /// incompatible; the source-dimension sum overflows; or the new index
2100    /// dimension does not match that sum.
2101    ///
2102    /// # Examples
2103    ///
2104    /// ```
2105    /// use tensor4all_core::{DynIndex, IdxTensor, TensorConstructionLike};
2106    ///
2107    /// let row = DynIndex::new_dyn(2);
2108    /// let first_batch = DynIndex::new_link(1).unwrap();
2109    /// let second_batch = DynIndex::new_link(2).unwrap();
2110    /// let combined = DynIndex::new_link(3).unwrap();
2111    /// let first = IdxTensor::from_dense(
2112    ///     vec![row.clone(), first_batch.clone()],
2113    ///     vec![1.0_f64, 2.0],
2114    /// ).unwrap();
2115    /// let second = IdxTensor::from_dense(
2116    ///     vec![row.clone(), second_batch.clone()],
2117    ///     vec![3.0, 4.0, 5.0, 6.0],
2118    /// ).unwrap();
2119    /// let result = <IdxTensor as TensorConstructionLike>::concatenate_along_new_index(
2120    ///     &[&first, &second],
2121    ///     &[first_batch, second_batch],
2122    ///     combined.clone(),
2123    /// ).unwrap();
2124    /// assert_eq!(result.indices(), &[row, combined]);
2125    /// assert_eq!(result.to_vec::<f64>().unwrap(), vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
2126    /// ```
2127    fn concatenate_along_new_index(
2128        tensors: &[&Self],
2129        source_indices: &[<Self as TensorIndex>::Index],
2130        new_index: <Self as TensorIndex>::Index,
2131    ) -> std::result::Result<Self, Self::Error>
2132    where
2133        Self: TensorVectorSpace,
2134    {
2135        let first = tensors
2136            .first()
2137            .ok_or_else(|| anyhow::anyhow!("concatenate requires at least one tensor"))?;
2138        if tensors.len() != source_indices.len() {
2139            return Err(anyhow::anyhow!(
2140                "concatenate tensor count {} does not match source-index count {}",
2141                tensors.len(),
2142                source_indices.len()
2143            )
2144            .into());
2145        }
2146        let first_axis = first
2147            .external_indices()
2148            .iter()
2149            .position(|index| index == &source_indices[0])
2150            .ok_or_else(|| anyhow::anyhow!("concatenate source index is not present"))?;
2151        let mut total_dim = 0usize;
2152        for (tensor, source) in tensors.iter().zip(source_indices) {
2153            let axis = tensor
2154                .external_indices()
2155                .iter()
2156                .position(|index| index == source)
2157                .ok_or_else(|| anyhow::anyhow!("concatenate source index is not present"))?;
2158            if axis != first_axis {
2159                return Err(
2160                    anyhow::anyhow!("concatenate source axes must have the same position").into(),
2161                );
2162            }
2163            let indices = tensor.external_indices();
2164            let first_indices = first.external_indices();
2165            if indices.len() != first_indices.len()
2166                || indices.iter().zip(first_indices).enumerate().any(
2167                    |(position, (actual, expected))| position != first_axis && *actual != expected,
2168                )
2169            {
2170                return Err(anyhow::anyhow!(
2171                    "concatenate tensors must match away from the source axis"
2172                )
2173                .into());
2174            }
2175            total_dim = total_dim
2176                .checked_add(source.dim())
2177                .ok_or_else(|| anyhow::anyhow!("concatenate dimension overflow"))?;
2178        }
2179        if new_index.dim() != total_dim {
2180            return Err(anyhow::anyhow!(
2181                "concatenate output dimension {} does not match source dimension sum {}",
2182                new_index.dim(),
2183                total_dim
2184            )
2185            .into());
2186        }
2187
2188        let mut slices = Vec::with_capacity(total_dim);
2189        for (tensor, source) in tensors.iter().zip(source_indices) {
2190            for position in 0..source.dim() {
2191                slices.push(tensor.select_indices(std::slice::from_ref(source), &[position])?);
2192            }
2193        }
2194        let slice_refs = slices.iter().collect::<Vec<_>>();
2195        Self::stack_along_new_index(&slice_refs, new_index, first_axis as isize)
2196    }
2197
2198    /// Select fixed coordinates for a subset of this tensor's external indices.
2199    ///
2200    /// # Errors
2201    ///
2202    /// Returns `Self::Error` when `selected_indices` and `positions` differ in
2203    /// length (a length mismatch), when an index is selected more than once
2204    /// (a duplicate-index failure), when a coordinate is out of range (an
2205    /// out of bounds failure), or when the underlying one-hot construction or
2206    /// contraction reports a failure; propagates failures from
2207    /// [`Self::onehot`] and [`TensorContractionLike::contract`].
2208    fn select_indices(
2209        &self,
2210        selected_indices: &[<Self as TensorIndex>::Index],
2211        positions: &[usize],
2212    ) -> std::result::Result<Self, Self::Error> {
2213        if selected_indices.len() != positions.len() {
2214            return Err(anyhow::anyhow!(
2215                "selected_indices length {} does not match positions length {}",
2216                selected_indices.len(),
2217                positions.len()
2218            )
2219            .into());
2220        }
2221        if selected_indices.is_empty() {
2222            return Ok(self.clone());
2223        }
2224
2225        let mut seen = HashSet::with_capacity(selected_indices.len());
2226        for (index, &position) in selected_indices.iter().zip(positions.iter()) {
2227            if !seen.insert(index.clone()) {
2228                return Err(anyhow::anyhow!("selected index appears more than once").into());
2229            }
2230            if position >= index.dim() {
2231                return Err(anyhow::anyhow!(
2232                    "selected coordinate {} is out of range for index {:?} with dim {}",
2233                    position,
2234                    index,
2235                    index.dim()
2236                )
2237                .into());
2238            }
2239        }
2240
2241        let index_vals = selected_indices
2242            .iter()
2243            .cloned()
2244            .zip(positions.iter().copied())
2245            .collect::<Vec<_>>();
2246        let onehot = Self::onehot(&index_vals)?;
2247        Self::contract(&[self, &onehot])
2248    }
2249
2250    /// Create a one-hot tensor with value 1.0 at the specified index positions.
2251    ///
2252    /// # Errors
2253    ///
2254    /// Returns `Self::Error` when a position is out of range for its index
2255    /// (an out of bounds failure) or the underlying construction reports a
2256    /// failure.
2257    fn onehot(
2258        index_vals: &[(<Self as TensorIndex>::Index, usize)],
2259    ) -> std::result::Result<Self, Self::Error>;
2260}
2261
2262// ============================================================================
2263// TensorLike trait (fully generic composite)
2264// ============================================================================
2265
2266/// Trait for tensor-like objects that expose external indices and support contraction.
2267///
2268/// This trait is **fully generic** (monomorphic), meaning it does not support
2269/// trait objects (`dyn TensorLike`). For heterogeneous tensor collections,
2270/// use an enum wrapper instead.
2271///
2272/// # Design Principles
2273///
2274/// - **Capability composition**: combines vector-space, factorization, construction, and contraction traits
2275/// - **Fully generic**: Uses associated type for `Index`, returns `Self`
2276/// - **Stable ordering**: `external_indices()` returns indices in deterministic order
2277/// - **No trait objects**: Requires `Sized`, cannot use `dyn TensorLike`
2278///
2279/// # Example
2280///
2281/// ```
2282/// use tensor4all_core::{DynIndex, TensorContractionLike, IdxTensor};
2283///
2284/// fn contract_pair(a: &IdxTensor, b: &IdxTensor) -> anyhow::Result<IdxTensor> {
2285///     Ok(<IdxTensor as TensorContractionLike>::contract(&[a, b])?)
2286/// }
2287///
2288/// # fn main() -> anyhow::Result<()> {
2289/// let i = DynIndex::new_dyn(2);
2290/// let j = DynIndex::new_dyn(2);
2291/// let a = IdxTensor::from_dense(
2292///     vec![i.clone(), j.clone()],
2293///     vec![1.0, 0.0, 0.0, 1.0],
2294/// )?;
2295/// let b = IdxTensor::from_dense(vec![j.clone()], vec![2.0, 3.0])?;
2296///
2297/// let result = contract_pair(&a, &b)?;
2298/// assert_eq!(result.to_vec::<f64>()?, vec![2.0, 3.0]);
2299/// # Ok(())
2300/// # }
2301/// ```
2302///
2303/// # Heterogeneous Collections
2304///
2305/// For mixing different tensor types, define an enum:
2306///
2307/// ```
2308/// use tensor4all_core::{block_tensor::BlockTensor, DynIndex, IdxTensor};
2309///
2310/// let i = DynIndex::new_dyn(2);
2311/// let dense = IdxTensor::from_dense(vec![i.clone()], vec![1.0, 2.0]).unwrap();
2312/// let block = BlockTensor::new(vec![dense.clone()], (1, 1)).unwrap();
2313///
2314/// enum TensorNetwork {
2315///     Dense(IdxTensor),
2316///     Block(BlockTensor<IdxTensor>),
2317/// }
2318///
2319/// let network = TensorNetwork::Block(block);
2320/// assert!(matches!(network, TensorNetwork::Block(_)));
2321/// ```
2322///
2323/// # Supertrait
2324///
2325/// `TensorLike` extends several capability traits. Through those traits it provides:
2326/// - `external_indices()` - Get all external indices
2327/// - `num_external_indices()` - Count external indices
2328/// - `replaceind()` / `replace_indices()` - Replace indices
2329/// - vector-space operations such as `axpby`, `inner_product`, and `norm`
2330/// - tensor-network operations such as contraction, construction, and factorization
2331///
2332/// Use narrower traits such as [`TensorVectorSpace`] or
2333/// [`TensorContractionLike`] when an algorithm does not need the full surface.
2334pub trait TensorLike: TensorVectorSpace + TensorFactorizationLike + TensorConstructionLike {}
2335
2336impl<T> TensorLike for T where
2337    T: TensorVectorSpace + TensorFactorizationLike + TensorConstructionLike
2338{
2339}
2340
2341/// Result of direct sum operation.
2342///
2343/// Contains the resulting tensor and the new indices created for the summed
2344/// dimensions (one new index per pair in the input).
2345///
2346/// # Examples
2347///
2348/// ```
2349/// use tensor4all_core::{DynIndex, IndexLike, TensorContractionLike, IdxTensor};
2350///
2351/// let i = DynIndex::new_dyn(2);
2352/// let j = DynIndex::new_dyn(3);
2353///
2354/// let a = IdxTensor::from_dense(vec![i.clone()], vec![1.0, 2.0]).unwrap();
2355/// let b = IdxTensor::from_dense(vec![j.clone()], vec![3.0, 4.0, 5.0]).unwrap();
2356///
2357/// let result = a.direct_sum(&b, &[(i.clone(), j.clone())]).unwrap();
2358///
2359/// // New index has dimension = 2 + 3 = 5
2360/// assert_eq!(result.new_indices.len(), 1);
2361/// assert_eq!(result.new_indices[0].dim(), 5);
2362/// assert_eq!(result.tensor.to_vec::<f64>().unwrap(), vec![1.0, 2.0, 3.0, 4.0, 5.0]);
2363/// ```
2364#[derive(Debug, Clone)]
2365pub struct DirectSumResult<T: TensorIndex> {
2366    /// The resulting tensor from direct sum.
2367    pub tensor: T,
2368    /// New indices created for the summed dimensions (one per pair).
2369    pub new_indices: Vec<T::Index>,
2370}
2371
2372#[cfg(test)]
2373mod tests;