tenferro_tensor_core/layout.rs
1use crate::{
2 checked_logical_element_count, checked_product, col_major_strides, validate_permutation,
3 DynRank, Rank, Result, ShapeMismatch, ShapeVec, SliceSpec, StrideVec, TensorRank,
4 ValidationError,
5};
6use strided_view::is_injective_layout;
7
8pub(crate) fn reachable_offset_range(
9 shape: &[usize],
10 strides: &[isize],
11 offset: isize,
12) -> Result<Option<(isize, isize)>> {
13 if shape.contains(&0) {
14 return Ok(None);
15 }
16
17 let mut min = offset;
18 let mut max = offset;
19 for (&extent, &stride) in shape.iter().zip(strides) {
20 let last = isize::try_from(extent.saturating_sub(1))
21 .map_err(|_| ValidationError::IntegerOverflow)?;
22 let delta = last
23 .checked_mul(stride)
24 .ok_or(ValidationError::IntegerOverflow)?;
25 if delta < 0 {
26 min = min
27 .checked_add(delta)
28 .ok_or(ValidationError::IntegerOverflow)?;
29 } else {
30 max = max
31 .checked_add(delta)
32 .ok_or(ValidationError::IntegerOverflow)?;
33 }
34 }
35 Ok(Some((min, max)))
36}
37
38pub(crate) fn validate_reachable_bounds(
39 shape: &[usize],
40 strides: &[isize],
41 offset: isize,
42 buffer_len: usize,
43) -> Result<()> {
44 if shape.len() != strides.len() {
45 return Err(ValidationError::RankMismatch {
46 expected: shape.len(),
47 actual: strides.len(),
48 });
49 }
50
51 match reachable_offset_range(shape, strides, offset)? {
52 Some((min, max)) => {
53 if min < 0 {
54 return Err(ValidationError::ViewOutOfBounds);
55 }
56 let max = usize::try_from(max).map_err(|_| ValidationError::IntegerOverflow)?;
57 if max < buffer_len {
58 Ok(())
59 } else {
60 Err(ValidationError::ViewOutOfBounds)
61 }
62 }
63 None => {
64 if offset < 0 {
65 return Err(ValidationError::ViewOutOfBounds);
66 }
67 let offset = usize::try_from(offset).map_err(|_| ValidationError::IntegerOverflow)?;
68 if offset <= buffer_len {
69 Ok(())
70 } else {
71 Err(ValidationError::ViewOutOfBounds)
72 }
73 }
74 }
75}
76
77fn layout_from_vecs<R: TensorRank>(
78 shape: ShapeVec,
79 strides: StrideVec,
80 offset: isize,
81 buffer_len: usize,
82) -> Result<TensorLayout<R>> {
83 TensorLayout::from_parts(
84 R::shape_from_vec(shape)?,
85 R::strides_from_vec(strides)?,
86 offset,
87 buffer_len,
88 )
89}
90
91fn positive_ceil_div(numerator: isize, denominator: isize) -> Result<usize> {
92 if numerator < 0 || denominator <= 0 {
93 return Err(ValidationError::IntegerOverflow);
94 }
95 let extent = if numerator == 0 {
96 0
97 } else {
98 1 + (numerator - 1) / denominator
99 };
100 usize::try_from(extent).map_err(|_| ValidationError::IntegerOverflow)
101}
102
103fn normalize_slice(slice: SliceSpec, axis_len: usize) -> Result<(isize, usize)> {
104 if slice.step == 0 {
105 return Err(ValidationError::InvalidSliceStep { step: slice.step });
106 }
107 if axis_len == 0 {
108 return Ok((0, 0));
109 }
110
111 let axis_len = isize::try_from(axis_len).map_err(|_| ValidationError::IntegerOverflow)?;
112 if slice.step > 0 {
113 let start = if slice.start < 0 {
114 slice
115 .start
116 .checked_add(axis_len)
117 .ok_or(ValidationError::IntegerOverflow)?
118 } else {
119 slice.start
120 };
121 let end = if slice.end < 0 {
122 slice
123 .end
124 .checked_add(axis_len)
125 .ok_or(ValidationError::IntegerOverflow)?
126 } else {
127 slice.end
128 };
129 if start < 0 || start > axis_len || end < 0 || end > axis_len {
130 return Err(ValidationError::InvalidSliceBounds {
131 start: slice.start,
132 end: slice.end,
133 axis_len: usize::try_from(axis_len)
134 .map_err(|_| ValidationError::IntegerOverflow)?,
135 });
136 }
137 if start >= end {
138 return Ok((start, 0));
139 }
140 return Ok((start, positive_ceil_div(end - start, slice.step)?));
141 }
142
143 let start = if slice.start < 0 {
144 slice
145 .start
146 .checked_add(axis_len)
147 .ok_or(ValidationError::IntegerOverflow)?
148 } else {
149 slice.start
150 };
151 let end = if slice.end < -1 {
152 slice
153 .end
154 .checked_add(axis_len)
155 .ok_or(ValidationError::IntegerOverflow)?
156 } else {
157 slice.end
158 };
159 if start < 0 || start >= axis_len || end < -1 || end >= axis_len {
160 return Err(ValidationError::InvalidSliceBounds {
161 start: slice.start,
162 end: slice.end,
163 axis_len: usize::try_from(axis_len).map_err(|_| ValidationError::IntegerOverflow)?,
164 });
165 }
166 if start <= end {
167 return Ok((start, 0));
168 }
169 let step = slice
170 .step
171 .checked_neg()
172 .ok_or(ValidationError::IntegerOverflow)?;
173 Ok((start, positive_ceil_div(start - end, step)?))
174}
175
176/// Storage-neutral tensor layout metadata.
177///
178/// # Examples
179///
180/// ```rust
181/// use tenferro_tensor_core::{Rank, TensorLayout};
182///
183/// let layout = TensorLayout::<Rank<2>>::compact([2, 3])?;
184/// assert_eq!(layout.shape(), &[2, 3]);
185/// assert_eq!(layout.strides(), &[1, 2]);
186/// # Ok::<(), tenferro_tensor_core::ValidationError>(())
187/// ```
188#[derive(Clone, Debug, PartialEq, Eq)]
189pub struct TensorLayout<R: TensorRank = DynRank> {
190 shape: R::Shape,
191 strides: R::Strides,
192 offset: isize,
193}
194
195impl<R: TensorRank> TensorLayout<R> {
196 /// Create a compact column-major layout with zero offset.
197 ///
198 /// # Examples
199 ///
200 /// ```rust
201 /// use tenferro_tensor_core::{Rank, TensorLayout};
202 ///
203 /// let layout = TensorLayout::<Rank<2>>::compact([2, 3])?;
204 /// assert_eq!(layout.strides(), &[1, 2]);
205 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
206 /// ```
207 ///
208 /// # Errors
209 ///
210 /// Returns [`ValidationError::IntegerOverflow`] when compact strides
211 /// cannot be computed for `shape`.
212 pub fn compact(shape: R::Shape) -> Result<Self> {
213 let strides = R::strides_from_vec(col_major_strides(shape.as_ref())?)?;
214 Ok(Self {
215 shape,
216 strides,
217 offset: 0,
218 })
219 }
220
221 /// Create a layout from shape, strides, element offset, and backing buffer length.
222 ///
223 /// # Examples
224 ///
225 /// ```rust
226 /// use tenferro_tensor_core::{DynRank, TensorLayout};
227 ///
228 /// let layout = TensorLayout::<DynRank>::from_parts(
229 /// vec![2, 3].into_iter().collect(),
230 /// vec![1, 2].into_iter().collect(),
231 /// 0,
232 /// 6,
233 /// )?;
234 /// assert!(layout.is_compact_col_major()?);
235 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
236 /// ```
237 ///
238 /// # Errors
239 ///
240 /// Returns [`ValidationError::RankMismatch`] for incompatible shape and
241 /// stride ranks, [`ValidationError::ViewOutOfBounds`] when the reachable
242 /// range exceeds `buffer_len`, or [`ValidationError::IntegerOverflow`]
243 /// when metadata arithmetic overflows.
244 pub fn from_parts(
245 shape: R::Shape,
246 strides: R::Strides,
247 offset: isize,
248 buffer_len: usize,
249 ) -> Result<Self> {
250 checked_logical_element_count(shape.as_ref())?;
251 validate_reachable_bounds(shape.as_ref(), strides.as_ref(), offset, buffer_len)?;
252 Ok(Self {
253 shape,
254 strides,
255 offset,
256 })
257 }
258
259 /// Return the layout shape.
260 ///
261 /// # Examples
262 ///
263 /// ```rust
264 /// use tenferro_tensor_core::{Rank, TensorLayout};
265 ///
266 /// let layout = TensorLayout::<Rank<1>>::compact([4])?;
267 /// assert_eq!(layout.shape(), &[4]);
268 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
269 /// ```
270 pub fn shape(&self) -> &[usize] {
271 self.shape.as_ref()
272 }
273
274 /// Return the layout strides in element units.
275 ///
276 /// # Examples
277 ///
278 /// ```rust
279 /// use tenferro_tensor_core::{Rank, TensorLayout};
280 ///
281 /// let layout = TensorLayout::<Rank<2>>::compact([2, 3])?;
282 /// assert_eq!(layout.strides(), &[1, 2]);
283 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
284 /// ```
285 pub fn strides(&self) -> &[isize] {
286 self.strides.as_ref()
287 }
288
289 /// Return the layout element offset.
290 ///
291 /// # Examples
292 ///
293 /// ```rust
294 /// use tenferro_tensor_core::{DynRank, TensorLayout};
295 ///
296 /// let layout = TensorLayout::<DynRank>::from_parts(vec![3].into_iter().collect(), vec![1].into_iter().collect(), 2, 5)?;
297 /// assert_eq!(layout.offset(), 2);
298 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
299 /// ```
300 pub fn offset(&self) -> isize {
301 self.offset
302 }
303
304 /// Return whether the layout has compact column-major strides.
305 ///
306 /// # Examples
307 ///
308 /// ```rust
309 /// use tenferro_tensor_core::{Rank, TensorLayout};
310 ///
311 /// let layout = TensorLayout::<Rank<2>>::compact([2, 3])?;
312 /// assert!(layout.is_compact_col_major()?);
313 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
314 /// ```
315 ///
316 /// # Errors
317 ///
318 /// Returns [`ValidationError::IntegerOverflow`] when compactness
319 /// validation overflows metadata arithmetic.
320 pub fn is_compact_col_major(&self) -> Result<bool> {
321 if self.shape().contains(&0) {
322 return Ok(true);
323 }
324
325 col_major_strides(self.shape()).map(|strides| strides.as_slice() == self.strides())
326 }
327
328 /// Validate that the layout can be used for mutable access without aliasing.
329 ///
330 /// Empty logical views are accepted. A non-empty layout is accepted exactly
331 /// when distinct logical positions map to distinct physical offsets, as
332 /// decided by [`strided_view::is_injective_layout`]: the one injectivity
333 /// rule this workspace uses. There is no tenferro-local shortcut and no
334 /// element-count ceiling, so a legal layout is never refused for being
335 /// large.
336 ///
337 /// # Examples
338 ///
339 /// ```rust
340 /// use tenferro_tensor_core::{DynRank, TensorLayout};
341 ///
342 /// let layout = TensorLayout::<DynRank>::from_parts(vec![3].into_iter().collect(), vec![-1].into_iter().collect(), 2, 3)?;
343 /// layout.validate_mutable_no_overlap()?;
344 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
345 /// ```
346 ///
347 /// # Errors
348 ///
349 /// Returns [`ValidationError::OverlappingMutableLayout`] when multiple
350 /// logical elements can alias, or [`ValidationError::IntegerOverflow`]
351 /// when the logical element count does not fit `usize`. Metadata whose
352 /// reachable offsets do not fit `isize` is rejected by
353 /// [`TensorLayout::from_parts`] before a layout exists.
354 pub fn validate_mutable_no_overlap(&self) -> Result<()> {
355 if self.shape().contains(&0) {
356 return Ok(());
357 }
358
359 // Keep the element-count error distinct: an overflowing product is not
360 // an overlapping layout, and injectivity analysis reports it as one.
361 checked_product(self.shape())?;
362
363 if is_injective_layout(self.shape(), self.strides()) {
364 Ok(())
365 } else {
366 Err(ValidationError::OverlappingMutableLayout)
367 }
368 }
369
370 /// Return a metadata-only axis permutation of this layout.
371 ///
372 /// # Examples
373 ///
374 /// ```rust
375 /// use tenferro_tensor_core::{Rank, TensorLayout};
376 ///
377 /// let layout = TensorLayout::<Rank<2>>::compact([2, 3])?;
378 /// let transposed = layout.transpose_view([1, 0])?;
379 /// assert_eq!(transposed.shape(), &[3, 2]);
380 /// assert_eq!(transposed.strides(), &[2, 1]);
381 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
382 /// ```
383 ///
384 /// # Errors
385 ///
386 /// Returns [`ValidationError::InvalidPermutationLength`],
387 /// [`ValidationError::AxisOutOfBounds`], or
388 /// [`ValidationError::DuplicateAxis`] when `axes` is not a permutation of
389 /// the layout rank.
390 pub fn transpose_view(&self, axes: impl AsRef<[usize]>) -> Result<Self> {
391 let axes = axes.as_ref();
392 validate_permutation(self.shape().len(), axes)?;
393 let shape = axes
394 .iter()
395 .map(|&axis| self.shape()[axis])
396 .collect::<ShapeVec>();
397 let strides = axes
398 .iter()
399 .map(|&axis| self.strides()[axis])
400 .collect::<StrideVec>();
401 Ok(Self {
402 shape: R::shape_from_vec(shape)?,
403 strides: R::strides_from_vec(strides)?,
404 offset: self.offset,
405 })
406 }
407
408 /// Return a metadata-only slice of this layout.
409 ///
410 /// # Examples
411 ///
412 /// ```rust
413 /// use tenferro_tensor_core::{Rank, SliceSpec, TensorLayout};
414 ///
415 /// let layout = TensorLayout::<Rank<1>>::compact([4])?;
416 /// let view = layout.slice_view([SliceSpec { start: 3, end: -1, step: -2 }], 4)?;
417 /// assert_eq!(view.shape(), &[2]);
418 /// assert_eq!(view.strides(), &[-2]);
419 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
420 /// ```
421 ///
422 /// # Errors
423 ///
424 /// Returns [`ValidationError::RankMismatch`] when `spec` does not cover
425 /// every axis, [`ValidationError::InvalidSliceStep`] or
426 /// [`ValidationError::InvalidSliceBounds`] for invalid slice parameters,
427 /// or [`ValidationError::ViewOutOfBounds`] when the result is outside the
428 /// backing buffer.
429 pub fn slice_view(&self, spec: impl AsRef<[SliceSpec]>, buffer_len: usize) -> Result<Self> {
430 let spec = spec.as_ref();
431 if spec.len() != self.shape().len() {
432 return Err(ValidationError::RankMismatch {
433 expected: self.shape().len(),
434 actual: spec.len(),
435 });
436 }
437
438 let mut shape = ShapeVec::new();
439 let mut strides = StrideVec::new();
440 let mut offset = self.offset;
441 for ((&axis_len, &stride), &slice) in self
442 .shape()
443 .iter()
444 .zip(self.strides().iter())
445 .zip(spec.iter())
446 {
447 let (start, extent) = normalize_slice(slice, axis_len)?;
448 let start_offset = start
449 .checked_mul(stride)
450 .ok_or(ValidationError::IntegerOverflow)?;
451 offset = offset
452 .checked_add(start_offset)
453 .ok_or(ValidationError::IntegerOverflow)?;
454 shape.push(extent);
455 strides.push(
456 stride
457 .checked_mul(slice.step)
458 .ok_or(ValidationError::IntegerOverflow)?,
459 );
460 }
461 layout_from_vecs(shape, strides, offset, buffer_len)
462 }
463
464 /// Return a metadata-only reshape of this compact column-major layout.
465 ///
466 /// # Examples
467 ///
468 /// ```rust
469 /// use tenferro_tensor_core::{Rank, TensorLayout};
470 ///
471 /// let layout = TensorLayout::<Rank<2>>::compact([2, 3])?;
472 /// let reshaped = layout.reshape_view_as::<Rank<1>>([6], 6)?;
473 /// assert_eq!(reshaped.shape(), &[6]);
474 /// assert_eq!(reshaped.strides(), &[1]);
475 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
476 /// ```
477 ///
478 /// # Errors
479 ///
480 /// Returns [`ValidationError::NonContiguousViewAsSlice`] for a noncompact
481 /// source, [`ValidationError::ShapeMismatch`] for a different element
482 /// count, or [`ValidationError::IntegerOverflow`] when shape arithmetic
483 /// overflows.
484 pub fn reshape_view_as<R2: TensorRank>(
485 &self,
486 shape: impl Into<R2::Shape>,
487 buffer_len: usize,
488 ) -> Result<TensorLayout<R2>> {
489 let shape = shape.into();
490 if !self.is_compact_col_major()? {
491 return Err(ValidationError::NonContiguousViewAsSlice);
492 }
493 let from = checked_product(self.shape())?;
494 let to = checked_product(shape.as_ref())?;
495 if from != to {
496 return Err(ShapeMismatch::ReshapeElementCount { from, to }.into());
497 }
498 let strides = R2::strides_from_vec(col_major_strides(shape.as_ref())?)?;
499 TensorLayout::from_parts(shape, strides, self.offset, buffer_len)
500 }
501
502 /// Return a metadata-only explicit broadcast of this layout into a target rank.
503 ///
504 /// # Examples
505 ///
506 /// ```rust
507 /// use tenferro_tensor_core::{Rank, TensorLayout};
508 ///
509 /// let layout = TensorLayout::<Rank<1>>::compact([3])?;
510 /// let broadcast = layout.broadcast_in_dim_view::<Rank<2>>([2, 3], [1], 3)?;
511 /// assert_eq!(broadcast.shape(), &[2, 3]);
512 /// assert_eq!(broadcast.strides(), &[0, 1]);
513 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
514 /// ```
515 ///
516 /// # Errors
517 ///
518 /// Returns [`ValidationError::RankMismatch`],
519 /// [`ValidationError::AxisOutOfBounds`], or
520 /// [`ValidationError::DuplicateAxis`] for invalid broadcast axes;
521 /// [`ValidationError::ShapeDataLengthMismatch`] for incompatible extents;
522 /// or [`ValidationError::ViewOutOfBounds`] for an invalid result layout.
523 pub fn broadcast_in_dim_view<R2: TensorRank>(
524 &self,
525 shape: impl Into<R2::Shape>,
526 broadcast_dims: impl AsRef<[usize]>,
527 buffer_len: usize,
528 ) -> Result<TensorLayout<R2>> {
529 let shape = shape.into();
530 let broadcast_dims = broadcast_dims.as_ref();
531 if broadcast_dims.len() != self.shape().len() {
532 return Err(ValidationError::RankMismatch {
533 expected: self.shape().len(),
534 actual: broadcast_dims.len(),
535 });
536 }
537
538 let output_rank = shape.as_ref().len();
539 let mut strides = StrideVec::new();
540 strides.resize(output_rank, 0);
541 for (input_axis, &output_axis) in broadcast_dims.iter().enumerate() {
542 if output_axis >= output_rank {
543 return Err(ValidationError::AxisOutOfBounds {
544 axis: isize::try_from(output_axis).unwrap_or(isize::MAX),
545 rank: output_rank,
546 });
547 }
548 // A linear scan over the axes already placed keeps this path free of
549 // a rank-sized scratch allocation; the ranks here are tiny.
550 if broadcast_dims[..input_axis].contains(&output_axis) {
551 return Err(ValidationError::DuplicateAxis {
552 axis: output_axis,
553 role: "permutation",
554 });
555 }
556
557 let input_extent = self.shape()[input_axis];
558 let output_extent = shape.as_ref()[output_axis];
559 if input_extent != output_extent && input_extent != 1 {
560 return Err(ValidationError::ShapeDataLengthMismatch {
561 expected: input_extent,
562 actual: output_extent,
563 });
564 }
565 if input_extent == output_extent {
566 strides[output_axis] = self.strides()[input_axis];
567 }
568 }
569
570 TensorLayout::from_parts(
571 shape,
572 R2::strides_from_vec(strides)?,
573 self.offset,
574 buffer_len,
575 )
576 }
577}
578
579impl<const N: usize> TensorLayout<Rank<N>> {
580 /// Return the compile-time-rank shape without erasing its array type.
581 ///
582 /// # Examples
583 ///
584 /// ```rust
585 /// use tenferro_tensor_core::{Rank, TensorLayout};
586 ///
587 /// let layout = TensorLayout::<Rank<2>>::compact([2, 3])?;
588 /// assert_eq!(layout.shape_array(), &[2, 3]);
589 /// # Ok::<(), tenferro_tensor_core::ValidationError>(())
590 /// ```
591 pub fn shape_array(&self) -> &[usize; N] {
592 &self.shape
593 }
594}
595
596#[cfg(test)]
597mod tests {
598 use super::positive_ceil_div;
599 use crate::ValidationError;
600 use std::panic::{catch_unwind, AssertUnwindSafe};
601
602 #[test]
603 fn positive_ceil_div_rejects_invalid_preconditions_without_panicking() {
604 for (numerator, denominator) in [(-1, 1), (1, 0), (1, -1)] {
605 let result = catch_unwind(AssertUnwindSafe(|| {
606 positive_ceil_div(numerator, denominator)
607 }));
608
609 assert!(
610 result.is_ok(),
611 "invalid positive_ceil_div inputs should return Err"
612 );
613 assert!(matches!(
614 result.unwrap(),
615 Err(ValidationError::IntegerOverflow)
616 ));
617 }
618 }
619}