Skip to main content

tensor4all_core/
lib.rs

1#![warn(missing_docs)]
2//! Core tensor operations and types for tensor4all-rs.
3//!
4//! This crate provides the foundational types and operations for tensor networks:
5//!
6//! - **Index types**: [`DynIndex`], [`Index`], [`DynId`] for tensor indices
7//! - **Tag sets**: [`TagSet`], [`TagSetLike`] for metadata tagging
8//! - **Tensors**: [`IdxTensor`] for dynamic-rank dense tensors
9//! - **Operations**: Contraction, SVD, QR decomposition, factorization
10//!
11//! # Example
12//!
13//! ```
14//! use tensor4all_core::{Index, DynIndex, IdxTensor};
15//!
16//! // Create indices with dynamic identity
17//! let i = Index::new_dyn(2);
18//! let j = Index::new_dyn(3);
19//!
20//! // Create a tensor
21//! let data = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
22//! let t = IdxTensor::from_dense(vec![i.clone(), j.clone()], data).unwrap();
23//! ```
24
25#[cfg(doctest)]
26#[doc = include_str!("../README.md")]
27pub struct ReadmeDoctests;
28
29pub mod prelude;
30
31pub mod chain_compression;
32pub use chain_compression::{
33    compress_chain_cores_mut, compress_chain_lu_mut, compress_chain_lu_on_session,
34    ChainCompressionError, ChainCore, ChainLuFactorization, ChainLuOptions,
35};
36
37pub mod col_major_array;
38pub use col_major_array::{ColMajorArray, ColMajorArrayMut, ColMajorArrayRef};
39
40// Common (tags, utilities, scalar)
41/// Dynamic scalar compatibility wrapper built on rank-0 `IdxTensor`.
42pub mod any_scalar;
43pub mod global_default;
44/// Bit-packed integer keys for multi-index maps.
45pub mod index_key;
46pub mod index_like;
47pub mod scalar;
48/// Stack-allocated fixed-capacity string types for ITensors.jl compatibility.
49pub mod smallstring;
50/// Tag set types for tensor metadata.
51pub mod tagset;
52pub mod truncation;
53
54/// Shared element-count budget for dense materialization in production paths.
55pub mod dense_budget;
56pub use dense_budget::{DenseBudgetError, DenseElementBudget, DEFAULT_MAX_DENSE_ELEMENTS};
57
58// TCI substrate absorbed from tensor4all-tcicore (dissolved, #639): matrix
59// cross interpolation (LU/LUCI/ACA), common scalar trait, floating-zone
60// pivot search, caching, and index sets.
61pub mod cached_function;
62pub mod error;
63pub mod floating_zone;
64pub mod indexset;
65mod matrix_luci;
66pub mod matrixaca;
67pub mod matrixlu;
68pub mod matrixluci;
69pub mod traits;
70
71pub use self::matrixluci::MatrixLuciScalar;
72pub use cached_function::cache_key::CacheKey;
73pub use cached_function::error::CacheKeyError;
74pub use cached_function::index_int::IndexInt;
75pub use cached_function::multi_index_cache::{
76    CachedBatchError, LeftSide, MultiIndexCache, RightSide, SideKeys, DEFAULT_RETAINED_BYTE_LIMIT,
77};
78pub use cached_function::CachedFunction;
79pub use error::{MatrixCIError, Result};
80pub use floating_zone::{
81    floating_zone_walk, floating_zone_walk_with_initial_error, FloatingZoneError,
82};
83pub use indexset::{IndexSet, LocalIndex, MultiIndex};
84#[doc(hidden)]
85pub use matrix_luci::matrix_luci_factors_from_blocks_seeded;
86pub use matrix_luci::{
87    matrix_luci_factors_from_blocks, matrix_luci_factors_from_matrix,
88    matrix_luci_factors_from_matrix_owned, matrix_luci_factors_from_matrix_owned_in,
89    matrix_luci_factors_from_matrix_owned_on_session,
90    matrix_luci_factors_from_matrix_owned_with_rank_selection,
91    matrix_luci_factors_from_matrix_owned_with_rank_selection_on_session,
92    matrix_luci_factors_working_bytes, matrix_luci_row_interpolation_owned_in,
93    matrix_luci_row_interpolation_owned_on_session, MatrixLUCI, MatrixLuciFactors,
94    MatrixLuciRowInterpolation,
95};
96pub use matrixaca::MatrixACA;
97pub use matrixlu::{rrlu, rrlu_mut, rrlu_pivots, RrLU, RrLUOptions, RrLUPivots};
98pub use scalar::Scalar;
99pub use traits::AbstractMatrixCI;
100
101pub use scalar::Scalar as CommonScalar;
102
103// Default concrete type implementations (index, tensor, linalg, etc.)
104pub mod defaults;
105
106// Backwards compatibility: re-export defaults submodules as top-level modules
107// This allows `tensor4all_core::index::...` to work
108pub use defaults::index;
109
110pub use defaults::{DefaultIndex, DefaultTagSet, DynId, DynIndex, Index, TagSet};
111pub use index_like::{sort_indices_deterministic, ConjState, IndexLike};
112
113/// Index operations (replacement, set operations, contraction preparation).
114pub mod index_ops;
115pub use index_ops::{
116    check_unique_indices, common_ind_positions, common_inds, has_common_inds, has_inds, hasind,
117    noncommon_inds, replace_indices, replace_indices_mut, union_inds, unique_inds,
118    ReplaceIndsError,
119};
120pub use smallstring::{SmallChar, SmallString, SmallStringError};
121pub use tagset::{Tag, TagSetError, TagSetLike};
122
123// Tensor (storage, tensor types)
124pub mod tensor_index;
125pub mod tensor_like;
126
127pub use tensor_index::TensorIndex;
128
129// Krylov subspace methods (GMRES, etc.)
130pub mod krylov;
131pub mod randomized;
132pub use randomized::{
133    randomized_range, randomized_range_in, randomized_range_on_session, randomized_svd,
134    RangeOptions, RsvdOptions, RsvdResult, RsvdTimings,
135};
136
137// Block tensor for block matrix GMRES
138pub mod block_tensor;
139
140// Backwards compatibility: re-export defaults::idx_tensor as tensor
141pub use defaults::idx_tensor as tensor;
142
143pub use any_scalar::{AnyScalar, AnyScalarError};
144pub use defaults::idx_tensor::{
145    compute_permutation_from_indices, diag_idx_tensor, unfold_split, IdxTensor, IdxTensorError,
146    StructuredSelectorError, TensorStorageError,
147};
148#[cfg(feature = "tenferro-cuda")]
149pub use defaults::IdxTensorCudaError;
150pub use tensor4all_tensorbackend::ExecutionContext;
151pub use tensor4all_tensorbackend::TensorElement;
152pub use tensor4all_tensorbackend::{
153    print_and_reset_native_einsum_profile, reset_native_einsum_profile,
154};
155#[cfg(feature = "tenferro-cuda")]
156pub use tensor4all_tensorbackend::{CudaExecutionContext, CudaExecutionContextError, CUDA_ORDINAL};
157pub use tensor_like::{
158    Canonical, DirectSumResult, FactorizeAlg, FactorizeError, FactorizeOptions, FactorizeResult,
159    LinearizationOrder, TensorConstructionLike, TensorContractionLike, TensorFactorizationLike,
160    TensorLike, TensorVectorSpace, TensorVectorSpaceError,
161};
162
163pub use defaults::contract::{
164    contract, contract_owned, contract_owned_with_options, contract_pair,
165    contract_pair_with_operand_options, contract_pair_with_options, contract_with_options,
166    outer_product, print_and_reset_contract_profile, reset_contract_profile, tensordot,
167    ContractionOptions, PairwiseContractionOptions, PreparedContraction,
168};
169pub use defaults::idx_tensor::{
170    print_and_reset_pairwise_contract_profile, reset_pairwise_contract_profile,
171};
172pub use defaults::{
173    contract_pair_on_session, contract_with_options_on_session, dense_values_on_session,
174    index_select_on_session, inner_product_on_session, norm_on_session, norm_squared_on_session,
175    permute_indices_on_session, permute_on_session, select_indices_on_session,
176    stack_along_new_index_on_session, sum_on_session,
177};
178
179// Re-export linear algebra modules from defaults for backwards compatibility
180// This allows `tensor4all_core::svd::...`, `tensor4all_core::qr::...`, etc.
181pub mod direct_sum {
182    //! Re-export of direct sum operations.
183    pub use crate::defaults::direct_sum::*;
184}
185pub mod factorize {
186    //! Re-export of factorization operations.
187    pub use crate::defaults::factorize::*;
188}
189pub mod qr {
190    //! Re-export of QR decomposition operations.
191    pub use crate::defaults::qr::*;
192}
193pub mod svd {
194    //! Re-export of SVD decomposition operations.
195    pub use crate::defaults::svd::{
196        default_svd_truncation_policy, set_default_svd_truncation_policy, svd, svd_with,
197        svd_with_in, SvdError, SvdOptions,
198    };
199}
200
201// Re-export linear algebra items for top-level access
202pub use defaults::direct_sum::{direct_sum, direct_sum_many};
203pub use defaults::factorize::{
204    factorize, factorize_full_rank, factorize_full_rank_in, factorize_full_rank_on_session,
205    factorize_in, factorize_on_session, factorize_with_rng, factorize_with_rng_in,
206    factorize_with_rng_on_session,
207};
208pub use defaults::qr::{
209    default_qr_rtol, qr, qr_with, qr_with_on_session, set_default_qr_rtol, QrError, QrOptions,
210};
211pub use defaults::svd::{
212    default_svd_truncation_policy, set_default_svd_truncation_policy, svd, svd_with, SvdError,
213    SvdOptions,
214};
215
216// Global default and truncation utilities
217pub use global_default::{GlobalDefault, InvalidRtolError};
218pub use truncation::{
219    validate_svd_truncation_options, DecompositionAlg, InvalidThresholdError, SingularValueMeasure,
220    SvdTruncationOptionsError, SvdTruncationPolicy, ThresholdScale, TruncationRule,
221};