Module error 

Error types for the apex-solver library

This module provides the main error and result types used throughout the library. All errors use the thiserror crate for automatic trait implementations.

Error Hierarchy

The library uses a strict three-layer error hierarchy with bubble-up propagation using the ? operator:

• Layer A (Top/API): ApexSolverError — exposed to end-users, wraps all module errors
• Layer B (Logic): OptimizerError, ObserverError — wrap Layer C errors with context
• Layer C (Deep/Math): CoreError, LinAlgError, ManifoldError, FactorError — module-specific errors that must never return ApexSolverError directly

Error Propagation Convention

Deep modules (Layer C) must return their own module-specific error type (e.g., Result<T, CoreError>, not Result<T, ApexSolverError>). The ? operator and #[from] attributes handle automatic conversions at each layer boundary.

Example error chain (Layer C → B → A):

LinAlgError::SingularMatrix
  → OptimizerError::LinAlg (via #[from] at Layer B)
    → ApexSolverError::Optimizer (via #[from] at Layer A)

Dual-Path Convention for LinAlgError

LinAlgError can convert to ApexSolverError via two paths:

1. Direct: LinAlgError → ApexSolverError::LinearAlgebra(...) — for standalone linalg usage
2. Through optimizer: LinAlgError → OptimizerError::LinAlg → ApexSolverError::Optimizer(...) — during optimization

When a LinAlgError occurs inside the optimizer, it should propagate through the optimizer layer (path 2) to preserve optimization context. Standalone linalg usage should use path 1 directly.

Enums

ApexSolverError

Main error type for the apex-solver library

Traits

ErrorLogging

Trait for error logging with chaining support.

Type Aliases

ApexSolverResult

Main result type used throughout the apex-solver library