tenferro_tensor/
lib.rs

1//! Core tensor types, views, backend traits, and backend-independent contracts.
2//!
3//! # Owned Tensors And Views
4//!
5//! [`TypedTensor<T>`](TypedTensor) and the dtype-erased [`Tensor`] enum are
6//! owned tensor values. They are the right representation when a result is
7//! materialized as compact column-major storage.
8//!
9//! [`TypedTensorView`] is a borrowed typed view over an existing tensor buffer.
10//! It carries logical shape, arbitrary strides, and an offset, so metadata-only
11//! layout changes such as transposes, slices, and broadcasts can be represented
12//! without copying. Backend-aware code materializes and copies views through
13//! [`TensorViewCanonicalization`], preserving placement and backend execution
14//! policy.
15//!
16//! [`TensorRead`] is the dtype-erased borrowed input type used by eager kernels
17//! and backend dispatch. It can borrow either an owned [`Tensor`] or a
18//! [`TensorView`] with arbitrary strides. Prefer `TensorRead` for read-only
19//! operation inputs so callers are not forced to materialize layout-only views.
20//!
21//! [`TensorValue`] is the owned lazy-value form. Use it when an API must store
22//! a view result beyond the lifetime of a borrowed input, then expose a
23//! short-lived `TensorRead` at kernel-dispatch time.
24//!
25//! Use [`Tensor::as_slice`] or [`TypedTensorView::as_slice`] only when compact
26//! contiguous storage is part of the API contract. Use shape/stride-aware kernel
27//! paths or `TensorRead` otherwise.
28//!
29//! # Examples
30//!
31//! ```rust
32//! use tenferro_tensor::{Tensor, TypedTensor};
33//!
34//! let a = Tensor::from_typed::<f64>(TypedTensor::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap());
35//! assert_eq!(a.shape(), &[2]);
36//! ```
37
38/// Lightweight backend-independent host tensor data model.
39///
40/// Execution-capable tensors and backends in this crate remain separate from
41/// the host-only core model during the crate-boundary split.
42pub mod core {
43    pub use tenferro_tensor_core::{
44        col_major_strides, DType, DynRank, ErrorKind, HostTensor, HostTensorView, IntoShapeVec,
45        Rank, Result, ShapeMismatch, ShapeVec, SliceSpec, StrideVec, Tensor, TensorLayout,
46        TensorRank, TensorRef, TensorScalar, TensorView, ValidationError, ValidationKind,
47    };
48}
49
50// Re-exported so the exported dispatch macros can name them with `$crate` paths.
51pub use num_complex::Complex;
52
53/// The 32-bit complex scalar the exported dispatch macros name.
54///
55/// # Examples
56///
57/// ```
58/// use tenferro_tensor::Complex32;
59///
60/// assert_eq!(Complex32::new(1.0, 2.0).im, 2.0);
61/// ```
62pub type Complex32 = Complex<f32>;
63
64/// The 64-bit complex scalar the exported dispatch macros name.
65///
66/// # Examples
67///
68/// ```
69/// use tenferro_tensor::Complex64;
70///
71/// assert_eq!(Complex64::new(1.0, 2.0).re, 1.0);
72/// ```
73pub type Complex64 = Complex<f64>;
74
75pub use tenferro_tensor_core::{
76    ErrorKind, IntoRankShape, IntoShapeVec, ShapeMismatch, ShapeVec, SliceSpec, StrideVec,
77    TensorRef, ValidationError, ValidationKind,
78};
79
80pub mod backend;
81pub mod cache;
82pub mod capability;
83pub mod config;
84pub mod dispatch;
85pub mod error;
86pub mod prelude;
87pub mod types;
88pub mod validate;
89
90pub use backend::{
91    default_backend_session, with_session_entry_guard, BackendCachedDot, BackendRuntimeCache,
92    BackendSession, BackendSessionHost, ContractionScalar, DotGeneralAccumulation,
93    ElementwiseReadOp, SessionCachedDot, TensorAnalytic, TensorBackend, TensorBackendOps,
94    TensorBuffer, TensorDeviceTransfer, TensorDot, TensorElementwise, TensorFusion, TensorIndexing,
95    TensorReduction, TensorStructural, TensorViewCanonicalization,
96};
97pub use cache::{CacheStats, RuntimeCacheControl};
98pub use capability::{
99    capability_output_dtype, BackendId, CapabilityAxis, CapabilityQuery, OperationCapability,
100    SupportLevel, TensorBackendCapability,
101};
102pub use config::{
103    CompareDir, DotGeneralConfig, GatherConfig, PadConfig, ScatterConfig, SliceConfig,
104};
105pub use error::{BoxError, Error, ReinterpretError, Result};
106pub use types::{
107    col_major_strides, AllocationDomainId, AllocationId, BackendStorage, BackendStorageHandle,
108    ColMajorView, ColMajorViewMut, CpuDomainId, DType, DeviceAccessError, DeviceAccessRequest,
109    DeviceId, DeviceKind, DynRank, GpuBackendKind, HostAccessError, HostReadGuard, HostWriteGuard,
110    MemoryKind, Placement, PreparedDeviceAccess, Rank, SharedTensorAllocationDomain, StorageBuffer,
111    StridedSliceSpec, Tensor, TensorLayout, TensorRank, TensorRead, TensorScalar, TensorStorageRef,
112    TensorStorageRefMut, TensorValue, TensorView, TensorViewMut, TensorWrite, TypedTensor,
113    TypedTensorView, TypedTensorViewMut, TypedTensorViewMutSplit, TypedTensorWrite,
114};
115
116mod storage;
117
118#[doc(hidden)]
119pub use storage::{
120    AccessError, AllocationKey, BackendAllocation, HostBufferRecycler, ProviderCapabilities,
121    ProviderKind, ProviderReadMapping, ProviderWriteMapping, RootBoundSpan, RootResourceExtent,
122    RootResourceId, SpanValidationError,
123};
124pub use storage::{AllocationGroup, DescriptorSlot, GroupError};
125
126#[cfg(test)]
127pub(crate) mod tests;
tenferro_tensor/lib.rs

tenferro_tensor/
lib.rs
