Skip to main content

coeus_nn/conv/
depthwise3d.rs

1//! Depthwise three-dimensional convolution.
2
3use super::{Conv3d, ConvParams};
4use crate::{Module, ModuleError};
5use coeus_autograd::{add, cat, reshape, slice, Var};
6use coeus_core::{CpuAddressableStorage, CpuAddressableStorageMut, Float, MoiraiBackend};
7use coeus_tensor::Tensor;
8
9/// Channel-independent 3-D convolution with one learned kernel per channel.
10#[derive(Clone)]
11pub struct DepthwiseConv3d<T: Float, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
12    /// Kernels with shape `[channels, 1, kernel, kernel, kernel]`.
13    pub weight: Var<T, B>,
14    /// Optional channel bias with shape `[channels]`.
15    pub bias: Option<Var<T, B>>,
16    /// Number of input and output channels.
17    pub channels: usize,
18    /// Isotropic kernel side length.
19    pub kernel_size: usize,
20    /// Isotropic stride.
21    pub stride: usize,
22    /// Symmetric zero padding.
23    pub padding: usize,
24    /// Isotropic kernel dilation.
25    pub dilation: usize,
26}
27
28impl<T, B> DepthwiseConv3d<T, B>
29where
30    T: Float + coeus_cpu::RealScalar,
31    B: coeus_ops::BackendOps<T> + Default,
32{
33    /// Construct a depthwise convolution with unit stride and dilation.
34    pub fn new(
35        channels: usize,
36        kernel_size: usize,
37        padding: usize,
38        bias: bool,
39    ) -> Result<Self, crate::init::InitializationError<B::Error>> {
40        Self::with_params(channels, kernel_size, 1, padding, 1, bias)
41    }
42
43    /// Construct a depthwise convolution with explicit spatial parameters.
44    pub fn with_params(
45        channels: usize,
46        kernel_size: usize,
47        stride: usize,
48        padding: usize,
49        dilation: usize,
50        bias: bool,
51    ) -> Result<Self, crate::init::InitializationError<B::Error>> {
52        assert!(channels > 0, "DepthwiseConv3d: channels must be positive");
53        assert!(stride > 0, "DepthwiseConv3d: stride must be positive");
54        assert!(dilation > 0, "DepthwiseConv3d: dilation must be positive");
55        let backend = B::default();
56        let bias = if bias {
57            Some(Var::new(Tensor::zeros_on([channels], &backend)?, true)?)
58        } else {
59            None
60        };
61        Ok(Self {
62            weight: Var::new(
63                Tensor::ones_on(
64                    [channels, 1, kernel_size, kernel_size, kernel_size],
65                    &backend,
66                )?,
67                true,
68            )?,
69            bias,
70            channels,
71            kernel_size,
72            stride,
73            padding,
74            dilation,
75        })
76    }
77}
78
79impl<T, B> Module<T, B> for DepthwiseConv3d<T, B>
80where
81    T: Float + coeus_cpu::RealScalar,
82    B: coeus_ops::BackendOps<T> + Default,
83    B::DeviceBuffer<T>: CpuAddressableStorage<T> + CpuAddressableStorageMut<T>,
84{
85    fn parameters(&self) -> Vec<Var<T, B>> {
86        let mut parameters = vec![self.weight.clone()];
87        parameters.extend(self.bias.iter().cloned());
88        parameters
89    }
90
91    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
92        let shape = input.tensor.shape();
93        if shape.len() != 5 {
94            return Err(ModuleError::InvalidRank {
95                module: "DepthwiseConv3d",
96                expected: "5",
97                actual: shape.len(),
98            });
99        }
100        if shape[1] != self.channels {
101            return Err(ModuleError::ChannelMismatch {
102                module: "DepthwiseConv3d",
103                expected: self.channels,
104                actual: shape[1],
105            });
106        }
107        let params = ConvParams::new(
108            1,
109            1,
110            self.kernel_size,
111            self.stride,
112            self.padding,
113            self.dilation,
114        );
115        let outputs = (0..self.channels)
116            .map(|channel| {
117                let channel_input = slice(
118                    input,
119                    &[
120                        (0, shape[0]),
121                        (channel, channel + 1),
122                        (0, shape[2]),
123                        (0, shape[3]),
124                        (0, shape[4]),
125                    ],
126                )?;
127                let channel_weight = slice(
128                    &self.weight,
129                    &[
130                        (channel, channel + 1),
131                        (0, 1),
132                        (0, self.kernel_size),
133                        (0, self.kernel_size),
134                        (0, self.kernel_size),
135                    ],
136                )?;
137                let output =
138                    Conv3d::from_vars(channel_weight, None, params).forward(&channel_input)?;
139                if let Some(bias) = &self.bias {
140                    let channel_bias =
141                        reshape(&slice(bias, &[(channel, channel + 1)])?, [1, 1, 1, 1, 1])?;
142                    Ok(add(&output, &channel_bias)?)
143                } else {
144                    Ok(output)
145                }
146            })
147            .collect::<Result<Vec<_>, ModuleError<B::Error>>>()?;
148        Ok(cat(&outputs.iter().collect::<Vec<_>>(), 1)?)
149    }
150
151    fn load_parameters(&mut self, parameters: &[Var<T, B>]) {
152        self.weight = parameters[0].clone();
153        if self.bias.is_some() {
154            self.bias = Some(parameters[1].clone());
155        }
156    }
157}
158
159#[cfg(test)]
160mod tests {
161    use super::*;
162    use coeus_core::MoiraiBackend;
163
164    #[test]
165    fn applies_independent_channel_kernels_and_gradients() -> Result<(), Box<dyn std::error::Error>>
166    {
167        let backend = MoiraiBackend::new();
168        let mut convolution = DepthwiseConv3d::<f32>::new(2, 1, 0, true)?;
169        convolution.weight = Var::new(
170            Tensor::from_slice_on([2, 1, 1, 1, 1], &[2.0, 3.0], &backend)?,
171            true,
172        )?;
173        convolution.bias = Some(Var::new(
174            Tensor::from_slice_on([2], &[1.0, -1.0], &backend)?,
175            true,
176        )?);
177        let input = Var::new(
178            Tensor::from_slice_on([1, 2, 1, 1, 2], &[4.0, 5.0, 6.0, 7.0], &backend)?,
179            true,
180        )?;
181
182        let output = convolution
183            .forward(&input)
184            .expect("valid DepthwiseConv3d input");
185
186        assert_eq!(output.tensor.shape(), &[1, 2, 1, 1, 2]);
187        assert_eq!(output.tensor.as_slice(), &[9.0, 11.0, 17.0, 20.0]);
188        output
189            .backward()
190            .expect("invariant: valid autograd fixture completes backward");
191        assert_eq!(
192            input.grad().expect("input gradient").as_slice(),
193            &[2.0, 2.0, 3.0, 3.0]
194        );
195        assert!(convolution.weight.grad().is_some());
196        assert!(convolution
197            .bias
198            .as_ref()
199            .expect("bias enabled")
200            .grad()
201            .is_some());
202        Ok(())
203    }
204}