Exceptions#

Solver Exceptions#

Exceptions raised by Cvxium’s solvers and their numerical building blocks.

The exceptions fall into four groups:

  • ProblemInfeasibleError, for a problem shown or judged to have no feasible point. optimization defines two subclasses, for a certified and for a suspected infeasibility.

  • NewtonStepError, for a Newton step that cannot be computed, typically because a structured solve met a matrix that is not positive definite.

  • BacktrackingLineSearchError and its subclasses, for each way the backtracking line search can fail to accept a step.

  • OptimizationError and its subclasses, for a solve that stops before reaching its tolerance. These carry the last (or best) iterate so a caller can recover a partial solution.

ConeBoundaryError stands apart: a cone operation that needs a strictly interior point was given one on the boundary.

exception cvxium.exceptions.ProblemInfeasibleError[source]#

Bases: Exception

Error raised when a problem has, or appears to have, no feasible point.

Raised, for example, when the equality constraints A x = b have no solution because b is not in the range of A, or when Phase I finds no strictly interior point. The subclasses ProblemCertifiablyInfeasibleError and ProblemMarginallyFeasibleError distinguish a proof of infeasibility from a failure to find a feasible point.

exception cvxium.exceptions.NewtonStepError(message)[source]#

Bases: Exception

Error raised when a Newton step cannot be computed.

Raised by the structured linear-system solvers when the purported Hessian (or KKT system) is not positive definite, is singular, or yields a non-finite result. A solver that catches it can fall back rather than take a corrupt step.

Parameters:

message (str) – Description of the failure.

exception cvxium.exceptions.BacktrackingLineSearchError(message)[source]#

Bases: Exception

Base error for a backtracking line search that cannot accept a step.

The line search raises one of the subclasses, which name the cause: ConstraintBoundaryError, InvalidDescentDirectionError or SevereCurvatureError. Catch this class to handle any of them.

Parameters:

message (str) – Description of the failure.

exception cvxium.exceptions.ConstraintBoundaryError(message)[source]#

Bases: BacktrackingLineSearchError

Error raised when even tiny steps would leave the feasible region.

Raised by the line search when the largest step that keeps every constraint strictly satisfied is below the minimum step size, so the iterate is pinned against a constraint boundary.

Parameters:

message (str) – Description of the failure.

exception cvxium.exceptions.InvalidDescentDirectionError(message, grad_ft_dot_delta_x)[source]#

Bases: BacktrackingLineSearchError

Error raised when the Newton step is not a descent direction.

A Newton step Δx should satisfy

∇f^T Δx ≤ 0.

When it does not, the Hessian is usually nearly singular and the step was computed inaccurately.

Parameters:

  • message (str) – Description of the failure.

  • grad_ft_dot_delta_x (float) – The directional derivative ∇f^T Δx, which was positive.

exception cvxium.exceptions.SevereCurvatureError(message, required_improvement, actual_improvement)[source]#

Bases: BacktrackingLineSearchError

Error raised when no step size meets the sufficient-decrease condition.

The line search backtracked to its minimum step size without the objective decreasing enough. Usually the linear approximation fails even for small steps, a sign of severe curvature.

Parameters:

  • message (str) – Description of the failure.

  • required_improvement (float) – Decrease in the merit function required at the last step tried.

  • actual_improvement (float) – Decrease actually achieved at that step.

exception cvxium.exceptions.OptimizationError(message, suboptimality, last_iterate)[source]#

Bases: Exception

Base error for a solve that stops before reaching its tolerance.

Carries the last iterate and how far it was from optimal, so a caller can inspect or reuse a partial solution.

Parameters:

  • message (str) – Description of the failure.

  • suboptimality (float) – Bound on, or estimate of, the suboptimality of last_iterate when the solve stopped.

  • last_iterate (npt.NDArray[np.float64]) – The iterate when the solve stopped.

exception cvxium.exceptions.CenteringStepError(message, suboptimality, last_iterate, equality_multipliers=None, inequality_multipliers=None)[source]#

Bases: OptimizationError

Error raised when a centering step of the barrier method fails.

Raised when the Newton step cannot be computed, the line search fails, or the centering Newton iterations do not converge. When available, the error also carries the multiplier estimates at the last iterate.

Parameters:

  • message (str) – Description of the failure.

  • suboptimality (float) – Suboptimality bound of the centering subproblem at last_iterate.

  • last_iterate (npt.NDArray[np.float64]) – The iterate when the centering step stopped.

  • equality_multipliers (npt.NDArray[np.float64] | None) – Equality multiplier estimates ν at last_iterate, when available.

  • inequality_multipliers (npt.NDArray[np.float64] | None) – Inequality multiplier estimates λ at last_iterate, when available.

exception cvxium.exceptions.InteriorPointMethodError(message, remaining_steps, suboptimality, last_iterate, result=None)[source]#

Bases: OptimizationError

Error raised when the interior-point method cannot reach its tolerance.

When available, the error carries the best primal-dual result found before stopping. That result may not meet the soft tolerance, but it is often good enough; inspect its objective and duality gap before re-running with a looser tolerance.

Parameters:

  • message (str) – Description of the failure.

  • remaining_steps (int) – Number of outer barrier steps left in the schedule when the method stopped.

  • suboptimality (float) – Bound on the suboptimality of last_iterate.

  • last_iterate (npt.NDArray[np.float64]) – The iterate when the method stopped.

  • result (SolveResult | None) – The best result found before stopping, when available.

Infeasibility#

exception cvxium.solvers.optimization.ProblemCertifiablyInfeasibleError(message, result)[source]#

Bases: ProblemInfeasibleError

Error raised when a problem is certifiably infeasible.

Raised when a feasibility (Phase I) solve certifies that no feasible point exists, typically through a strictly positive dual value of the Phase I problem. Carries the best-effort result of the solve.

Parameters:

  • message (str) – Description of the failure, returned by str.

  • result (SolveResult) – The best-effort result of the solve.

property solve_result#

Return the best-effort result of the solve.

Returns:

result – The result given at construction.

Return type:

SolveResult

exception cvxium.solvers.optimization.ProblemMarginallyFeasibleError(message, result)[source]#

Bases: ProblemInfeasibleError

Error raised when a problem may be infeasible but cannot be certified as such.

Raised when a feasibility (Phase I) solve neither finds a strictly feasible point nor certifies infeasibility. Carries the best-effort result of the solve.

Parameters:

  • message (str) – Description of the failure, returned by str.

  • result (SolveResult) – The best-effort result of the solve.

property solve_result#

Return the best-effort result of the solve.

Returns:

result – The result given at construction.

Return type:

SolveResult

Result Access#

exception cvxium.problems.result.NoObjectiveError[source]#

Bases: AttributeError

Error raised when objective fields are read from a feasibility result.

exception cvxium.problems.result.NoDualsError[source]#

Bases: AttributeError

Error raised when reading multipliers from a result that has none.

exception cvxium.problems.result.NoDualValueError[source]#

Bases: AttributeError

Error raised when dual_value is read but the solver did not compute one.

exception cvxium.problems.result.WrongDiagnosticsError[source]#

Bases: TypeError

Error raised when diagnostics are narrowed to the wrong solver engine.

Structure#

exception cvxium.linalg.systems.IncompatibleStructureError[source]#

Bases: ValueError

Error raised when two MatrixSystem shapes cannot be summed structurally.

Bases of the same shape, or a base and a strictly simpler one, combine through MatrixSystem.plus; an incompatible pair, such as a banded matrix and a block-diagonal one, raises this rather than silently forming a dense matrix. A low-rank update sits on top of any base, so it never raises this by itself.