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}