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    /// 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}