cultivars.exceptions

Public exception and warning hierarchy for cultivars.

Every failure the package detects is raised as one of three exceptions, and the three are distinguished by where the failure was found rather than by which module found it. DimensionError is the geometry of an input: a rank, a shape, a length that does not conform. SpecificationError is the content of a choice: an option outside its closed list, an order below its floor, a sample too short for the depth asked of it, a result handed to a consumer that does not expose the surface it reads. NumericalError is the arithmetic: a non-finite value, a covariance that is not positive semidefinite, a singular system, an unstable transition where a stationary solution was required. A user reading a traceback learns from the class alone whether to reshape the data, change the specification, or look at the numbers; the message then names the argument and the permitted values.

Two commitments shape the surface. First, the hierarchy is complete: all three derive from CultivarsError, so except CultivarsError catches everything the package raises on purpose and nothing it raises by accident – an AssertionError or a library error escaping from numpy is a bug and propagates. Second, the hierarchy is compatible: each exception also derives from the builtin that best matches its failure mode, ValueError for the two that concern the argument and RuntimeError for the one that concerns the computation, so code written against the builtins keeps working. StabilityWarning stands apart as a UserWarning because a non-stationary fit is not a failure; it is a fit whose forecasts and impulse responses mean something other than their names promise, and a warning is the honest register for that.

Layout. The four classes are the whole module; there is no __init__ logic, no error-code table, and no message formatting helper, because the raise sites across _core and _internals compose their own messages in one shape – what was expected, what was got – and a central formatter would only hide which check fired. The validators that raise most of them are in _core (validate_endog_matrix, validate_order, validate_choice, validate_transition and their kin), and typing holds the closed lists a SpecificationError quotes.

Example

The class says what kind of fix is needed; the builtin ancestry keeps generic handlers working:

>>> import numpy as np
>>> from cultivars.univariate.box_jenkins import ARIMA
>>> from cultivars.multivariate.reduced_form.vector_autoregression import VAR
>>> attempts = (
...     lambda: VAR(np.zeros((50, 2, 2)), order=1),
...     lambda: ARIMA(np.arange(50.0), order=(1, 0, 0), trend="quadratic"),
...     lambda: ARIMA(np.r_[np.arange(49.0), np.nan], order=(1, 0, 0)),
... )
>>> for attempt in attempts:
...     try:
...         attempt()
...     except CultivarsError as error:
...         print(type(error).__name__, isinstance(error, ValueError))
DimensionError True
SpecificationError True
NumericalError False

Exceptions

CultivarsError	Base class for every exception raised by cultivars.
DimensionError	An array has the wrong shape, rank, or is non-conformable.
ExperimentalWarning	Raised once when cultivars.experimental is imported.
NumericalError	A computation failed numerically (non-finite input, singular system).
SpecificationError	A model, polynomial, or coefficient set is invalid or inconsistent.
StabilityWarning	The warning category for a fitted model that is non-stationary.