Skip to main content

coeus_nn/module/
trait_def.rs

1use coeus_autograd::Var;
2use coeus_core::{MoiraiBackend, Scalar};
3
4use super::{ModuleError, ParameterLoadError};
5use coeus_autograd::Parameter;
6
7pub(crate) fn prefixed_parameters<T, B, M>(prefix: &str, module: &M) -> Vec<Parameter<T, B>>
8where
9    T: Scalar,
10    B: coeus_ops::BackendOps<T> + Default,
11    M: Module<T, B> + ?Sized,
12{
13    module
14        .named_parameters()
15        .into_iter()
16        .map(|parameter| parameter.with_prefix(prefix))
17        .collect()
18}
19
20/// Trait for neural network modules.
21///
22/// Each module owns `Parameter`s, can contain sub-modules, and can support train/eval modes.
23pub trait Module<T: Scalar, B: coeus_ops::BackendOps<T> + Default = MoiraiBackend> {
24    /// Collect all trainable parameters (including from sub-modules).
25    fn parameters(&self) -> Vec<Var<T, B>>;
26
27    /// Collect trainable parameters with stable hierarchical names.
28    ///
29    /// Leaf modules with the canonical zero-, one-, or two-parameter layout
30    /// inherit `[]`, `[weight]`, or `[weight, bias]`. Modules with a wider
31    /// layout or child modules must override this method so names express the
32    /// owned field hierarchy instead of depending on flattened ordinals.
33    fn named_parameters(&self) -> Vec<Parameter<T, B>> {
34        let parameters = self.parameters();
35        let names: &[&str] = match parameters.len() {
36            0 => &[],
37            1 => &["weight"],
38            2 => &["weight", "bias"],
39            count => panic!(
40                "invariant: module with {count} parameters must define stable hierarchical names"
41            ),
42        };
43        parameters
44            .into_iter()
45            .zip(names)
46            .map(|(parameter, name)| Parameter::new(parameter, *name))
47            .collect()
48    }
49
50    /// Evaluate this module.
51    ///
52    /// # Errors
53    ///
54    /// Returns a typed module or backend failure when the input violates the
55    /// module contract, state cannot be borrowed, or backend execution fails.
56    fn forward(&self, input: &Var<T, B>) -> Result<Var<T, B>, ModuleError<B::Error>>;
57
58    /// Write optimizer-updated parameter values back into this module's own
59    /// fields, consuming `params` in the same order `parameters()` enumerates
60    /// them (i.e. `params.len() == parameters().len()`).
61    ///
62    /// This exists because `Var::clone()` shares gradient state but not the
63    /// value storage: `coeus_optim::{SGD, Adam}::step` mutates its own owned
64    /// `Vec<Var<T, B>>` in place (via copy-on-write on first mutation), so a
65    /// module that read `parameters()` to build an optimizer must call this
66    /// after each `step()` to see the updated values, unless the module's own
67    /// fields *are* the optimizer's `Var`s (as in a flat training loop that
68    /// never separately clones them into a named struct).
69    ///
70    /// Default is a no-op, which is correct for parameterless modules
71    /// (activations, dropout, pooling, reshape/view layers, ...). Any module
72    /// whose `parameters()` returns a non-empty `Vec` must override this.
73    #[inline]
74    fn load_parameters(&mut self, _params: &[Var<T, B>]) {}
75
76    /// Load optimizer-updated named parameters after validating the complete
77    /// stable path inventory.
78    ///
79    /// # Errors
80    ///
81    /// Returns [`ParameterLoadError`] when count or path ordering differs from
82    /// this module's canonical named inventory.
83    fn load_named_parameters(
84        &mut self,
85        parameters: &[Parameter<T, B>],
86    ) -> Result<(), ParameterLoadError> {
87        let expected = self.named_parameters();
88        if expected.len() != parameters.len() {
89            return Err(ParameterLoadError::Count {
90                expected: expected.len(),
91                actual: parameters.len(),
92            });
93        }
94        for (index, (expected, actual)) in expected.iter().zip(parameters).enumerate() {
95            if expected.name != actual.name {
96                return Err(ParameterLoadError::Name {
97                    index,
98                    expected: expected.name.clone(),
99                    actual: actual.name.clone(),
100                });
101            }
102        }
103        let variables = parameters
104            .iter()
105            .map(|parameter| parameter.var.clone())
106            .collect::<Vec<_>>();
107        self.load_parameters(&variables);
108        Ok(())
109    }
110
111    /// Zero all parameter gradients.
112    #[inline]
113    fn zero_grad(&self) {
114        for p in self.parameters() {
115            p.zero_grad();
116        }
117    }
118
119    /// Set the training mode of the module and its sub-modules.
120    #[inline]
121    fn train(&mut self, _mode: bool) {}
122
123    /// Set the module and its sub-modules to evaluation mode.
124    #[inline]
125    fn eval(&mut self) {
126        self.train(false);
127    }
128}