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}