Source code for quantdata.dysanos.implied.experiment

"""Versioned configurations for the PCA-IV-AR(1) benchmark."""

from __future__ import annotations

import math
from dataclasses import dataclass

from cdxcore.err import verify_inp
from cdxcore.uniquehash import named_unique_filename48_8
from cdxcore.version import version

from quantdata.biz_calendar import DAYS_PER_YEAR, NMS
from quantdata.dysanos.grid.torch_simulator import GaussianSpotImportanceConfig


[docs] @version("0.1") @dataclass(frozen=True, kw_only=True) class PCAFitConfig: """Logical inputs to the direct log-IV PCA representation.""" grid_strikes: int = 100 num_surface_state: int = 20 nms_eps: float = NMS.EPS interpolation: str = "linear-total-variance-v1" def __post_init__(self) -> None: verify_inp( isinstance(self.grid_strikes, int) and self.grid_strikes >= 2, lambda: ( "'grid_strikes' must be an integer of at least two, got " f"{self.grid_strikes!r}" ), ) verify_inp( isinstance(self.num_surface_state, int) and 0 < self.num_surface_state <= self.grid_strikes * 7, lambda: ( "'num_surface_state' must be a positive feasible integer, got " f"{self.num_surface_state!r}" ), ) verify_inp( math.isfinite(self.nms_eps) and self.nms_eps > 0.0, lambda: f"'nms_eps' must be finite and positive, got {self.nms_eps}", ) verify_inp( self.interpolation == "linear-total-variance-v1", lambda: f"unsupported interpolation convention {self.interpolation!r}", ) def __str__(self) -> str: return ( f"logiv-pca-h={self.num_surface_state},n={self.grid_strikes}," f"nms-eps={self.nms_eps:.6g},{self.interpolation}" ) @property def filename(self) -> str: """Stable cache identity for a fitted PCA representation.""" return named_unique_filename48_8("pca-iv-level-fit", self)
[docs] @version( "0.6", dependencies=[PCAFitConfig, GaussianSpotImportanceConfig], ) @dataclass(frozen=True, kw_only=True) class ImpliedPCAExperiment: """Logical inputs for one PCA-IV-AR(1) simulation and diagnostic run. The published comparison uses 100,000 or 1,000,000 paths, 20 level components, and either five or all surface innovation factors. Smaller positive path counts remain valid for deterministic smoke tests. """ num_samples: int = 100_000 grid_strikes: int = 100 num_traded_nms: int = 20 num_surface_state: int = 20 num_alpha: int | None = 5 use_matrix_exp: bool = True bandwidth: float = 1.0 trading_frequency: str = "daily" return_horizon: str = "expiry" num_trading_times: int = 10 # Deprecated aliases for earlier stored experiments. mode: str | None = None option_return_horizon: str | None = None num_steps: int | None = None dt: float = 1.0 / DAYS_PER_YEAR seed: int = 700_000 block_size: int = 10_000 importance_sampling: GaussianSpotImportanceConfig | None = ( GaussianSpotImportanceConfig() ) # Matched return diagnostics. neighbors: int = 1_024 candidate_neighbors: int = 8_192 query_paths_per_split: int = 1_024 instrument_block_size: int = 20 tail_ranks: tuple[int, ...] = (1, 2, 10, 20, 50) signal_thresholds: tuple[float, ...] = (2.0, 3.0) cost_proportion: float = 1.0e-4 roundoff_multipliers: tuple[int, ...] = (0, 1, 8, 32, 128) static_mesh_points: int = 201 def __post_init__(self) -> None: if self.mode is not None: verify_inp( self.mode in {"one-step", "one-step-weekly", "path", "weekly"}, lambda: f"unsupported PCA experiment mode {self.mode!r}", ) object.__setattr__( self, "trading_frequency", "weekly" if self.mode in {"one-step-weekly", "weekly"} else "daily", ) if self.option_return_horizon is not None: verify_inp( self.option_return_horizon in {"expiry", "one-day"}, lambda: ( "'option_return_horizon' must be 'expiry' or 'one-day', got " f"{self.option_return_horizon!r}" ), ) object.__setattr__( self, "return_horizon", "incremental" if self.option_return_horizon == "one-day" else "expiry", ) if self.mode is not None: if self.mode in {"one-step", "one-step-weekly"}: object.__setattr__(self, "num_trading_times", 1) elif self.num_steps is not None: legacy_times = ( self.num_steps if self.return_horizon == "incremental" else self.num_steps - 1 ) object.__setattr__(self, "num_trading_times", legacy_times) if self.mode is None: object.__setattr__( self, "mode", ( "one-step-weekly" if self.num_trading_times == 1 and self.trading_frequency == "weekly" else "one-step" if self.num_trading_times == 1 else "weekly" if self.trading_frequency == "weekly" else "path" ), ) if self.option_return_horizon is None: object.__setattr__( self, "option_return_horizon", "one-day" if self.return_horizon == "incremental" else "expiry", ) positive_integers = ( "num_samples", "grid_strikes", "num_traded_nms", "num_surface_state", "num_trading_times", "block_size", "neighbors", "candidate_neighbors", "query_paths_per_split", "instrument_block_size", "static_mesh_points", ) for name in positive_integers: value = getattr(self, name) verify_inp( isinstance(value, int) and value > 0, lambda name=name, value=value: ( f"'{name}' must be a positive integer, got {value!r}" ), ) verify_inp( self.num_traded_nms <= self.grid_strikes, lambda: ( "'num_traded_nms' cannot exceed 'grid_strikes', got " f"{self.num_traded_nms}/{self.grid_strikes}" ), ) verify_inp( self.num_samples >= 2, lambda: ( "'num_samples' must provide nonempty reference and audit " f"sets, got {self.num_samples}" ), ) verify_inp( self.num_alpha in (5, None), lambda: ( "the primary benchmark requires 'num_alpha' to be 5 or None, " f"got {self.num_alpha!r}" ), ) verify_inp( self.use_matrix_exp is True, "the PCA benchmark requires exact matrix-exponential transitions", ) verify_inp( self.bandwidth == 1.0, lambda: ( "the PCA benchmark uses Gaussian innovations only, so " f"'bandwidth' must equal 1, got {self.bandwidth}" ), ) verify_inp( self.trading_frequency in {"daily", "weekly"}, lambda: f"unsupported trading frequency {self.trading_frequency!r}", ) verify_inp( self.return_horizon in {"expiry", "incremental"}, lambda: ( "'return_horizon' must be 'expiry' or 'incremental', got " f"{self.return_horizon!r}" ), ) verify_inp( self.return_horizon == "expiry" or self.num_trading_times >= 2, "incremental returns require at least two trading timestamps", ) verify_inp( math.isfinite(self.dt) and self.dt > 0.0, lambda: f"'dt' must be finite and positive, got {self.dt}", ) verify_inp( isinstance(self.seed, int), lambda: f"'seed' must be an integer, got {self.seed!r}", ) verify_inp( self.num_alpha is None or self.num_alpha <= self.num_surface_state, lambda: ( "'num_alpha' cannot exceed 'num_surface_state', got " f"{self.num_alpha}/{self.num_surface_state}" ), ) verify_inp( tuple(sorted(set(self.tail_ranks))) == self.tail_ranks and self.tail_ranks[0] > 0 and self.tail_ranks[-1] <= self.neighbors, lambda: f"invalid tail ranks {self.tail_ranks}", ) verify_inp( all(math.isfinite(value) and value > 0.0 for value in self.signal_thresholds), lambda: f"invalid signal thresholds {self.signal_thresholds}", ) verify_inp( math.isfinite(self.cost_proportion) and self.cost_proportion >= 0.0, lambda: f"invalid proportional cost {self.cost_proportion}", ) verify_inp( tuple(sorted(set(self.roundoff_multipliers))) == self.roundoff_multipliers and self.roundoff_multipliers[0] == 0 and 32 in self.roundoff_multipliers, lambda: f"invalid roundoff multipliers {self.roundoff_multipliers}", ) verify_inp( self.static_mesh_points >= 5 and self.static_mesh_points % 2 == 1, lambda: ( "'static_mesh_points' must be an odd integer of at least five, " f"got {self.static_mesh_points}" ), ) @property def fit_config(self) -> PCAFitConfig: """The result-affecting subset used by the fitted-PCA cache.""" return PCAFitConfig( grid_strikes=self.grid_strikes, num_surface_state=self.num_surface_state, ) @property def trading_times(self) -> int: return ( self.num_trading_times if self.return_horizon == "expiry" else self.num_trading_times - 1 ) @property def trading_step_stride(self) -> int: return 5 if self.trading_frequency == "weekly" else 1 @property def is_primary_path_count(self) -> bool: return self.num_samples in {100_000, 1_000_000} @property def reference_paths(self) -> int: """Paths used to fit diagnostic estimators (80% of the universe).""" return min(self.num_samples - 1, 4 * self.num_samples // 5) @property def audit_paths(self) -> int: """Held-out paths used only to audit fitted diagnostics.""" return self.num_samples - self.reference_paths @property def filename(self) -> str: """Stable identity including every logical simulation input.""" return named_unique_filename48_8( f"pca-iv-ar1-{self.num_samples}-{self.trading_frequency}-" f"{self.return_horizon}", self, ) def __str__(self) -> str: alpha = "all" if self.num_alpha is None else str(self.num_alpha) importance = "direct-p" if self.importance_sampling is None else "spot-is" return ( f"S={self.num_samples},frequency={self.trading_frequency}," f"return={self.return_horizon}," f"h={self.num_surface_state},alpha={alpha},n={self.grid_strikes}," f"nt={self.num_traded_nms},dt={self.dt:.6g},seed={self.seed},{importance}" )