Skip to main content

coeus_nn/conv/
conv_nd.rs

1use super::dim::{ConvDim, ConvDispatch};
2use crate::module::{Module, ModuleError};
3use coeus_autograd::Var;
4use coeus_core::{Float, MoiraiBackend, Scalar};
5use coeus_tensor::Tensor;
6use std::marker::PhantomData;
7
8/// Generic convolution layer parameterised over spatial dimensionality `D`.
9///
10/// Use the type aliases [`crate::conv::Conv1d`], [`crate::conv::Conv2d`],
11/// [`crate::conv::Conv3d`] for concrete dimensions rather than naming this type directly.
12#[derive(Clone)]
13pub struct Conv<
14    T: Scalar,
15    B: coeus_ops::BackendOps<T> + Default = MoiraiBackend,
16    D: ConvDim = super::dim::Dim2D,
17> {
18    /// Learned projection weight `[out_channels, in_channels, k...]`.
19    pub weight: Var<T, B>,
20    /// Optional learned bias `[out_channels]`.
21    pub bias: Option<Var<T, B>>,
22    /// Number of input feature channels.
23    pub in_channels: usize,
24    /// Number of output feature channels.
25    pub out_channels: usize,
26    /// Isotropic kernel side length.
27    pub kernel_size: usize,
28    /// Isotropic convolution stride.
29    pub stride: usize,
30    /// Zero-padding applied symmetrically to each spatial side.
31    pub padding: usize,
32    /// Spacing between kernel elements (à trous / dilated convolution).
33    pub dilation: usize,
34    _dim: PhantomData<D>,
35}
36
37/// Dimension-independent convolution hyperparameters.
38#[derive(Clone, Copy, Debug, Eq, PartialEq)]
39pub struct ConvParams {
40    /// Number of input feature channels.
41    pub in_channels: usize,
42    /// Number of output feature channels.
43    pub out_channels: usize,
44    /// Isotropic kernel side length.
45    pub kernel_size: usize,
46    /// Isotropic convolution stride.
47    pub stride: usize,
48    /// Zero-padding applied symmetrically to each spatial side.
49    pub padding: usize,
50    /// Spacing between kernel elements (à trous / dilated convolution).
51    pub dilation: usize,
52}
53
54impl ConvParams {
55    /// Construct convolution parameters after validating positive stride and dilation.
56    ///
57    /// # Panics
58    /// Panics if `stride == 0` or `dilation == 0`.
59    pub fn new(
60        in_channels: usize,
61        out_channels: usize,
62        kernel_size: usize,
63        stride: usize,
64        padding: usize,
65        dilation: usize,
66    ) -> Self {
67        assert!(
68            stride >= 1 && dilation >= 1,
69            "stride and dilation must be >= 1"
70        );
71        Self {
72            in_channels,
73            out_channels,
74            kernel_size,
75            stride,
76            padding,
77            dilation,
78        }
79    }
80}
81
82impl<T: Scalar, B: coeus_ops::BackendOps<T> + Default, D: ConvDim> Conv<T, B, D> {
83    /// Construct with default stride=1, padding=0, dilation=1.
84    pub fn new(
85        in_channels: usize,
86        out_channels: usize,
87        kernel_size: usize,
88        bias: bool,
89    ) -> Result<Self, crate::init::InitializationError<B::Error>> {
90        Self::with_params(in_channels, out_channels, kernel_size, 1, 0, 1, bias)
91    }
92
93    /// Construct with explicit hyperparameters.
94    pub fn with_params(
95        in_channels: usize,
96        out_channels: usize,
97        kernel_size: usize,
98        stride: usize,
99        padding: usize,
100        dilation: usize,
101        bias: bool,
102    ) -> Result<Self, crate::init::InitializationError<B::Error>> {
103        let params = ConvParams::new(
104            in_channels,
105            out_channels,
106            kernel_size,
107            stride,
108            padding,
109            dilation,
110        );
111        let backend = B::default();
112        let w_shape = D::weight_shape(params.out_channels, params.in_channels, params.kernel_size);
113        let weight = Var::new(Tensor::ones_on(w_shape, &backend)?, true)?;
114        let bias_var = if bias {
115            Some(Var::new(
116                Tensor::zeros_on([params.out_channels], &backend)?,
117                true,
118            )?)
119        } else {
120            None
121        };
122        Ok(Self::from_vars(weight, bias_var, params))
123    }
124
125    /// Construct directly from existing weight and bias variables.
126    ///
127    /// Used by PyO3 bindings that build `Var`s from Python-supplied tensors.
128    pub fn from_vars(weight: Var<T, B>, bias: Option<Var<T, B>>, params: ConvParams) -> Self {
129        Self {
130            weight,
131            bias,
132            in_channels: params.in_channels,
133            out_channels: params.out_channels,
134            kernel_size: params.kernel_size,
135            stride: params.stride,
136            padding: params.padding,
137            dilation: params.dilation,
138            _dim: PhantomData,
139        }
140    }
141
142    #[inline]
143    fn k_eff(&self) -> usize {
144        self.dilation * (self.kernel_size - 1) + 1
145    }
146}
147
148impl<T: Float, B: coeus_ops::BackendOps<T> + Default, D: ConvDim> Module<T, B> for Conv<T, B, D> {
149    fn parameters(&self) -> Vec<Var<T, B>> {
150        let mut p = vec![self.weight.clone()];
151        if let Some(ref b) = self.bias {
152            p.push(b.clone());
153        }
154        p
155    }
156
157    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
158        let backend = B::default();
159        let shape = input.tensor.shape();
160        let expected_rank = D::SPATIAL_RANK + 2;
161        if shape.len() != expected_rank {
162            return Err(ModuleError::InvalidRank {
163                module: "Conv",
164                expected: match expected_rank {
165                    3 => "3",
166                    4 => "4",
167                    5 => "5",
168                    _ => "configured convolution rank",
169                },
170                actual: shape.len(),
171            });
172        }
173        if shape[1] != self.in_channels {
174            return Err(ModuleError::ChannelMismatch {
175                module: "Conv",
176                expected: self.in_channels,
177                actual: shape[1],
178            });
179        }
180        let in_spatial = &shape[2..];
181        let k_eff = self.k_eff();
182        let out_sp = D::out_spatial(in_spatial, k_eff, self.stride, self.padding);
183        if out_sp.contains(&0) {
184            return Err(ModuleError::ShapeMismatch {
185                module: "Conv",
186                parameter: "output spatial dimensions",
187                expected: vec![1; D::SPATIAL_RANK],
188                actual: out_sp,
189            });
190        }
191        let out_shape = D::output_shape(shape[0], self.out_channels, &out_sp);
192        let mut out_tensor = Tensor::zeros_on(out_shape, &backend)?;
193        {
194            let (out_storage, out_layout) = out_tensor.storage_mut_and_layout()?;
195            D::backend_conv(ConvDispatch {
196                backend: &backend,
197                input_buf: input.tensor.storage(),
198                input_layout: input.tensor.layout(),
199                weight_buf: self.weight.tensor.storage(),
200                weight_layout: self.weight.tensor.layout(),
201                bias: self.bias.as_ref().map(|b| b.tensor.storage()),
202                stride: self.stride,
203                padding: self.padding,
204                dilation: self.dilation,
205                out_buf: out_storage,
206                out_layout,
207            })
208            .map_err(|source| ModuleError::Backend {
209                module: "Conv",
210                source,
211            })?;
212        }
213        Ok(D::autograd_conv(
214            input,
215            &self.weight,
216            &self.bias,
217            out_tensor,
218            self.stride,
219            self.padding,
220            self.dilation,
221        )?)
222    }
223}