numra_core/
error.rs

1//! Error types for Numra.
2//!
3//! This module defines the error types used throughout the Numra library.
4//!
5//! Author: Moussa Leblouba
6//! Date: 9 February 2026
7//! Modified: 2 May 2026
8
9use core::fmt;
10
11/// Result type alias for Numra operations.
12pub type NumraResult<T> = Result<T, NumraError>;
13
14/// Errors that can occur in Numra operations.
15///
16/// `NumraError` is the workspace-wide error type into which every fallible
17/// crate's error converts via a `From<…> for NumraError` impl. This lets a
18/// user write `solve_ode(...)?.integrate(...)?.fit(...)?` and have `?` work
19/// uniformly across crate boundaries.
20///
21/// Variants fall into two tiers:
22///
23/// - **Low-level numerics-failure modes from `numra-core`** (structurally
24///   preserved): [`Linalg`], [`Convergence`], [`NumericalOptim`].
25/// - **Crate-level user-facing errors** (stringified, tagged by source crate):
26///   [`Ode`], [`Optim`], [`Ocp`], [`Fit`], [`Signal`], [`LineSearch`],
27///   [`Interp`], [`Integrate`], [`Special`], [`Stats`].
28///
29/// The [`NumericalOptim`] variant wraps `numra-core`'s
30/// [`OptimizationError`] (line-search / descent / convergence failures that
31/// happen *inside* algorithms regardless of which crate hosts them); the
32/// [`Optim`] variant carries `numra-optim::OptimError` (the optimization
33/// crate's API-level failures: missing objective, infeasibility, unbounded,
34/// etc.). The two are distinct concerns; do not confuse them.
35///
36/// `NumraError` is `#[non_exhaustive]`; new variants may be added in minor
37/// releases. Match arms must include a `_ => …` catch-all.
38///
39/// [`Linalg`]: NumraError::Linalg
40/// [`Convergence`]: NumraError::Convergence
41/// [`NumericalOptim`]: NumraError::NumericalOptim
42/// [`Ode`]: NumraError::Ode
43/// [`Optim`]: NumraError::Optim
44/// [`Ocp`]: NumraError::Ocp
45/// [`Fit`]: NumraError::Fit
46/// [`Signal`]: NumraError::Signal
47/// [`LineSearch`]: NumraError::LineSearch
48/// [`Interp`]: NumraError::Interp
49/// [`Integrate`]: NumraError::Integrate
50/// [`Special`]: NumraError::Special
51/// [`Stats`]: NumraError::Stats
52#[derive(Clone, Debug, PartialEq)]
53#[non_exhaustive]
54pub enum NumraError {
55    /// Linear algebra error from `numra-linalg` / `numra-core`.
56    Linalg(LinalgError),
57    /// Convergence failure from a Newton or fixed-point iteration.
58    Convergence(ConvergenceError),
59    /// Invalid input that doesn't fit a more specific variant.
60    InvalidInput(String),
61    /// Step size became too small.
62    StepSizeTooSmall { h: f64, h_min: f64 },
63    /// Maximum iterations exceeded.
64    MaxIterations { iterations: usize, max: usize },
65    /// Integration reached a singularity or stiffness.
66    Stiffness { t: f64, message: String },
67    /// Event caused termination.
68    EventTermination { t: f64, event_index: usize },
69    /// Numerical-optimization failure from inside an algorithm
70    /// (line search, descent, convergence). See [`OptimizationError`].
71    NumericalOptim(OptimizationError),
72    /// ODE solver error from `numra-ode`.
73    Ode(String),
74    /// Optimization error from `numra-optim` (API-level failures).
75    Optim(String),
76    /// ODE-constrained-optimization error from `numra-ocp`.
77    Ocp(String),
78    /// Curve-fitting error from `numra-fit`.
79    Fit(String),
80    /// Signal-processing error from `numra-signal`.
81    Signal(String),
82    /// Line-search error from `numra-nonlinear`.
83    LineSearch(String),
84    /// Interpolation error from `numra-interp`.
85    Interp(String),
86    /// Numerical-integration (quadrature) error from `numra-integrate`.
87    Integrate(String),
88    /// Special-function evaluation error from `numra-special`.
89    Special(String),
90    /// Statistics error from `numra-stats`.
91    Stats(String),
92}
93
94impl fmt::Display for NumraError {
95    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
96        match self {
97            NumraError::Linalg(e) => write!(f, "Linear algebra error: {}", e),
98            NumraError::Convergence(e) => write!(f, "Convergence error: {}", e),
99            NumraError::InvalidInput(msg) => write!(f, "Invalid input: {}", msg),
100            NumraError::StepSizeTooSmall { h, h_min } => {
101                write!(f, "Step size {} below minimum {}", h, h_min)
102            }
103            NumraError::MaxIterations { iterations, max } => {
104                write!(f, "Maximum iterations ({}) exceeded at {}", max, iterations)
105            }
106            NumraError::Stiffness { t, message } => {
107                write!(f, "Stiffness detected at t={}: {}", t, message)
108            }
109            NumraError::EventTermination { t, event_index } => {
110                write!(f, "Event {} terminated integration at t={}", event_index, t)
111            }
112            NumraError::NumericalOptim(e) => write!(f, "Numerical optimization error: {}", e),
113            NumraError::Ode(s) => write!(f, "ODE error: {}", s),
114            NumraError::Optim(s) => write!(f, "Optimization error: {}", s),
115            NumraError::Ocp(s) => write!(f, "OCP error: {}", s),
116            NumraError::Fit(s) => write!(f, "Fit error: {}", s),
117            NumraError::Signal(s) => write!(f, "Signal error: {}", s),
118            NumraError::LineSearch(s) => write!(f, "Line search error: {}", s),
119            NumraError::Interp(s) => write!(f, "Interpolation error: {}", s),
120            NumraError::Integrate(s) => write!(f, "Integration error: {}", s),
121            NumraError::Special(s) => write!(f, "Special function error: {}", s),
122            NumraError::Stats(s) => write!(f, "Statistics error: {}", s),
123        }
124    }
125}
126
127#[cfg(feature = "std")]
128impl std::error::Error for NumraError {}
129
130/// Linear algebra specific errors.
131#[derive(Clone, Debug, PartialEq)]
132pub enum LinalgError {
133    /// Matrix is singular
134    Singular { step: usize },
135    /// Dimensions mismatch
136    DimensionMismatch {
137        expected: (usize, usize),
138        actual: (usize, usize),
139    },
140    /// Matrix is not square
141    NotSquare { nrows: usize, ncols: usize },
142    /// Matrix is not positive definite
143    NotPositiveDefinite,
144    /// Iterative solver did not converge
145    IterativeNotConverged { iterations: usize, residual: f64 },
146    /// Eigenvalue decomposition failed
147    EigenDecompositionFailed,
148    /// SVD computation failed
149    SvdFailed,
150}
151
152impl fmt::Display for LinalgError {
153    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
154        match self {
155            LinalgError::Singular { step } => {
156                write!(f, "Matrix is singular (detected at step {})", step)
157            }
158            LinalgError::DimensionMismatch { expected, actual } => {
159                write!(
160                    f,
161                    "Dimension mismatch: expected {:?}, got {:?}",
162                    expected, actual
163                )
164            }
165            LinalgError::NotSquare { nrows, ncols } => {
166                write!(f, "Matrix is not square: {}x{}", nrows, ncols)
167            }
168            LinalgError::NotPositiveDefinite => {
169                write!(f, "Matrix is not positive definite")
170            }
171            LinalgError::IterativeNotConverged {
172                iterations,
173                residual,
174            } => {
175                write!(
176                    f,
177                    "Iterative solver did not converge after {} iterations (residual: {})",
178                    iterations, residual
179                )
180            }
181            LinalgError::EigenDecompositionFailed => {
182                write!(f, "Eigenvalue decomposition failed")
183            }
184            LinalgError::SvdFailed => {
185                write!(f, "SVD computation failed")
186            }
187        }
188    }
189}
190
191impl From<LinalgError> for NumraError {
192    fn from(e: LinalgError) -> Self {
193        NumraError::Linalg(e)
194    }
195}
196
197/// Convergence-related errors.
198#[derive(Clone, Debug, PartialEq)]
199pub enum ConvergenceError {
200    /// Newton iteration did not converge
201    Newton { iterations: usize, residual: f64 },
202    /// Fixed point iteration did not converge
203    FixedPoint { iterations: usize, delta: f64 },
204}
205
206impl fmt::Display for ConvergenceError {
207    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
208        match self {
209            ConvergenceError::Newton {
210                iterations,
211                residual,
212            } => {
213                write!(
214                    f,
215                    "Newton iteration did not converge after {} iterations (residual: {})",
216                    iterations, residual
217                )
218            }
219            ConvergenceError::FixedPoint { iterations, delta } => {
220                write!(
221                    f,
222                    "Fixed point iteration did not converge after {} iterations (delta: {})",
223                    iterations, delta
224                )
225            }
226        }
227    }
228}
229
230impl From<ConvergenceError> for NumraError {
231    fn from(e: ConvergenceError) -> Self {
232        NumraError::Convergence(e)
233    }
234}
235
236/// Optimization-related errors.
237#[derive(Clone, Debug, PartialEq)]
238pub enum OptimizationError {
239    /// Line search failed to find sufficient decrease
240    LineSearchFailed { iterations: usize, step_size: f64 },
241    /// Search direction is not a descent direction
242    NotDescentDirection { directional_derivative: f64 },
243    /// Optimization did not converge
244    NotConverged {
245        iterations: usize,
246        gradient_norm: f64,
247    },
248    /// Function evaluation returned NaN or infinity
249    InvalidFunctionValue { value: f64 },
250}
251
252impl fmt::Display for OptimizationError {
253    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
254        match self {
255            OptimizationError::LineSearchFailed {
256                iterations,
257                step_size,
258            } => {
259                write!(
260                    f,
261                    "Line search failed after {} iterations (step size: {})",
262                    iterations, step_size
263                )
264            }
265            OptimizationError::NotDescentDirection {
266                directional_derivative,
267            } => {
268                write!(
269                    f,
270                    "Search direction is not a descent direction (directional derivative: {})",
271                    directional_derivative
272                )
273            }
274            OptimizationError::NotConverged {
275                iterations,
276                gradient_norm,
277            } => {
278                write!(
279                    f,
280                    "Optimization did not converge after {} iterations (gradient norm: {})",
281                    iterations, gradient_norm
282                )
283            }
284            OptimizationError::InvalidFunctionValue { value } => {
285                write!(f, "Function evaluation returned invalid value: {}", value)
286            }
287        }
288    }
289}
290
291impl From<OptimizationError> for NumraError {
292    fn from(e: OptimizationError) -> Self {
293        NumraError::NumericalOptim(e)
294    }
295}
numra_core/error.rs

numra_core/
error.rs
