Source code for quantdata.dysanos.tangent_levy.experiment

"""End-to-end orchestration for Tangent Lévy historical experiments."""

from __future__ import annotations

from dataclasses import dataclass
from datetime import date

import numpy as np
from cdxcore.err import verify, verify_inp
from cdxcore.subdir import SubDir
from cdxcore.uniquehash import named_unique_filename48_8
from cdxcore.verbose import Context

from quantdata.biz_calendar import get_half_days, to_date
from quantdata.dysanos import _locations_dysanos

from .config import TangentLevyConfig
from .double_exponential import DoubleExponentialParameters, call_prices
from .dynamics import DynamicsFit, fit_dynamics
from .markets import (
    MarketAudit,
    TangentLevyMarketDay,
    load_market_day,
    market_dates,
)
from .pricing import density_call_prices
from .simulator import SimulationResult, simulate_codebooks
from .static_fit import (
    DayFit,
    MaturityFit,
    SymmetryCurve,
    fit_market_day,
    fitted_average_density,
    reconstruct_forward_density,
)

_history_cache = _locations_dysanos.training("tangent-levy/history")


[docs] @dataclass(frozen=True) class HistoricalCalibration: """Successful daily code-books with failures preserved in the audit.""" ticker: str requested_dates: tuple[date, ...] dates: tuple[date, ...] day_fits: tuple[DayFit, ...] symmetry_curve: SymmetryCurve forward_density: np.ndarray consecutive_mask: np.ndarray reconstruction_relative_error: np.ndarray reconstruction_l1_error: np.ndarray reconstruction_repricing_rmse: np.ndarray reconstruction_maximum_price_error: np.ndarray reconstruction_passed: np.ndarray audits: tuple[MarketAudit, ...] failure_reasons: dict[str, str] @property def successful_date_fraction(self) -> float: """Fraction of requested sessions producing a code-book.""" return len(self.dates) / len(self.requested_dates)
[docs] def to_state_dict(self) -> dict[str, object]: """Return an HDF5-safe logical artifact.""" fit_states: list[dict[str, object]] = [] for day_fit in self.day_fits: fit_states.append( { "market_date": str(day_fit.market_date), "initial_symmetry_fit": day_fit.initial_symmetry_fit, "maturities": day_fit.maturities, "parameters": np.asarray( [ ( fit.parameters.intensity, fit.parameters.positive_rate, fit.parameters.negative_rate, fit.parameters.positive_probability, ) for fit in day_fit.fits ], dtype=np.float64, ), "objective": np.asarray( [fit.objective for fit in day_fit.fits], dtype=np.float64, ), "success": np.asarray( [fit.success for fit in day_fit.fits], dtype=bool, ), "iterations": np.asarray( [fit.iterations for fit in day_fit.fits], dtype=np.int32, ), "selected_start": np.asarray( [fit.selected_start for fit in day_fit.fits], dtype=np.int32, ), "start_objectives": [ fit.start_objectives for fit in day_fit.fits ], "num_quotes": np.asarray( [fit.num_quotes for fit in day_fit.fits], dtype=np.int32, ), "weighted_rmse": np.asarray( [fit.weighted_rmse for fit in day_fit.fits], dtype=np.float64, ), "maximum_absolute_error": np.asarray( [fit.maximum_absolute_error for fit in day_fit.fits], dtype=np.float64, ), "messages": [fit.message for fit in day_fit.fits], } ) return { "ticker": self.ticker, "requested_dates": [value.isoformat() for value in self.requested_dates], "dates": [value.isoformat() for value in self.dates], "day_fits": fit_states, "symmetry_maturities": self.symmetry_curve.maturities, "symmetry_values": self.symmetry_curve.values, "forward_density": self.forward_density, "consecutive_mask": self.consecutive_mask, "reconstruction_relative_error": self.reconstruction_relative_error, "reconstruction_l1_error": self.reconstruction_l1_error, "reconstruction_repricing_rmse": self.reconstruction_repricing_rmse, "reconstruction_maximum_price_error": ( self.reconstruction_maximum_price_error ), "reconstruction_passed": self.reconstruction_passed, "audits": [ {**audit.__dict__, "market_date": audit.market_date.isoformat()} for audit in self.audits ], "failure_reasons": self.failure_reasons, }
[docs] @classmethod def from_state_dict(cls, state: dict[str, object]) -> HistoricalCalibration: """Reconstruct a cached historical calibration artifact.""" day_fits: list[DayFit] = [] for day_state_object in state["day_fits"]: day_state = dict(day_state_object) maturities = np.asarray(day_state["maturities"], dtype=np.float64) parameter_values = np.asarray(day_state["parameters"], dtype=np.float64) objectives = np.asarray(day_state["objective"], dtype=np.float64) successes = np.asarray(day_state["success"], dtype=bool) iterations = np.asarray(day_state["iterations"], dtype=np.int32) selected_starts = np.asarray(day_state["selected_start"], dtype=np.int32) num_quotes = np.asarray(day_state["num_quotes"], dtype=np.int32) weighted_rmse = np.asarray(day_state["weighted_rmse"], dtype=np.float64) maximum_error = np.asarray( day_state["maximum_absolute_error"], dtype=np.float64 ) start_objectives = day_state["start_objectives"] messages = day_state["messages"] maturity_fits: list[MaturityFit] = [] for index, tau in enumerate(maturities): parameters = DoubleExponentialParameters( intensity=float(parameter_values[index, 0]), positive_rate=float(parameter_values[index, 1]), negative_rate=float(parameter_values[index, 2]), positive_probability=float(parameter_values[index, 3]), ) maturity_fits.append( MaturityFit( tau=float(tau), parameters=parameters, objective=float(objectives[index]), success=bool(successes[index]), iterations=int(iterations[index]), selected_start=int(selected_starts[index]), start_objectives=np.asarray( start_objectives[index], dtype=np.float64 ), num_quotes=int(num_quotes[index]), weighted_rmse=float(weighted_rmse[index]), maximum_absolute_error=float(maximum_error[index]), message=str(messages[index]), ) ) day_fits.append( DayFit( market_date=to_date(day_state["market_date"]), fits=tuple(maturity_fits), initial_symmetry_fit=bool(day_state["initial_symmetry_fit"]), ) ) audits = tuple( MarketAudit( **{ **dict(audit_state), "market_date": to_date(dict(audit_state)["market_date"]), } ) for audit_state in state["audits"] ) return cls( ticker=str(state["ticker"]), requested_dates=tuple(to_date(value) for value in state["requested_dates"]), dates=tuple(to_date(value) for value in state["dates"]), day_fits=tuple(day_fits), symmetry_curve=SymmetryCurve( maturities=np.asarray(state["symmetry_maturities"], dtype=np.float64), values=np.asarray(state["symmetry_values"], dtype=np.float64), ), forward_density=np.asarray(state["forward_density"], dtype=np.float64), consecutive_mask=np.asarray(state["consecutive_mask"], dtype=bool), reconstruction_relative_error=np.asarray( state["reconstruction_relative_error"], dtype=np.float64 ), reconstruction_l1_error=np.asarray( state["reconstruction_l1_error"], dtype=np.float64 ), reconstruction_repricing_rmse=np.asarray( state["reconstruction_repricing_rmse"], dtype=np.float64 ), reconstruction_maximum_price_error=np.asarray( state["reconstruction_maximum_price_error"], dtype=np.float64 ), reconstruction_passed=np.asarray( state["reconstruction_passed"], dtype=bool ), audits=audits, failure_reasons={ str(key): str(value) for key, value in dict(state["failure_reasons"]).items() }, )
[docs] @dataclass(frozen=True) class CoreExperimentResult: """Calibrated history, fitted dynamics, and optional Q simulation.""" history: HistoricalCalibration dynamics: DynamicsFit simulation: SimulationResult | None dynamics_end: date
def _missing_audit(market_date: date, reason: str) -> MarketAudit: return MarketAudit( market_date=market_date, early_close=market_date in get_half_days(market_date, market_date), available=False, input_expiries=0, retained_expiries=0, retained_min_tau=float("nan"), retained_max_tau=float("nan"), input_quotes=0, active_quotes=0, excluded_american_quotes=0, option_cap_bound=False, reason=reason, ) def _reconstruction_repricing_error( market: TangentLevyMarketDay, day_fit: DayFit, *, projected_average_density: np.ndarray, jump_x: np.ndarray, config: TangentLevyConfig, ) -> tuple[float, float]: """Measure the price change caused only by density reconstruction.""" normalized_errors: list[np.ndarray] = [] price_errors: list[np.ndarray] = [] for fit_index, fit in enumerate(day_fit.fits): matches = np.flatnonzero( np.isclose(market.expiries, fit.tau, rtol=0.0, atol=1.0e-8) ) verify( matches.size == 1, lambda fit=fit: ( f"fit maturity {fit.tau} does not uniquely match the market grid" ), ) market_index = int(matches[0]) strikes = market.strikes[market_index] log_strikes = np.log(strikes) fitted_calls = call_prices( tau=fit.tau, log_strikes=log_strikes, parameters=fit.parameters, config=config.static_fit.pricing, ) reconstructed_calls = density_call_prices( tau=fit.tau, log_strikes=log_strikes, jump_x=jump_x, average_density=projected_average_density[fit_index], config=config.static_fit.pricing, ) active = market.model_masks[market_index] half_spread = np.maximum( 0.5 * ( market.pure_asks[market_index] - market.pure_bids[market_index] ), config.static_fit.half_spread_floor, ) errors = reconstructed_calls[active] - fitted_calls[active] normalized_errors.append(errors / half_spread[active]) price_errors.append(errors) normalized = np.concatenate(normalized_errors) price = np.concatenate(price_errors) return ( float(np.sqrt(np.mean(np.square(normalized)))), float(np.max(np.abs(price))), )
[docs] def calibrate_history( ticker: str, start: date | str, end: date | str, *, config: TangentLevyConfig, verbose: Context | None = Context.all, maximum_dates: int | None = None, ) -> HistoricalCalibration: """Calibrate all available days and reconstruct a fixed-grid code-book panel.""" verify_inp( isinstance(ticker, str) and len(ticker) > 0, lambda: f"'ticker' must be nonempty, got {ticker!r}", ) if maximum_dates is not None: verify_inp( isinstance(maximum_dates, int) and maximum_dates > 0, lambda: f"'maximum_dates' must be positive, got {maximum_dates!r}", ) requested = market_dates(start, end) if maximum_dates is not None: requested = requested[:maximum_dates] verify_inp( len(requested) > 0, lambda: f"no exchange sessions in requested range {start} through {end}", ) requested_positions = {market_date: index for index, market_date in enumerate(requested)} tau = np.asarray(config.dynamics.tau_grid, dtype=np.float64) jump_x = np.asarray(config.dynamics.jump_x_grid, dtype=np.float64) symmetry_curve: SymmetryCurve | None = None previous_fit: DayFit | None = None dates: list[date] = [] fits: list[DayFit] = [] densities: list[np.ndarray] = [] relative_errors: list[float] = [] l1_errors: list[float] = [] repricing_errors: list[float] = [] maximum_price_errors: list[float] = [] reconstruction_passed: list[bool] = [] audits: list[MarketAudit] = [] failure_reasons: dict[str, str] = {} for market_date in requested: try: market = load_market_day( ticker, market_date, config=config.market, verbose=verbose, ) except (AssertionError, RuntimeError, ValueError) as error: reason = f"market generation failed: {error}" audits.append(_missing_audit(market_date, reason)) failure_reasons[market_date.isoformat()] = reason continue if market is None: reason = "canonical smoothed market unavailable or outside configured domain" audits.append(_missing_audit(market_date, reason)) failure_reasons[market_date.isoformat()] = reason continue audits.append(market.audit) try: day_fit = fit_market_day( market, config=config.static_fit, symmetry_curve=symmetry_curve, warm_start=previous_fit, ) candidate_symmetry_curve = ( day_fit.symmetry_curve() if symmetry_curve is None else symmetry_curve ) eta = fitted_average_density(day_fit, jump_x) reconstruction = reconstruct_forward_density( fitted_tau=day_fit.maturities, fitted_average_density=eta, target_tau=tau, jump_x=jump_x, relative_tolerance=config.static_fit.reconstruction_relative_tolerance, forward_density_floor=config.static_fit.forward_density_floor, ) repricing_rmse, maximum_price_error = _reconstruction_repricing_error( market, day_fit, projected_average_density=( reconstruction.projected_fitted_average_density ), jump_x=jump_x, config=config, ) except (RuntimeError, ValueError) as error: failure_reasons[market_date.isoformat()] = str(error) previous_fit = None continue dates.append(market_date) fits.append(day_fit) densities.append(reconstruction.forward_density) relative_errors.append(reconstruction.maximum_relative_projection) l1_errors.append(reconstruction.relative_l1_projection) repricing_errors.append(repricing_rmse) maximum_price_errors.append(maximum_price_error) reconstruction_passed.append( reconstruction.passed_tolerance and repricing_rmse <= config.static_fit.reconstruction_repricing_tolerance ) symmetry_curve = candidate_symmetry_curve previous_fit = day_fit verify( symmetry_curve is not None and len(dates) >= 3, lambda: ( "history calibration requires at least three successful dates, got " f"{len(dates)}; failures={failure_reasons}" ), ) positions = np.asarray([requested_positions[value] for value in dates], dtype=np.int64) consecutive = np.diff(positions) == 1 return HistoricalCalibration( ticker=ticker, requested_dates=tuple(requested), dates=tuple(dates), day_fits=tuple(fits), symmetry_curve=symmetry_curve, forward_density=np.stack(densities, axis=0), consecutive_mask=consecutive, reconstruction_relative_error=np.asarray(relative_errors), reconstruction_l1_error=np.asarray(l1_errors), reconstruction_repricing_rmse=np.asarray(repricing_errors), reconstruction_maximum_price_error=np.asarray(maximum_price_errors), reconstruction_passed=np.asarray(reconstruction_passed, dtype=bool), audits=tuple(audits), failure_reasons=failure_reasons, )
def _history_cache_uid( ticker: str, start: date | str, end: date | str, *, config: TangentLevyConfig, maximum_dates: int | None, ) -> str: scope = f"{ticker}/{to_date(start)}--{to_date(end)}" if maximum_dates is not None: scope += f"-first-{maximum_dates}" history_key = named_unique_filename48_8( config.label, config.user_version, config.market, config.static_fit, config.dynamics, ) return f"{scope}/{history_key}" @_history_cache(fmt=SubDir.PYTREE_HDF5).cache( "0.7", dependencies=[TangentLevyConfig], uid=_history_cache_uid, exclude_args=["verbose"], ) def _cached_history_state( ticker: str, start: date | str, end: date | str, *, config: TangentLevyConfig, verbose: Context | None, maximum_dates: int | None, ) -> dict[str, object]: return calibrate_history( ticker, start, end, config=config, verbose=verbose, maximum_dates=maximum_dates, ).to_state_dict()
[docs] def load_calibrated_history( ticker: str, start: date | str, end: date | str, *, config: TangentLevyConfig, verbose: Context | None = Context.all, maximum_dates: int | None = None, ) -> HistoricalCalibration: """Load or generate the versioned cached historical calibration.""" state = _cached_history_state( ticker, start, end, config=config, verbose=verbose, maximum_dates=maximum_dates, ) return HistoricalCalibration.from_state_dict(state)
[docs] def validate_reconstruction_gate( history: HistoricalCalibration, *, dynamics_position: int, include_simulation_origin: bool, ) -> None: """Fail before dynamics consume a materially altered static code-book.""" verify_inp( 0 < dynamics_position <= len(history.dates), lambda: ( "'dynamics_position' must identify a nonempty history prefix, got " f"{dynamics_position} for {len(history.dates)} dates" ), ) required = np.arange(dynamics_position, dtype=np.int64) if include_simulation_origin: required = np.unique( np.concatenate([required, np.asarray([len(history.dates) - 1])]) ) failed = required[~history.reconstruction_passed[required]] verify( failed.size == 0, lambda: ( "cumulative-density reconstruction gate failed for " f"{failed.size} of {required.size} required dates; examples=" f"{[history.dates[index].isoformat() for index in failed[:5]]}, " "maximum relative-L1 projection=" f"{float(np.max(history.reconstruction_l1_error[failed])):.6g}, " "maximum repricing RMSE=" f"{float(np.max(history.reconstruction_repricing_rmse[failed])):.6g} " "half-spreads. Set DynamicsConfig(require_reconstruction_pass=False) " "only for an explicitly labeled diagnostic run." ), )
[docs] def run_core_experiment( ticker: str, start: date | str, end: date | str, *, config: TangentLevyConfig, verbose: Context | None = Context.all, maximum_dates: int | None = None, dynamics_end: date | str | None = None, simulate: bool = True, ) -> CoreExperimentResult: """Calibrate history, fit constrained factors, and optionally simulate Q.""" history = load_calibrated_history( ticker, start, end, config=config, verbose=verbose, maximum_dates=maximum_dates, ) dynamics_position = ( len(history.dates) if dynamics_end is None else sum(value <= to_date(dynamics_end) for value in history.dates) ) verify_inp( dynamics_position >= config.dynamics.minimum_observations + 1, lambda: ( "dynamics cutoff leaves too few calibrated dates: " f"{dynamics_position} through {dynamics_end}" ), ) if config.dynamics.require_reconstruction_pass: validate_reconstruction_gate( history, dynamics_position=dynamics_position, include_simulation_origin=simulate, ) dynamics = fit_dynamics( history.forward_density[:dynamics_position], config=config.dynamics, consecutive_mask=history.consecutive_mask[: dynamics_position - 1], ) simulation = ( simulate_codebooks( history.forward_density[-1], dynamics, config=config.simulation, ) if simulate else None ) return CoreExperimentResult( history=history, dynamics=dynamics, simulation=simulation, dynamics_end=history.dates[dynamics_position - 1], )