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}