Coverage for src/cvxcla/errors.py: 100%
8 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 13:36 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 13:36 +0000
1"""Exceptions raised while tracing a frontier.
3A trace can stop for three different reasons, and the remedy differs for each:
5* :class:`InfeasibleProblemError` -- the constraints admit no portfolio at all
6 (bounds that cross, a budget the box cannot reach, an inconsistent equality
7 system, or a linear program that HiGHS proves infeasible). Fix the data.
8* :class:`DegenerateProblemError` -- the problem is feasible but lies outside the
9 domain the algorithm supports: a numerically singular free covariance block, or
10 a maximum-return vertex whose free set cannot span its active constraints. A
11 small ridge, a factor model, or a perturbation of the constraints usually helps.
12* :class:`NumericalError` -- the trace broke down numerically: the iteration cap
13 was hit, the feasibility projection did not converge (:class:`ProjectionError`),
14 or a turning point failed its constraint validation (:class:`FeasibilityError`).
16Every class derives from :class:`CLAError`, and also from the builtin exception the
17package raised before these classes existed (``ValueError`` for the first two,
18``RuntimeError`` for numerical failures, both for :class:`FeasibilityError`), so
19code that catches the builtins keeps working. Malformed input (wrong shapes, a
20non-symmetric covariance, a builder used out of order) still raises a plain
21``ValueError``: those are programming errors, not properties of the problem.
22"""
24from __future__ import annotations
26__all__ = [
27 "CLAError",
28 "DegenerateProblemError",
29 "FeasibilityError",
30 "InfeasibleProblemError",
31 "NumericalError",
32 "ProjectionError",
33]
36class CLAError(Exception):
37 """Base class for every error the tracer raises about the problem or its numerics."""
40class InfeasibleProblemError(CLAError, ValueError):
41 """The constraints admit no portfolio."""
44class DegenerateProblemError(CLAError, ValueError):
45 """The problem is feasible but outside the domain the algorithm supports."""
48class NumericalError(CLAError, RuntimeError):
49 """The trace broke down numerically."""
52class FeasibilityError(NumericalError, ValueError):
53 """A turning point violated a constraint beyond tolerance after projection.
55 Also a ``ValueError``, which is what this check raised before the hierarchy.
56 """
59class ProjectionError(NumericalError):
60 """The feasibility projection of a turning point did not converge.
62 The candidate lay outside its box by more than round-off, or the box and the
63 active constraints barely intersect, so clipping and re-projecting onto
64 ``{w : C w = d}`` did not reach a feasible point. This signals a numerical
65 failure, not an infeasible problem; the remedy is usually a better-conditioned
66 covariance (a small ridge, or a factor model).
67 """