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    /// ```ignore
67    /// operation()
68    ///     .map_err(|e| CoreError::from(e).log())?;
69    /// ```
70    #[must_use]
71    pub fn log(self) -> Self {
72        error!("{}", self);
73        self
74    }
75
76    /// Log the error with the original source error from a third-party library
77    ///
78    /// This method logs both the CoreError and the underlying error
79    /// from external libraries. This provides full debugging context when
80    /// errors occur in third-party code.
81    ///
82    /// # Arguments
83    /// * `source_error` - The original error from the third-party library (must implement Debug)
84    ///
85    /// # Example
86    /// ```ignore
87    /// matrix_operation()
88    ///     .map_err(|e| {
89    ///         CoreError::SymbolicStructure(
90    ///             "Failed to build sparse matrix structure".to_string()
91    ///         )
92    ///         .log_with_source(e)
93    ///     })?;
94    /// ```
95    #[must_use]
96    pub fn log_with_source<E: std::fmt::Debug>(self, source_error: E) -> Self {
97        error!("{} | Source: {:?}", self, source_error);
98        self
99    }
100}
101
102/// Result type for core module operations
103pub type CoreResult<T> = Result<T, CoreError>;
apex_solver/core/mod.rs

apex_solver/core/
mod.rs
