VolatilityProcess#

class impulso.protocols.VolatilityProcess(*args, **kwargs)[source]#

Bases: Protocol

Contract for volatility processes.

A VolatilityProcess owns the construction of the structural-shock covariance Σ_t — for constant adapters, Σ is shared across time; for stochastic adapters, Σ_t evolves. The seam’s primary output is the lower-triangular Cholesky factor L_t such that Σ_t = L_t @ L_t.T. See docs/adr/0001-volatility-process-seam-exposes-cholesky-factor.md.

A VolatilityProcess owns how big the error is and never what shape its tails take — that is the ErrorDistribution seam, which chooses the law the standardised innovations are drawn from. The two are siblings and the separation is strict in both directions: no adapter here may widen a tail, and no error distribution may set a scale.

Adapters own their downstream computation: time-t query and forward simulation for forecasts.

cholesky_at(posterior, t)[source]#

Posterior draws of the Cholesky factor at time t.

Returns shape (chains, draws, n_vars, n_vars). For constant volatility, t is ignored. For stochastic volatility, indexes into the time dimension; t=None defaults to the most recent period.

Parameters:

  • posterior (xr.Dataset)

  • t (int | None)

Return type:

ndarray

cholesky_path(posterior, T)[source]#

Posterior draws of the Cholesky factor path across all in-sample t.

Returns shape (chains, draws, T, n_vars, n_vars). For constant volatility, broadcasts the time-invariant L across the requested T. For stochastic volatility, indexes into the latent log-vol posterior to construct L_t for each t.

Parameters:

  • posterior (xr.Dataset)

  • T (int)

Return type:

ndarray

forecast_cholesky_path(posterior, steps, rng)[source]#

Posterior-predictive Cholesky factors for steps ahead.

Returns shape (chains, draws, steps, n_vars, n_vars). For constant volatility, broadcasts the constant L across steps. For stochastic volatility, simulates forward from posterior dynamics.

Parameters:
Return type:

ndarray

is_time_varying: bool#

Whether Σ_t evolves over time. False for homoscedastic adapters (Constant); True for stochastic-volatility adapters. Drives branching in FittedVAR.sigma and IdentifiedVAR.historical_decomposition so neither has to string-sniff the adapter name.