Skip to main content

incin_core/nn/
conv2d.rs

1use crate::backend_authoring::SupportsDType;
2use crate::dist::Local;
3use crate::err::{Error, Result};
4use crate::exec::catalog::{Conv2dAttributes, op};
5use crate::exec::context::ExecutionContext;
6use crate::exec::request::TensorHandle;
7use crate::nn::init::{InitContext, ParameterRole};
8use crate::nn::param::{Frozen, TrainState, Trainable, execute_plan_raw};
9use crate::nn::{Module, Param};
10use crate::shapes::{Dim, Dyn, DynShape, Shape, ShapeBuf, ShapeError, ShapeValue};
11use crate::tensor::backend::Execute;
12use crate::tensor::base::Tensor;
13use crate::tensor::device::Device;
14use crate::tensor::dtype::DType;
15
16/// A shape marker trait specifying a [`Conv2d`] layer's channel counts and
17/// compile-time-fixed kernel/stride/padding/dilation. The typical usage is
18/// `(OutC, InC, K, S, P, D)` for a fully static, square-kernel layer.
19pub trait Conv2dShape: Shape + DynShape {
20    /// Number of output channels.
21    type OutC: Dim;
22    /// Number of input channels.
23    type InC: Dim;
24    /// Kernel (window) size - square, applied to both spatial dimensions.
25    type K: Dim<Arg = ()>;
26    /// Stride.
27    type S: Dim<Arg = ()>;
28    /// Padding.
29    type P: Dim<Arg = ()>;
30    /// Dilation.
31    type D: Dim<Arg = ()>;
32    /// The shape argument type used to construct the weight tensor.
33    type WeightArg: crate::tensor::arg_into::NotUnit;
34    /// The shape argument type used to construct the bias tensor.
35    type BiasArg: crate::tensor::arg_into::NotUnit;
36    /// The static shape type of the weight parameter tensor.
37    type WeightShape: Shape<Arg = Self::WeightArg> + DynShape;
38    /// The static shape type of the bias parameter tensor.
39    type BiasShape: Shape<Arg = Self::BiasArg> + DynShape;
40
41    /// Converts the target arguments into concrete shape args for weight and bias tensors.
42    fn build_args(
43        target: (<Self::OutC as Dim>::Arg, <Self::InC as Dim>::Arg),
44    ) -> core::result::Result<(usize, usize, Self::WeightArg, Self::BiasArg), ShapeError>;
45}
46
47impl<OutC: Dim, InC: Dim, K: Dim<Arg = ()>, S: Dim<Arg = ()>, P: Dim<Arg = ()>, D: Dim<Arg = ()>>
48    Conv2dShape
49    for crate::shapes::shape::DimCons<
50        OutC,
51        crate::shapes::shape::DimCons<
52            InC,
53            crate::shapes::shape::DimCons<
54                K,
55                crate::shapes::shape::DimCons<
56                    S,
57                    crate::shapes::shape::DimCons<
58                        P,
59                        crate::shapes::shape::DimCons<D, crate::shapes::shape::Nil>,
60                    >,
61                >,
62            >,
63        >,
64    >
65{
66    type OutC = OutC;
67    type InC = InC;
68    type K = K;
69    type S = S;
70    type P = P;
71    type D = D;
72    type WeightArg = (
73        <OutC as Dim>::Arg,
74        (<InC as Dim>::Arg, (<K as Dim>::Arg, (<K as Dim>::Arg, ()))),
75    );
76    type BiasArg = (<OutC as Dim>::Arg, ());
77    type WeightShape = crate::shapes::shape::DimCons<
78        OutC,
79        crate::shapes::shape::DimCons<
80            InC,
81            crate::shapes::shape::DimCons<
82                K,
83                crate::shapes::shape::DimCons<K, crate::shapes::shape::Nil>,
84            >,
85        >,
86    >;
87    type BiasShape = crate::shapes::shape::DimCons<OutC, crate::shapes::shape::Nil>;
88
89    #[inline]
90    fn build_args(
91        target: (<Self::OutC as Dim>::Arg, <Self::InC as Dim>::Arg),
92    ) -> core::result::Result<(usize, usize, Self::WeightArg, Self::BiasArg), ShapeError> {
93        let out_channels = OutC::resolve_arg(target.0.clone())?;
94        let in_channels = InC::resolve_arg(target.1.clone())?;
95        Ok((
96            out_channels,
97            in_channels,
98            (target.0.clone(), (target.1, ((), ((), ())))),
99            (target.0, ()),
100        ))
101    }
102}
103
104/// A 2D convolutional layer operating on 4D tensors of shape `[Batch, Channels, H, W]`.
105#[derive(Debug, Clone)]
106#[incin_macros::module(internal)]
107pub struct Conv2d<
108    S: Conv2dShape,
109    B: crate::tensor::backend::VariableBackend,
110    Bias: crate::nn::optional::OptionalField = crate::nn::optional::True,
111    K: DType = f32,
112    Train: TrainState = Trainable,
113> {
114    /// The learnable weight matrix parameter.
115    pub weight: Param<S::WeightShape, B, K, Train>,
116    /// The optional learnable bias vector parameter.
117    pub bias: Option<Param<S::BiasShape, B, K, Train>>,
118    #[module(ignore)]
119    _phantom: core::marker::PhantomData<(S, B, Bias, K, Train)>,
120}
121
122impl<
123    S: Conv2dShape,
124    B: crate::tensor::backend::VariableBackend,
125    Bias: crate::nn::optional::OptionalField,
126    K: DType,
127    Train: TrainState,
128> Conv2d<S, B, Bias, K, Train>
129{
130    /// Constructs a Conv2d from raw parts.
131    pub fn from_raw_parts(
132        weight: Param<S::WeightShape, B, K, Train>,
133        bias: Option<Param<S::BiasShape, B, K, Train>>,
134    ) -> Self {
135        Self {
136            weight,
137            bias,
138            _phantom: core::marker::PhantomData,
139        }
140    }
141
142    /// Freezes this layer's parameters.
143    pub fn freeze(self) -> Conv2d<S, B, Bias, K, Frozen> {
144        Conv2d {
145            weight: self.weight.freeze(),
146            bias: self.bias.map(|b| b.freeze()),
147            _phantom: core::marker::PhantomData,
148        }
149    }
150
151    /// Unfreezes this layer's parameters.
152    pub fn unfreeze(self) -> Conv2d<S, B, Bias, K, Trainable> {
153        Conv2d {
154            weight: self.weight.unfreeze(),
155            bias: self.bias.map(|b| b.unfreeze()),
156            _phantom: core::marker::PhantomData,
157        }
158    }
159}
160
161/// A builder for constructing a [`Conv2d`] layer with a target.
162#[derive(Debug, Clone)]
163pub struct Conv2dBuilder<
164    S: Conv2dShape,
165    Bias: crate::nn::optional::OptionalField = crate::nn::optional::True,
166    Train: TrainState = Trainable,
167> {
168    /// Convolution geometry (out_channels plus kernel dims).
169    pub shape: ShapeValue<S>,
170    /// Initialization scheme for weights.
171    pub weight_init: crate::nn::init::Init,
172    /// Initialization scheme for bias.
173    pub bias_init: crate::nn::init::Init,
174    /// Bias-presence marker.
175    pub _bias: core::marker::PhantomData<Bias>,
176    /// Train-state marker.
177    pub _train: core::marker::PhantomData<Train>,
178}
179
180/// Creates a new builder for a [`Conv2d`] layer with shape `shape`.
181pub fn conv2d<S: Conv2dShape>(shape: ShapeValue<S>) -> Conv2dBuilder<S> {
182    Conv2dBuilder {
183        shape,
184        weight_init: crate::nn::init::kaiming_uniform(),
185        bias_init: crate::nn::init::kaiming_uniform(),
186        _bias: core::marker::PhantomData,
187        _train: core::marker::PhantomData,
188    }
189}
190
191impl<S: Conv2dShape, Bias: crate::nn::optional::OptionalField, Train: TrainState>
192    Conv2dBuilder<S, Bias, Train>
193{
194    /// Disables bias parameter for this convolution layer.
195    pub fn no_bias(self) -> Conv2dBuilder<S, crate::nn::optional::False, Train> {
196        Conv2dBuilder {
197            shape: self.shape,
198            weight_init: self.weight_init,
199            bias_init: self.bias_init,
200            _bias: core::marker::PhantomData,
201            _train: self._train,
202        }
203    }
204
205    /// Marks the resulting layer as frozen (non-trainable).
206    pub fn frozen(self) -> Conv2dBuilder<S, Bias, Frozen> {
207        Conv2dBuilder {
208            shape: self.shape,
209            weight_init: self.weight_init,
210            bias_init: self.bias_init,
211            _bias: self._bias,
212            _train: core::marker::PhantomData,
213        }
214    }
215
216    /// Configures weight initialization.
217    pub fn weight_init(mut self, init: crate::nn::init::Init) -> Self {
218        self.weight_init = init;
219        self
220    }
221
222    /// Configures bias initialization.
223    pub fn bias_init(mut self, init: crate::nn::init::Init) -> Self {
224        self.bias_init = init;
225        self
226    }
227}
228
229impl<S, B, Bias, K: DType> Conv2d<S, B, Bias, K, Trainable>
230where
231    S: Conv2dShape,
232    B: crate::tensor::backend::VariableBackend
233        + SupportsDType<K>
234        + crate::tensor::backend::SupportsDType<K>
235        + crate::nn::param::ParameterInit<K>,
236    Bias: crate::nn::optional::OptionalField,
237    <K as DType>::Arg: Clone,
238    <B::Device as Device>::Arg: Clone,
239{
240    /// Builds the layer from channel arguments.
241    pub fn build<A>(args: A) -> Result<Self>
242    where
243        A: crate::tensor::arg_into::LayerArgInto<(
244                <S::OutC as Dim>::Arg,
245                <S::InC as Dim>::Arg,
246                <K as DType>::Arg,
247                <B::Device as Device>::Arg,
248                <Bias as crate::nn::optional::OptionalField>::Arg,
249            )>,
250    {
251        let (out_c, in_c, dtype_arg, device_arg, bias_arg) = args.into_layer_arg();
252        let (cout, cin, weight_shape_arg, bias_shape_arg) =
253            S::build_args((out_c, in_c)).map_err(Error::Shape)?;
254        let kernel_size = S::K::static_size().map_err(Error::Shape)?;
255        let fan_in = cin * kernel_size * kernel_size;
256        let fan_out = cout * kernel_size * kernel_size;
257
258        let dtype_field = <K as DType>::init(dtype_arg);
259        let device_field = <B::Device as Device>::init(device_arg);
260        let weight_shape_field =
261            <S::WeightShape as Shape>::resolve(weight_shape_arg).map_err(Error::Shape)?;
262        let bias_shape_field =
263            <S::BiasShape as Shape>::resolve(bias_shape_arg).map_err(Error::Shape)?;
264
265        let init = crate::nn::init::kaiming_uniform();
266        let context_w = InitContext::new(ParameterRole::Weight).with_fan(fan_in, fan_out);
267        let plan_w = init.plan(context_w)?;
268        let weight_dims = weight_shape_field.clone();
269        let raw_w =
270            execute_plan_raw::<B, K>(weight_dims.as_ref(), &dtype_field, &device_field, plan_w)?;
271        let weight = Param::<S::WeightShape, B, K, Trainable>::from_parts_checked(
272            raw_w,
273            weight_shape_field,
274            dtype_field.clone(),
275            device_field.clone(),
276        )?;
277
278        let bias = if Bias::init(bias_arg) {
279            let context_b = InitContext::new(ParameterRole::Bias).with_fan(fan_in, fan_out);
280            let plan_b = init.plan(context_b)?;
281            let bias_dims = bias_shape_field.clone();
282            let raw_b =
283                execute_plan_raw::<B, K>(bias_dims.as_ref(), &dtype_field, &device_field, plan_b)?;
284            Some(Param::<S::BiasShape, B, K, Trainable>::from_parts_checked(
285                raw_b,
286                bias_shape_field,
287                dtype_field,
288                device_field,
289            )?)
290        } else {
291            None
292        };
293
294        Ok(Self {
295            weight,
296            bias,
297            _phantom: core::marker::PhantomData,
298        })
299    }
300}
301
302impl<I, S, B, COut: Dim, CIn: Dim, K: DType, Train: TrainState> Module<Tensor<I, B, K>>
303    for Conv2d<S, B, crate::nn::optional::True, K, Train>
304where
305    S: Conv2dShape<OutC = COut, InC = CIn>,
306    I: Shape
307        + DynShape
308        + crate::shapes::SpatialConv2d<COut, S::K, S::S, S::P, S::D>
309        + crate::shapes::HasChannels2D<CIn>,
310    B: crate::tensor::backend::VariableBackend
311        + Execute<op::Conv2dExact>
312        + Execute<op::ReshapeExact>,
313    <B as Execute<op::Conv2dExact>>::Output: Into<B::Storage<K>>,
314    <B as Execute<op::ReshapeExact>>::Output: Into<B::Storage<K>>,
315{
316    /// The output tensor type produced by this module's forward pass.
317    type Output = Tensor<I::Output, B, K>;
318    /// The error type returned if the forward pass fails.
319    type Error = Error;
320
321    #[inline]
322    /// Runs the forward pass of this module on the given input.
323    fn forward(&self, x: Tensor<I, B, K>) -> core::result::Result<Self::Output, Error> {
324        let weight = self.weight.as_tensor()?;
325        let bias = self.bias.as_ref().unwrap().as_tensor()?;
326
327        let x_shape = x.dims();
328        let x_shape = x_shape.as_ref();
329        let rank = x_shape.len();
330        let batch_size = crate::shapes::ShapeBuf::from_slice(&x_shape[0..rank - 3])
331            .checked_numel(crate::shapes::error::OperationKind::Conv2d)?;
332        let in_channels = x_shape[rank - 3];
333        let height = x_shape[rank - 2];
334        let width = x_shape[rank - 1];
335
336        let x_inner = if rank > 4 {
337            crate::tensor::ops::manipulation::reshape_storage_exact::<B, K>(
338                &x.inner,
339                &ShapeBuf::from_slice(&[batch_size, in_channels, height, width]),
340            )?
341        } else {
342            x.inner.clone()
343        };
344
345        let shape =
346            <I as crate::shapes::SpatialConv2d<COut, S::K, S::S, S::P, S::D>>::compute_output_shape(
347                &x.shape_buf_value(),
348                weight.dims()[0],
349            )?;
350
351        let intermediate_shape = ShapeValue::<Dyn>::try_new(ShapeBuf::from_slice(&[
352            batch_size,
353            shape[shape.len() - 3],
354            shape[shape.len() - 2],
355            shape[shape.len() - 1],
356        ]))
357        .map_err(Error::Shape)?;
358        let inputs = [
359            TensorHandle::from_storage::<B, K, Local>(&x_inner),
360            TensorHandle::from_storage::<B, K, Local>(&weight.inner),
361            TensorHandle::from_storage::<B, K, Local>(&bias.inner),
362        ];
363        let context = ExecutionContext::from_scope(B::default());
364        let out = crate::exec::dispatch::execute_shaped::<op::Conv2dExact, B, Dyn>(
365            &context,
366            Conv2dAttributes {
367                stride: [S::S::static_size().map_err(Error::Shape)?; 2],
368                padding: [S::P::static_size().map_err(Error::Shape)?; 2],
369                dilation: [S::D::static_size().map_err(Error::Shape)?; 2],
370                groups: 1,
371                has_bias: true,
372            },
373            &inputs,
374            &intermediate_shape,
375        )?
376        .into();
377
378        let out_shape = shape.clone();
379        let out = if rank > 4 {
380            crate::tensor::ops::manipulation::reshape_storage_exact::<B, K>(&out, &out_shape)?
381        } else {
382            out
383        };
384
385        Tensor::from_parts(
386            out,
387            shape,
388            x._dtype.clone(),
389            weight._device.clone(),
390            *x.grad_field(),
391        )
392    }
393}
394
395impl<I, S, B, COut: Dim, CIn: Dim, K: DType, Train: TrainState> Module<Tensor<I, B, K>>
396    for Conv2d<S, B, crate::nn::optional::False, K, Train>
397where
398    S: Conv2dShape<OutC = COut, InC = CIn>,
399    I: Shape
400        + DynShape
401        + crate::shapes::SpatialConv2d<COut, S::K, S::S, S::P, S::D>
402        + crate::shapes::HasChannels2D<CIn>,
403    B: crate::tensor::backend::VariableBackend
404        + Execute<op::Conv2dExact>
405        + Execute<op::ReshapeExact>,
406    <B as Execute<op::Conv2dExact>>::Output: Into<B::Storage<K>>,
407    <B as Execute<op::ReshapeExact>>::Output: Into<B::Storage<K>>,
408{
409    /// The output tensor type produced by this module's forward pass.
410    type Output = Tensor<I::Output, B, K>;
411    /// The error type returned if the forward pass fails.
412    type Error = Error;
413
414    #[inline]
415    /// Runs the forward pass of this module on the given input.
416    fn forward(&self, x: Tensor<I, B, K>) -> core::result::Result<Self::Output, Error> {
417        let weight = self.weight.as_tensor()?;
418
419        let x_shape = x.dims();
420        let x_shape = x_shape.as_ref();
421        let rank = x_shape.len();
422        let batch_size = crate::shapes::ShapeBuf::from_slice(&x_shape[0..rank - 3])
423            .checked_numel(crate::shapes::error::OperationKind::Conv2d)?;
424        let in_channels = x_shape[rank - 3];
425        let height = x_shape[rank - 2];
426        let width = x_shape[rank - 1];
427
428        let x_inner = if rank > 4 {
429            crate::tensor::ops::manipulation::reshape_storage_exact::<B, K>(
430                &x.inner,
431                &ShapeBuf::from_slice(&[batch_size, in_channels, height, width]),
432            )?
433        } else {
434            x.inner.clone()
435        };
436
437        let shape =
438            <I as crate::shapes::SpatialConv2d<COut, S::K, S::S, S::P, S::D>>::compute_output_shape(
439                &x.shape_buf_value(),
440                weight.dims()[0],
441            )?;
442
443        let intermediate_shape = ShapeValue::<Dyn>::try_new(ShapeBuf::from_slice(&[
444            batch_size,
445            shape[shape.len() - 3],
446            shape[shape.len() - 2],
447            shape[shape.len() - 1],
448        ]))
449        .map_err(Error::Shape)?;
450        let inputs = [
451            TensorHandle::from_storage::<B, K, Local>(&x_inner),
452            TensorHandle::from_storage::<B, K, Local>(&weight.inner),
453        ];
454        let context = ExecutionContext::from_scope(B::default());
455        let out = crate::exec::dispatch::execute_shaped::<op::Conv2dExact, B, Dyn>(
456            &context,
457            Conv2dAttributes {
458                stride: [S::S::static_size().map_err(Error::Shape)?; 2],
459                padding: [S::P::static_size().map_err(Error::Shape)?; 2],
460                dilation: [S::D::static_size().map_err(Error::Shape)?; 2],
461                groups: 1,
462                has_bias: false,
463            },
464            &inputs,
465            &intermediate_shape,
466        )?
467        .into();
468
469        let out_shape = shape.clone();
470        let out = if rank > 4 {
471            crate::tensor::ops::manipulation::reshape_storage_exact::<B, K>(&out, &out_shape)?
472        } else {
473            out
474        };
475
476        Tensor::from_parts(
477            out,
478            shape,
479            x._dtype.clone(),
480            weight._device.clone(),
481            *x.grad_field(),
482        )
483    }
484}
485
486impl<I, S, B, COut: Dim, CIn: Dim, K: DType, Train: TrainState> Module<Tensor<I, B, K>>
487    for Conv2d<S, B, Dyn, K, Train>
488where
489    S: Conv2dShape<OutC = COut, InC = CIn>,
490    I: Shape
491        + DynShape
492        + crate::shapes::SpatialConv2d<COut, S::K, S::S, S::P, S::D>
493        + crate::shapes::HasChannels2D<CIn>,
494    B: crate::tensor::backend::VariableBackend
495        + Execute<op::Conv2dExact>
496        + Execute<op::ReshapeExact>,
497    <B as Execute<op::Conv2dExact>>::Output: Into<B::Storage<K>>,
498    <B as Execute<op::ReshapeExact>>::Output: Into<B::Storage<K>>,
499{
500    /// The output tensor type produced by this module's forward pass.
501    type Output = Tensor<I::Output, B, K>;
502    /// The error type returned if the forward pass fails.
503    type Error = Error;
504
505    #[inline]
506    /// Runs the forward pass of this module on the given input.
507    fn forward(&self, x: Tensor<I, B, K>) -> core::result::Result<Self::Output, Error> {
508        let weight = self.weight.as_tensor()?;
509        let bias = match &self.bias {
510            Some(b) => Some(b.as_tensor()?),
511            None => None,
512        };
513
514        let x_shape = x.dims();
515        let x_shape = x_shape.as_ref();
516        let rank = x_shape.len();
517        let batch_size = crate::shapes::ShapeBuf::from_slice(&x_shape[0..rank - 3])
518            .checked_numel(crate::shapes::error::OperationKind::Conv2d)?;
519        let in_channels = x_shape[rank - 3];
520        let height = x_shape[rank - 2];
521        let width = x_shape[rank - 1];
522
523        let x_inner = if rank > 4 {
524            crate::tensor::ops::manipulation::reshape_storage_exact::<B, K>(
525                &x.inner,
526                &ShapeBuf::from_slice(&[batch_size, in_channels, height, width]),
527            )?
528        } else {
529            x.inner.clone()
530        };
531
532        let shape =
533            <I as crate::shapes::SpatialConv2d<COut, S::K, S::S, S::P, S::D>>::compute_output_shape(
534                &x.shape_buf_value(),
535                weight.dims()[0],
536            )?;
537
538        let intermediate_shape = ShapeValue::<Dyn>::try_new(ShapeBuf::from_slice(&[
539            batch_size,
540            shape[shape.len() - 3],
541            shape[shape.len() - 2],
542            shape[shape.len() - 1],
543        ]))
544        .map_err(Error::Shape)?;
545        let mut inputs = alloc::vec::Vec::with_capacity(3);
546        inputs.push(TensorHandle::from_storage::<B, K, Local>(&x_inner));
547        inputs.push(TensorHandle::from_storage::<B, K, Local>(&weight.inner));
548        if let Some(bias) = bias.as_ref() {
549            inputs.push(TensorHandle::from_storage::<B, K, Local>(&bias.inner));
550        }
551        let context = ExecutionContext::from_scope(B::default());
552        let out = crate::exec::dispatch::execute_shaped::<op::Conv2dExact, B, Dyn>(
553            &context,
554            Conv2dAttributes {
555                stride: [S::S::static_size().map_err(Error::Shape)?; 2],
556                padding: [S::P::static_size().map_err(Error::Shape)?; 2],
557                dilation: [S::D::static_size().map_err(Error::Shape)?; 2],
558                groups: 1,
559                has_bias: bias.is_some(),
560            },
561            &inputs,
562            &intermediate_shape,
563        )?
564        .into();
565
566        let out_shape = shape.clone();
567        let out = if rank > 4 {
568            crate::tensor::ops::manipulation::reshape_storage_exact::<B, K>(&out, &out_shape)?
569        } else {
570            out
571        };
572
573        Tensor::from_parts(
574            out,
575            shape,
576            x._dtype.clone(),
577            weight._device.clone(),
578            *x.grad_field(),
579        )
580    }
581}