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

tenferro_tensor/
lib.rs
