pounce-qp 0.7.0

//! Error and status types for the QP solver.

use std::fmt;

/// Terminal status of a QP solve.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QpStatus {
    /// KKT residual and feasibility within tolerance.
    Optimal,
    /// Phase-1 elastic mode certified the QP as infeasible
    /// (residual elastic slacks are nonzero at the elastic
    /// solution).
    Infeasible,
    /// Descent direction of unbounded length found (only possible
    /// when the reduced Hessian is indefinite or negative semi-
    /// definite along a feasible ray).
    Unbounded,
    /// Iteration limit reached before convergence.
    MaxIter,
    /// Solver detected numerical breakdown (e.g., factor failure
    /// not recoverable by inertia correction).
    NumericalError,
}

impl fmt::Display for QpStatus {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            QpStatus::Optimal => write!(f, "optimal"),
            QpStatus::Infeasible => write!(f, "infeasible"),
            QpStatus::Unbounded => write!(f, "unbounded"),
            QpStatus::MaxIter => write!(f, "max-iter"),
            QpStatus::NumericalError => write!(f, "numerical-error"),
        }
    }
}

/// Hard errors — problems the solver cannot return any meaningful
/// solution for. Soft outcomes (max-iter, infeasible, unbounded) are
/// reported via [`QpStatus`] inside a successful
/// [`crate::QpSolution`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum QpError {
    /// Problem-data dimensions disagree (e.g., `g.len() != n`).
    DimensionMismatch(String),
    /// A bound vector contains `bl > bu` for some index.
    InvertedBounds(String),
    /// Warm-start working set has the wrong length for the problem
    /// dimensions.
    WarmStartDimensionMismatch(String),
    /// Linear-solver backend reported a hard failure that cannot be
    /// recovered by the inertia / refactor logic.
    LinearSolverFailure(String),
    /// Feature required by this QP is not yet implemented in the
    /// current crate phase (e.g., one-sided inequality constraints
    /// before the working-set machinery lands).
    UnsupportedFeature(String),
}

impl QpError {
    /// True when this is a linear-solver failure that the §4.5
    /// inertia-control loop may recover from by shifting the Hessian
    /// diagonal — i.e. a singular factor or a wrong-inertia report.
    ///
    /// Centralizes the recoverability decision so the retry loops in
    /// `solver.rs` and `schur.rs` don't each re-implement a fragile
    /// substring test. The match is **case-insensitive**: some failure
    /// messages embed the backend's `Debug`-formatted `ESymSolverStatus`
    /// (`Singular` / `WrongInertia`, capitalized — produced by
    /// `LinearSolver::resolve`'s catch-all `"resolve backend status:
    /// {status:?}"`), which a bare lowercase `contains("singular")` /
    /// `contains("inertia")` would silently miss, so those failures would
    /// propagate as unrecoverable instead of triggering a shift retry
    /// (L14).
    pub fn is_recoverable_factorization_failure(&self) -> bool {
        match self {
            QpError::LinearSolverFailure(msg) => {
                let m = msg.to_ascii_lowercase();
                m.contains("inertia") || m.contains("singular")
            }
            _ => false,
        }
    }
}

impl fmt::Display for QpError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            QpError::DimensionMismatch(s) => write!(f, "dimension mismatch: {s}"),
            QpError::InvertedBounds(s) => write!(f, "inverted bounds: {s}"),
            QpError::WarmStartDimensionMismatch(s) => {
                write!(f, "warm-start dimension mismatch: {s}")
            }
            QpError::LinearSolverFailure(s) => write!(f, "linear solver failure: {s}"),
            QpError::UnsupportedFeature(s) => write!(f, "unsupported feature: {s}"),
        }
    }
}

impl std::error::Error for QpError {}