Skip to main content

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    normalize_axes, normalize_axis, AxisVec, ErrorKind, IntoRankShape, IntoShapeVec, ShapeMismatch,
76    ShapeVec, SliceSpec, StrideVec, ValidationError, ValidationKind, INLINE_RANK,
77};
78
79mod default_scalars;
80mod dest;
81mod erased_host;
82mod scalar_set;
83mod view;
84
85pub mod backend;
86pub mod cache;
87pub mod capability;
88pub mod config;
89pub mod dispatch;
90pub mod error;
91mod native_engine;
92pub mod prelude;
93pub mod types;
94pub mod validate;
95
96pub use backend::{
97    ActivationOp, ContractionScalar, DotGeneralAccumulation, ElementwiseReadOp, Engine,
98    SessionCachedDot, TensorAnalytic, TensorBackendOps, TensorBuffer, TensorDeviceTransfer,
99    TensorDot, TensorElementwise, TensorFusion, TensorIndexing, TensorReduction, TensorStructural,
100    TensorViewCanonicalization,
101};
102pub use cache::{CacheStats, RuntimeCacheControl};
103pub use capability::{
104    capability_entry, capability_output_dtype, BackendId, CapabilityAxis, CapabilityQuery,
105    OperationCapability, SupportLevel, TensorBackendCapability,
106};
107pub use config::{
108    degenerate_dot_kind, CompareDir, DegenerateDotKind, DotGeneralConfig, GatherConfig, PadConfig,
109    ScatterConfig, SliceConfig,
110};
111pub use dest::{Conj, Dest, DestMode, DotGeneralOptions};
112pub use erased_host::ErasedHostTensor;
113pub use error::{BoxError, Error, ReinterpretError, Result};
114pub use native_engine::NativeSessionRef;
115pub use scalar_set::ScalarSet;
116pub use view::{AsView, Erased, Repr, Typed};
117
118pub use default_scalars::{DefaultScalars, DefaultScalarsRef, DefaultScalarsView};
119
120pub use types::{
121    col_major_strides, AllocationDomainId, AllocationId, BackendStorage, BackendStorageHandle,
122    ColMajorView, ColMajorViewMut, CpuDomainId, DType, DeviceAccessError, DeviceAccessRequest,
123    DeviceId, DeviceKind, DynRank, Dynamic, Gpu, GpuBackendKind, Host, HostAccessError,
124    HostReadGuard, HostWriteGuard, MemoryKind, Placement, PreparedDeviceAccess, Rank,
125    Representation, SharedTensorAllocationDomain, StorageBuffer, StridedSliceSpec, Tensor,
126    TensorLayout, TensorRank, TensorRead, TensorScalar, TensorStorageRef, TensorStorageRefMut,
127    TensorValue, TensorView, TensorViewMut, TensorWrite, TypedTensor, TypedTensorView,
128    TypedTensorViewMut, TypedTensorViewMutSplit, TypedTensorWrite,
129};
130
131mod storage;
132
133#[doc(hidden)]
134pub use storage::{
135    AccessError, AllocationKey, BackendAllocation, HostBufferRecycler, ProviderCapabilities,
136    ProviderKind, ProviderReadMapping, ProviderWriteMapping, RootBoundSpan, RootResourceExtent,
137    RootResourceId, SpanValidationError,
138};
139pub use storage::{AllocationGroup, DescriptorSlot, GroupError};
140
141#[cfg(test)]
142pub(crate) mod tests;