volengine 0.9.0__py3-none-win_amd64.whl

volengine/_native.py

@@ -0,0 +1,329 @@
+"""ctypes bindings that mirror include/volengine/volengine.h."""
+
+from __future__ import annotations
+
+import ctypes
+import os
+from collections.abc import Callable, Mapping
+from contextlib import ExitStack
+from pathlib import Path
+from types import TracebackType
+from typing import Any, cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+VE_ABI_VERSION = 0
+VE_INTERNAL_ERROR = 5
+INT32_MIN = -(2**31)
+INT32_MAX = 2**31 - 1
+LIBRARY_ENV = "VOLENGINE_LIB"
+LIBRARY_DIRECTORY = Path(__file__).resolve().parent / "_lib"
+LIBRARY_NAMES = ("libvolengine.dll", "volengine.dll", "libvolengine.so", "libvolengine.dylib")
+
+_HANDLE = ctypes.c_void_p
+_OUT_HANDLE = ctypes.POINTER(ctypes.c_void_p)
+_STATUS = ctypes.c_int32
+_SIZE = ctypes.c_size_t
+_I32 = ctypes.c_int32
+_DOUBLE = ctypes.c_double
+_OUT_DOUBLE = ctypes.POINTER(ctypes.c_double)
+_OUT_SIZE = ctypes.POINTER(ctypes.c_size_t)
+_OUT_I32 = ctypes.POINTER(ctypes.c_int32)
+_OUT_VIEW = ctypes.POINTER(ctypes.POINTER(ctypes.c_double))
+_OUT_TEXT = ctypes.POINTER(ctypes.c_char_p)
+
+_SCALAR_CRITERION = [_HANDLE, _I32, _OUT_DOUBLE]
+_VIEW = [_HANDLE, _OUT_VIEW, _OUT_SIZE]
+_SE_VALUES = [_HANDLE, _I32, _HANDLE]
+
+PROTOTYPES: dict[str, tuple[Any, list[Any]]] = {
+    "ve_dcc_spec_create": (_STATUS, [_I32, _OUT_HANDLE]),
+    "ve_dcc_spec_set_order": (_STATUS, [_HANDLE, _I32, _I32]),
+    "ve_dcc_spec_set_dist": (_STATUS, [_HANDLE, _I32]),
+    "ve_dcc_spec_set_groups": (_STATUS, [_HANDLE, ctypes.POINTER(_I32), _SIZE]),
+    "ve_dcc_spec_set_fixed": (_STATUS, [_HANDLE, ctypes.c_char_p, _DOUBLE]),
+    "ve_dcc_spec_set_start": (_STATUS, [_HANDLE, ctypes.c_char_p, _DOUBLE]),
+    "ve_dcc_spec_set_copula": (_STATUS, [_HANDLE, _I32]),
+    "ve_dcc_spec_set_static_method": (_STATUS, [_HANDLE, _I32]),
+    "ve_dcc_options_create": (_STATUS, [_OUT_HANDLE]),
+    "ve_dcc_options_set_standard_errors": (_STATUS, [_HANDLE, _I32]),
+    "ve_dcc_batch_create": (_STATUS, [_OUT_HANDLE]),
+    "ve_dcc_batch_set_specs": (_STATUS, [_HANDLE, ctypes.POINTER(_HANDLE), _SIZE]),
+    "ve_dcc_batch_set_fits": (_STATUS, [_HANDLE, ctypes.POINTER(_HANDLE), _SIZE]),
+    "ve_dcc_batch_set_options": (_STATUS, [_HANDLE, _HANDLE]),
+    "ve_dcc_fit_batch": (_STATUS, [_HANDLE, _HANDLE, ctypes.POINTER(_HANDLE)]),
+    "ve_dcc_fit_standard_errors": (_STATUS, [_HANDLE, _HANDLE, ctypes.POINTER(_HANDLE), _SIZE, _OUT_HANDLE]),
+    "ve_dcc_fit_status": (_STATUS, [_HANDLE, _OUT_I32]),
+    "ve_dcc_fit_nobs": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_dcc_fit_series": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_dcc_fit_param_count": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_dcc_fit_param_name": (_STATUS, [_HANDLE, _SIZE, _OUT_TEXT]),
+    "ve_dcc_fit_estimates": (_STATUS, [_HANDLE, _HANDLE]),
+    "ve_dcc_fit_std_errors": (_STATUS, _SE_VALUES),
+    "ve_dcc_fit_t_values": (_STATUS, _SE_VALUES),
+    "ve_dcc_fit_p_values": (_STATUS, _SE_VALUES),
+    "ve_dcc_fit_loglik": (_STATUS, [_HANDLE, _OUT_DOUBLE]),
+    "ve_dcc_fit_criterion": (_STATUS, [_HANDLE, _I32, _I32, _OUT_DOUBLE]),
+    "ve_dcc_fit_correlation": (_STATUS, _VIEW),
+    "ve_dcc_fit_covariance": (_STATUS, _VIEW),
+    "ve_dcc_spec_free": (None, [_HANDLE]),
+    "ve_dcc_options_free": (None, [_HANDLE]),
+    "ve_dcc_batch_free": (None, [_HANDLE]),
+    "ve_dcc_fit_free": (None, [_HANDLE]),
+    "ve_fit_ljung_box": (_STATUS, [_HANDLE, _I32, _SIZE, _SIZE, _HANDLE]),
+    "ve_fit_arch_lm": (_STATUS, [_HANDLE, _SIZE, _SIZE, _HANDLE]),
+    "ve_fit_nyblom": (_STATUS, [_HANDLE, _HANDLE, _OUT_DOUBLE, _HANDLE]),
+    "ve_nyblom_critical": (_STATUS, [_SIZE, _HANDLE]),
+    "ve_fit_sign_bias": (_STATUS, [_HANDLE, _HANDLE]),
+    "ve_fit_gof": (_STATUS, [_HANDLE, _SIZE, _HANDLE]),
+    "ve_abi_version": (_I32, []),
+    "ve_last_error": (ctypes.c_char_p, []),
+    "ve_context_create": (_STATUS, [_OUT_HANDLE]),
+    "ve_context_set_threads": (_STATUS, [_HANDLE, _I32]),
+    "ve_context_threads": (_STATUS, [_HANDLE, _OUT_I32]),
+    "ve_context_free": (None, [_HANDLE]),
+    "ve_spec_create": (_STATUS, [_I32, _OUT_HANDLE]),
+    "ve_spec_set_order": (_STATUS, [_HANDLE, _I32, _I32]),
+    "ve_spec_set_arma": (_STATUS, [_HANDLE, _I32, _I32]),
+    "ve_spec_set_dist": (_STATUS, [_HANDLE, _I32]),
+    "ve_spec_set_include_mean": (_STATUS, [_HANDLE, _I32]),
+    "ve_spec_set_mxreg": (_STATUS, [_HANDLE, _I32]),
+    "ve_spec_set_vxreg": (_STATUS, [_HANDLE, _I32]),
+    "ve_spec_set_archm": (_STATUS, [_HANDLE, _I32]),
+    "ve_spec_set_arfima": (_STATUS, [_HANDLE, _I32]),
+    "ve_spec_set_fixed": (_STATUS, [_HANDLE, ctypes.c_char_p, _DOUBLE]),
+    "ve_spec_set_start": (_STATUS, [_HANDLE, ctypes.c_char_p, _DOUBLE]),
+    "ve_spec_set_variance_targeting": (_STATUS, [_HANDLE, _I32]),
+    "ve_spec_validate": (_STATUS, [_HANDLE]),
+    "ve_spec_free": (None, [_HANDLE]),
+    "ve_fit_options_create": (_STATUS, [_OUT_HANDLE]),
+    "ve_fit_options_set_max_iter": (_STATUS, [_HANDLE, _I32]),
+    "ve_fit_options_set_tolerance": (_STATUS, [_HANDLE, _DOUBLE]),
+    "ve_fit_options_set_var_init": (_STATUS, [_HANDLE, _I32]),
+    "ve_fit_options_set_standard_errors": (_STATUS, [_HANDLE, _I32]),
+    "ve_fit_options_free": (None, [_HANDLE]),
+    "ve_panel_create": (_STATUS, [_HANDLE, _SIZE, _SIZE, _OUT_HANDLE]),
+    "ve_panel_set_strides": (_STATUS, [_HANDLE, ctypes.c_ssize_t, ctypes.c_ssize_t]),
+    "ve_panel_set_ranges": (_STATUS, [_HANDLE, _HANDLE, _HANDLE]),
+    "ve_panel_free": (None, [_HANDLE]),
+    "ve_batch_create": (_STATUS, [_OUT_HANDLE]),
+    "ve_batch_set_specs": (_STATUS, [_HANDLE, ctypes.POINTER(ctypes.c_void_p), _SIZE]),
+    "ve_batch_set_panel": (_STATUS, [_HANDLE, _HANDLE]),
+    "ve_batch_set_jobs": (_STATUS, [_HANDLE, _HANDLE, _HANDLE, _SIZE]),
+    "ve_batch_set_options": (_STATUS, [_HANDLE, _HANDLE]),
+    "ve_batch_set_regressors": (_STATUS, [_HANDLE, _HANDLE, _HANDLE, _SIZE]),
+    "ve_batch_job_count": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_batch_free": (None, [_HANDLE]),
+    "ve_fit_batch": (_STATUS, [_HANDLE, _HANDLE, ctypes.POINTER(ctypes.c_void_p)]),
+    "ve_fit_status": (_STATUS, [_HANDLE, _OUT_I32]),
+    "ve_fit_nobs": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_fit_param_count": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_fit_param_name": (_STATUS, [_HANDLE, _SIZE, _OUT_TEXT]),
+    "ve_fit_estimates": (_STATUS, [_HANDLE, _HANDLE]),
+    "ve_fit_std_errors": (_STATUS, _SE_VALUES),
+    "ve_fit_t_values": (_STATUS, _SE_VALUES),
+    "ve_fit_p_values": (_STATUS, _SE_VALUES),
+    "ve_loglik": (_STATUS, [_HANDLE, _OUT_DOUBLE]),
+    "ve_aic": (_STATUS, _SCALAR_CRITERION),
+    "ve_bic": (_STATUS, _SCALAR_CRITERION),
+    "ve_hqic": (_STATUS, _SCALAR_CRITERION),
+    "ve_sic": (_STATUS, _SCALAR_CRITERION),
+    "ve_fit_sigma": (_STATUS, _VIEW),
+    "ve_fit_residuals": (_STATUS, _VIEW),
+    "ve_fit_std_residuals": (_STATUS, _VIEW),
+    "ve_fit_fitted": (_STATUS, _VIEW),
+    "ve_fit_free": (None, [_HANDLE]),
+    "ve_forecast_create": (_STATUS, [_HANDLE, _SIZE, _HANDLE, _HANDLE, _OUT_HANDLE]),
+    "ve_forecast_horizon": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_forecast_sigma": (_STATUS, _VIEW),
+    "ve_forecast_mean": (_STATUS, _VIEW),
+    "ve_forecast_free": (None, [_HANDLE]),
+    "ve_sim_options_create": (_STATUS, [_SIZE, _SIZE, ctypes.c_uint64, _OUT_HANDLE]),
+    "ve_sim_options_set_regressors": (_STATUS, [_HANDLE, _HANDLE, _HANDLE]),
+    "ve_sim_options_free": (None, [_HANDLE]),
+    "ve_simulate_fit": (_STATUS, [_HANDLE, _HANDLE, _HANDLE, _OUT_HANDLE]),
+    "ve_simulate_spec": (_STATUS, [_HANDLE, _HANDLE, _HANDLE, _OUT_HANDLE]),
+    "ve_sim_paths": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_sim_horizon": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_sim_returns": (_STATUS, _VIEW),
+    "ve_sim_sigma": (_STATUS, _VIEW),
+    "ve_sim_free": (None, [_HANDLE]),
+    "ve_dcc_future_create": (_STATUS, [_SIZE, _SIZE, _OUT_HANDLE]),
+    "ve_dcc_future_set": (_STATUS, [_HANDLE, _SIZE, _HANDLE, _HANDLE]),
+    "ve_dcc_future_free": (None, [_HANDLE]),
+    "ve_dcc_forecast_create": (_STATUS, [_HANDLE, _SIZE, _HANDLE, _OUT_HANDLE]),
+    "ve_dcc_forecast_horizon": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_dcc_forecast_series": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_dcc_forecast_correlation": (_STATUS, _VIEW),
+    "ve_dcc_forecast_covariance": (_STATUS, _VIEW),
+    "ve_dcc_forecast_sigma": (_STATUS, _VIEW),
+    "ve_dcc_forecast_mean": (_STATUS, _VIEW),
+    "ve_dcc_forecast_free": (None, [_HANDLE]),
+    "ve_sim_options_set_correlations": (_STATUS, [_HANDLE, _I32]),
+    "ve_simulate_dcc": (_STATUS, [_HANDLE, _HANDLE, _HANDLE, _HANDLE, _OUT_HANDLE]),
+    "ve_dcc_sim_paths": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_dcc_sim_horizon": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_dcc_sim_series": (_STATUS, [_HANDLE, _OUT_SIZE]),
+    "ve_dcc_sim_returns": (_STATUS, _VIEW),
+    "ve_dcc_sim_sigma": (_STATUS, _VIEW),
+    "ve_dcc_sim_correlation": (_STATUS, _VIEW),
+    "ve_dcc_sim_covariance": (_STATUS, _VIEW),
+    "ve_dcc_sim_free": (None, [_HANDLE]),
+}
+
+
+class VolEngineError(Exception):
+    """A native call failed; `status` is the VE_* code and the message comes from ve_last_error()."""
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+def locate_library(override: str | None, directory: Path) -> Path:
+    if override:
+        path = Path(override)
+        if not path.is_file():
+            raise ImportError(f"{LIBRARY_ENV} points to {override}, which is not a file")
+        return path
+    for name in LIBRARY_NAMES:
+        if (directory / name).is_file():
+            return directory / name
+    raise ImportError(
+        f"VolEngine native library not found: set {LIBRARY_ENV} to the library file, "
+        f"or place one of {', '.join(LIBRARY_NAMES)} in {directory}"
+    )
+
+
+def load_library(environ: Mapping[str, str], directory: Path) -> ctypes.CDLL:
+    path = locate_library(environ.get(LIBRARY_ENV), directory)
+    try:
+        library = ctypes.CDLL(str(path))
+    except OSError as error:
+        raise ImportError(f"cannot load the VolEngine native library {path}: {error}") from error
+    check_abi(library, path)
+    declare_prototypes(library)
+    return library
+
+
+def check_abi(library: ctypes.CDLL, path: Path) -> None:
+    try:
+        declare_function(library, "ve_abi_version")
+    except AttributeError as error:
+        raise ImportError(f"{path} does not export ve_abi_version, it is not a VolEngine library") from error
+    abi = library.ve_abi_version()
+    if abi != VE_ABI_VERSION:
+        raise ImportError(f"{path} has ABI version {abi}, this package needs {VE_ABI_VERSION}")
+
+
+def declare_function(library: ctypes.CDLL, name: str) -> None:
+    restype, argtypes = PROTOTYPES[name]
+    function = getattr(library, name)
+    function.restype = restype
+    function.argtypes = argtypes
+
+
+def declare_prototypes(library: ctypes.CDLL) -> None:
+    for name in PROTOTYPES:
+        declare_function(library, name)
+
+
+lib = load_library(os.environ, LIBRARY_DIRECTORY)
+
+
+def last_error() -> str:
+    message = cast(bytes | None, lib.ve_last_error())
+    if message is None:
+        return ""
+    return message.decode("utf-8", errors="replace")
+
+
+def int32(value: int, name: str) -> int:
+    """`value` checked to fit a C int32_t, which ctypes would otherwise wrap around silently."""
+    if not INT32_MIN <= value <= INT32_MAX:
+        raise ValueError(f"{name} must fit in a 32-bit signed integer, got {value}")
+    return value
+
+
+def check(status: int) -> None:
+    if status != 0:
+        raise VolEngineError(status, last_error())
+
+
+class Handle:
+    """Owns one native handle and frees it exactly once."""
+
+    def __init__(self, pointer: int | None, free: Callable[[int], None]) -> None:
+        self._pointer: int | None = pointer
+        self._free = free
+
+    @property
+    def pointer(self) -> int:
+        if self._pointer is None:
+            raise ValueError("the native handle is already closed")
+        return self._pointer
+
+    def close(self) -> None:
+        pointer, self._pointer = self._pointer, None
+        if pointer is not None:
+            self._free(pointer)
+
+    def __enter__(self) -> Handle:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+def create_handle(create: Callable[..., int], free: Callable[[int], None], *args: Any) -> Handle:
+    out = ctypes.c_void_p()
+    check(create(*args, ctypes.byref(out)))
+    if out.value is None:
+        raise VolEngineError(VE_INTERNAL_ERROR, "the native create call returned a null handle")
+    return Handle(out.value, free)
+
+
+def read_scalar(ctype: Any, function: Callable[..., int], *args: Any) -> Any:
+    out = ctype()
+    check(function(*args, ctypes.byref(out)))
+    return out.value
+
+
+ELEMENT_BYTES = np.dtype(np.float64).itemsize
+
+
+def open_panel(stack: ExitStack, array: NDArray[np.float64]) -> Handle:
+    panel = stack.enter_context(
+        create_handle(lib.ve_panel_create, lib.ve_panel_free, array.ctypes.data, array.shape[0], array.shape[1])
+    )
+    stride_t, stride_n = (stride // ELEMENT_BYTES for stride in array.strides)
+    check(lib.ve_panel_set_strides(panel.pointer, stride_t, stride_n))
+    return panel
+
+
+def read_only(array: NDArray[np.float64]) -> NDArray[np.float64]:
+    array.flags.writeable = False
+    return array
+
+
+def native_view(owner: object, function: Callable[..., int], pointer: int) -> NDArray[np.float64]:
+    """The read-only view a VE_* view function returns for `pointer`; it keeps `owner` (and its handle) alive."""
+    data = ctypes.POINTER(ctypes.c_double)()
+    length = ctypes.c_size_t()
+    check(function(pointer, ctypes.byref(data), ctypes.byref(length)))
+    if length.value == 0:
+        return read_only(np.empty(0, dtype=np.float64))
+    address = ctypes.cast(data, ctypes.c_void_p).value
+    assert address is not None
+    buffer = (ctypes.c_double * length.value).from_address(address)
+    setattr(buffer, "_owner", owner)
+    return read_only(np.frombuffer(buffer, dtype=np.float64))

volengine/_simulation.py

@@ -0,0 +1,70 @@
+"""Simulated paths over ve_sim 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 DccSimulation:
+    """Paths simulated from a DCC fit, after its last observation.
+
+    `returns` and `sigma` are read-only arrays of shape (paths, horizon, N); `R` and `H` of shape (paths, horizon,
+    N, N) exist only for a simulation run with `correlations=True` (VolEngineError otherwise). Each step takes R
+    from the exact recursion, draws a shock of covariance R (a Gaussian scale mixture for the mvt and the
+    mvlaplace), and turns it into the standardized shock of each series: itself in a DCC, or through the copula and
+    the margin of the series in a Copula-DCC. Path p reads only the stream (seed, p): the same seed gives the same
+    paths for any number of threads, within one version of the library. The simulation does not depend on its fit.
+    """
+
+    def __init__(self, handle: Handle) -> None:
+        self._handle = handle
+        self._shape = (
+            read_scalar(ctypes.c_size_t, lib.ve_dcc_sim_paths, handle.pointer),
+            read_scalar(ctypes.c_size_t, lib.ve_dcc_sim_horizon, handle.pointer),
+            read_scalar(ctypes.c_size_t, lib.ve_dcc_sim_series, handle.pointer),
+        )
+
+    @property
+    def returns(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_dcc_sim_returns, self._handle.pointer).reshape(self._shape)
+
+    @property
+    def sigma(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_dcc_sim_sigma, self._handle.pointer).reshape(self._shape)
+
+    @property
+    def R(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_dcc_sim_correlation, self._handle.pointer).reshape(*self._shape, self._shape[2])
+
+    @property
+    def H(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_dcc_sim_covariance, self._handle.pointer).reshape(*self._shape, self._shape[2])
+
+
+class Simulation:
+    """Paths simulated from a fit (after its last observation) or from a spec with every parameter fixed.
+
+    `returns` and `sigma` are read-only arrays of shape (paths, horizon): row p is path p, `returns` the simulated
+    series and `sigma` its conditional standard deviation. The same seed gives the same paths for any number of
+    threads, but only within one version of the library. The simulation does not depend on its source.
+    """
+
+    def __init__(self, handle: Handle) -> None:
+        self._handle = handle
+        self._shape = (
+            read_scalar(ctypes.c_size_t, lib.ve_sim_paths, handle.pointer),
+            read_scalar(ctypes.c_size_t, lib.ve_sim_horizon, handle.pointer),
+        )
+
+    @property
+    def returns(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_sim_returns, self._handle.pointer).reshape(self._shape)
+
+    @property
+    def sigma(self) -> NDArray[np.float64]:
+        return native_view(self, lib.ve_sim_sigma, self._handle.pointer).reshape(self._shape)

volengine/_spec.py

@@ -0,0 +1,240 @@
+"""Model specifications and fit options, validated eagerly through the native library."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import KW_ONLY, dataclass, field
+from typing import NoReturn
+
+from ._native import Handle, check, create_handle, int32, lib
+
+MODELS = {"sgarch": 0, "egarch": 1, "gjrgarch": 2, "aparch": 3, "igarch": 4, "csgarch": 5}
+SUBMODELS = {
+    "garch": 6,
+    "tgarch": 7,
+    "avgarch": 8,
+    "ngarch": 9,
+    "nagarch": 10,
+    "aparch": 11,
+    "gjrgarch": 12,
+    "allgarch": 13,
+}
+DISTRIBUTIONS = {"norm": 0, "std": 1, "ged": 2, "sstd": 3, "sged": 4, "nig": 5, "ghyp": 6, "jsu": 7}
+VAR_INITS = {"sample": 0, "backcast": 1}
+
+
+def code_of(table: dict[str, int], kind: str, name: str) -> int:
+    if name not in table:
+        listed = list(table)
+        if kind == "model":
+            listed.append("fgarch")
+        raise ValueError(f"unknown {kind} {name!r}; expected one of {sorted(listed)}")
+    return table[name]
+
+
+class _FrozenDict(dict[str, float]):
+    """A dict that refuses every mutation; unlike MappingProxyType it pickles, deep-copies and works with asdict."""
+
+    def _refuse(self, *args: object, **kwargs: object) -> NoReturn:
+        raise TypeError(f"{type(self).__name__} is read-only")
+
+    __setitem__ = __delitem__ = clear = pop = popitem = setdefault = update = __ior__ = _refuse
+
+    def __reduce__(self) -> tuple[type[_FrozenDict], tuple[dict[str, float]]]:
+        return (type(self), (dict(self),))
+
+
+def frozen_values(values: Mapping[str, float]) -> Mapping[str, float]:
+    return _FrozenDict({name: float(value) for name, value in values.items()})
+
+
+def encoded_name(name: str) -> bytes:
+    if "\0" in name:
+        raise ValueError(f"parameter name {name!r} contains a NUL byte")
+    return name.encode()
+
+
+@dataclass(frozen=True)
+class Spec:
+    """Model specification. Unknown names raise ValueError, native rejections VolEngineError.
+
+    `p` is the ARCH order (number of alpha terms, lagged squared residuals) and `q` the GARCH order
+    (number of beta terms, lagged variances), as in arch's `p` and `q` and in rugarch's
+    `garchOrder = c(alpha order, beta order)` (rugarch calls those orders q and p, the other way
+    round). `arma` is the ARMA(m, n) order of the conditional mean. Orders are limited to 1..6 for
+    `p` and `q` and 0..6 for `arma` (VE_MAX_ORDER).
+
+    `model` is one of "sgarch", "egarch", "gjrgarch", "aparch", "igarch", "csgarch" and "fgarch".
+    "fgarch" requires `submodel`, one of "garch", "tgarch", "avgarch", "ngarch", "nagarch", "aparch",
+    "gjrgarch" and "allgarch"; every other model rejects it. The iGARCH `beta_q` is derived
+    (1 - sum of alphas - the other betas), not estimated: it has a name and a value, its standard error
+    is NaN and the criteria count the estimated parameters only.
+
+    `dist` is one of "norm", "std", "ged", "sstd", "sged", "nig", "ghyp" and "jsu", all standardized to
+    zero mean and unit variance. Distribution parameters come last in the fit names, in the order `skew`,
+    `shape`, `ghlambda`: "std" has `shape` (nu > 2), "ged" has `shape` (nu > 0); "sstd" and "sged" are
+    Fernandez-Steel skewed versions of those kernels with `skew` xi > 0 and the same `shape`; "nig" and
+    "ghyp" are the generalized hyperbolic in the standardized (rho, zeta) parametrization with `skew` rho
+    in (-1, 1) and `shape` zeta in (0, 1e6] ("ghyp" adds `ghlambda`, a real number; "nig" fixes it at
+    -1/2); "jsu" is Johnson SU with `skew` nu (a real number) and `shape` tau > 0. The "sstd" `skew` is
+    xi, not arch's Hansen skewness lambda in (-1, 1): xi = sqrt((1 + lambda) / (1 - lambda)), and the
+    standard error of lambda follows by the delta method, d xi / d lambda = 1 / (xi * (1 - lambda)**2);
+    the other way, lambda = (xi**2 - 1) / (xi**2 + 1) and SE(lambda) = SE(xi) * 4 * xi / (xi**2 + 1)**2.
+
+    Past zeta = 1e6 double precision no longer standardizes "nig" and "ghyp" (by then a normal to an
+    excess kurtosis of order 1 / zeta, 1.5e-5 for nig), and the log-likelihood is -inf there. On
+    near-normal data their fits drive zeta up, where rho and zeta are barely identified: the Hessian is
+    then often not positive definite, and every standard error is NaN.
+
+    Every parameter is estimated, fixed or derived. `fixed` maps parameter names (those of `Fit.names`:
+    "mu", "ar1", "omega", "alpha1", "beta1", "gamma1", "eta11", "skew", "shape", ...) to values the
+    fit keeps: they are not optimized, their standard errors are NaN and the criteria do not count them.
+    A derived parameter (the iGARCH `beta_q`, and `omega` under variance targeting) is a function of
+    the others: it has a name and a value, NaN standard errors, and is not counted either. `start`
+    maps names to starting values that replace the defaults; a start value for a derived parameter is
+    ignored, so `dict(zip(fit.names, fit.coef().estimate))` is a valid warm start. A start value for a
+    name that is also in `fixed` is ignored, because fixed wins: `Spec(fixed=..., start=dict(zip(fit.names,
+    fit.coef().estimate)))` is a valid warm start. A name with a NUL character is a ValueError. If the
+    starting point is outside the model's domain, the fit ends "failed" with NaN. A spec with every parameter fixed does not optimize: the fit evaluates the model
+    at the fixed point and is "converged" when the log-likelihood is finite.
+
+    `variance_targeting=True` makes `omega` derived: it is computed inside the likelihood from the
+    residuals of the current mean parameters over the whole sample (m2 = mean of e_t**2, P the
+    persistence): omega = m2 * (1 - P) for sgarch and gjrgarch (P = sum(alpha) + sum(beta), plus
+    pi * sum(gamma) with pi = P(z < 0) for gjrgarch); omega = log(m2) * (1 - sum(beta)) for egarch;
+    omega = mean(|e_t|**delta) * (1 - P) for aparch and fgarch, with delta the power and
+    P = sum(alpha_i * kappa_i) + sum(beta). The standard errors of the other parameters come from the
+    likelihood in which omega is a function of them (as in rugarch), not from the two-step covariance
+    of Francq, Horvath and Zakoian (2011).
+
+    `mxreg` and `vxreg` are the numbers of mean and variance regressor columns (0..8, VE_MAX_REGRESSORS) and
+    `archm` is ARCH-in-mean: 0 none, 1 adds xi * sigma_t to the mean, 2 adds xi * sigma_t**2. Their parameters are
+    named, in order, "mu", "ar1".., "ma1".., "archm", "mxreg1".., "omega", ... and "vxreg1".. before "skew". The
+    data go to `Context.fit(..., mxreg=, vxreg=)`. Mean: m_t = mu + sum(delta_k * x_t,k) + xi * sigma_t**p and
+    d_t = r_t - m_t; the ARMA acts on d_t, and the pre-sample residuals (for var_init "sample" and variance
+    targeting) are those with xi = 0. Variance: omega becomes omega + sum(zeta_k * v_t,k) in the scale of the
+    model (sigma**2, log sigma**2 or sigma**delta; in csgarch it enters q_t). Under variance targeting
+    omega = target - sum(zeta_k * mean(v_k)). With var_init "backcast" and `mxreg`, the backcast uses the
+    residuals of the OLS of r on [1 (with a mean), X], as arch does. Persistence < 1 is always enforced, unlike
+    rugarch, which drops it when there is `vxreg`; a sigma**2 <= 0 gives a log-likelihood of -inf.
+
+    `arfima=True` is rugarch's ARFIMA mean: the parameter "arfima", named after "ma1".. (where "archm" would be;
+    a spec cannot have both), is d in (1e-8, 0.5). The ARMA residuals e_t become
+    y_t = sum(pi_k * e_(t-k), k = 0..t), pi_0 = 1, pi_k = pi_(k-1) * (k - 1 - d) / k, the (1 - L)**d truncated at
+    the start of the series, at a cost of O(T**2); y_t replaces e_t everywhere after.
+
+    Rejected with VolEngineError (the message names the problem): a name the spec does not have
+    (`fixed={"shpe": 5.0}`, or "shape" under dist "norm"), fixing the iGARCH `beta_q` or `omega` under
+    variance targeting (both derived), variance targeting with "igarch" or "csgarch", and a csgarch
+    with `eta21` fixed and a free `beta` (fixing it together with every `beta` is accepted).
+    """
+
+    model: str = "sgarch"
+    _: KW_ONLY
+    p: int = 1
+    q: int = 1
+    arma: tuple[int, int] = (0, 0)
+    dist: str = "norm"
+    include_mean: bool = True
+    submodel: str | None = None
+    fixed: Mapping[str, float] = field(default_factory=dict)
+    start: Mapping[str, float] = field(default_factory=dict)
+    variance_targeting: bool = False
+    mxreg: int = 0
+    vxreg: int = 0
+    archm: int = 0
+    arfima: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "fixed", frozen_values(self.fixed))
+        object.__setattr__(self, "start", frozen_values(self.start))
+        self.native_handle().close()
+        object.__setattr__(self, "arma", tuple(self.arma))
+
+    def __hash__(self) -> int:
+        return hash(
+            (
+                self.model,
+                self.p,
+                self.q,
+                tuple(self.arma),
+                self.dist,
+                self.include_mean,
+                self.submodel,
+                frozenset(self.fixed.items()),
+                frozenset(self.start.items()),
+                self.variance_targeting,
+                self.mxreg,
+                self.vxreg,
+                self.archm,
+                self.arfima,
+            )
+        )
+
+    def arma_orders(self) -> tuple[int, int]:
+        arma = self.arma
+        if not isinstance(arma, tuple | list) or len(arma) != 2 or not all(type(i) is int for i in arma):
+            raise ValueError(f"arma must be a pair of integers (m, n), got {arma!r}")
+        return int32(arma[0], "arma m"), int32(arma[1], "arma n")
+
+    def model_code(self) -> int:
+        if self.model != "fgarch":
+            if self.submodel is not None:
+                raise ValueError(f"submodel is only for model 'fgarch', got model {self.model!r}")
+            return code_of(MODELS, "model", self.model)
+        if self.submodel is None:
+            raise ValueError(f"model 'fgarch' requires a submodel, one of {sorted(SUBMODELS)}")
+        return code_of(SUBMODELS, "submodel", self.submodel)
+
+    def native_handle(self) -> Handle:
+        model = self.model_code()
+        dist = code_of(DISTRIBUTIONS, "dist", self.dist)
+        arma = self.arma_orders()
+        handle = create_handle(lib.ve_spec_create, lib.ve_spec_free, model)
+        check(lib.ve_spec_set_order(handle.pointer, int32(self.p, "p"), int32(self.q, "q")))
+        check(lib.ve_spec_set_arma(handle.pointer, *arma))
+        check(lib.ve_spec_set_dist(handle.pointer, dist))
+        check(lib.ve_spec_set_include_mean(handle.pointer, int(self.include_mean)))
+        check(lib.ve_spec_set_mxreg(handle.pointer, int32(self.mxreg, "mxreg")))
+        check(lib.ve_spec_set_vxreg(handle.pointer, int32(self.vxreg, "vxreg")))
+        check(lib.ve_spec_set_archm(handle.pointer, int32(self.archm, "archm")))
+        check(lib.ve_spec_set_arfima(handle.pointer, int(self.arfima)))
+        self.apply_values(handle)
+        return handle
+
+    def apply_values(self, handle: Handle) -> None:
+        for name, value in self.fixed.items():
+            check(lib.ve_spec_set_fixed(handle.pointer, encoded_name(name), value))
+        for name, value in self.start.items():
+            check(lib.ve_spec_set_start(handle.pointer, encoded_name(name), value))
+        check(lib.ve_spec_set_variance_targeting(handle.pointer, int(self.variance_targeting)))
+        check(lib.ve_spec_validate(handle.pointer))
+
+
+@dataclass(frozen=True)
+class FitOptions:
+    """Optimizer settings for a fit.
+
+    standard_errors=False skips the inference at the estimate (Hessian and robust standard errors, scores,
+    Nyblom): Fit.coef() and Fit.nyblom() then raise VolEngineError, while Fit.estimate, the criteria, the series,
+    forecasts, simulations and DCC fits stay the same. Useful for a grid chosen by a criterion; refit the chosen
+    model with standard errors.
+    """
+
+    _: KW_ONLY
+    max_iter: int = 500
+    tol: float = 1e-6
+    var_init: str = "sample"
+    standard_errors: bool = True
+
+    def __post_init__(self) -> None:
+        self.native_handle().close()
+
+    def native_handle(self) -> Handle:
+        var_init = code_of(VAR_INITS, "var_init", self.var_init)
+        handle = create_handle(lib.ve_fit_options_create, lib.ve_fit_options_free)
+        check(lib.ve_fit_options_set_max_iter(handle.pointer, int32(self.max_iter, "max_iter")))
+        check(lib.ve_fit_options_set_tolerance(handle.pointer, self.tol))
+        check(lib.ve_fit_options_set_var_init(handle.pointer, var_init))
+        check(lib.ve_fit_options_set_standard_errors(handle.pointer, int(self.standard_errors)))
+        return handle