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

1"""Exceptions raised while tracing a frontier. 

2 

3A trace can stop for three different reasons, and the remedy differs for each: 

4 

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`). 

15 

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""" 

23 

24from __future__ import annotations 

25 

26__all__ = [ 

27 "CLAError", 

28 "DegenerateProblemError", 

29 "FeasibilityError", 

30 "InfeasibleProblemError", 

31 "NumericalError", 

32 "ProjectionError", 

33] 

34 

35 

36class CLAError(Exception): 

37 """Base class for every error the tracer raises about the problem or its numerics.""" 

38 

39 

40class InfeasibleProblemError(CLAError, ValueError): 

41 """The constraints admit no portfolio.""" 

42 

43 

44class DegenerateProblemError(CLAError, ValueError): 

45 """The problem is feasible but outside the domain the algorithm supports.""" 

46 

47 

48class NumericalError(CLAError, RuntimeError): 

49 """The trace broke down numerically.""" 

50 

51 

52class FeasibilityError(NumericalError, ValueError): 

53 """A turning point violated a constraint beyond tolerance after projection. 

54 

55 Also a ``ValueError``, which is what this check raised before the hierarchy. 

56 """ 

57 

58 

59class ProjectionError(NumericalError): 

60 """The feasibility projection of a turning point did not converge. 

61 

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 """