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::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
50pub use tenferro_tensor_core::{
51    ErrorKind, IntoShapeVec, ShapeMismatch, ShapeVec, SliceSpec, StrideVec, TensorRef,
52    ValidationError, ValidationKind,
53};
54
55pub mod backend;
56pub mod cache;
57pub mod capability;
58pub mod config;
59pub mod dispatch;
60pub mod error;
61pub mod prelude;
62pub mod types;
63pub mod validate;
64
65pub use backend::{
66    default_backend_session, BackendCachedDot, BackendRuntimeCache, BackendSession,
67    BackendSessionHost, ContractionScalar, DotGeneralAccumulation, ElementwiseReadOp,
68    SessionCachedDot, TensorAnalytic, TensorBackend, TensorBackendOps, TensorBuffer,
69    TensorDeviceTransfer, TensorDot, TensorElementwise, TensorFusion, TensorIndexing,
70    TensorReduction, TensorStructural, TensorViewCanonicalization,
71};
72pub use cache::{CacheStats, RuntimeCacheControl};
73pub use capability::{
74    capability_output_dtype, BackendId, CapabilityAxis, CapabilityQuery, OperationCapability,
75    SupportLevel, TensorBackendCapability,
76};
77pub use config::{
78    CompareDir, DotGeneralConfig, GatherConfig, PadConfig, ScatterConfig, SliceConfig,
79};
80pub use error::{BoxError, Error, ReinterpretError, Result};
81pub use types::{
82    col_major_strides, AllocationDomainId, AllocationId, BackendStorage, BackendStorageHandle,
83    CpuDomainId, DType, DeviceAccessError, DeviceAccessRequest, DeviceId, DeviceKind, DynRank,
84    GpuBackendKind, HostAccessError, HostReadGuard, HostWriteGuard, MemoryKind, Placement,
85    PreparedDeviceAccess, Rank, SharedTensorAllocationDomain, StorageBuffer, StridedSliceSpec,
86    Tensor, TensorLayout, TensorRank, TensorRead, TensorScalar, TensorStorageRef,
87    TensorStorageRefMut, TensorValue, TensorView, TensorViewMut, TensorWrite, TypedTensor,
88    TypedTensorView, TypedTensorViewMut, TypedTensorViewMutSplit, TypedTensorWrite,
89};
90
91mod storage;
92
93#[doc(hidden)]
94pub use storage::{
95    AccessError, AllocationKey, BackendAllocation, ProviderCapabilities, ProviderKind,
96    ProviderReadMapping, ProviderWriteMapping, RootBoundSpan, RootResourceExtent, RootResourceId,
97    SpanValidationError,
98};
99pub use storage::{AllocationGroup, DescriptorSlot, GroupError};
100
101pub(crate) fn core_dtype(dtype: DType) -> tenferro_tensor_core::DType {
102    match dtype {
103        DType::F32 => tenferro_tensor_core::DType::F32,
104        DType::F64 => tenferro_tensor_core::DType::F64,
105        DType::I32 => tenferro_tensor_core::DType::I32,
106        DType::I64 => tenferro_tensor_core::DType::I64,
107        DType::Bool => tenferro_tensor_core::DType::Bool,
108        DType::C32 => tenferro_tensor_core::DType::C32,
109        DType::C64 => tenferro_tensor_core::DType::C64,
110    }
111}
112
113#[cfg(test)]
114mod tests;
tenferro_tensor/lib.rs

tenferro_tensor/
lib.rs
