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