Skip to main content

tensor4all_tensorbackend/
lib.rs

1#![warn(missing_docs)]
2//! Tensor storage and linear algebra backend for tensor4all.
3//!
4//! [`CpuExecutionContext`] is the canonical CPU integration path. It requires a
5//! caller-supplied [`CpuBackend`] and owns plain, graph, and eager-AD runtime state.
6//!
7//! ## Feature flags
8//!
9//! - `explicit-context`: explicit CPU execution and logical tensor transfer.
10//! - `global-defaults`: legacy process-global tensor operations.
11//! - `backend-tenferro` (default): compatibility alias for `global-defaults`.
12
13#[cfg(feature = "global-defaults")]
14/// Dynamic scalar types supporting f32, f64, Complex32, and Complex64.
15mod any_scalar;
16#[cfg(feature = "global-defaults")]
17/// Backend dispatch for dense linear algebra operations.
18mod backend;
19#[cfg(feature = "global-defaults")]
20/// Complete-pivoting LU of a square matrix stopped at a rank cap.
21mod capped_full_piv_lu;
22#[cfg(feature = "explicit-context")]
23/// Explicit and optional process-global tenferro execution helpers.
24mod context;
25#[cfg(feature = "tenferro-cuda")]
26/// Explicit visible-ordinal-0 CUDA execution and transfer boundaries.
27mod cuda;
28#[cfg(feature = "explicit-context")]
29/// Einsum label helpers shared by both frontends.
30mod einsum_ids;
31#[cfg(feature = "explicit-context")]
32/// Opt-in explicit/concrete execution frontend (issue #859 B1).
33pub mod explicit;
34#[cfg(feature = "global-defaults")]
35/// Incremental QR state for successive randomized compression.
36mod incremental_qr;
37#[cfg(feature = "explicit-context")]
38/// Backend-free tensor snapshots for execution-domain transfer.
39mod logical_tensor;
40#[cfg(feature = "global-defaults")]
41/// Dense column-major matrix type and backend-backed matrix utilities.
42mod matrix;
43#[cfg(feature = "global-defaults")]
44/// Process-level memory pressure helpers.
45mod memory;
46#[cfg(feature = "global-defaults")]
47/// Tensor snapshot storage types and low-level dense/diagonal kernels.
48mod storage;
49#[cfg(feature = "global-defaults")]
50pub(crate) mod tenferro_bridge;
51#[cfg(feature = "global-defaults")]
52/// Supported public tensor element types and native constructor hooks.
53mod tensor_element;
54
55#[cfg(feature = "global-defaults")]
56pub use any_scalar::{BackendScalar, ScalarTensorElement, ScalarValue};
57#[cfg(feature = "global-defaults")]
58pub use backend::{
59    full_piv_lu_backend, full_piv_lu_matrix, full_piv_lu_matrix_in, full_piv_lu_matrix_owned,
60    qr_backend, qr_backend_in, solve_backend, solve_matrix, solve_matrix_in, solve_matrix_owned,
61    src_error_estimate, src_error_estimate_general, svd_backend, svd_backend_in,
62    triangular_solve_backend, triangular_solve_matrix, triangular_solve_matrix_in,
63    triangular_solve_matrix_owned, BackendLinalgError, BackendLinalgScalar, FullPivLuMatrixResult,
64    FullPivLuResult, FullPivLuScalar, MatrixSolveScalar, MatrixTriangularSolveScalar,
65    SrcErrorEstimate, SvdResult,
66};
67#[cfg(feature = "global-defaults")]
68pub use capped_full_piv_lu::{capped_full_piv_lu, CappedFullPivLu, CappedFullPivLuScalar};
69#[cfg(feature = "global-defaults")]
70pub use context::{
71    default_cpu_execution_context, default_eager_ctx, with_default_backend, with_runtime_engine,
72    EagerContextError, ExecutionContextEntryError,
73};
74#[cfg(feature = "explicit-context")]
75pub use context::{
76    default_cpu_wait_policy, set_default_cpu_threads, set_default_cpu_wait_policy,
77    AlreadyInitialized, CpuBackend, CpuExecutionContext, CpuExecutionContextError, CpuThreadError,
78    CpuWaitPolicy, ExecutionContext, WaitPolicyAlreadyInitialized,
79};
80#[cfg(feature = "tenferro-cuda")]
81pub use cuda::{
82    CudaExecutionContext, CudaExecutionContextError, CudaPinnedBuffer, PendingCudaDownload,
83    PendingCudaUpload, CUDA_ORDINAL,
84};
85#[cfg(feature = "global-defaults")]
86pub use incremental_qr::{IncrementalQr, IncrementalQrScalar};
87#[cfg(feature = "explicit-context")]
88pub use logical_tensor::{LogicalTensor, LogicalTensorData, LogicalTensorError};
89#[cfg(feature = "global-defaults")]
90pub use matrix::{
91    batched_mat_mul_same_shape, batched_mat_mul_same_shape_owned, from_vec2d,
92    hermitian_eigendecomposition, hermitian_exponential_first_column, lowest_hermitian_eigenpair,
93    mat_mul, mat_mul_in, mat_mul_owned, submatrix, submatrix_argmax, swap_cols, swap_rows,
94    transpose, try_from_vec2d, BlasMul, HermitianEigenError, HermitianEigenScalar,
95    HermitianEigendecomposition, HermitianEigenpair, Matrix, MatrixMulError, MatrixScalar,
96    MatrixShapeError, MatrixTensorConversionError,
97};
98#[cfg(feature = "global-defaults")]
99pub use memory::{release_process_allocator_cached_memory, AllocatorPressureRelief};
100#[cfg(feature = "global-defaults")]
101pub use storage::{
102    contract_storage, make_mut_storage, min_dim, scale_target_dtype, NonfiniteFlags, Storage,
103    StorageError, StorageKind, StorageResult, StorageScalar, StructuredStorage, SumFromStorage,
104};
105#[cfg(feature = "global-defaults")]
106pub use tenferro_bridge::{
107    axpby_native_tensor, axpby_storage_native, conj_native_tensor, contract_native_tensor,
108    contract_storage_native, dense_native_tensor_from_col_major,
109    dense_native_tensor_from_col_major_owned, dense_native_tensor_read_input_from_col_major,
110    diag_native_tensor_from_col_major, einsum_native_subscripts, einsum_native_tensor_reads,
111    einsum_native_tensors, einsum_native_tensors_owned, native_tensor_primal_to_dense_col_major,
112    native_tensor_primal_to_diag, native_tensor_primal_to_storage, outer_product_native_tensor,
113    outer_product_storage_native, permute_native_tensor, permute_storage_native,
114    print_and_reset_native_einsum_profile, qr_native_tensor, reset_native_einsum_profile,
115    reshape_col_major_native_tensor, scale_native_tensor, scale_storage_native,
116    storage_from_payload_native, storage_payload_native, storage_payload_native_read_input,
117    storage_to_native_tensor, sum_native_tensor, svd_native_tensor, tangent_native_tensor,
118    BridgeError, NativeEinsumPlan, NativeTensorReadInput,
119};
120#[cfg(feature = "global-defaults")]
121pub use tensor_element::TensorElement;
122
123/// Report a violated internal invariant that no public input can reach.
124///
125/// This is the only sanctioned `panic!` in production code. Use it only for
126/// (a) an internal invariant — a state no public input can reach — or (b) the
127/// documented `# Panics` precondition of an infallible standard-trait
128/// implementation that cannot return `Result`, such as an out-of-range
129/// [`Index`](std::ops::Index)/[`IndexMut`](std::ops::IndexMut). Never use it
130/// for user-reachable invalid input of a function that can return `Result`;
131/// return a crate-local typed error instead.
132///
133/// `context` names the invariant and `error` carries the underlying
134/// diagnostic, so the panic message is `"{context}: {error}"`. The library
135/// panic audit allowlists this single `panic!` and reports every call site, so
136/// invariant panics stay visible.
137///
138/// # Panics
139///
140/// Always panics and never returns.
141///
142/// # Examples
143///
144/// ```
145/// use tensor4all_tensorbackend::invariant_violated;
146///
147/// let payload = std::panic::catch_unwind(|| {
148///     invariant_violated("rank mismatch", "expected 2 rows");
149/// })
150/// .unwrap_err();
151/// let message = payload
152///     .downcast_ref::<String>()
153///     .expect("panic payload is a formatted string");
154/// assert_eq!(message, "rank mismatch: expected 2 rows");
155/// ```
156#[doc(hidden)]
157#[track_caller]
158pub fn invariant_violated(context: &str, error: impl std::fmt::Display) -> ! {
159    panic!("{context}: {error}")
160}
161
162#[cfg(all(test, feature = "global-defaults"))]
163mod tests;
164
165// Execution vocabulary for downstream algorithms that borrow caller-owned lanes.
166#[cfg(feature = "explicit-context")]
167pub use tenferro_cpu::{threadteam::Exec, CpuEngine};