Skip to main content

coeus_nn/module/
error.rs

1use std::error::Error;
2
3/// Contract failures returned by neural-network module execution.
4#[derive(Debug, thiserror::Error)]
5#[non_exhaustive]
6pub enum ModuleError<E>
7where
8    E: Error + 'static,
9{
10    /// A backend operation failed while evaluating the module.
11    #[error("{module} backend operation failed")]
12    Backend {
13        /// Module family performing the operation.
14        module: &'static str,
15        /// Backend-owned typed failure.
16        #[source]
17        source: E,
18    },
19    /// The input rank violates the module contract.
20    #[error("{module} expected input rank {expected}, got {actual}")]
21    InvalidRank {
22        /// Module family rejecting the input.
23        module: &'static str,
24        /// Accepted rank or rank range.
25        expected: &'static str,
26        /// Observed input rank.
27        actual: usize,
28    },
29    /// An operation axis is outside the input rank.
30    #[error("{module} axis {axis} is out of range for rank {rank}")]
31    InvalidAxis {
32        /// Module family rejecting the axis.
33        module: &'static str,
34        /// Requested axis.
35        axis: usize,
36        /// Observed input rank.
37        rank: usize,
38    },
39    /// A split operation requires an even extent.
40    #[error("{module} axis {axis} requires an even extent, got {extent}")]
41    UnevenSplit {
42        /// Module family rejecting the split.
43        module: &'static str,
44        /// Split axis.
45        axis: usize,
46        /// Observed axis extent.
47        extent: usize,
48    },
49    /// A parameter or input has an incompatible shape.
50    #[error("{module} {parameter} shape mismatch: expected {expected:?}, got {actual:?}")]
51    ShapeMismatch {
52        /// Module family rejecting the shape.
53        module: &'static str,
54        /// Input or parameter role.
55        parameter: &'static str,
56        /// Required shape.
57        expected: Vec<usize>,
58        /// Observed shape.
59        actual: Vec<usize>,
60    },
61    /// The input channel count differs from the configured module width.
62    #[error("{module} channel mismatch: expected {expected}, got {actual}")]
63    ChannelMismatch {
64        /// Module family rejecting the channel count.
65        module: &'static str,
66        /// Configured channel count.
67        expected: usize,
68        /// Observed channel count.
69        actual: usize,
70    },
71    /// A group count cannot partition the configured channels.
72    #[error("{module} group count {groups} does not divide {channels} channels")]
73    InvalidGroupCount {
74        /// Module family rejecting the configuration.
75        module: &'static str,
76        /// Requested normalization groups.
77        groups: usize,
78        /// Configured channel count.
79        channels: usize,
80    },
81    /// The normalization epsilon is negative or not finite.
82    #[error("{module} epsilon must be finite and non-negative")]
83    InvalidEpsilon {
84        /// Module family rejecting epsilon.
85        module: &'static str,
86    },
87    /// A reduction domain contains too few values for the module statistic.
88    #[error("{module} requires at least {minimum} values per channel, got {actual}")]
89    InsufficientElements {
90        /// Module family rejecting the reduction domain.
91        module: &'static str,
92        /// Minimum supported reduction width.
93        minimum: usize,
94        /// Observed reduction width.
95        actual: usize,
96    },
97    /// Interior module state is already borrowed.
98    #[error("{module} state {state} is already borrowed")]
99    StateBorrow {
100        /// Module family attempting the borrow.
101        module: &'static str,
102        /// Conflicting state field.
103        state: &'static str,
104    },
105}
106
107/// Contract failures when loading optimizer-owned named parameters.
108#[derive(Debug, thiserror::Error, PartialEq, Eq)]
109pub enum ParameterLoadError {
110    /// The incoming inventory has a different parameter count.
111    #[error("named parameter count mismatch: expected {expected}, got {actual}")]
112    Count {
113        /// Module inventory length.
114        expected: usize,
115        /// Incoming inventory length.
116        actual: usize,
117    },
118    /// A hierarchical name differs at a stable inventory position.
119    #[error("named parameter mismatch at index {index}: expected {expected}, got {actual}")]
120    Name {
121        /// Inventory position.
122        index: usize,
123        /// Module-owned path.
124        expected: String,
125        /// Incoming path.
126        actual: String,
127    },
128}
129
130#[cfg(test)]
131mod tests {
132    use super::ModuleError;
133    use coeus_core::BackendError;
134
135    #[test]
136    fn backend_failure_preserves_module_and_source() {
137        let source = BackendError::AxisOutOfRange {
138            operation: "sum",
139            axis: 3,
140            rank: 2,
141        };
142
143        let error = ModuleError::Backend {
144            module: "LayerNorm",
145            source: source.clone(),
146        };
147
148        match error {
149            ModuleError::Backend {
150                module,
151                source: actual,
152            } => {
153                assert_eq!(module, "LayerNorm");
154                assert_eq!(actual, source);
155            }
156            other => panic!("expected backend failure, got {other:?}"),
157        }
158    }
159}