Skip to main content

incin_core/nn/
conv1d.rs

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