Skip to main content

coeus_nn/conv/
conv_transpose.rs

1//! Generic N-dimensional transposed (fractional-stride) convolution.
2//!
3//! [`ConvTranspose`] is the single implementation behind the
4//! `ConvTranspose1d`/`ConvTranspose2d`/`ConvTranspose3d` aliases. The spatial
5//! rank is a const parameter rather than a `ConvDim` marker: const generics
6//! need no `PhantomData`, so `ConvTranspose1d::<f64, B> { .. }` struct-literal
7//! construction keeps working unchanged, and it agrees with the `const DIM`
8//! idiom already used by `coeus-autograd`'s batch-norm nodes.
9
10use crate::module::{Module, ModuleError};
11use coeus_autograd::Var;
12use coeus_core::{Float, MoiraiBackend, Scalar};
13use coeus_tensor::Tensor;
14
15/// Transposed-convolution weight shape `[C_in, C_out, k...]`.
16fn weight_shape<const DIM: usize>(
17    in_channels: usize,
18    out_channels: usize,
19    kernel_size: usize,
20) -> Vec<usize> {
21    let mut shape = Vec::with_capacity(2 + DIM);
22    shape.push(in_channels);
23    shape.push(out_channels);
24    shape.extend(std::iter::repeat_n(kernel_size, DIM));
25    shape
26}
27
28/// Diagnostic module name for a given spatial rank.
29const fn module_name<const DIM: usize>() -> &'static str {
30    match DIM {
31        1 => "ConvTranspose1d",
32        2 => "ConvTranspose2d",
33        3 => "ConvTranspose3d",
34        _ => "ConvTransposeNd",
35    }
36}
37
38/// Expected-rank description for the rank check.
39const fn rank_str<const DIM: usize>() -> &'static str {
40    match DIM {
41        1 => "3",
42        2 => "4",
43        3 => "5",
44        _ => "configured transposed-convolution rank",
45    }
46}
47
48/// N-dimensional Transposed Convolution parameterised over spatial rank `DIM`.
49///
50/// Weight convention: `[C_in, C_out, k...]` (groups=1; the in/out channel order
51/// is reversed relative to the regular [`crate::conv::Conv`]). Prefer the
52/// `ConvTranspose1d`/`ConvTranspose2d`/`ConvTranspose3d` aliases.
53#[derive(Clone)]
54pub struct ConvTranspose<
55    T: Scalar,
56    B: coeus_ops::BackendOps<T> + Default = MoiraiBackend,
57    const DIM: usize = 1,
58> {
59    /// Transposed convolution weight: `[in_channels, out_channels, k...]`.
60    pub weight: Var<T, B>,
61    /// Optional bias: `[out_channels]`.
62    pub bias: Option<Var<T, B>>,
63    /// Number of input channels.
64    pub in_channels: usize,
65    /// Number of output channels.
66    pub out_channels: usize,
67    /// Isotropic kernel side length.
68    pub kernel_size: usize,
69    /// Stride (upsampling factor).
70    pub stride: usize,
71    /// Input-side zero-padding removed from the output.
72    pub padding: usize,
73    /// Extra output size added to one side to resolve output-size ambiguity.
74    pub output_padding: usize,
75    /// Spacing between kernel elements.
76    pub dilation: usize,
77}
78
79impl<T: Float, B: coeus_ops::BackendOps<T> + Default, const DIM: usize> ConvTranspose<T, B, DIM> {
80    /// Create with default stride=1, padding=0, output_padding=0, dilation=1.
81    ///
82    /// # Errors
83    ///
84    /// Returns a typed error when the fan is invalid or the selected backend
85    /// cannot initialize the weight.
86    pub fn new(
87        in_channels: usize,
88        out_channels: usize,
89        kernel_size: usize,
90        bias: bool,
91    ) -> Result<Self, crate::init::InitializationError<B::Error>>
92    where
93        T: coeus_cpu::RealScalar,
94        B: coeus_ops::RandomInitOps<T>,
95    {
96        Self::with_params(in_channels, out_channels, kernel_size, 1, 0, 0, 1, bias)
97    }
98
99    /// Create with explicit hyperparameters.
100    ///
101    /// # Errors
102    ///
103    /// Returns a typed error when the fan is invalid or the selected backend
104    /// cannot initialize the weight.
105    #[expect(clippy::too_many_arguments, reason = "transposed convolution contract")]
106    pub fn with_params(
107        in_channels: usize,
108        out_channels: usize,
109        kernel_size: usize,
110        stride: usize,
111        padding: usize,
112        output_padding: usize,
113        dilation: usize,
114        bias: bool,
115    ) -> Result<Self, crate::init::InitializationError<B::Error>>
116    where
117        T: coeus_cpu::RealScalar,
118        B: coeus_ops::RandomInitOps<T>,
119    {
120        let backend = B::default();
121        // Weight: [C_in, C_out, k...] — transposed convention.
122        let w_shape = weight_shape::<DIM>(in_channels, out_channels, kernel_size);
123        let w_tensor = Tensor::ones_on(w_shape, &backend)?;
124        let mut weight = Var::new(w_tensor, true)?;
125        crate::init::kaiming_uniform(&mut weight, in_channels)?;
126        let bias_var = if bias {
127            Some(Var::new(Tensor::zeros_on([out_channels], &backend)?, true)?)
128        } else {
129            None
130        };
131        Ok(Self {
132            weight,
133            bias: bias_var,
134            in_channels,
135            out_channels,
136            kernel_size,
137            stride,
138            padding,
139            output_padding,
140            dilation,
141        })
142    }
143}
144
145// ── Rank-specific output-size helpers ──
146//
147// One inherent impl per rank keeps each alias's method surface exactly what it
148// was before the merge (`output_len` for 1-D; `output_dims` for 2-D and 3-D).
149
150impl<T: Float, B: coeus_ops::BackendOps<T> + Default> ConvTranspose<T, B, 1> {
151    /// Compute the output length for a given input length.
152    pub fn output_len(&self, l: usize) -> usize {
153        coeus_ops::conv_transpose::conv_transpose1d_output_len(
154            l,
155            self.kernel_size,
156            self.stride,
157            self.padding,
158            self.output_padding,
159            self.dilation,
160        )
161    }
162}
163
164impl<T: Float, B: coeus_ops::BackendOps<T> + Default> ConvTranspose<T, B, 2> {
165    /// Compute the output spatial dimensions for a given input shape.
166    pub fn output_dims(&self, h: usize, w: usize) -> (usize, usize) {
167        coeus_ops::conv_transpose::conv_transpose2d_output_dims(
168            h,
169            w,
170            self.kernel_size,
171            self.kernel_size,
172            self.stride,
173            self.padding,
174            self.output_padding,
175            self.dilation,
176        )
177    }
178}
179
180impl<T: Float, B: coeus_ops::BackendOps<T> + Default> ConvTranspose<T, B, 3> {
181    /// Compute the output spatial dimensions for a given input shape.
182    pub fn output_dims(&self, d: usize, h: usize, w: usize) -> (usize, usize, usize) {
183        coeus_ops::conv_transpose::conv_transpose3d_output_dims(
184            d,
185            h,
186            w,
187            self.kernel_size,
188            self.kernel_size,
189            self.kernel_size,
190            self.stride,
191            self.padding,
192            self.output_padding,
193            self.dilation,
194        )
195    }
196}
197
198impl<T: Float, B: coeus_ops::BackendOps<T> + Default, const DIM: usize> Module<T, B>
199    for ConvTranspose<T, B, DIM>
200where
201    T: coeus_cpu::RealScalar,
202{
203    fn parameters(&self) -> Vec<Var<T, B>> {
204        let mut p = vec![self.weight.clone()];
205        if let Some(ref b) = self.bias {
206            p.push(b.clone());
207        }
208        p
209    }
210
211    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
212        let module: &str = module_name::<DIM>();
213        let backend = B::default();
214        let shape = input.tensor.shape();
215        if shape.len() != DIM + 2 {
216            return Err(ModuleError::InvalidRank {
217                module,
218                expected: rank_str::<DIM>(),
219                actual: shape.len(),
220            });
221        }
222        if shape[1] != self.in_channels {
223            return Err(ModuleError::ChannelMismatch {
224                module,
225                expected: self.in_channels,
226                actual: shape[1],
227            });
228        }
229        let n = shape[0];
230        let out_spatial: Vec<usize> = match DIM {
231            1 => vec![coeus_ops::conv_transpose::conv_transpose1d_output_len(
232                shape[2],
233                self.kernel_size,
234                self.stride,
235                self.padding,
236                self.output_padding,
237                self.dilation,
238            )],
239            2 => {
240                let (h_out, w_out) = coeus_ops::conv_transpose::conv_transpose2d_output_dims(
241                    shape[2],
242                    shape[3],
243                    self.kernel_size,
244                    self.kernel_size,
245                    self.stride,
246                    self.padding,
247                    self.output_padding,
248                    self.dilation,
249                );
250                vec![h_out, w_out]
251            }
252            3 => {
253                let (d_out, h_out, w_out) = coeus_ops::conv_transpose::conv_transpose3d_output_dims(
254                    shape[2],
255                    shape[3],
256                    shape[4],
257                    self.kernel_size,
258                    self.kernel_size,
259                    self.kernel_size,
260                    self.stride,
261                    self.padding,
262                    self.output_padding,
263                    self.dilation,
264                );
265                vec![d_out, h_out, w_out]
266            }
267            _ => panic!("ConvTranspose: unsupported DIM {DIM}"),
268        };
269        let mut out_shape = Vec::with_capacity(2 + DIM);
270        out_shape.push(n);
271        out_shape.push(self.out_channels);
272        out_shape.extend_from_slice(&out_spatial);
273
274        let mut out_tensor = Tensor::zeros_on(out_shape, &backend)?;
275        let (out_storage, out_layout) = out_tensor.storage_mut_and_layout()?;
276        let dispatch = match DIM {
277            1 => backend.conv_transpose1d(
278                input.tensor.storage(),
279                input.tensor.layout(),
280                self.weight.tensor.storage(),
281                self.weight.tensor.layout(),
282                self.bias.as_ref().map(|b| b.tensor.storage()),
283                self.stride,
284                self.padding,
285                self.output_padding,
286                self.dilation,
287                out_storage,
288                out_layout,
289            ),
290            2 => backend.conv_transpose2d(
291                input.tensor.storage(),
292                input.tensor.layout(),
293                self.weight.tensor.storage(),
294                self.weight.tensor.layout(),
295                self.bias.as_ref().map(|b| b.tensor.storage()),
296                self.stride,
297                self.padding,
298                self.output_padding,
299                self.dilation,
300                out_storage,
301                out_layout,
302            ),
303            3 => backend.conv_transpose3d(
304                input.tensor.storage(),
305                input.tensor.layout(),
306                self.weight.tensor.storage(),
307                self.weight.tensor.layout(),
308                self.bias.as_ref().map(|b| b.tensor.storage()),
309                self.stride,
310                self.padding,
311                self.output_padding,
312                self.dilation,
313                out_storage,
314                out_layout,
315            ),
316            _ => panic!("ConvTranspose: unsupported DIM {DIM}"),
317        };
318        dispatch.map_err(|source| ModuleError::Backend { module, source })?;
319
320        Ok(match DIM {
321            1 => coeus_autograd::conv_transpose1d(
322                input,
323                &self.weight,
324                &self.bias,
325                out_tensor,
326                self.stride,
327                self.padding,
328                self.output_padding,
329                self.dilation,
330            )?,
331            2 => coeus_autograd::conv_transpose2d(
332                input,
333                &self.weight,
334                &self.bias,
335                out_tensor,
336                self.stride,
337                self.padding,
338                self.output_padding,
339                self.dilation,
340            )?,
341            3 => coeus_autograd::conv_transpose3d(
342                input,
343                &self.weight,
344                &self.bias,
345                out_tensor,
346                self.stride,
347                self.padding,
348                self.output_padding,
349                self.dilation,
350            )?,
351            _ => panic!("ConvTranspose: unsupported DIM {DIM}"),
352        })
353    }
354}