Skip to main content

tenferro_ad/
shape_packing.rs

1use std::ops::Range;
2
3use tenferro_tensor::{GatherConfig, SliceConfig, Tensor, TypedTensor};
4
5use crate::eager::{EagerSession, EagerTensor};
6use crate::error::{Error, Result};
7
8/// Normalize one signed axis of an eager operation (#2552 ยง3.2) through the
9/// shared `tenferro_tensor::normalize_axis`.
10pub(crate) fn normalize_existing_axis(op: &'static str, axis: isize, rank: usize) -> Result<usize> {
11    tenferro_tensor::normalize_axis(axis, rank)
12        .map_err(|e| Error::TensorRuntime(tenferro_tensor::Error::validation(op, e)))
13}
14
15/// Normalize a signed axis list of an eager operation, keeping its order.
16/// Duplicates are left to the operation's own validation.
17pub(crate) fn normalize_existing_axes(
18    op: &'static str,
19    axes: &[isize],
20    rank: usize,
21) -> Result<Vec<usize>> {
22    axes.iter()
23        .map(|&axis| normalize_existing_axis(op, axis, rank))
24        .collect()
25}
26
27/// A normalized axis as the signed form of the public eager methods.
28pub(crate) fn signed_axis(axis: usize) -> Result<isize> {
29    isize::try_from(axis)
30        .map_err(|_| Error::Internal(format!("normalized axis {axis} does not fit isize")))
31}
32
33pub(crate) fn normalize_insert_axis(op: &'static str, axis: isize, rank: usize) -> Result<usize> {
34    let insert_rank = rank
35        .checked_add(1)
36        .ok_or_else(|| tenferro_tensor::Error::axis_out_of_bounds(op, axis.unsigned_abs(), rank))?;
37    let normalized = if axis >= 0 {
38        axis as usize
39    } else {
40        insert_rank
41            .checked_sub(axis.unsigned_abs())
42            .ok_or_else(|| {
43                tenferro_tensor::Error::axis_out_of_bounds(op, axis.unsigned_abs(), insert_rank)
44            })?
45    };
46    if normalized > rank {
47        return Err(tenferro_tensor::Error::axis_out_of_bounds(
48            op,
49            axis.unsigned_abs(),
50            insert_rank,
51        )
52        .into());
53    }
54    Ok(normalized)
55}
56
57fn index_select_config(
58    shape: &[usize],
59    axis: isize,
60    positions: &[usize],
61) -> Result<(Tensor, GatherConfig)> {
62    let axis = normalize_existing_axis("index_select", axis, shape.len())?;
63    let axis_extent = shape[axis];
64    for &position in positions {
65        if position >= axis_extent {
66            return Err(tenferro_tensor::Error::invalid_argument(
67                "index_select",
68                "position",
69                format!(
70                    "position {position} out of bounds for axis {axis} with extent {axis_extent}"
71                ),
72            )
73            .into());
74        }
75    }
76
77    let mut slice_sizes = shape.to_vec();
78    slice_sizes[axis] = 1;
79
80    let offset_dims = (0..shape.len()).filter(|&dim| dim != axis).collect();
81    let index_data = positions
82        .iter()
83        .map(|&position| {
84            i64::try_from(position).map_err(|_| {
85                tenferro_tensor::Error::invalid_argument(
86                    "index_select",
87                    "position",
88                    format!("position {position} cannot be represented as i64"),
89                )
90            })
91        })
92        .collect::<tenferro_tensor::Result<Vec<_>>>()?;
93    let indices = Tensor::from_typed::<i64>(TypedTensor::from_vec_col_major(
94        vec![positions.len(), 1],
95        index_data,
96    )?);
97
98    let config = GatherConfig {
99        offset_dims,
100        collapsed_slice_dims: vec![axis],
101        start_index_map: vec![axis],
102        index_vector_dim: 1,
103        slice_sizes,
104    };
105
106    Ok((indices, config))
107}
108
109fn validate_stack_shapes(op: &'static str, shapes: &[&[usize]]) -> Result<()> {
110    let Some(first) = shapes.first() else {
111        return Err(tenferro_tensor::Error::invalid_argument(
112            op,
113            "inputs",
114            "stack requires at least one input",
115        )
116        .into());
117    };
118    for shape in shapes.iter().skip(1) {
119        if *shape != *first {
120            return Err(tenferro_tensor::Error::shape_mismatch(op, *first, *shape).into());
121        }
122    }
123    Ok(())
124}
125
126#[derive(Clone, Debug)]
127enum AxisSelection<A = usize> {
128    Slice {
129        axis: A,
130        range: Range<usize>,
131        step: usize,
132    },
133    Take {
134        axis: A,
135        indices: Vec<usize>,
136    },
137}
138
139fn validate_axis_selection(
140    op: &'static str,
141    rank: usize,
142    seen: &mut [bool],
143    axis: usize,
144) -> Result<()> {
145    if axis >= rank {
146        return Err(tenferro_tensor::Error::axis_out_of_bounds(op, axis, rank).into());
147    }
148    if seen[axis] {
149        return Err(tenferro_tensor::Error::duplicate_axis(op, axis, "selection").into());
150    }
151    seen[axis] = true;
152    Ok(())
153}
154
155fn apply_slice_axis_config(
156    op: &'static str,
157    shape: &[usize],
158    selections: &[AxisSelection],
159) -> Result<Option<SliceConfig>> {
160    let mut starts = vec![0; shape.len()];
161    let mut limits = shape.to_vec();
162    let mut strides = vec![1; shape.len()];
163    let mut has_slice = false;
164    for selection in selections {
165        let AxisSelection::Slice { axis, range, step } = selection else {
166            continue;
167        };
168        if *step == 0 {
169            return Err(tenferro_tensor::Error::invalid_argument(
170                op,
171                "step",
172                format!("axis {axis} has zero step"),
173            )
174            .into());
175        }
176        let extent = shape[*axis];
177        if range.start > range.end || range.end > extent {
178            return Err(tenferro_tensor::Error::invalid_argument(
179                op,
180                "range",
181                format!(
182                    "axis {axis} range {}..{} is out of bounds for extent {extent}",
183                    range.start, range.end
184                ),
185            )
186            .into());
187        }
188        starts[*axis] = range.start;
189        limits[*axis] = range.end;
190        strides[*axis] = *step;
191        has_slice = true;
192    }
193    Ok(has_slice.then_some(SliceConfig {
194        starts,
195        limits,
196        strides,
197    }))
198}
199
200/// Rank-preserving eager tensor slicing builder.
201///
202/// Unspecified axes are kept whole. Range selections become one `Slice`
203/// operation; host-known position selections become `Gather`/`index_select`
204/// operations.
205///
206/// # Examples
207///
208/// ```rust
209/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
210///
211/// let ctx = EagerRuntime::new()?;
212/// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![3, 4], vec![0.0_f64; 12]).unwrap()).unwrap();
213/// let y = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| x.slice_builder().axis(0, 0..2).axis_step(1, 0..4, 2).apply(s))?;
214/// assert_eq!(y.shape(), &[2, 2]);
215/// # Ok::<(), tenferro_ad::Error>(())
216/// ```
217#[derive(Clone, Debug)]
218pub struct EagerSliceBuilder<'a> {
219    tensor: &'a EagerTensor,
220    selections: Vec<AxisSelection<isize>>,
221}
222
223impl<'a> EagerSliceBuilder<'a> {
224    fn new(tensor: &'a EagerTensor) -> Self {
225        Self {
226            tensor,
227            selections: Vec::new(),
228        }
229    }
230
231    /// Add an exclusive-end range selection for one axis.
232    ///
233    /// # Examples
234    ///
235    /// ```rust
236    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
237    ///
238    /// let ctx = EagerRuntime::new()?;
239    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0]).unwrap()).unwrap();
240    /// let y = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| x.slice_builder().axis(0, 1..3).apply(s))?;
241    /// assert_eq!(y.shape(), &[2]);
242    /// # Ok::<(), tenferro_ad::Error>(())
243    /// ```
244    pub fn axis(mut self, axis: isize, range: Range<usize>) -> Self {
245        self.selections.push(AxisSelection::Slice {
246            axis,
247            range,
248            step: 1,
249        });
250        self
251    }
252
253    /// Add an exclusive-end strided range selection for one axis.
254    ///
255    /// # Examples
256    ///
257    /// ```rust
258    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
259    ///
260    /// let ctx = EagerRuntime::new()?;
261    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![5], vec![1.0_f64, 2.0, 3.0, 4.0, 5.0]).unwrap()).unwrap();
262    /// let y = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| x.slice_builder().axis_step(0, 0..5, 2).apply(s))?;
263    /// assert_eq!(y.shape(), &[3]);
264    /// # Ok::<(), tenferro_ad::Error>(())
265    /// ```
266    pub fn axis_step(mut self, axis: isize, range: Range<usize>, step: usize) -> Self {
267        self.selections
268            .push(AxisSelection::Slice { axis, range, step });
269        self
270    }
271
272    /// Add a host-known position selection for one axis.
273    ///
274    /// # Examples
275    ///
276    /// ```rust
277    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
278    ///
279    /// let ctx = EagerRuntime::new()?;
280    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
281    /// let y = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| x.slice_builder().take_axis(0, &[2, 0]).apply(s))?;
282    /// assert_eq!(y.shape(), &[2]);
283    /// # Ok::<(), tenferro_ad::Error>(())
284    /// ```
285    pub fn take_axis(mut self, axis: isize, indices: &[usize]) -> Self {
286        self.selections.push(AxisSelection::Take {
287            axis,
288            indices: indices.to_vec(),
289        });
290        self
291    }
292
293    /// Build and apply the requested slice/take operations.
294    ///
295    /// # Examples
296    ///
297    /// ```rust
298    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
299    ///
300    /// let ctx = EagerRuntime::new()?;
301    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0]).unwrap()).unwrap();
302    /// let y = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| x.slice_builder().axis(0, 1..4).apply(s))?;
303    /// assert_eq!(y.shape(), &[3]);
304    /// # Ok::<(), tenferro_ad::Error>(())
305    /// ```
306    /// # Errors
307    ///
308    /// Returns [`tenferro_tensor::ValidationError::AxisOutOfBounds`] or
309    /// `DuplicateAxis` when selections address an invalid/repeated axis,
310    /// `InvalidArgument` for zero steps or out-of-bounds ranges, or a typed
311    /// backend/runtime-state error while applying the selections.
312    pub fn apply(self, session: &mut EagerSession<'_>) -> Result<EagerTensor> {
313        session.ensure_runtime(self.tensor)?;
314        let shape = self.tensor.shape().to_vec();
315        let selections = self
316            .selections
317            .into_iter()
318            .map(|selection| {
319                Ok(match selection {
320                    AxisSelection::Slice { axis, range, step } => AxisSelection::Slice {
321                        axis: normalize_existing_axis("slice_builder", axis, shape.len())?,
322                        range,
323                        step,
324                    },
325                    AxisSelection::Take { axis, indices } => AxisSelection::Take {
326                        axis: normalize_existing_axis("slice_builder", axis, shape.len())?,
327                        indices,
328                    },
329                })
330            })
331            .collect::<Result<Vec<AxisSelection>>>()?;
332        let mut seen = vec![false; shape.len()];
333        for selection in &selections {
334            let axis = match selection {
335                AxisSelection::Slice { axis, .. } | AxisSelection::Take { axis, .. } => *axis,
336            };
337            validate_axis_selection("slice_builder", shape.len(), &mut seen, axis)?;
338        }
339
340        let mut output = self.tensor.clone();
341        if let Some(config) = apply_slice_axis_config("slice_builder", &shape, &selections)? {
342            output = session.slice(&output, config)?;
343        }
344        for selection in selections {
345            if let AxisSelection::Take { axis, indices } = selection {
346                output = session.take_axis(&output, signed_axis(axis)?, &indices)?;
347            }
348        }
349        Ok(output)
350    }
351}
352
353impl EagerTensor {
354    /// Start a rank-preserving slicing builder for this tensor.
355    ///
356    /// # Examples
357    ///
358    /// ```rust
359    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
360    ///
361    /// let ctx = EagerRuntime::new()?;
362    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
363    /// let y = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| x.slice_builder().axis(0, 0..2).apply(s))?;
364    /// assert_eq!(y.shape(), &[2]);
365    /// # Ok::<(), tenferro_ad::Error>(())
366    /// ```
367    pub fn slice_builder(&self) -> EagerSliceBuilder<'_> {
368        EagerSliceBuilder::new(self)
369    }
370}
371
372impl EagerSession<'_> {
373    /// Select positions from one axis using a borrowed session.
374    ///
375    /// # Examples
376    /// ```rust
377    /// use tenferro_ad::{EagerRuntime, Tensor};
378    /// let ctx = EagerRuntime::new()?;
379    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
380    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0])?)?;
381    ///     s.index_select(&x, -1, &[2, 0])
382    /// })?;
383    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[3.0, 1.0]);
384    /// # Ok::<(), tenferro_ad::Error>(())
385    /// ```
386    /// # Errors
387    /// Returns a typed foreign-runtime, invalid-axis/index, or backend error.
388    pub fn index_select(
389        &mut self,
390        tensor: &EagerTensor,
391        axis: isize,
392        positions: &[usize],
393    ) -> Result<EagerTensor> {
394        self.ensure_runtime(tensor)?;
395        let (indices, config) = index_select_config(tensor.shape(), axis, positions)?;
396        let indices = self.constant_from_host(indices)?;
397        self.gather(tensor, &indices, config)
398    }
399
400    /// Select entries from an axis by host-known positions.
401    ///
402    /// # Examples
403    /// ```rust
404    /// use tenferro_ad::{EagerRuntime, Tensor};
405    /// let ctx = EagerRuntime::new()?;
406    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
407    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
408    ///     s.take_axis(&x, 0, &[1])
409    /// })?;
410    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[2.0]);
411    /// # Ok::<(), tenferro_ad::Error>(())
412    /// ```
413    /// # Errors
414    /// Returns a typed foreign-runtime, invalid-axis/index, or backend error.
415    pub fn take_axis(
416        &mut self,
417        tensor: &EagerTensor,
418        axis: isize,
419        positions: &[usize],
420    ) -> Result<EagerTensor> {
421        self.ensure_runtime(tensor)?;
422        self.index_select(tensor, axis, positions)
423    }
424
425    /// Select matrix rows by host-known positions.
426    ///
427    /// # Examples
428    /// ```rust
429    /// use tenferro_ad::{EagerRuntime, Tensor};
430    /// let ctx = EagerRuntime::new()?;
431    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
432    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2, 1], vec![1.0_f64, 2.0])?)?;
433    ///     s.take_rows(&x, &[1])
434    /// })?;
435    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[2.0]);
436    /// # Ok::<(), tenferro_ad::Error>(())
437    /// ```
438    /// # Errors
439    /// Returns a typed foreign-runtime, invalid-row, or backend error.
440    pub fn take_rows(&mut self, tensor: &EagerTensor, rows: &[usize]) -> Result<EagerTensor> {
441        self.take_axis(tensor, 0, rows)
442    }
443
444    /// Select matrix columns by host-known positions.
445    ///
446    /// # Examples
447    /// ```rust
448    /// use tenferro_ad::{EagerRuntime, Tensor};
449    /// let ctx = EagerRuntime::new()?;
450    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
451    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1, 2], vec![1.0_f64, 2.0])?)?;
452    ///     s.take_cols(&x, &[1])
453    /// })?;
454    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[2.0]);
455    /// # Ok::<(), tenferro_ad::Error>(())
456    /// ```
457    /// # Errors
458    /// Returns a typed foreign-runtime, invalid-column, or backend error.
459    pub fn take_cols(&mut self, tensor: &EagerTensor, cols: &[usize]) -> Result<EagerTensor> {
460        self.take_axis(tensor, 1, cols)
461    }
462
463    /// Select a matrix block by host-known row and column positions.
464    ///
465    /// # Examples
466    /// ```rust
467    /// use tenferro_ad::{EagerRuntime, Tensor};
468    /// let ctx = EagerRuntime::new()?;
469    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
470    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
471    ///     s.take_block(&x, &[1], &[0])
472    /// })?;
473    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[2.0]);
474    /// # Ok::<(), tenferro_ad::Error>(())
475    /// ```
476    /// # Errors
477    /// Returns a typed foreign-runtime, invalid-row/column, or backend error.
478    pub fn take_block(
479        &mut self,
480        tensor: &EagerTensor,
481        rows: &[usize],
482        cols: &[usize],
483    ) -> Result<EagerTensor> {
484        let rows = self.take_rows(tensor, rows)?;
485        self.take_cols(&rows, cols)
486    }
487
488    /// Slice one axis using an exclusive-end range in this borrowed session.
489    ///
490    /// # Examples
491    /// ```rust
492    /// use tenferro_ad::{EagerRuntime, Tensor};
493    /// let ctx = EagerRuntime::new()?;
494    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
495    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0])?)?;
496    ///     s.slice_axis(&x, 0, 1..3)
497    /// })?;
498    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[2.0, 3.0]);
499    /// # Ok::<(), tenferro_ad::Error>(())
500    /// ```
501    /// # Errors
502    /// Returns a typed foreign-runtime, invalid-axis/range, or backend error.
503    pub fn slice_axis(
504        &mut self,
505        tensor: &EagerTensor,
506        axis: isize,
507        range: Range<usize>,
508    ) -> Result<EagerTensor> {
509        tensor.slice_builder().axis(axis, range).apply(self)
510    }
511
512    /// Stack eager tensors along a new axis in this borrowed session.
513    ///
514    /// # Examples
515    /// ```rust
516    /// use tenferro_ad::{EagerRuntime, Tensor};
517    /// let ctx = EagerRuntime::new()?;
518    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
519    ///     let a = s.constant_from(Tensor::from_vec_col_major(vec![], vec![1.0_f64])?)?;
520    ///     let b = s.constant_from(Tensor::from_vec_col_major(vec![], vec![2.0_f64])?)?;
521    ///     s.stack(&[&a, &b], -1)
522    /// })?;
523    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[1.0, 2.0]);
524    /// # Ok::<(), tenferro_ad::Error>(())
525    /// ```
526    /// # Errors
527    /// Returns a typed empty-input, invalid-axis/shape, foreign-runtime, or backend error.
528    pub fn stack(&mut self, tensors: &[&EagerTensor], dim: isize) -> Result<EagerTensor> {
529        let first = tensors.first().copied().ok_or_else(|| {
530            Error::TensorRuntime(tenferro_tensor::Error::invalid_argument(
531                "stack",
532                "inputs",
533                "stack requires at least one input",
534            ))
535        })?;
536        let shapes = tensors
537            .iter()
538            .map(|tensor| tensor.shape())
539            .collect::<Vec<_>>();
540        validate_stack_shapes("stack", &shapes)?;
541        let axis = normalize_insert_axis("stack", dim, first.shape().len())?;
542        let mut expanded_shape = first.shape().to_vec();
543        expanded_shape.insert(axis, 1);
544        let expanded = tensors
545            .iter()
546            .map(|tensor| self.reshape(tensor, &expanded_shape))
547            .collect::<Result<Vec<_>>>()?;
548        let refs = expanded.iter().collect::<Vec<_>>();
549        self.concatenate(&refs, signed_axis(axis)?)
550    }
551}
552
553#[cfg(test)]
554mod tests {
555    use super::{normalize_existing_axis, normalize_insert_axis};
556
557    #[test]
558    fn axis_normalization_handles_ranks_larger_than_isize_max() {
559        assert_eq!(normalize_existing_axis("test", 0, usize::MAX).unwrap(), 0);
560        assert_eq!(
561            normalize_existing_axis("test", -1, usize::MAX).unwrap(),
562            usize::MAX - 1
563        );
564        assert_eq!(
565            normalize_insert_axis("test", -1, usize::MAX - 1).unwrap(),
566            usize::MAX - 1
567        );
568        assert!(normalize_insert_axis("test", -1, usize::MAX).is_err());
569    }
570}