volengine 0.9.0__py3-none-win_amd64.whl

volengine/__init__.py

@@ -0,0 +1,37 @@
+"""VolEngine: GARCH estimation over the VolEngine C API."""
+
+from .api import (
+    CoefTable,
+    Context,
+    DccFit,
+    DccForecast,
+    DccSimulation,
+    DccSpec,
+    DiagnosticResult,
+    Fit,
+    FitOptions,
+    Forecast,
+    Nyblom,
+    SignBias,
+    Simulation,
+    Spec,
+    VolEngineError,
+)
+
+__all__ = [
+    "CoefTable",
+    "Context",
+    "DccFit",
+    "DccForecast",
+    "DccSimulation",
+    "DccSpec",
+    "DiagnosticResult",
+    "Fit",
+    "FitOptions",
+    "Forecast",
+    "Nyblom",
+    "SignBias",
+    "Simulation",
+    "Spec",
+    "VolEngineError",
+]

volengine/_dcc.py

@@ -0,0 +1,264 @@
+"""DCC specifications, batch fitting and immutable native results."""
+
+from __future__ import annotations
+
+import ctypes
+import operator
+from collections.abc import Callable, Mapping, Sequence
+from contextlib import ExitStack
+from dataclasses import KW_ONLY, dataclass, field
+from typing import Any, cast
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from ._fit import IC_PER_OBS, IC_TOTAL, SE_KINDS, CoefTable, Fit, status_name
+from ._forecast import DccForecast
+from ._native import ELEMENT_BYTES, Handle, check, create_handle, int32, lib, native_view, open_panel, read_scalar
+from ._spec import code_of, encoded_name, frozen_values
+
+MODELS = {"dcc": 0, "adcc": 1, "fdcc": 2, "static": 3}
+COPULAS = {"parametric": 1, "empirical": 2}
+STATIC_METHODS = {"kendall": 1, "ml": 2}
+DISTRIBUTIONS = {"mvnorm": 0, "mvt": 1, "mvlaplace": 2}
+
+
+@dataclass(frozen=True)
+class DccSpec:
+    """Second-stage DCC model, using the paper convention.
+
+    FDCC needs one group label per series, consecutive from 1, and order (1, 1).
+    Fixed parameters are excluded from coefficient tables and information criteria.
+
+    copula="parametric" (each fit's cdf) or "empirical" (ranks) makes it a Copula-DCC on
+    the normal or Student scores of the margins; model="static" is a constant-correlation
+    copula, with static_method "kendall" (the default) or "ml", whose C1.. are the free
+    entries of A in R = cov2cor(A A'), as in rmgarch.
+    """
+
+    model: str = "dcc"
+    _: KW_ONLY
+    order: tuple[int, int] = (1, 1)
+    dist: str = "mvnorm"
+    groups: Sequence[int] | None = None
+    fixed: Mapping[str, float] = field(default_factory=dict)
+    start: Mapping[str, float] = field(default_factory=dict)
+    copula: str | None = None
+    static_method: str | None = None
+
+    def __post_init__(self) -> None:
+        if len(self.order) != 2 or any(type(value) is not int for value in self.order):
+            raise ValueError("order must be a pair of integers (p, q)")
+        object.__setattr__(self, "order", tuple(self.order))
+        if self.groups is not None:
+            object.__setattr__(self, "groups", tuple(self.groups))
+        object.__setattr__(self, "fixed", frozen_values(self.fixed))
+        object.__setattr__(self, "start", frozen_values(self.start))
+        self.native_handle().close()
+
+    def __hash__(self) -> int:
+        groups = None
+        if self.groups is not None:
+            groups = tuple(self.groups)
+        return hash((self.model, self.order, self.dist, groups, frozenset(self.fixed.items()), frozenset(self.start.items()),
+                     self.copula, self.static_method))
+
+    def native_handle(self) -> Handle:
+        model = code_of(MODELS, "model", self.model)
+        dist = code_of(DISTRIBUTIONS, "dist", self.dist)
+        handle = create_handle(lib.ve_dcc_spec_create, lib.ve_dcc_spec_free, model)
+        check(lib.ve_dcc_spec_set_order(handle.pointer, int32(self.order[0], "p"), int32(self.order[1], "q")))
+        check(lib.ve_dcc_spec_set_dist(handle.pointer, dist))
+        if self.groups is not None:
+            groups = (ctypes.c_int32 * len(self.groups))(*(int32(value, "group") for value in self.groups))
+            check(lib.ve_dcc_spec_set_groups(handle.pointer, groups, len(groups)))
+        for name, value in self.fixed.items():
+            check(lib.ve_dcc_spec_set_fixed(handle.pointer, encoded_name(name), value))
+        for name, value in self.start.items():
+            check(lib.ve_dcc_spec_set_start(handle.pointer, encoded_name(name), value))
+        if self.copula is not None:
+            check(lib.ve_dcc_spec_set_copula(handle.pointer, code_of(COPULAS, "copula", self.copula)))
+        if self.static_method is not None:
+            method = code_of(STATIC_METHODS, "static_method", self.static_method)
+            check(lib.ve_dcc_spec_set_static_method(handle.pointer, method))
+        return handle
+
+
+def fit_pointers(fits: Sequence[Fit]) -> Any:
+    if any(not isinstance(fit, Fit) for fit in fits):
+        raise TypeError("univariate must contain Fit objects")
+    return (ctypes.c_void_p * len(fits))(*(fit._handle.pointer for fit in fits))
+
+
+def fit_dcc(context: Handle, spec: DccSpec | Sequence[DccSpec], univariate: Sequence[Fit], standard_errors: bool) -> list[DccFit]:
+    specs: list[DccSpec] = []
+    if isinstance(spec, DccSpec):
+        specs.append(spec)
+    if not isinstance(spec, DccSpec):
+        specs = list(spec)
+    if not specs:
+        raise ValueError("fit_dcc needs at least one spec")
+    if any(not isinstance(item, DccSpec) for item in specs):
+        raise TypeError("spec must contain DccSpec objects")
+    fits = fit_pointers(univariate)
+    with ExitStack() as stack:
+        handles = [stack.enter_context(item.native_handle()) for item in specs]
+        pointers = (ctypes.c_void_p * len(handles))(*(handle.pointer for handle in handles))
+        options = stack.enter_context(create_handle(lib.ve_dcc_options_create, lib.ve_dcc_options_free))
+        check(lib.ve_dcc_options_set_standard_errors(options.pointer, int(standard_errors)))
+        batch = stack.enter_context(create_handle(lib.ve_dcc_batch_create, lib.ve_dcc_batch_free))
+        check(lib.ve_dcc_batch_set_specs(batch.pointer, pointers, len(handles)))
+        check(lib.ve_dcc_batch_set_fits(batch.pointer, fits, len(univariate)))
+        check(lib.ve_dcc_batch_set_options(batch.pointer, options.pointer))
+        out = (ctypes.c_void_p * len(specs))()
+        check(lib.ve_dcc_fit_batch(context.pointer, batch.pointer, out))
+        owned = [Handle(pointer, lib.ve_dcc_fit_free) for pointer in out]
+        return [DccFit(handle) for handle in owned]
+
+
+def future_panel_of(stack: ExitStack, values: ArrayLike | None) -> int | None:
+    """The native panel of one series' regressors of the horizon (T x k, or (T,) for one), None for none."""
+    if values is None:
+        return None
+    array = np.asarray(values, dtype=np.float64)
+    if array.ndim == 1:
+        array = array[:, None]
+    if array.ndim != 2:
+        raise ValueError(f"the regressors of a series must be 1D or 2D, got {array.ndim} dimensions")
+    if any(stride % ELEMENT_BYTES for stride in array.strides):
+        array = np.ascontiguousarray(array)
+    return open_panel(stack, array).pointer
+
+
+def listed(entries: Sequence[ArrayLike | None] | None) -> list[ArrayLike | None] | None:
+    if entries is None:
+        return None
+    return list(entries)
+
+
+def entry_of(entries: list[ArrayLike | None] | None, series: int) -> ArrayLike | None:
+    if entries is None:
+        return None
+    return entries[series]
+
+
+def open_future(
+    stack: ExitStack,
+    horizon: int,
+    mxreg: Sequence[ArrayLike | None] | None,
+    vxreg: Sequence[ArrayLike | None] | None,
+) -> int | None:
+    """The native regressors of the horizon, one entry per series, or None when no series has any."""
+    if mxreg is None and vxreg is None:
+        return None
+    mean = listed(mxreg)
+    variance = listed(vxreg)
+    if mean is not None and variance is not None and len(mean) != len(variance):
+        raise ValueError(f"mxreg and vxreg must have one entry per series, got {len(mean)} and {len(variance)}")
+    entries = mean if mean is not None else variance
+    assert entries is not None
+    future = stack.enter_context(create_handle(lib.ve_dcc_future_create, lib.ve_dcc_future_free, len(entries), horizon))
+    for series in range(len(entries)):
+        mean_panel = future_panel_of(stack, entry_of(mean, series))
+        variance_panel = future_panel_of(stack, entry_of(variance, series))
+        check(lib.ve_dcc_future_set(future.pointer, series, mean_panel, variance_panel))
+    return future.pointer
+
+
+class DccFit:
+    """One DCC result. R and H are read-only views that keep the result alive.
+
+    H is computed once on first access. Standard errors can be added to a new
+    result using the original ordered univariate fits; regressor fits are unsupported.
+
+    A fit made by `Context.fit_dcc` keeps the final state of each series and of its correlation recursion, so
+    `forecast` and `Context.simulate` do not need the univariate `Fit` objects, which `standard_errors` does need
+    because it refilters the whole sample.
+    """
+
+    def __init__(self, handle: Handle) -> None:
+        self._handle = handle
+        self.status = status_name(read_scalar(ctypes.c_int32, lib.ve_dcc_fit_status, handle.pointer))
+        self.nobs = read_scalar(ctypes.c_size_t, lib.ve_dcc_fit_nobs, handle.pointer)
+        self.series = read_scalar(ctypes.c_size_t, lib.ve_dcc_fit_series, handle.pointer)
+        count = read_scalar(ctypes.c_size_t, lib.ve_dcc_fit_param_count, handle.pointer)
+        self.names = tuple(self._param_name(index) for index in range(count))
+
+    def _param_name(self, index: int) -> str:
+        name = read_scalar(ctypes.c_char_p, lib.ve_dcc_fit_param_name, self._handle.pointer, index)
+        return cast(bytes, name).decode("utf-8")
+
+    @property
+    def R(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_dcc_fit_correlation, self._handle.pointer).reshape(-1, self.series, self.series)
+
+    @property
+    def H(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_dcc_fit_covariance, self._handle.pointer).reshape(-1, self.series, self.series)
+
+    @property
+    def loglik(self) -> float:
+        return cast(float, read_scalar(ctypes.c_double, lib.ve_dcc_fit_loglik, self._handle.pointer))
+
+    def aic(self, *, per_obs: bool = True) -> float:
+        return self._criterion(0, per_obs)
+
+    def bic(self, *, per_obs: bool = True) -> float:
+        return self._criterion(1, per_obs)
+
+    def hqic(self, *, per_obs: bool = True) -> float:
+        return self._criterion(2, per_obs)
+
+    def sic(self, *, per_obs: bool = True) -> float:
+        return self._criterion(3, per_obs)
+
+    def _criterion(self, kind: int, per_obs: bool) -> float:
+        scale = IC_PER_OBS if per_obs else IC_TOTAL
+        return cast(float, read_scalar(ctypes.c_double, lib.ve_dcc_fit_criterion, self._handle.pointer, kind, scale))
+
+    def coef(self, se: str = "hessian") -> CoefTable:
+        kind = code_of(SE_KINDS, "se", se)
+        return CoefTable(
+            self.names,
+            self._values(lib.ve_dcc_fit_estimates),
+            self._values(lib.ve_dcc_fit_std_errors, kind),
+            self._values(lib.ve_dcc_fit_t_values, kind),
+            self._values(lib.ve_dcc_fit_p_values, kind),
+        )
+
+    def _values(self, function: Callable[..., int], *args: Any) -> NDArray[np.float64]:
+        out = np.empty(len(self.names), dtype=np.float64)
+        check(function(self._handle.pointer, *args, out.ctypes.data))
+        return out
+
+    def forecast(
+        self,
+        horizon: int,
+        *,
+        mxreg: Sequence[ArrayLike | None] | None = None,
+        vxreg: Sequence[ArrayLike | None] | None = None,
+    ) -> DccForecast:
+        """R, H, sigma and mean for h = 1..horizon after the last observation, as rmgarch's dccforecast (n.roll = 0).
+
+        `mxreg` and `vxreg` hold, for each series, the regressors of the horizon ((horizon, k), or (horizon,) for
+        one) or None for a series without; a series' regressors must match its spec (VolEngineError naming the
+        series, from 1, otherwise). A fit with no finite point raises VolEngineError. The fit keeps what it needs:
+        the univariate `Fit` objects can be freed. See `DccForecast` for the rules of R.
+        """
+        horizon = operator.index(horizon)
+        if horizon < 1:
+            raise ValueError(f"horizon must be at least 1, got {horizon}")
+        with ExitStack() as stack:
+            future = open_future(stack, horizon, mxreg, vxreg)
+            handle = create_handle(
+                lib.ve_dcc_forecast_create, lib.ve_dcc_forecast_free, self._handle.pointer, horizon, future
+            )
+        return DccForecast(handle)
+
+    def standard_errors(self, univariate: Sequence[Fit]) -> DccFit:
+        fits = fit_pointers(univariate)
+        with create_handle(lib.ve_context_create, lib.ve_context_free) as context:
+            return DccFit(create_handle(
+                lib.ve_dcc_fit_standard_errors, lib.ve_dcc_fit_free,
+                context.pointer, self._handle.pointer, fits, len(univariate),
+            ))

volengine/_diagnostics.py

@@ -0,0 +1,51 @@
+"""Diagnostic result types and native array readers."""
+
+from __future__ import annotations
+
+import operator
+from collections.abc import Callable
+from typing import Any, NamedTuple
+
+import numpy as np
+
+from ._native import check, lib
+
+
+class DiagnosticResult(NamedTuple):
+    statistic: float
+    p_value: float
+
+
+class SignBias(NamedTuple):
+    sign: DiagnosticResult
+    negative: DiagnosticResult
+    positive: DiagnosticResult
+    joint: DiagnosticResult
+
+
+class Nyblom(NamedTuple):
+    individual: dict[str, float]
+    joint: float
+    individual_critical: tuple[float, float, float]
+    joint_critical: tuple[float, float, float] | None
+
+
+def size_argument(value: int, name: str) -> int:
+    value = operator.index(value)
+    if not 0 <= value < 2**64:
+        raise ValueError(f"{name} must be an integer in [0, 2**64), got {value}")
+    return value
+
+
+def read_test(function: Callable[..., int], *args: Any) -> DiagnosticResult:
+    out = np.empty(2, dtype=np.float64)
+    check(function(*args, out.ctypes.data))
+    return DiagnosticResult(float(out[0]), float(out[1]))
+
+
+def critical_values(parameters: int) -> tuple[float, float, float] | None:
+    if not 1 <= parameters <= 20:
+        return None
+    out = np.empty(3, dtype=np.float64)
+    check(lib.ve_nyblom_critical(parameters, out.ctypes.data))
+    return float(out[0]), float(out[1]), float(out[2])

volengine/_fit.py

@@ -0,0 +1,209 @@
+"""Fit results over ve_fit handles: coefficient tables, read-only views and information criteria."""
+
+from __future__ import annotations
+
+import ctypes
+import operator
+from collections.abc import Callable
+from contextlib import ExitStack
+from typing import Any, NamedTuple, cast
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from ._diagnostics import DiagnosticResult, Nyblom, SignBias, critical_values, read_test, size_argument
+from ._forecast import Forecast
+from ._native import (
+    ELEMENT_BYTES,
+    Handle,
+    check,
+    create_handle,
+    lib,
+    native_view,
+    open_panel,
+    read_scalar,
+)
+from ._spec import code_of
+
+STATUS_NAMES = {0: "converged", 1: "max_iter", 2: "failed", 3: "insufficient_data"}
+SE_KINDS = {"hessian": 0, "robust": 1}
+IC_PER_OBS = 0
+IC_TOTAL = 1
+
+
+def status_name(code: int) -> str:
+    """The name of a VE_FIT_* code; a code newer than this package is "unknown(<code>)"."""
+    return STATUS_NAMES.get(code, f"unknown({code})")
+
+
+class CoefTable(NamedTuple):
+    names: tuple[str, ...]
+    estimate: NDArray[np.float64]
+    std_error: NDArray[np.float64]
+    t_value: NDArray[np.float64]
+    p_value: NDArray[np.float64]
+
+
+class Fit:
+    """One fitted model. Owns its native handle; the arrays it returns keep it alive.
+
+    `status` is "converged", "max_iter", "failed" or "insufficient_data" ("unknown(<code>)" for a status
+    added by a newer native library). A "failed" fit may carry the values of the best finite point the
+    optimizer reached, or NaN (with empty series) when it reached none. An "insufficient_data" fit is
+    always NaN with empty series. Check `status` before using the values.
+    """
+
+    status: str
+    nobs: int
+    names: tuple[str, ...]
+
+    def __init__(self, handle: Handle) -> None:
+        self._handle = handle
+        pointer = handle.pointer
+        self.status = status_name(read_scalar(ctypes.c_int32, lib.ve_fit_status, pointer))
+        self.nobs = read_scalar(ctypes.c_size_t, lib.ve_fit_nobs, pointer)
+        count = read_scalar(ctypes.c_size_t, lib.ve_fit_param_count, pointer)
+        self.names = tuple(self._param_name(index) for index in range(count))
+
+    def _param_name(self, index: int) -> str:
+        text = read_scalar(ctypes.c_char_p, lib.ve_fit_param_name, self._handle.pointer, index)
+        return cast(bytes, text).decode("utf-8")
+
+    @property
+    def sigma(self) -> NDArray[np.float64]:
+        return self._view(lib.ve_fit_sigma)
+
+    @property
+    def residuals(self) -> NDArray[np.float64]:
+        return self._view(lib.ve_fit_residuals)
+
+    @property
+    def std_residuals(self) -> NDArray[np.float64]:
+        return self._view(lib.ve_fit_std_residuals)
+
+    @property
+    def fitted(self) -> NDArray[np.float64]:
+        return self._view(lib.ve_fit_fitted)
+
+    @property
+    def loglik(self) -> float:
+        return cast(float, read_scalar(ctypes.c_double, lib.ve_loglik, self._handle.pointer))
+
+    def aic(self, *, per_obs: bool = True) -> float:
+        return self._criterion(lib.ve_aic, per_obs)
+
+    def bic(self, *, per_obs: bool = True) -> float:
+        return self._criterion(lib.ve_bic, per_obs)
+
+    def hqic(self, *, per_obs: bool = True) -> float:
+        return self._criterion(lib.ve_hqic, per_obs)
+
+    def sic(self, *, per_obs: bool = True) -> float:
+        return self._criterion(lib.ve_sic, per_obs)
+
+    def _criterion(self, function: Callable[..., int], per_obs: bool) -> float:
+        scale = IC_PER_OBS if per_obs else IC_TOTAL
+        return cast(float, read_scalar(ctypes.c_double, function, self._handle.pointer, scale))
+
+    @property
+    def estimate(self) -> NDArray[np.float64]:
+        """The estimates, in `names` order; also on a fit made with FitOptions(standard_errors=False)."""
+        return self._values(lib.ve_fit_estimates)
+
+    def coef(self, se: str = "hessian") -> CoefTable:
+        kind = code_of(SE_KINDS, "se", se)
+        return CoefTable(
+            self.names,
+            self._values(lib.ve_fit_estimates),
+            self._values(lib.ve_fit_std_errors, kind),
+            self._values(lib.ve_fit_t_values, kind),
+            self._values(lib.ve_fit_p_values, kind),
+        )
+
+    def _values(self, function: Callable[..., int], *args: Any) -> NDArray[np.float64]:
+        out = np.empty(len(self.names), dtype=np.float64)
+        check(function(self._handle.pointer, *args, out.ctypes.data))
+        return out
+
+    def _view(self, function: Callable[..., int]) -> NDArray[np.float64]:
+        return native_view(self, function, self._handle.pointer)
+
+    def ljung_box(self, lag: int, *, squared: bool = False, fitdf: int = 0) -> DiagnosticResult:
+        """Weighted Ljung-Box. show() uses lags 1, max(2, 3*d-1), max(5, 5*d-1).
+
+        d is the ARMA order sum (residuals) or p+q (squares). fitdf is forced to zero for squares.
+        Requires 1 <= lag < nobs and lag >= 3*fitdf-1. Constant autocorrelations return NaN.
+        """
+        lag = size_argument(lag, "lag")
+        fitdf = size_argument(fitdf, "fitdf")
+        return read_test(lib.ve_fit_ljung_box, self._handle.pointer, int(squared), lag, fitdf)
+
+    def arch_lm(self, lag: int, *, fitdf: int) -> DiagnosticResult:
+        """Weighted ARCH-LM. show() uses fitdf=p+q and lags fitdf+1, fitdf+3, fitdf+5."""
+        lag = size_argument(lag, "lag")
+        fitdf = size_argument(fitdf, "fitdf")
+        return read_test(lib.ve_fit_arch_lm, self._handle.pointer, lag, fitdf)
+
+    def nyblom(self) -> Nyblom:
+        """Parameter stability, with Hansen critical values at 10%, 5%, 1%."""
+        values = np.empty(len(self.names), dtype=np.float64)
+        estimated = np.empty(len(self.names), dtype=np.int32)
+        joint = ctypes.c_double()
+        check(lib.ve_fit_nyblom(self._handle.pointer, values.ctypes.data, ctypes.byref(joint), estimated.ctypes.data))
+        roles = zip(self.names, values, estimated, strict=True)
+        individual = {name: float(value) for name, value, flag in roles if flag}
+        individual_critical = critical_values(1)
+        assert individual_critical is not None
+        return Nyblom(individual, joint.value, individual_critical, critical_values(len(individual)))
+
+    def sign_bias(self) -> SignBias:
+        """Engle-Ng tests with lagged raw residuals, as in rugarch."""
+        out = np.empty(8, dtype=np.float64)
+        check(lib.ve_fit_sign_bias(self._handle.pointer, out.ctypes.data))
+        tests = [DiagnosticResult(float(out[i]), float(out[i + 1])) for i in range(0, 8, 2)]
+        return SignBias(*tests)
+
+    def gof(self, groups: int = 20) -> DiagnosticResult:
+        """Adjusted Pearson goodness of fit, 2 <= groups <= nobs. show() uses 20, 30, 40 and 50 groups."""
+        return read_test(lib.ve_fit_gof, self._handle.pointer, size_argument(groups, "groups"))
+
+    def forecast(self, horizon: int, *, mxreg: ArrayLike | None = None, vxreg: ArrayLike | None = None) -> Forecast:
+        """sigma and mean for h = 1..horizon after the last observation, as rugarch's ugarchforecast (n.roll = 0).
+
+        `mxreg` and `vxreg` are the regressors of the horizon, (horizon, k) for a spec with k of them ((horizon,)
+        when k = 1), and must be absent when the spec has none. A fit with no finite point raises VolEngineError.
+        See `Forecast` for what `sigma` means in eGARCH, apARCH and fGARCH.
+        """
+        horizon = operator.index(horizon)
+        if horizon < 1:
+            raise ValueError(f"horizon must be at least 1, got {horizon}")
+        with ExitStack() as stack:
+            mean = self._future(stack, mxreg, "mxreg", horizon)
+            variance = self._future(stack, vxreg, "vxreg", horizon)
+            handle = create_handle(
+                lib.ve_forecast_create, lib.ve_forecast_free, self._handle.pointer, horizon, mean, variance
+            )
+        return Forecast(handle)
+
+    def _future(self, stack: ExitStack, values: ArrayLike | None, name: str, horizon: int) -> int | None:
+        """The native panel of the regressors of the horizon, or None for a spec without them."""
+        count = sum(1 for parameter in self.names if parameter.startswith(name))
+        return future_panel(stack, values, name, count, horizon)
+
+
+def future_panel(stack: ExitStack, values: ArrayLike | None, name: str, count: int, horizon: int) -> int | None:
+    """The native panel of `count` regressors over the horizon, or None when the spec has none."""
+    if count == 0:
+        if values is not None:
+            raise ValueError(f"{name} was given but the spec has no {name}")
+        return None
+    if values is None:
+        raise ValueError(f"the spec has {name} = {count}, so {name} is required")
+    array = np.asarray(values, dtype=np.float64)
+    if array.ndim == 1 and count == 1:
+        array = array[:, None]
+    if array.shape != (horizon, count):
+        raise ValueError(f"{name} must have shape {(horizon, count)}, got {array.shape}")
+    if any(stride % ELEMENT_BYTES for stride in array.strides):
+        array = np.ascontiguousarray(array)
+    return open_panel(stack, array).pointer

volengine/_forecast.py

@@ -0,0 +1,65 @@
+"""Forecasts over ve_forecast handles."""
+
+from __future__ import annotations
+
+import ctypes
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ._native import Handle, lib, native_view, read_scalar
+
+
+class DccForecast:
+    """The forecast of a DCC fit for h = 1..horizon after its last observation, as rmgarch's dccforecast.
+
+    `R` and `H` are read-only arrays of shape (horizon, N, N), `sigma` and `mean` of shape (horizon, N). `sigma`
+    and `mean` are those of each series' own `Fit.forecast`. `R[0]` is the exact recursion one step after the last
+    observation and, for h >= 2, R[h - 1] = (1 - k^(h-1)) Rbar + k^(h-1) R[0] with k the total persistence sum(a) +
+    sum(b) (the aDCC g does not enter; the FDCC takes k per element; a static copula keeps its R) and Rbar the
+    correlation of Qbar. `H = D R D` with D = diag(sigma). The forecast does not depend on its fit.
+    """
+
+    def __init__(self, handle: Handle) -> None:
+        self._handle = handle
+        self._series = read_scalar(ctypes.c_size_t, lib.ve_dcc_forecast_series, handle.pointer)
+        self._horizon = read_scalar(ctypes.c_size_t, lib.ve_dcc_forecast_horizon, handle.pointer)
+
+    @property
+    def R(self) -> NDArray[np.float64]:
+        view = native_view(self, lib.ve_dcc_forecast_correlation, self._handle.pointer)
+        return view.reshape(self._horizon, self._series, self._series)
+
+    @property
+    def H(self) -> NDArray[np.float64]:
+        view = native_view(self, lib.ve_dcc_forecast_covariance, self._handle.pointer)
+        return view.reshape(self._horizon, self._series, self._series)
+
+    @property
+    def sigma(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_dcc_forecast_sigma, self._handle.pointer).reshape(self._horizon, self._series)
+
+    @property
+    def mean(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_dcc_forecast_mean, self._handle.pointer).reshape(self._horizon, self._series)
+
+
+class Forecast:
+    """The forecast of a fit for h = 1..horizon after its last observation, as rugarch's ugarchforecast.
+
+    `sigma` and `mean` are read-only arrays of shape (horizon,). `sigma` is rugarch's sigmaFor: the square root of
+    the expected variance in sGARCH, iGARCH, gjrGARCH and csGARCH, but exp(E[log sigma2] / 2) in eGARCH and
+    E[sigma^delta]^(1/delta) in apARCH and fGARCH, which for h > 1 is not sqrt(E[sigma2]). `mean` is the
+    conditional mean (rugarch's seriesFor). The forecast does not depend on its fit.
+    """
+
+    def __init__(self, handle: Handle) -> None:
+        self._handle = handle
+
+    @property
+    def sigma(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_forecast_sigma, self._handle.pointer)
+
+    @property
+    def mean(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_forecast_mean, self._handle.pointer)