Skip to main content

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}