apex_solver/core/
mod.rs

1//! Core optimization components for the apex-solver library
2//!
3//! This module contains the fundamental building blocks for nonlinear least squares optimization:
4//! - Problem formulation and management
5//! - Residual blocks
6//! - Variables and manifold handling
7//! - Loss functions for robust estimation
8//! - Correctors for applying loss functions
9
10pub mod corrector;
11pub mod loss_functions;
12pub mod problem;
13pub mod residual_block;
14pub mod variable;
15
16use thiserror::Error;
17use tracing::error;
18
19/// Core module error types for optimization problems and factors
20#[derive(Debug, Clone, Error)]
21pub enum CoreError {
22    /// Residual block operation failed
23    #[error("Residual block error: {0}")]
24    ResidualBlock(String),
25
26    /// Variable initialization or constraint error
27    #[error("Variable error: {0}")]
28    Variable(String),
29
30    /// Factor linearization failed
31    #[error("Factor linearization failed: {0}")]
32    FactorLinearization(String),
33
34    /// Symbolic structure construction failed
35    #[error("Symbolic structure error: {0}")]
36    SymbolicStructure(String),
37
38    /// Parallel computation error (thread/mutex failures)
39    #[error("Parallel computation error: {0}")]
40    ParallelComputation(String),
41
42    /// Dimension mismatch between residual/Jacobian/variables
43    #[error("Dimension mismatch: {0}")]
44    DimensionMismatch(String),
45
46    /// Invalid constraint specification (bounds, fixed indices)
47    #[error("Invalid constraint: {0}")]
48    InvalidConstraint(String),
49
50    /// Loss function error
51    #[error("Loss function error: {0}")]
52    LossFunction(String),
53
54    /// Invalid input parameter or configuration
55    #[error("Invalid input: {0}")]
56    InvalidInput(String),
57}
58
59impl CoreError {
60    /// Log the error with tracing::error and return self for chaining
61    ///
62    /// This method allows for a consistent error logging pattern throughout
63    /// the core module, ensuring all errors are properly recorded.
64    ///
65    /// # Example
66    /// ```
67    /// # use apex_solver::core::CoreError;
68    /// # fn operation() -> Result<(), CoreError> { Ok(()) }
69    /// # fn example() -> Result<(), CoreError> {
70    /// operation()
71    ///     .map_err(|e| e.log())?;
72    /// # Ok(())
73    /// # }
74    /// ```
75    #[must_use]
76    pub fn log(self) -> Self {
77        error!("{}", self);
78        self
79    }
80
81    /// Log the error with the original source error from a third-party library
82    ///
83    /// This method logs both the CoreError and the underlying error
84    /// from external libraries. This provides full debugging context when
85    /// errors occur in third-party code.
86    ///
87    /// # Arguments
88    /// * `source_error` - The original error from the third-party library (must implement Debug)
89    ///
90    /// # Example
91    /// ```
92    /// # use apex_solver::core::CoreError;
93    /// # fn matrix_operation() -> Result<(), std::io::Error> { Ok(()) }
94    /// # fn example() -> Result<(), CoreError> {
95    /// matrix_operation()
96    ///     .map_err(|e| {
97    ///         CoreError::SymbolicStructure(
98    ///             "Failed to build sparse matrix structure".to_string()
99    ///         )
100    ///         .log_with_source(e)
101    ///     })?;
102    /// # Ok(())
103    /// # }
104    /// ```
105    #[must_use]
106    pub fn log_with_source<E: std::fmt::Debug>(self, source_error: E) -> Self {
107        error!("{} | Source: {:?}", self, source_error);
108        self
109    }
110}
111
112/// Result type for core module operations
113pub type CoreResult<T> = Result<T, CoreError>;
apex_solver/core/mod.rs

apex_solver/core/
mod.rs
