Principle:Avhz RustQuant Error Handling
| Knowledge Sources | |
|---|---|
| Domains | Software_Engineering, Error_Management |
| Last Updated | 2026-02-07 21:00 GMT |
Overview
RustQuant defines a centralized error type hierarchy using the thiserror crate, providing structured error variants for computation failures, invalid arguments, missing inputs, statistical distribution errors, and interoperability with Python via PyO3.
Description
Error handling in RustQuant is built around the RustQuantError enum, which uses the #[derive(Error)] macro from the thiserror crate for automatic Display and Error trait implementations.
The error hierarchy is organized into several categories:
General computation errors:
- NotImplemented: indicates a feature that has not yet been implemented
- ComputationError: signals a problem during numerical computation
- InvalidArgument: reports invalid parameter or argument values
- ConditionViolated: indicates that a precondition or invariant was broken
- FileOperationFailed: covers file I/O failures
- MissingInput: reports required inputs that were not provided
- MutexPoison: wraps
std::sync::PoisonErrorfor thread safety issues
Data and I/O errors:
- IoError: wraps
std::io::Errorusing#[from]for automatic conversion - PyO3Error: wraps
pyo3::PyErrfor Python interoperability errors
Statistical distribution errors: automatic From conversions for distribution construction failures from the rand_distr crate, including Bernoulli, Binomial, ChiSquared, Exponential, Gamma, Gaussian (Normal), and Poisson errors.
Linear algebra errors:
- MatrixInversionFailed: signals failure in matrix inversion
- SvdDecompositionFailed: indicates SVD decomposition failure
Interpolation errors:
- UnequalLength: mismatched input vector lengths
- Unfitted: interpolator used before fitting
- OutsideOfRange: query point outside interpolation bounds
- BSplineInvalidParameters: inconsistent B-spline knot/control point counts
- BSplineOutsideOfRange: B-spline evaluation outside valid range
A separate CurveError enum handles curve-specific errors like DateOutsideRange and NoPoints.
The library also provides an error! macro for convenient error construction and implements From<RustQuantError> for pyo3::PyErr to enable seamless error propagation to Python.
Usage
Use RustQuantError as the error type in Result return types throughout the library. The #[from] attributes allow using the ? operator to automatically convert external errors into the unified error type. When calling from Python via PyO3, errors are automatically converted to PyValueError.
Theoretical Basis
RustQuant follows the Rust ecosystem's idiomatic error handling pattern: functions that can fail return Result<T, RustQuantError>, enabling callers to handle errors explicitly. The thiserror crate eliminates boilerplate by deriving Display and Error implementations from the enum definition.
The error type hierarchy is designed to be exhaustive across the library's domains (computation, data, statistics, linear algebra, interpolation) while remaining ergonomic through automatic conversions. This approach ensures that error information is preserved across module boundaries and that downstream consumers can pattern-match on specific error variants.