Skip to main content

coeus_nn/pool/
adaptive.rs

1// ── Adaptive Pooling NN modules ──
2//
3// AdaptiveAvgPool1d / AdaptiveAvgPool2d / AdaptiveMaxPool1d / AdaptiveMaxPool2d:
4//   Stateless modules where the user specifies the output spatial size rather
5//   than the kernel/stride.  The pooling regions are computed dynamically to
6//   evenly cover the input spatial extent.
7//
8//   Matches PyTorch `nn.AdaptiveAvgPool1d(output_size)` etc.
9//
10// ZST phantom markers provide zero-overhead type safety without any allocation.
11
12use crate::module::{Module, ModuleError};
13use coeus_autograd::Var;
14use coeus_core::{CpuAddressableStorage, CpuAddressableStorageMut, Float, MoiraiBackend, Scalar};
15use coeus_tensor::Tensor;
16use std::marker::PhantomData;
17
18/// Transposed averaging matrix `P_T` `[in_len, out_len]` for adaptive average
19/// pooling along one axis. Output column `o` carries `1/region` in the rows of
20/// its input region `[floor(o*in/out), ceil((o+1)*in/out))` — PyTorch's adaptive
21/// region convention — and zero elsewhere. `input @ P_T` then averages each
22/// region; being a constant matmul it is differentiable (the backward scatters
23/// the per-region-averaged gradient back to every input position in the region).
24fn avg_pool_matrix_t<T: Float + coeus_core::FloatElement, B: coeus_ops::BackendOps<T> + Default>(
25    in_len: usize,
26    out_len: usize,
27    backend: &B,
28) -> Result<Var<T, B>, B::Error>
29where
30    B::DeviceBuffer<T>: CpuAddressableStorage<T> + CpuAddressableStorageMut<T>,
31{
32    let mut pt = vec![T::ZERO; in_len * out_len];
33    for o in 0..out_len {
34        let start = o * in_len / out_len;
35        let end = ((o + 1) * in_len).div_ceil(out_len);
36        let inv = <T as coeus_core::FloatElement>::from_count_reciprocal(end - start);
37        // Column `o`, rows `start..end`: flat index `l * out_len + o`.
38        for slot in pt
39            .iter_mut()
40            .skip(start * out_len + o)
41            .step_by(out_len)
42            .take(end - start)
43        {
44            *slot = inv;
45        }
46    }
47    Var::new(
48        Tensor::from_slice_on([in_len, out_len], &pt, backend)?,
49        false,
50    )
51}
52
53/// Adaptive **max** pool over the last axis of a 2D view `[rows, in_len]` →
54/// `[rows, out_len]`. Each output takes the max over its adaptive input region
55/// (PyTorch's region convention). Differentiable: non-region positions are
56/// filled with `-inf` and `max_axis` routes the gradient to each region's
57/// argmax. The transient `[rows, out_len, in_len]` mask is `out_len`× the slice
58/// — modest for typical pools; an argmax-scatter kernel would avoid it.
59fn masked_adaptive_max<
60    T: Float + coeus_core::FloatElement + coeus_cpu::RealScalar,
61    B: coeus_ops::BackendOps<T> + Default,
62>(
63    x2: &Var<T, B>,
64    rows: usize,
65    in_len: usize,
66    out_len: usize,
67    backend: &B,
68) -> Result<Var<T, B>, B::Error>
69where
70    B::DeviceBuffer<T>: CpuAddressableStorage<T> + CpuAddressableStorageMut<T>,
71{
72    // outside[o, l] = 1 where l is NOT in region o → filled with -inf below.
73    let mut outside = vec![T::ONE; out_len * in_len];
74    for o in 0..out_len {
75        let start = o * in_len / out_len;
76        let end = ((o + 1) * in_len).div_ceil(out_len);
77        outside[o * in_len + start..o * in_len + end].fill(T::ZERO);
78    }
79    let outside_var = Var::new(
80        Tensor::from_slice_on([1, out_len, in_len], &outside, backend)?,
81        false,
82    )?;
83    let xb = coeus_autograd::broadcast_to(
84        &coeus_autograd::reshape(x2, [rows, 1, in_len])?,
85        vec![rows, out_len, in_len],
86    )?;
87    let ob = coeus_autograd::broadcast_to(&outside_var, vec![rows, out_len, in_len])?;
88    let masked = coeus_autograd::masked_fill(
89        &xb,
90        &ob,
91        <T as coeus_core::FloatElement>::from_f64(f64::NEG_INFINITY),
92    )?;
93    coeus_autograd::max_axis(&masked, 2)
94}
95
96// ── AdaptiveAvgPool1d ─────────────────────────────────────────────────────────
97
98/// Adaptive average pooling for `[N, C, L]` → `[N, C, output_size]`.
99///
100/// Matches PyTorch `nn.AdaptiveAvgPool1d(output_size)`.  Each output position
101/// pools over a region of the input whose size is determined by the ratio
102/// `L / output_size`, with ceiling/floor arithmetic for non-divisible sizes.
103///
104/// # Examples
105///
106/// ```
107/// use coeus_nn::{AdaptiveAvgPool1d, Module};
108/// use coeus_autograd::Var;
109/// use coeus_tensor::Tensor;
110/// use coeus_core::SequentialBackend;
111///
112/// let m = AdaptiveAvgPool1d::<f32, SequentialBackend>::new(2);
113/// let x = Var::new(
114///     Tensor::<f32, SequentialBackend>::ones([1, 3, 8])
115///         .expect("invariant: example shape allocation succeeds"),
116///     false,
117/// ).expect("invariant: constant example variable needs no gradient buffer");
118/// let y = m.forward(&x).expect("valid AdaptiveAvgPool1d input");
119/// assert_eq!(y.tensor.shape(), &[1, 3, 2]);
120/// ```
121#[derive(Clone, Debug)]
122pub struct AdaptiveAvgPool1d<T: Scalar, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
123    /// Target spatial output length.
124    output_size: usize,
125    _marker: PhantomData<(T, B)>,
126}
127
128impl<T: coeus_core::FloatElement + Scalar, B: coeus_ops::BackendOps<T> + Default>
129    AdaptiveAvgPool1d<T, B>
130{
131    /// Create an `AdaptiveAvgPool1d` with the given output size.
132    pub const fn new(output_size: usize) -> Self {
133        Self {
134            output_size,
135            _marker: PhantomData,
136        }
137    }
138}
139
140impl<
141        T: coeus_core::FloatElement + Float + coeus_cpu::RealScalar,
142        B: coeus_ops::BackendOps<T> + Default,
143    > Module<T, B> for AdaptiveAvgPool1d<T, B>
144where
145    B::DeviceBuffer<T>: CpuAddressableStorage<T> + CpuAddressableStorageMut<T>,
146{
147    fn parameters(&self) -> Vec<Var<T, B>> {
148        vec![]
149    }
150
151    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
152        // Differentiable: average each adaptive region via a constant averaging
153        // matmul over the length axis.  [N, C, L] -> [N*C, L] @ P_T[L, O].
154        let shape = input.tensor.shape_cloned();
155        if shape.len() != 3 {
156            return Err(ModuleError::InvalidRank {
157                module: "AdaptiveAvgPool1d",
158                expected: "3",
159                actual: shape.len(),
160            });
161        }
162        let (n, c, l) = (shape[0], shape[1], shape[2]);
163        let o = self.output_size;
164        if l == 0 || o == 0 {
165            return Err(ModuleError::ShapeMismatch {
166                module: "AdaptiveAvgPool1d",
167                parameter: "spatial input and output dimensions",
168                expected: vec![1, 1],
169                actual: vec![l, o],
170            });
171        }
172        let backend = B::default();
173        let p_t = avg_pool_matrix_t::<T, B>(l, o, &backend)?;
174        let x2 = coeus_autograd::reshape(input, [n * c, l])?;
175        let out2 = coeus_autograd::matmul(&x2, &p_t)?;
176        Ok(coeus_autograd::reshape(&out2, [n, c, o])?)
177    }
178}
179
180// ── AdaptiveAvgPool2d ─────────────────────────────────────────────────────────
181
182/// Adaptive average pooling for `[N, C, H, W]` → `[N, C, out_h, out_w]`.
183///
184/// Matches PyTorch `nn.AdaptiveAvgPool2d((out_h, out_w))`.  Commonly used as
185/// the final spatial pooling stage in CNN classifiers (e.g., ResNet).
186///
187/// # Examples
188///
189/// ```
190/// use coeus_nn::{AdaptiveAvgPool2d, Module};
191/// use coeus_autograd::Var;
192/// use coeus_tensor::Tensor;
193/// use coeus_core::SequentialBackend;
194///
195/// let m = AdaptiveAvgPool2d::<f32, SequentialBackend>::new(1, 1);
196/// let x = Var::new(
197///     Tensor::<f32, SequentialBackend>::ones([2, 4, 8, 8])
198///         .expect("invariant: example shape allocation succeeds"),
199///     false,
200/// ).expect("invariant: constant example variable needs no gradient buffer");
201/// let y = m.forward(&x).expect("valid AdaptiveAvgPool2d input");
202/// assert_eq!(y.tensor.shape(), &[2, 4, 1, 1]);
203/// ```
204#[derive(Clone, Debug)]
205pub struct AdaptiveAvgPool2d<T: Scalar, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
206    /// Target output height.
207    out_h: usize,
208    /// Target output width.
209    out_w: usize,
210    _marker: PhantomData<(T, B)>,
211}
212
213impl<T: coeus_core::FloatElement + Scalar, B: coeus_ops::BackendOps<T> + Default>
214    AdaptiveAvgPool2d<T, B>
215{
216    /// Create an `AdaptiveAvgPool2d` pooling to `(out_h, out_w)` output size.
217    pub const fn new(out_h: usize, out_w: usize) -> Self {
218        Self {
219            out_h,
220            out_w,
221            _marker: PhantomData,
222        }
223    }
224
225    /// Create an `AdaptiveAvgPool2d` pooling to a square `(size, size)` output.
226    pub const fn square(size: usize) -> Self {
227        Self::new(size, size)
228    }
229}
230
231impl<
232        T: coeus_core::FloatElement + Float + coeus_cpu::RealScalar,
233        B: coeus_ops::BackendOps<T> + Default,
234    > Module<T, B> for AdaptiveAvgPool2d<T, B>
235where
236    B::DeviceBuffer<T>: CpuAddressableStorage<T> + CpuAddressableStorageMut<T>,
237{
238    fn parameters(&self) -> Vec<Var<T, B>> {
239        vec![]
240    }
241
242    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
243        // Differentiable separable pooling: average over W, then over H, each a
244        // constant averaging matmul. Averaging is separable so this equals the
245        // joint 2D adaptive average.
246        let shape = input.tensor.shape_cloned();
247        if shape.len() != 4 {
248            return Err(ModuleError::InvalidRank {
249                module: "AdaptiveAvgPool2d",
250                expected: "4",
251                actual: shape.len(),
252            });
253        }
254        let (n, c, h, w) = (shape[0], shape[1], shape[2], shape[3]);
255        let (oh, ow) = (self.out_h, self.out_w);
256        if h == 0 || w == 0 || oh == 0 || ow == 0 {
257            return Err(ModuleError::ShapeMismatch {
258                module: "AdaptiveAvgPool2d",
259                parameter: "spatial input and output dimensions",
260                expected: vec![1; 4],
261                actual: vec![h, w, oh, ow],
262            });
263        }
264        let backend = B::default();
265
266        // Fast path for global (1×1) pooling: sequential mean_axis reductions
267        // avoid allocating the O(H*W) averaging matrix.
268        if oh == 1 && ow == 1 {
269            let after_h = coeus_autograd::mean_axis(input, 2)?; // [N, C, 1, W]
270            return Ok(coeus_autograd::mean_axis(&after_h, 3)?); // [N, C, 1, 1]
271        }
272
273        // Pool W: [N, C, H, W] -> [N*C*H, W] @ PW_T[W, OW] -> [N, C, H, OW].
274        let pw_t = avg_pool_matrix_t::<T, B>(w, ow, &backend)?;
275        let yw = coeus_autograd::matmul(&coeus_autograd::reshape(input, [n * c * h, w])?, &pw_t)?;
276        let yw = coeus_autograd::reshape(&yw, [n, c, h, ow])?;
277
278        // Pool H: bring H last, [N, C, OW, H] -> [N*C*OW, H] @ PH_T[H, OH].
279        let ph_t = avg_pool_matrix_t::<T, B>(h, oh, &backend)?;
280        let yw_p = coeus_autograd::permute(&yw, &[0, 1, 3, 2])?;
281        let yh = coeus_autograd::matmul(&coeus_autograd::reshape(&yw_p, [n * c * ow, h])?, &ph_t)?;
282        let yh = coeus_autograd::reshape(&yh, [n, c, ow, oh])?;
283        // Final transpose to [N, C, OH, OW]; reshape materializes it contiguous.
284        let out = coeus_autograd::permute(&yh, &[0, 1, 3, 2])?;
285        Ok(coeus_autograd::reshape(&out, [n, c, oh, ow])?)
286    }
287}
288
289// ── AdaptiveMaxPool1d ─────────────────────────────────────────────────────────
290
291/// Adaptive max pooling for `[N, C, L]` → `[N, C, output_size]`.
292///
293/// Matches PyTorch `nn.AdaptiveMaxPool1d(output_size)`.
294#[derive(Clone, Debug)]
295pub struct AdaptiveMaxPool1d<T: Scalar, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
296    /// Target spatial output length.
297    output_size: usize,
298    _marker: PhantomData<(T, B)>,
299}
300
301impl<T: coeus_core::FloatElement + Scalar, B: coeus_ops::BackendOps<T> + Default>
302    AdaptiveMaxPool1d<T, B>
303{
304    /// Create an `AdaptiveMaxPool1d` with the given output size.
305    pub const fn new(output_size: usize) -> Self {
306        Self {
307            output_size,
308            _marker: PhantomData,
309        }
310    }
311}
312
313impl<
314        T: coeus_core::FloatElement + Float + coeus_cpu::RealScalar,
315        B: coeus_ops::BackendOps<T> + Default,
316    > Module<T, B> for AdaptiveMaxPool1d<T, B>
317where
318    B::DeviceBuffer<T>: CpuAddressableStorage<T> + CpuAddressableStorageMut<T>,
319{
320    fn parameters(&self) -> Vec<Var<T, B>> {
321        vec![]
322    }
323
324    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
325        // Direct region-maximum loop: one strided pass over the input with no
326        // [rows, out_len, in_len] broadcast intermediate (previously ~20ms on
327        // the standard fixture; COEUS-ADAPTIVE-MAX-POOL1D-PERF). Region maxima
328        // use strict `>`, so the first maximum wins; a NaN wins only when it
329        // is the first element of its region.
330        let shape = input.tensor.shape_cloned();
331        if shape.len() != 3 {
332            return Err(ModuleError::InvalidRank {
333                module: "AdaptiveMaxPool1d",
334                expected: "3",
335                actual: shape.len(),
336            });
337        }
338        let (n, c, l) = (shape[0], shape[1], shape[2]);
339        let o = self.output_size;
340        if l == 0 || o == 0 {
341            return Err(ModuleError::ShapeMismatch {
342                module: "AdaptiveMaxPool1d",
343                parameter: "spatial input and output dimensions",
344                expected: vec![1, 1],
345                actual: vec![l, o],
346            });
347        }
348        let backend = B::default();
349        // SAFETY: every output element is written by the loop below before the
350        // tensor is read.
351        let mut out_tensor = unsafe { Tensor::alloc_on([n, c, o], &backend) }?;
352        let (out_storage, out_layout) = out_tensor.storage_mut_and_layout()?;
353        let out_buf = out_storage.as_mut_slice()?;
354        let (out_off, out_st) = (out_layout.offset(), out_layout.strides());
355        let in_buf = input.tensor.storage().as_slice();
356        let in_layout = input.tensor.layout();
357        let (in_off, in_st) = (in_layout.offset(), in_layout.strides());
358        for n_i in 0..n {
359            for c_i in 0..c {
360                let in_base = in_off + n_i * in_st[0] + c_i * in_st[1];
361                let out_base = out_off + n_i * out_st[0] + c_i * out_st[1];
362                for o_i in 0..o {
363                    let (start, end) = coeus_autograd::ops::nn::pool::adaptive_region(o_i, l, o);
364                    let mut best = in_buf[in_base + start * in_st[2]];
365                    for i in (start + 1)..end {
366                        let v = in_buf[in_base + i * in_st[2]];
367                        if v > best {
368                            best = v;
369                        }
370                    }
371                    out_buf[out_base + o_i * out_st[2]] = best;
372                }
373            }
374        }
375        Ok(coeus_autograd::adaptive_max_pool1d(
376            input, out_tensor, l, o,
377        )?)
378    }
379}
380
381// ── AdaptiveMaxPool2d ─────────────────────────────────────────────────────────
382
383/// Adaptive max pooling for `[N, C, H, W]` → `[N, C, out_h, out_w]`.
384///
385/// Matches PyTorch `nn.AdaptiveMaxPool2d((out_h, out_w))`.
386#[derive(Clone, Debug)]
387pub struct AdaptiveMaxPool2d<T: Scalar, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
388    /// Target output height.
389    out_h: usize,
390    /// Target output width.
391    out_w: usize,
392    _marker: PhantomData<(T, B)>,
393}
394
395impl<T: coeus_core::FloatElement + Scalar, B: coeus_ops::BackendOps<T> + Default>
396    AdaptiveMaxPool2d<T, B>
397{
398    /// Create an `AdaptiveMaxPool2d` pooling to `(out_h, out_w)` output size.
399    pub const fn new(out_h: usize, out_w: usize) -> Self {
400        Self {
401            out_h,
402            out_w,
403            _marker: PhantomData,
404        }
405    }
406
407    /// Create an `AdaptiveMaxPool2d` pooling to a square `(size, size)` output.
408    pub const fn square(size: usize) -> Self {
409        Self::new(size, size)
410    }
411}
412
413impl<
414        T: coeus_core::FloatElement + Float + coeus_cpu::RealScalar,
415        B: coeus_ops::BackendOps<T> + Default,
416    > Module<T, B> for AdaptiveMaxPool2d<T, B>
417where
418    B::DeviceBuffer<T>: CpuAddressableStorage<T> + CpuAddressableStorageMut<T>,
419{
420    fn parameters(&self) -> Vec<Var<T, B>> {
421        vec![]
422    }
423
424    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
425        // Differentiable separable max pooling: max over W, then over H (max of a
426        // 2D region equals the max of per-axis maxes), each a masked max_axis.
427        let shape = input.tensor.shape_cloned();
428        if shape.len() != 4 {
429            return Err(ModuleError::InvalidRank {
430                module: "AdaptiveMaxPool2d",
431                expected: "4",
432                actual: shape.len(),
433            });
434        }
435        let (n, c, h, w) = (shape[0], shape[1], shape[2], shape[3]);
436        let (oh, ow) = (self.out_h, self.out_w);
437        if h == 0 || w == 0 || oh == 0 || ow == 0 {
438            return Err(ModuleError::ShapeMismatch {
439                module: "AdaptiveMaxPool2d",
440                parameter: "spatial input and output dimensions",
441                expected: vec![1; 4],
442                actual: vec![h, w, oh, ow],
443            });
444        }
445        let backend = B::default();
446
447        // Fast path for global (1×1) max pooling: sequential max_axis reductions.
448        if oh == 1 && ow == 1 {
449            let after_h = coeus_autograd::max_axis(input, 2)?; // [N, C, 1, W]
450            return Ok(coeus_autograd::max_axis(&after_h, 3)?); // [N, C, 1, 1]
451        }
452
453        // Pool W: [N, C, H, W] -> [N*C*H, W] -> [N*C*H, OW] -> [N, C, H, OW].
454        let xw = coeus_autograd::reshape(input, [n * c * h, w])?;
455        let pw = masked_adaptive_max::<T, B>(&xw, n * c * h, w, ow, &backend)?;
456        let yw = coeus_autograd::reshape(&pw, [n, c, h, ow])?;
457
458        // Pool H: bring H last, [N, C, OW, H] -> [N*C*OW, H] -> [N*C*OW, OH].
459        let yw_p = coeus_autograd::permute(&yw, &[0, 1, 3, 2])?;
460        let ph = masked_adaptive_max::<T, B>(
461            &coeus_autograd::reshape(&yw_p, [n * c * ow, h])?,
462            n * c * ow,
463            h,
464            oh,
465            &backend,
466        )?;
467        let yh = coeus_autograd::reshape(&ph, [n, c, ow, oh])?;
468        let out = coeus_autograd::permute(&yh, &[0, 1, 3, 2])?;
469        Ok(coeus_autograd::reshape(&out, [n, c, oh, ow])?)
470    }
471}