burn_nn/modules/conv/
conv2d.rs

1use alloc::format;
2
3use burn_core as burn;
4
5use crate::PaddingConfig2d;
6use burn::config::Config;
7use burn::module::Initializer;
8use burn::module::{Content, DisplaySettings, Ignored, Module, ModuleDisplay, Param};
9use burn::tensor::Tensor;
10use burn::tensor::backend::Backend;
11use burn::tensor::module::conv2d;
12use burn::tensor::ops::ConvOptions;
13
14use crate::conv::checks;
15
16/// Configuration to create a [2D convolution](Conv2d) layer, using the [init function](Conv2dConfig::init).
17#[derive(Config, Debug)]
18pub struct Conv2dConfig {
19    /// The number of channels.
20    pub channels: [usize; 2],
21    /// The size of the kernel.
22    pub kernel_size: [usize; 2],
23    /// The stride of the convolution.
24    #[config(default = "[1, 1]")]
25    pub stride: [usize; 2],
26    /// Spacing between kernel elements.
27    #[config(default = "[1, 1]")]
28    pub dilation: [usize; 2],
29    /// Controls the connections between input and output channels.
30    #[config(default = "1")]
31    pub groups: usize,
32    /// The padding configuration.
33    ///
34    /// ### Warning
35    /// Only symmetric padding is currently supported. As such, using `Same` padding with an even kernel
36    /// size is not supported as it will not produce the same output size.
37    #[config(default = "PaddingConfig2d::Valid")]
38    pub padding: PaddingConfig2d,
39    /// If bias should be added to the output.
40    #[config(default = true)]
41    pub bias: bool,
42    /// The type of function used to initialize neural network parameters
43    #[config(
44        default = "Initializer::KaimingUniform{gain:1.0/num_traits::Float::sqrt(3.0),fan_out_only:false}"
45    )]
46    pub initializer: Initializer,
47}
48
49/// Applies a 2D convolution over input tensors.
50///
51/// Should be created with [Conv2dConfig].
52#[derive(Module, Debug)]
53#[module(custom_display)]
54pub struct Conv2d<B: Backend> {
55    /// Tensor of shape `[channels_out, channels_in / groups, kernel_size_1, kernel_size_2]`
56    pub weight: Param<Tensor<B, 4>>,
57    /// Tensor of shape `[channels_out]`
58    pub bias: Option<Param<Tensor<B, 1>>>,
59    /// Stride of the convolution.
60    pub stride: [usize; 2],
61    /// Size of the kernel.
62    pub kernel_size: [usize; 2],
63    /// Spacing between kernel elements.
64    pub dilation: [usize; 2],
65    /// Controls the connections between input and output channels.
66    pub groups: usize,
67    /// The padding configuration.
68    pub padding: Ignored<PaddingConfig2d>,
69}
70
71impl Conv2dConfig {
72    /// Initialize a new [conv2d](Conv2d) module.
73    pub fn init<B: Backend>(&self, device: &B::Device) -> Conv2d<B> {
74        checks::checks_channels_div_groups(self.channels[0], self.channels[1], self.groups);
75        if self.padding == PaddingConfig2d::Same {
76            checks::check_same_padding_support(&self.kernel_size);
77        }
78
79        let shape = [
80            self.channels[1],
81            self.channels[0] / self.groups,
82            self.kernel_size[0],
83            self.kernel_size[1],
84        ];
85
86        let k = self.kernel_size.iter().product::<usize>();
87        let fan_in = self.channels[0] / self.groups * k;
88        let fan_out = self.channels[1] / self.groups * k;
89
90        let weight = self
91            .initializer
92            .init_with(shape, Some(fan_in), Some(fan_out), device);
93        let mut bias = None;
94
95        if self.bias {
96            bias = Some(self.initializer.init_with(
97                [self.channels[1]],
98                Some(fan_in),
99                Some(fan_out),
100                device,
101            ));
102        }
103
104        Conv2d {
105            weight,
106            bias,
107            stride: self.stride,
108            kernel_size: self.kernel_size,
109            dilation: self.dilation,
110            padding: Ignored(self.padding.clone()),
111            groups: self.groups,
112        }
113    }
114}
115
116impl<B: Backend> ModuleDisplay for Conv2d<B> {
117    fn custom_settings(&self) -> Option<DisplaySettings> {
118        DisplaySettings::new()
119            .with_new_line_after_attribute(false)
120            .optional()
121    }
122
123    fn custom_content(&self, content: Content) -> Option<Content> {
124        // Since padding does not implement ModuleDisplay, we need to format it manually.
125        let padding_formatted = format!("{}", &self.padding);
126
127        // Format the stride, kernel_size and dilation as strings, formatted as arrays instead of indexed.
128        let stride = format!("{:?}", self.stride);
129        let kernel_size = format!("{:?}", self.kernel_size);
130        let dilation = format!("{:?}", self.dilation);
131        let [channels_out, group_channels_in, _, _] = self.weight.dims();
132        let channels_in = group_channels_in * self.groups;
133        let ch_out = format!("{:?}", channels_out);
134        let ch_in = format!("{:?}", channels_in);
135        content
136            .add("ch_in", &ch_in)
137            .add("ch_out", &ch_out)
138            .add("stride", &stride)
139            .add("kernel_size", &kernel_size)
140            .add("dilation", &dilation)
141            .add("groups", &self.groups)
142            .add("padding", &padding_formatted)
143            .optional()
144    }
145}
146
147impl<B: Backend> Conv2d<B> {
148    /// Applies the forward pass on the input tensor.
149    ///
150    /// See [conv2d](burn::tensor::module::conv2d) for more information.
151    ///
152    /// # Shapes
153    /// - `input`: `[batch_size, channels_in, height_in, width_in]`
154    /// - `output`: `[batch_size, channels_out, height_out, width_out]`
155    ///
156    /// # Example
157    /// ```rust,ignore
158    /// use burn::nn::conv::Conv2dConfig;
159    /// use burn::tensor::Tensor;
160    ///
161    /// // Assuming backend type alias `B`
162    /// let device = Default::default();
163    /// let conv = Conv2dConfig::new([3, 8], [3, 3]).init::<B>(&device);
164    ///
165    /// let x = Tensor::<B, 4>::zeros([1, 3, 28, 28], &device);
166    /// let y = conv.forward(x);
167    ///
168    /// println!("{:?}", y.dims()); // [1, 8, 26, 26]
169    /// ```
170    pub fn forward(&self, input: Tensor<B, 4>) -> Tensor<B, 4> {
171        let [_batch_size, _channels_in, height_in, width_in] = input.dims();
172        let padding =
173            self.padding
174                .calculate_padding_2d(height_in, width_in, &self.kernel_size, &self.stride);
175        conv2d(
176            input,
177            self.weight.val(),
178            self.bias.as_ref().map(|bias| bias.val()),
179            ConvOptions::new(self.stride, padding, self.dilation, self.groups),
180        )
181    }
182}
183
184#[cfg(test)]
185mod tests {
186    use burn::tensor::ops::FloatElem;
187    use burn::tensor::{ElementConversion, Tolerance};
188
189    use super::*;
190    use crate::TestBackend;
191    use burn::tensor::TensorData;
192    type FT = FloatElem<TestBackend>; // Float test
193
194    #[test]
195    fn initializer_default() {
196        let device = Default::default();
197        TestBackend::seed(&device, 0);
198
199        let config = Conv2dConfig::new([5, 1], [5, 5]);
200        let k = (config.channels[0] * config.kernel_size[0] * config.kernel_size[1]) as f64;
201        let k = (config.groups as f64 / k).sqrt().elem::<FT>();
202        let conv = config.init::<TestBackend>(&device);
203
204        conv.weight.to_data().assert_within_range(-k..k);
205    }
206
207    #[test]
208    fn initializer_zeros() {
209        let device = Default::default();
210        TestBackend::seed(&device, 0);
211
212        let config = Conv2dConfig::new([5, 2], [5, 5]).with_initializer(Initializer::Zeros);
213        let conv = config.init::<TestBackend>(&device);
214
215        assert_eq!(config.initializer, Initializer::Zeros);
216        conv.weight.to_data().assert_approx_eq::<FT>(
217            &TensorData::zeros::<FT, _>(conv.weight.shape()),
218            Tolerance::default(),
219        );
220    }
221
222    #[test]
223    fn initializer_fan_out() {
224        let device = Default::default();
225        TestBackend::seed(&device, 0);
226
227        let init = Initializer::KaimingUniform {
228            gain: 1.0 / 3.0f64.sqrt(),
229            fan_out_only: true, // test that fan_out is passed to `init_with()`
230        };
231
232        let config = Conv2dConfig::new([5, 1], [5, 5]).with_initializer(init.clone());
233        let _ = config.init::<TestBackend>(&device);
234
235        assert_eq!(config.initializer, init);
236    }
237
238    #[test]
239    fn initializer_fan_with_groups_is_valid() {
240        let device = Default::default();
241        TestBackend::seed(&device, 0);
242
243        let init = Initializer::KaimingUniform {
244            gain: 1.0 / 3.0f64.sqrt(),
245            fan_out_only: true,
246        };
247
248        let config = Conv2dConfig::new([4, 4], [1, 1])
249            .with_initializer(init.clone())
250            .with_groups(4);
251        let _ = config.init::<TestBackend>(&device);
252
253        assert_eq!(config.initializer, init);
254    }
255
256    #[test]
257    #[should_panic = "Both channels must be divisible by the number of groups."]
258    fn channels_with_groups_is_invalid() {
259        let device = Default::default();
260        let config = Conv2dConfig::new([1, 4], [1, 1]).with_groups(4);
261        let _ = config.init::<TestBackend>(&device);
262    }
263
264    #[test]
265    #[should_panic = "Same padding with an even kernel size is not supported"]
266    fn same_with_even_kernel_is_invalid() {
267        let device = Default::default();
268        let config = Conv2dConfig::new([4, 4], [2, 2]).with_padding(PaddingConfig2d::Same);
269        let _ = config.init::<TestBackend>(&device);
270    }
271
272    #[test]
273    fn display() {
274        let config = Conv2dConfig::new([5, 1], [5, 5]);
275        let conv = config.init::<TestBackend>(&Default::default());
276
277        assert_eq!(
278            alloc::format!("{conv}"),
279            "Conv2d {ch_in: 5, ch_out: 1, stride: [1, 1], kernel_size: [5, 5], dilation: [1, 1], groups: 1, padding: Valid, params: 126}"
280        );
281    }
282
283    #[test]
284    #[should_panic = "Number of channels in input tensor and input channels of convolution must be equal. got: 4, expected: 5"]
285    fn input_channels_mismatch() {
286        let config = Conv2dConfig::new([5, 3], [3, 3]);
287        let conv = config.init::<TestBackend>(&Default::default());
288
289        let input = Tensor::<TestBackend, 4>::zeros([1, 4, 10, 10], &Default::default());
290        let _ = conv.forward(input);
291    }
292}
burn_nn/modules/conv/conv2d.rs

burn_nn/modules/conv/
conv2d.rs
