Skip to main content

tenferro_tensor_core/
lib.rs

1//! Backend-independent rank/layout, dtype and scalar metadata.
2//!
3//! `tenferro-tensor-core` owns backend-independent tensor metadata: scalar
4//! tags and promotion facts, rank/layout metadata, and layout validation. It
5//! does not own tensor storage, execution backends, backend buffers, GPU
6//! handles, provider selection, or materializing kernels. The tensor families
7//! that carry storage live in `tenferro-tensor`.
8//!
9//! # Examples
10//!
11//! ```rust
12//! use tenferro_tensor_core::{DType, Rank, TensorLayout};
13//!
14//! let layout = TensorLayout::<Rank<2>>::compact([2, 3])?;
15//! let transposed = layout.transpose_view([1, 0])?;
16//! assert_eq!(transposed.shape(), &[3, 2]);
17//!
18//! assert_eq!(DType::F64.spec().width, 64);
19//! # Ok::<(), tenferro_tensor_core::ValidationError>(())
20//! ```
21
22use num_complex::{Complex32, Complex64};
23use tinyvec::TinyVec;
24
25mod axis;
26mod error;
27mod layout;
28mod rank;
29mod scalar;
30#[macro_use]
31mod scalar_set;
32
33pub use axis::{normalize_axes, normalize_axis, AxisVec};
34pub use error::{ErrorKind, ShapeMismatch, ValidationError, ValidationKind};
35pub use layout::TensorLayout;
36pub use rank::{DynRank, IntoRankShape, Rank, TensorRank};
37pub use scalar::{ad_admission, AdAdmissionError, Scalar, ScalarArithmetic, ScalarDomain};
38pub use scalar_set::{promote_in_set, promote_specs, MemberKind, MemberSpec};
39
40/// Maximum rank whose shape/stride metadata stays inline without a heap
41/// allocation.
42///
43/// Mirrors `strided_view::INLINE_RANK`; `tenferro-cpu-basic` carries a
44/// compile-time assertion that the two values agree. At rank `<= INLINE_RANK`
45/// [`ShapeVec`] and [`StrideVec`] keep their elements inline; a higher rank
46/// spills to the heap gracefully.
47///
48/// # Examples
49///
50/// ```rust
51/// use tenferro_tensor_core::INLINE_RANK;
52///
53/// assert_eq!(INLINE_RANK, 8);
54/// ```
55pub const INLINE_RANK: usize = 8;
56
57/// Small tensor shape vector with inline capacity for common dynamic ranks.
58///
59/// # Examples
60///
61/// ```rust
62/// use tenferro_tensor_core::ShapeVec;
63///
64/// let shape: ShapeVec = vec![2, 3].into_iter().collect();
65/// assert_eq!(shape.as_slice(), &[2, 3]);
66/// ```
67pub type ShapeVec = TinyVec<[usize; INLINE_RANK]>;
68
69/// Convert a common shape container into the dynamic owned shape type.
70///
71/// Arrays, vectors, slices, and [`ShapeVec`] implement this trait through
72/// their `AsRef<[usize]>` representation.
73pub trait IntoShapeVec {
74    /// Convert this shape container into an owned [`ShapeVec`].
75    fn into_shape_vec(self) -> ShapeVec;
76}
77
78impl<S> IntoShapeVec for S
79where
80    S: AsRef<[usize]>,
81{
82    fn into_shape_vec(self) -> ShapeVec {
83        self.as_ref().iter().copied().collect()
84    }
85}
86
87/// Small tensor stride vector with signed element strides.
88///
89/// # Examples
90///
91/// ```rust
92/// use tenferro_tensor_core::StrideVec;
93///
94/// let strides: StrideVec = vec![1, 2].into_iter().collect();
95/// assert_eq!(strides.as_slice(), &[1, 2]);
96/// ```
97pub type StrideVec = TinyVec<[isize; INLINE_RANK]>;
98
99/// Result type for tensor data-model operations.
100///
101/// # Examples
102///
103/// ```rust
104/// use tenferro_tensor_core::{Result, ValidationError};
105///
106/// let result: Result<()> = Err(ValidationError::RankMismatch { expected: 2, actual: 1 });
107/// assert!(result.is_err());
108/// ```
109pub type Result<T> = std::result::Result<T, ValidationError>;
110
111define_scalar_tag! {
112    /// Runtime scalar dtype tag.
113    ///
114    /// # Examples
115    ///
116    /// ```rust
117    /// use tenferro_tensor_core::DType;
118    ///
119    /// assert_eq!(DType::F64, DType::F64);
120    /// ```
121    pub enum DType {
122        /// 32-bit floating point.
123        F32 => f32 : Float 0 32,
124        /// 64-bit floating point.
125        F64 => f64 : Float 1 64,
126        /// 32-bit signed integer.
127        I32 => i32 : Integer 0 32,
128        /// 64-bit signed integer.
129        I64 => i64 : Integer 1 64,
130        /// Boolean.
131        Bool => bool : Boolean 0 0,
132        /// 32-bit complex floating point.
133        C32 => Complex32 : Complex 0 32,
134        /// 64-bit complex floating point.
135        C64 => Complex64 : Complex 1 64,
136    }
137    external External(core::any::TypeId);
138}
139
140/// Sealed trait for scalar types supported by the core tensor data model.
141///
142/// # Examples
143///
144/// ```rust
145/// use tenferro_tensor_core::{DType, TensorScalar};
146///
147/// assert_eq!(f64::dtype(), DType::F64);
148/// assert_eq!(num_complex::Complex64::dtype(), DType::C64);
149/// ```
150pub trait TensorScalar: Scalar + Copy + Clone + Send + Sync + 'static + private::Sealed {
151    /// Real-valued counterpart of this scalar type.
152    type Real: TensorScalar;
153
154    /// Return the scalar dtype tag.
155    ///
156    /// # Examples
157    ///
158    /// ```rust
159    /// use tenferro_tensor_core::{DType, TensorScalar};
160    ///
161    /// assert_eq!(i64::dtype(), DType::I64);
162    /// ```
163    fn dtype() -> DType;
164}
165
166mod private {
167    pub trait Sealed {}
168
169    impl Sealed for f32 {}
170    impl Sealed for f64 {}
171    impl Sealed for i32 {}
172    impl Sealed for i64 {}
173    impl Sealed for bool {}
174    impl Sealed for num_complex::Complex32 {}
175    impl Sealed for num_complex::Complex64 {}
176}
177
178macro_rules! scalar_domain {
179    (float) => {
180        ScalarDomain::Field
181    };
182    (complex) => {
183        ScalarDomain::Field
184    };
185    (integer) => {
186        ScalarDomain::Field
187    };
188    (boolean) => {
189        ScalarDomain::NonField
190    };
191}
192
193macro_rules! impl_scalar_arithmetic {
194    ($ty:ty, float) => {
195        impl ScalarArithmetic for $ty {
196            fn scalar_zero() -> Self {
197                0.0
198            }
199
200            fn scalar_one() -> Self {
201                1.0
202            }
203
204            fn scalar_add(self, rhs: Self) -> Self {
205                std::ops::Add::add(self, rhs)
206            }
207
208            fn scalar_sub(self, rhs: Self) -> Self {
209                std::ops::Sub::sub(self, rhs)
210            }
211
212            fn scalar_mul(self, rhs: Self) -> Self {
213                std::ops::Mul::mul(self, rhs)
214            }
215        }
216    };
217    ($ty:ty, complex) => {
218        impl ScalarArithmetic for $ty {
219            fn scalar_zero() -> Self {
220                <$ty>::new(0.0, 0.0)
221            }
222
223            fn scalar_one() -> Self {
224                <$ty>::new(1.0, 0.0)
225            }
226
227            fn scalar_add(self, rhs: Self) -> Self {
228                std::ops::Add::add(self, rhs)
229            }
230
231            fn scalar_sub(self, rhs: Self) -> Self {
232                std::ops::Sub::sub(self, rhs)
233            }
234
235            fn scalar_mul(self, rhs: Self) -> Self {
236                std::ops::Mul::mul(self, rhs)
237            }
238        }
239    };
240    ($ty:ty, integer) => {
241        impl ScalarArithmetic for $ty {
242            fn scalar_zero() -> Self {
243                0
244            }
245
246            fn scalar_one() -> Self {
247                1
248            }
249
250            fn scalar_add(self, rhs: Self) -> Self {
251                self.wrapping_add(rhs)
252            }
253
254            fn scalar_sub(self, rhs: Self) -> Self {
255                self.wrapping_sub(rhs)
256            }
257
258            fn scalar_mul(self, rhs: Self) -> Self {
259                self.wrapping_mul(rhs)
260            }
261        }
262    };
263    ($ty:ty, boolean) => {};
264}
265
266macro_rules! impl_scalar {
267    ($ty:ty, $real:ty, $dtype:expr, $variant:ident, $kind:ident) => {
268        impl Scalar for $ty {
269            const DOMAIN: ScalarDomain = scalar_domain!($kind);
270        }
271
272        impl_scalar_arithmetic!($ty, $kind);
273
274        impl TensorScalar for $ty {
275            type Real = $real;
276
277            fn dtype() -> DType {
278                $dtype
279            }
280        }
281    };
282}
283
284// The single preset table: tag, real counterpart, erased variant, and algebra
285// kind are declared once here and expanded into every contract the preset
286// scalars implement.
287impl_scalar!(f32, f32, DType::F32, F32, float);
288impl_scalar!(f64, f64, DType::F64, F64, float);
289impl_scalar!(i32, i32, DType::I32, I32, integer);
290impl_scalar!(i64, i64, DType::I64, I64, integer);
291impl_scalar!(bool, bool, DType::Bool, Bool, boolean);
292impl_scalar!(Complex32, f32, DType::C32, C32, complex);
293impl_scalar!(Complex64, f64, DType::C64, C64, complex);
294
295/// Explicit slice descriptor.
296///
297/// A zero step is invalid. Layout metadata APIs support signed steps when
298/// reachable-range validation proves the view stays inside the backing
299/// allocation.
300///
301/// # Examples
302///
303/// ```rust
304/// use tenferro_tensor_core::SliceSpec;
305///
306/// let spec = SliceSpec { start: 1, end: 4, step: 2 };
307/// assert_eq!(spec.step, 2);
308/// ```
309#[derive(Clone, Copy, Debug, PartialEq, Eq)]
310pub struct SliceSpec {
311    pub start: isize,
312    pub end: isize,
313    pub step: isize,
314}
315
316// A valid empty slice. `tinyvec`'s storage (`Array::Item: Default`) needs a
317// default value to initialize unused inline slots; unlike a derived default,
318// `step` stays nonzero so the value is a legal `SliceSpec`.
319impl Default for SliceSpec {
320    fn default() -> Self {
321        Self {
322            start: 0,
323            end: 0,
324            step: 1,
325        }
326    }
327}
328
329fn checked_product(shape: &[usize]) -> Result<usize> {
330    shape.iter().try_fold(1usize, |acc, &dim| {
331        acc.checked_mul(dim).ok_or(ValidationError::IntegerOverflow)
332    })
333}
334
335fn checked_logical_element_count(shape: &[usize]) -> Result<usize> {
336    if shape.contains(&0) {
337        return Ok(0);
338    }
339    checked_product(shape)
340}
341
342/// Return compact column-major strides for a shape.
343///
344/// # Examples
345///
346/// ```rust
347/// use tenferro_tensor_core::col_major_strides;
348///
349/// assert_eq!(col_major_strides(&[2, 3])?.as_slice(), &[1, 2]);
350/// # Ok::<(), tenferro_tensor_core::ValidationError>(())
351/// ```
352///
353/// # Errors
354///
355/// Returns [`ValidationError::IntegerOverflow`] when a stride or extent
356/// cannot be represented by the metadata arithmetic.
357pub fn col_major_strides(shape: &[usize]) -> Result<StrideVec> {
358    let mut strides = StrideVec::new();
359    let mut stride = 1isize;
360    for &extent in shape {
361        strides.push(stride);
362        let extent = isize::try_from(extent).map_err(|_| ValidationError::IntegerOverflow)?;
363        stride = stride
364            .checked_mul(extent)
365            .ok_or(ValidationError::IntegerOverflow)?;
366    }
367    Ok(strides)
368}
369
370fn validate_permutation(rank: usize, axes: &[usize]) -> Result<()> {
371    if axes.len() != rank {
372        return Err(ValidationError::InvalidPermutationLength {
373            expected: rank,
374            actual: axes.len(),
375        });
376    }
377    // Common ranks track seen axes in a bitmask; only very high ranks allocate.
378    if rank <= u128::BITS as usize {
379        let mut seen = 0u128;
380        for &axis in axes {
381            if axis >= rank {
382                return Err(ValidationError::AxisOutOfBounds {
383                    axis: isize::try_from(axis).unwrap_or(isize::MAX),
384                    rank,
385                });
386            }
387            let bit = 1u128 << axis;
388            if seen & bit != 0 {
389                return Err(ValidationError::DuplicateAxis {
390                    axis,
391                    role: "permutation",
392                });
393            }
394            seen |= bit;
395        }
396        return Ok(());
397    }
398    let mut seen = vec![false; rank];
399    for &axis in axes {
400        if axis >= rank {
401            return Err(ValidationError::AxisOutOfBounds {
402                axis: isize::try_from(axis).unwrap_or(isize::MAX),
403                rank,
404            });
405        }
406        if seen[axis] {
407            return Err(ValidationError::DuplicateAxis {
408                axis,
409                role: "permutation",
410            });
411        }
412        seen[axis] = true;
413    }
414    Ok(())
415}