Skip to main content

coeus_nn/conv/unfold_fold/
unfold1d.rs

1use super::validation::{checked_output_dim, invalid_window};
2use crate::module::{Module, ModuleError};
3use coeus_autograd::Var;
4use coeus_core::{MoiraiBackend, Scalar};
5use std::marker::PhantomData;
6
7/// Extracts sliding windows from `[N, C, L]` into `[N, C*kernel_size, L_out]`.
8///
9/// Stateless module with no learnable parameters. Matches PyTorch `nn.Unfold` in 1D.
10///
11/// # Shape
12/// - Input:  `[N, C, L]`
13/// - Output: `[N, C * kernel_size, L_out]`
14///   where `L_out = (L + 2*padding - dilation*(kernel_size-1) - 1) / stride + 1`
15///
16/// # Examples
17///
18/// ```
19/// use coeus_nn::{Unfold1d, Module};
20/// use coeus_autograd::Var;
21/// use coeus_tensor::Tensor;
22/// use coeus_core::SequentialBackend;
23///
24/// let m = Unfold1d::<f32, SequentialBackend>::new(3, 1, 0, 1);
25/// let x = Var::new(
26///     Tensor::<f32, SequentialBackend>::ones([1, 2, 5])
27///         .expect("invariant: example shape allocation succeeds"),
28///     false,
29/// ).expect("invariant: constant example variable needs no gradient buffer");
30/// let y = m.forward(&x).expect("valid Unfold1d input");
31/// assert_eq!(y.tensor.shape(), &[1, 6, 3]);
32/// ```
33#[derive(Clone, Debug)]
34pub struct Unfold1d<T: Scalar, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
35    kernel_size: usize,
36    stride: usize,
37    padding: usize,
38    dilation: usize,
39    _marker: PhantomData<(T, B)>,
40}
41
42impl<T: Scalar, B: coeus_ops::BackendOps<T> + Default> Unfold1d<T, B> {
43    /// Create an `Unfold1d` with the given hyperparameters.
44    pub fn new(kernel_size: usize, stride: usize, padding: usize, dilation: usize) -> Self {
45        Self {
46            kernel_size,
47            stride,
48            padding,
49            dilation,
50            _marker: PhantomData,
51        }
52    }
53}
54
55impl<T: Scalar, B: coeus_ops::BackendOps<T> + Default> Module<T, B> for Unfold1d<T, B> {
56    fn parameters(&self) -> Vec<Var<T, B>> {
57        vec![]
58    }
59
60    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
61        let shape = input.tensor.shape();
62        if shape.len() != 3 {
63            return Err(ModuleError::InvalidRank {
64                module: "Unfold1d",
65                expected: "3",
66                actual: shape.len(),
67            });
68        }
69        let output = checked_output_dim(
70            shape[2],
71            self.kernel_size,
72            self.stride,
73            self.padding,
74            self.dilation,
75        )
76        .filter(|&output| output != 0)
77        .ok_or_else(|| {
78            invalid_window(
79                "Unfold1d",
80                "kernel, stride, padding, and dilation",
81                vec![
82                    shape[2],
83                    self.kernel_size,
84                    self.stride,
85                    self.padding,
86                    self.dilation,
87                ],
88            )
89        })?;
90        shape[1]
91            .checked_mul(self.kernel_size)
92            .and_then(|channels| channels.checked_mul(output))
93            .ok_or_else(|| {
94                invalid_window(
95                    "Unfold1d",
96                    "output element count",
97                    vec![shape[1], self.kernel_size, output],
98                )
99            })?;
100
101        coeus_autograd::unfold1d(
102            input,
103            self.kernel_size,
104            self.stride,
105            self.padding,
106            self.dilation,
107        )
108        .map_err(|source| ModuleError::Backend {
109            module: "Unfold1d",
110            source,
111        })
112    }
113}