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