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/// Backend-independent rank/layout, dtype and scalar metadata re-exported from
39/// `tenferro-tensor-core`. It holds metadata only: every tensor type, including
40/// the default scalar set, is exported from this crate's root.
41pub mod core {
42    pub use tenferro_tensor_core::{
43        col_major_strides, DType, DynRank, ErrorKind, IntoShapeVec, Rank, Result, ShapeMismatch,
44        ShapeVec, SliceSpec, StrideVec, TensorLayout, TensorRank, TensorScalar, ValidationError,
45        ValidationKind,
46    };
47}
48
49// Re-exported so the exported dispatch macros can name them with `$crate` paths.
50pub use num_complex::Complex;
51
52/// The 32-bit complex scalar the exported dispatch macros name.
53///
54/// # Examples
55///
56/// ```
57/// use tenferro_tensor::Complex32;
58///
59/// assert_eq!(Complex32::new(1.0, 2.0).im, 2.0);
60/// ```
61pub type Complex32 = Complex<f32>;
62
63/// The 64-bit complex scalar the exported dispatch macros name.
64///
65/// # Examples
66///
67/// ```
68/// use tenferro_tensor::Complex64;
69///
70/// assert_eq!(Complex64::new(1.0, 2.0).re, 1.0);
71/// ```
72pub type Complex64 = Complex<f64>;
73
74pub use tenferro_tensor_core::{
75    ErrorKind, IntoRankShape, IntoShapeVec, ShapeMismatch, ShapeVec, SliceSpec, StrideVec,
76    ValidationError, ValidationKind,
77};
78
79mod default_scalars;
80mod erased_host;
81mod scalar_set;
82
83pub mod backend;
84pub mod cache;
85pub mod capability;
86pub mod config;
87pub mod dispatch;
88pub mod error;
89mod native_session;
90pub mod prelude;
91mod session_entry;
92pub mod types;
93pub mod validate;
94
95pub use backend::{
96    has_active_backend_session, with_session_entry_guard, BackendCachedDot, BackendRuntimeCache,
97    BackendSession, BackendSessionHost, ContractionScalar, DotGeneralAccumulation,
98    ElementwiseReadOp, SessionCachedDot, TensorAnalytic, TensorBackend, TensorBackendOps,
99    TensorBuffer, TensorDeviceTransfer, TensorDot, TensorElementwise, TensorFusion, TensorIndexing,
100    TensorReduction, TensorStructural, TensorViewCanonicalization,
101};
102pub use cache::{CacheStats, RuntimeCacheControl};
103pub use capability::{
104    capability_output_dtype, BackendId, CapabilityAxis, CapabilityQuery, OperationCapability,
105    SupportLevel, TensorBackendCapability,
106};
107pub use config::{
108    CompareDir, DotGeneralConfig, GatherConfig, PadConfig, ScatterConfig, SliceConfig,
109};
110pub use erased_host::ErasedHostTensor;
111pub use error::{BoxError, Error, ReinterpretError, Result};
112pub use native_session::NativeSessionRef;
113pub use scalar_set::ScalarSet;
114pub use session_entry::SessionEntryError;
115
116pub use default_scalars::{DefaultScalars, DefaultScalarsRef, DefaultScalarsView};
117
118pub use types::{
119    col_major_strides, AllocationDomainId, AllocationId, BackendStorage, BackendStorageHandle,
120    ColMajorView, ColMajorViewMut, CpuDomainId, DType, DeviceAccessError, DeviceAccessRequest,
121    DeviceId, DeviceKind, DynRank, Dynamic, Gpu, GpuBackendKind, Host, HostAccessError,
122    HostReadGuard, HostWriteGuard, MemoryKind, Placement, PreparedDeviceAccess, Rank,
123    Representation, SharedTensorAllocationDomain, StorageBuffer, StridedSliceSpec, Tensor,
124    TensorLayout, TensorRank, TensorRead, TensorScalar, TensorStorageRef, TensorStorageRefMut,
125    TensorValue, TensorView, TensorViewMut, TensorWrite, TypedTensor, TypedTensorView,
126    TypedTensorViewMut, TypedTensorViewMutSplit, TypedTensorWrite,
127};
128
129mod storage;
130
131#[doc(hidden)]
132pub use storage::{
133    AccessError, AllocationKey, BackendAllocation, HostBufferRecycler, ProviderCapabilities,
134    ProviderKind, ProviderReadMapping, ProviderWriteMapping, RootBoundSpan, RootResourceExtent,
135    RootResourceId, SpanValidationError,
136};
137pub use storage::{AllocationGroup, DescriptorSlot, GroupError};
138
139#[cfg(test)]
140pub(crate) mod tests;
tenferro_tensor/lib.rs

tenferro_tensor/
lib.rs
