Skip to main content

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}