coeus_nn/module/trait_def.rs
1use coeus_autograd::Var;
2use coeus_core::{ComputeBackend, 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: ComputeBackend + 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: ComputeBackend + 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) -> Result<(), B::Error> {
114 for p in self.parameters() {
115 p.zero_grad()?;
116 }
117 Ok(())
118 }
119
120 /// Set the training mode of the module and its sub-modules.
121 #[inline]
122 fn train(&mut self, _mode: bool) {}
123
124 /// Set the module and its sub-modules to evaluation mode.
125 #[inline]
126 fn eval(&mut self) {
127 self.train(false);
128 }
129}