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;