Skip to main content

coeus_nn/
sequential.rs

1// ── Sequential module combinator ──
2//
3// Sequential<T, B> chains a runtime-dynamic list of boxed modules.
4// `dyn Module<T, B>` is justified here by condition (1) in the architecture rules:
5// the concrete layer types are genuinely unknown at compile time and type erasure
6// is the domain requirement for a user-constructable heterogeneous module stack.
7
8use crate::module::{prefixed_parameters, Module, ModuleError};
9use coeus_autograd::Var;
10use coeus_core::{MoiraiBackend, Scalar};
11
12/// A sequential container that chains modules.
13///
14/// `forward` passes the output of each module as the input to the next.
15///
16/// # Example
17/// ```rust,ignore
18/// let mut seq = Sequential::<f64>::new();
19/// seq.add(Linear::new(64, 128, true));
20/// seq.add(ReLU);
21/// seq.add(Linear::new(128, 10, true));
22/// let output = seq.forward(&input).expect("valid Sequential input");
23/// ```
24pub struct Sequential<T: Scalar, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
25    /// Type-erased module list. dyn dispatch is justified: types are unknown at compile time.
26    layers: Vec<Box<dyn Module<T, B>>>,
27}
28
29impl<T: Scalar, B: coeus_ops::BackendOps<T> + Default> Sequential<T, B> {
30    /// Create an empty Sequential.
31    pub fn new() -> Self {
32        Self { layers: Vec::new() }
33    }
34
35    /// Append a module to the end of the sequence.
36    ///
37    /// Returns `&mut Self` to enable method chaining.
38    pub fn add<M: Module<T, B> + 'static>(&mut self, module: M) -> &mut Self {
39        self.layers.push(Box::new(module));
40        self
41    }
42
43    /// Return the number of modules in this sequential.
44    #[inline]
45    pub fn len(&self) -> usize {
46        self.layers.len()
47    }
48
49    /// Return true if this sequential has no modules.
50    #[inline]
51    pub fn is_empty(&self) -> bool {
52        self.layers.is_empty()
53    }
54}
55
56impl<T: Scalar, B: coeus_ops::BackendOps<T> + Default> Default for Sequential<T, B> {
57    fn default() -> Self {
58        Self::new()
59    }
60}
61
62impl<T: Scalar, B: coeus_ops::BackendOps<T> + Default> Module<T, B> for Sequential<T, B> {
63    fn parameters(&self) -> Vec<Var<T, B>> {
64        self.layers.iter().flat_map(|m| m.parameters()).collect()
65    }
66
67    fn named_parameters(&self) -> Vec<coeus_autograd::Parameter<T, B>> {
68        self.layers
69            .iter()
70            .enumerate()
71            .flat_map(|(index, module)| {
72                prefixed_parameters(&format!("layers.{index}"), module.as_ref())
73            })
74            .collect()
75    }
76
77    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>> {
78        self.layers
79            .iter()
80            .try_fold(input.clone(), |x, module| module.forward(&x))
81    }
82
83    fn train(&mut self, mode: bool) {
84        for m in &mut self.layers {
85            m.train(mode);
86        }
87    }
88
89    fn load_parameters(&mut self, params: &[Var<T, B>]) {
90        let mut offset = 0;
91        for m in &mut self.layers {
92            let n = m.parameters().len();
93            m.load_parameters(&params[offset..offset + n]);
94            offset += n;
95        }
96    }
97}
98
99/// A compile-time static sequential container that chains modules.
100///
101/// Chaining is achieved via nested `StaticSeq<H, T>` structs created using
102/// the `ModuleExt::append` builder method. Evaluation is fully monomorphized
103/// at compile-time by the Rust compiler, eliminating all dynamic dispatch.
104///
105/// # Example
106/// ```rust,ignore
107/// let model = Linear::new(64, 128)
108///     .append(ReLU)
109///     .append(Linear::new(128, 10));
110/// let output = model.forward(&input).expect("valid Chain input");
111/// ```
112#[derive(Clone, Copy, Debug)]
113pub struct StaticSeq<H, T>(pub H, pub T);
114
115impl<
116        ScalarType: Scalar,
117        B: coeus_ops::BackendOps<ScalarType> + Default,
118        H: Module<ScalarType, B>,
119        T: Module<ScalarType, B>,
120    > Module<ScalarType, B> for StaticSeq<H, T>
121{
122    #[inline]
123    fn parameters(&self) -> Vec<Var<ScalarType, B>> {
124        let mut params = self.0.parameters();
125        params.extend(self.1.parameters());
126        params
127    }
128
129    fn named_parameters(&self) -> Vec<coeus_autograd::Parameter<ScalarType, B>> {
130        let mut parameters = prefixed_parameters("head", &self.0);
131        parameters.extend(prefixed_parameters("tail", &self.1));
132        parameters
133    }
134
135    #[inline]
136    fn forward(
137        &self,
138        input: &Var<ScalarType, B>,
139    ) -> Result<Var<ScalarType, B>, ModuleError<B::Error>> {
140        let out = self.0.forward(input)?;
141        self.1.forward(&out)
142    }
143
144    #[inline]
145    fn train(&mut self, mode: bool) {
146        self.0.train(mode);
147        self.1.train(mode);
148    }
149
150    #[inline]
151    fn load_parameters(&mut self, params: &[Var<ScalarType, B>]) {
152        let n0 = self.0.parameters().len();
153        self.0.load_parameters(&params[..n0]);
154        self.1.load_parameters(&params[n0..]);
155    }
156}
157
158/// Extension trait for all `Module`s, enabling fluent construction of `StaticSeq` chains.
159pub trait ModuleExt<T: Scalar, B: coeus_ops::BackendOps<T> + Default>: Module<T, B> {
160    /// Append another module to the end of the sequence.
161    fn append<M: Module<T, B>>(self, next: M) -> StaticSeq<Self, M>
162    where
163        Self: Sized;
164}
165
166impl<T: Scalar, B: coeus_ops::BackendOps<T> + Default, M: Module<T, B>> ModuleExt<T, B> for M {
167    #[inline]
168    fn append<Next: Module<T, B>>(self, next: Next) -> StaticSeq<Self, Next> {
169        StaticSeq(self, next)
170    }
171}