Source code for quantdata.dysanos.grid.gendysanos.required_runs

"""Canonical case construction and statistical checks for required runs.

This module contains the generator-independent part of the experiment.  A
generator supplies one coherent path block using the common universe schema;
the routines below derive every hedge and transaction-cost case without
resimulating that block.
"""

from __future__ import annotations

import math
from dataclasses import asdict, dataclass
from typing import Any, Literal, Mapping

import numpy as np
from cdxcore.err import verify_inp
from scipy.optimize import linprog
from scipy.stats import beta, norm

from quantdata.dysanos.grid.rndysanos.unconditional_option_test import (
    DEFAULT_ROUNDOFF_MULTIPLIER,
    FLOAT32_UNIT_ROUNDOFF,
)

Generator = Literal["dysanos", "pca-iv"]
TradingFrequency = Literal["daily", "weekly"]
ReturnHorizon = Literal["expiry", "incremental"]
Hedge = Literal["raw", "delta"]

REPORTED_PATH_COUNTS = (100_000, 1_000_000)
REPORTED_COST_RATES = (0.0, 1.0e-4, 1.0e-3)


[docs] def positive_relative_weights(log_weights: np.ndarray) -> np.ndarray: """Exponentiate log weights stably for self-normalized calculations. Likelihood ratios can be arbitrarily close to zero. Subtracting the largest log weight preserves every self-normalized statistic; flooring at the smallest positive float64 value only represents values which would otherwise underflow to zero and has no measurable effect on the result. """ values = np.asarray(log_weights, dtype=np.float64) verify_inp(values.size > 0, "relative likelihood weights cannot be empty") if not np.all(np.isfinite(values)): raise FloatingPointError("log likelihood weights contain NaN or infinity") shifted = values - np.max(values) weights = np.exp(np.maximum(shifted, math.log(np.finfo(np.float64).tiny))) if not np.all(np.isfinite(weights)) or not np.all(weights > 0.0): raise FloatingPointError("relative likelihood weights are not finite-positive") return weights
GPU_ASSIGNMENT = { ("dysanos", "daily"): 0, ("dysanos", "weekly"): 1, ("pca-iv", "daily"): 2, ("pca-iv", "weekly"): 3, }
[docs] @dataclass(frozen=True, kw_only=True) class RequiredCase: """One of the 48 reported cases at a fixed Monte Carlo path count.""" generator: Generator trading_frequency: TradingFrequency return_horizon: ReturnHorizon hedge: Hedge cost_rate: float path_count: int num_trading_times: int = 10 schema_version: str = "1.0" def __post_init__(self) -> None: verify_inp( self.generator in {"dysanos", "pca-iv"}, lambda: f"unsupported generator {self.generator!r}", ) 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: f"unsupported return horizon {self.return_horizon!r}", ) verify_inp( self.hedge in {"raw", "delta"}, lambda: f"unsupported hedge convention {self.hedge!r}", ) verify_inp( self.cost_rate in REPORTED_COST_RATES, lambda: f"unsupported reported cost rate {self.cost_rate!r}", ) verify_inp( isinstance(self.path_count, int) and self.path_count > 1, lambda: f"path count must exceed one, got {self.path_count!r}", ) verify_inp( self.num_trading_times == 10, lambda: ( "reported markets require exactly ten trading timestamps, got " f"{self.num_trading_times}" ), ) @property def return_times(self) -> int: """Number of time-resolved return cross-sections.""" return 10 if self.return_horizon == "expiry" else 9 @property def gpu(self) -> int: """Required GPU assignment for this generator-frequency pair.""" return GPU_ASSIGNMENT[(self.generator, self.trading_frequency)] @property def base_key(self) -> tuple[str, str, int]: """Identity of the path sample shared by all twelve derived cases.""" return self.generator, self.trading_frequency, self.path_count
[docs] def required_cases(path_count: int) -> tuple[RequiredCase, ...]: """Return the complete 48-case matrix for one reported path count.""" return tuple( RequiredCase( generator=generator, trading_frequency=frequency, return_horizon=horizon, hedge=hedge, cost_rate=cost, path_count=path_count, ) for generator in ("dysanos", "pca-iv") for frequency in ("daily", "weekly") for horizon in ("expiry", "incremental") for hedge in ("delta", "raw") for cost in REPORTED_COST_RATES )
[docs] @dataclass(frozen=True, kw_only=True) class DerivedCaseArrays: """Pre-cost returns, costs, and observation-specific numerical bands.""" returns: np.ndarray costs: np.ndarray numerical_band: np.ndarray instrument_kind: tuple[str, ...] expiry_index: np.ndarray strike_index: np.ndarray return_horizon: ReturnHorizon hedge: Hedge cost_rate: float
[docs] def directional(self, direction: Literal["long", "short"]) -> np.ndarray: """Return net P&L for a unit long or short direction.""" verify_inp( direction in {"long", "short"}, lambda: f"unknown direction {direction!r}", ) signed = self.returns if direction == "long" else -self.returns return signed - self.costs
[docs] class TimeSeparatedUnconditionalAccumulator: """Stream unit-direction diagnostics without pooling trading times.""" def __init__(self, *, alpha: float = 0.05) -> None: verify_inp(0.0 < alpha < 1.0, lambda: f"invalid alpha {alpha}") self.alpha = alpha self.paths = 0 self.direct_paths = 0 self.weight_sum = 0.0 self.weight_square_sum = 0.0 self._shape: tuple[int, int] | None = None
[docs] def update( self, case: DerivedCaseArrays, *, log_path_weights: np.ndarray | None = None, importance_components: np.ndarray | None = None, ) -> None: """Accumulate one independent path block.""" S, times, instruments = case.returns.shape shape = times, instruments if self._shape is None: self._shape = shape count_shape = (2, times, instruments) self.loss = np.zeros(count_shape, dtype=np.int64) self.gain = np.zeros(count_shape, dtype=np.int64) self.neutral = np.zeros(count_shape, dtype=np.int64) self.direct_loss = np.zeros(count_shape, dtype=np.int64) self.direct_gain = np.zeros(count_shape, dtype=np.int64) self.weighted_loss = np.zeros(count_shape, dtype=np.float64) self.weighted_gain = np.zeros(count_shape, dtype=np.float64) self.weighted_loss_square = np.zeros(count_shape, dtype=np.float64) self.weighted_gain_square = np.zeros(count_shape, dtype=np.float64) self.weighted_value_sum = np.zeros(count_shape, dtype=np.float64) self.weighted_value_square_sum = np.zeros( count_shape, dtype=np.float64 ) self.direct_value_sum = np.zeros(count_shape, dtype=np.float64) self.direct_value_square_sum = np.zeros( count_shape, dtype=np.float64 ) self.instrument_kind = case.instrument_kind self.expiry_index = case.expiry_index.copy() self.strike_index = case.strike_index.copy() verify_inp(self._shape == shape, "unconditional case geometry changed") verify_inp( self.instrument_kind == case.instrument_kind and np.array_equal(self.expiry_index, case.expiry_index) and np.array_equal(self.strike_index, case.strike_index), "unconditional instrument descriptors changed", ) log_weights = ( np.zeros(S, dtype=np.float64) if log_path_weights is None else np.asarray(log_path_weights, dtype=np.float64) ) components = ( np.zeros(S, dtype=np.int16) if importance_components is None else np.asarray(importance_components) ) verify_inp( log_weights.shape == components.shape == (S,) and np.all(np.isfinite(log_weights)), "streaming path likelihood/component arrays have invalid geometry", ) weights = np.exp(log_weights) if not np.all(np.isfinite(weights)): raise FloatingPointError("streaming path weights contain NaN or infinity") direct = components == 0 weight = weights[:, None, None] for direction, sign in enumerate((1.0, -1.0)): value = sign * case.returns - case.costs loss = value < -case.numerical_band gain = value > case.numerical_band self.loss[direction] += loss.sum(axis=0, dtype=np.int64) self.gain[direction] += gain.sum(axis=0, dtype=np.int64) self.neutral[direction] += (~loss & ~gain).sum( axis=0, dtype=np.int64 ) self.direct_loss[direction] += loss[direct].sum( axis=0, dtype=np.int64 ) self.direct_gain[direction] += gain[direct].sum( axis=0, dtype=np.int64 ) weighted_value = weight * value.astype(np.float64, copy=False) self.weighted_loss[direction] += np.sum(weight * loss, axis=0) self.weighted_gain[direction] += np.sum(weight * gain, axis=0) self.weighted_loss_square[direction] += np.sum( np.square(weight * loss), axis=0 ) self.weighted_gain_square[direction] += np.sum( np.square(weight * gain), axis=0 ) self.weighted_value_sum[direction] += np.sum( weighted_value, axis=0 ) self.weighted_value_square_sum[direction] += np.sum( np.square(weighted_value), axis=0 ) self.direct_value_sum[direction] += np.sum( value[direct].astype(np.float64, copy=False), axis=0 ) self.direct_value_square_sum[direction] += np.sum( np.square(value[direct].astype(np.float64, copy=False)), axis=0 ) self.paths += S self.direct_paths += int(np.count_nonzero(direct)) self.weight_sum += float(weights.sum()) self.weight_square_sum += float(np.square(weights).sum())
[docs] def report(self) -> dict[str, Any]: """Return complete time-resolved physical-law diagnostics.""" verify_inp( self.paths > 0 and self._shape is not None, "cannot report an empty unconditional accumulator", ) verify_inp( self.direct_paths > 0, "unconditional report has no direct-P paths", ) times, instruments = self._shape mean = self.weighted_value_sum / self.paths variance = np.maximum( self.weighted_value_square_sum / self.paths - np.square(mean), 0.0, ) standard_error = np.sqrt(variance / self.paths) weighted_loss = self.weighted_loss / self.paths weighted_gain = self.weighted_gain / self.paths weighted_loss_error = np.sqrt( np.maximum( self.weighted_loss_square / self.paths - np.square(weighted_loss), 0.0, ) / self.paths ) weighted_gain_error = np.sqrt( np.maximum( self.weighted_gain_square / self.paths - np.square(weighted_gain), 0.0, ) / self.paths ) one_sided_95_z = float(norm.ppf(0.95)) direct_mean = self.direct_value_sum / self.direct_paths direct_variance = np.maximum( self.direct_value_square_sum / self.direct_paths - np.square(direct_mean), 0.0, ) direct_standard_error = np.sqrt(direct_variance / self.direct_paths) reports: list[dict[str, Any]] = [] for time_index in range(times): directions: dict[str, list[dict[str, Any]]] = {} for direction, name in enumerate(("long", "short")): items: list[dict[str, Any]] = [] for instrument in range(instruments): gain_lower, _ = clopper_pearson_one_sided( int(self.direct_gain[direction, time_index, instrument]), self.direct_paths, alpha=self.alpha, ) _, loss_upper = clopper_pearson_one_sided( int(self.direct_loss[direction, time_index, instrument]), self.direct_paths, alpha=self.alpha, ) error = standard_error[direction, time_index, instrument] value_mean = mean[direction, time_index, instrument] items.append( { "instrument": instrument, "kind": self.instrument_kind[instrument], "expiry_index": int(self.expiry_index[instrument]), "strike_index": int(self.strike_index[instrument]), "proposal_loss_count": int( self.loss[direction, time_index, instrument] ), "proposal_neutral_count": int( self.neutral[direction, time_index, instrument] ), "proposal_gain_count": int( self.gain[direction, time_index, instrument] ), "weighted_P_loss_probability": float( weighted_loss[direction, time_index, instrument] ), "weighted_P_loss_probability_standard_error": float( weighted_loss_error[ direction, time_index, instrument ] ), "weighted_P_loss_probability_upper_95": float( min( 1.0, weighted_loss[ direction, time_index, instrument ] + one_sided_95_z * weighted_loss_error[ direction, time_index, instrument ], ) ), "weighted_P_gain_probability": float( weighted_gain[direction, time_index, instrument] ), "weighted_P_gain_probability_standard_error": float( weighted_gain_error[ direction, time_index, instrument ] ), "weighted_P_gain_probability_lower_95": float( max( 0.0, weighted_gain[ direction, time_index, instrument ] - one_sided_95_z * weighted_gain_error[ direction, time_index, instrument ], ) ), "weighted_P_mean": float(value_mean), "weighted_P_path_standard_error": float(error), "weighted_P_mean_lower_95": float( value_mean - one_sided_95_z * error ), "weighted_P_mean_upper_95": float( value_mean + one_sided_95_z * error ), "weighted_P_mean_over_standard_error": ( float(value_mean / error) if error > 0.0 else math.copysign(math.inf, value_mean) if value_mean != 0.0 else 0.0 ), "direct_P_loss_count": int( self.direct_loss[direction, time_index, instrument] ), "direct_P_gain_count": int( self.direct_gain[direction, time_index, instrument] ), "direct_P_mean": float( direct_mean[direction, time_index, instrument] ), "direct_P_std_population": float( math.sqrt( direct_variance[ direction, time_index, instrument ] ) ), "direct_P_path_standard_error": float( direct_standard_error[ direction, time_index, instrument ] ), "direct_P_mean_lower_95": float( direct_mean[direction, time_index, instrument] - one_sided_95_z * direct_standard_error[ direction, time_index, instrument ] ), "direct_P_mean_upper_95": float( direct_mean[direction, time_index, instrument] + one_sided_95_z * direct_standard_error[ direction, time_index, instrument ] ), "direct_P_loss_probability_upper": loss_upper, "direct_P_gain_probability_lower": gain_lower, } ) directions[name] = items reports.append( {"trading_time_index": time_index, "directions": directions} ) return { "definition": ( "unit directions separated by trading time; physical estimates " "use N^-1 sum_r (p/q)_r f_r" ), "paths": self.paths, "direct_P_paths": self.direct_paths, "trading_times": times, "instruments": instruments, "path_weights": { "mean_p_over_q": self.weight_sum / self.paths, "effective_sample_size": ( self.weight_sum**2 / self.weight_square_sum ), }, "times": reports, }
[docs] class OptionCoverageAccumulator: """Stream strike, payoff, and pre-cost sign support by trading time.""" def __init__(self) -> None: self.paths = 0 self._shape: tuple[int, int, int] | None = None
[docs] def update( self, universe: Mapping[str, np.ndarray], *, log_path_weights: np.ndarray | None = None, ) -> None: """Accumulate one coherent path block for both hedge definitions.""" dC = np.asarray(universe["dC"], dtype=np.float32) S, times, expiries, strikes = dC.shape shape = times, expiries, strikes if self._shape is None: self._shape = shape count_shape = (times, expiries * strikes) for name in ( "crossing", "noncrossing", "raw_positive", "raw_negative", "delta_positive", "delta_negative", ): setattr(self, name, np.zeros(count_shape, dtype=np.int64)) setattr( self, f"weighted_{name}", np.zeros(count_shape, dtype=np.float64), ) verify_inp(self._shape == shape, "option coverage geometry changed") option_dS = np.asarray( universe["expiry_dS" if "expiry_dS" in universe else "option_dS"], dtype=np.float32, ) settlement_dS = np.asarray( universe.get("option_settlement_dS", option_dS), dtype=np.float32 ) spot = np.asarray(universe["spot"], dtype=np.float32) strike = np.exp(np.asarray(universe["log_strikes"], dtype=np.float32)) * spot[ ..., None, None ] endpoint_spot = spot[..., None] + settlement_dS crossing = (endpoint_spot[..., None] > strike).reshape(S, times, -1) raw = derive_case_arrays(universe, hedge="raw", cost_rate=0.0) delta = derive_case_arrays(universe, hedge="delta", cost_rate=0.0) spot_instruments = sum(kind == "spot" for kind in raw.instrument_kind) verify_inp( spot_instruments == expiries, lambda: ( f"expected one spot instrument per expiry, got " f"{spot_instruments}/{expiries}" ), ) raw_return = raw.returns[..., spot_instruments:] raw_band = raw.numerical_band[..., spot_instruments:] delta_return = delta.returns[..., spot_instruments:] delta_band = delta.numerical_band[..., spot_instruments:] events = { "crossing": crossing, "noncrossing": ~crossing, "raw_positive": raw_return > raw_band, "raw_negative": raw_return < -raw_band, "delta_positive": delta_return > delta_band, "delta_negative": delta_return < -delta_band, } weights = np.exp( np.zeros(S, dtype=np.float64) if log_path_weights is None else np.asarray(log_path_weights, dtype=np.float64) ) verify_inp( weights.shape == (S,) and np.all(np.isfinite(weights)), "option coverage weights have invalid geometry", ) for name, event in events.items(): getattr(self, name)[:] += event.sum(axis=0, dtype=np.int64) getattr(self, f"weighted_{name}")[:] += np.sum( weights[:, None, None] * event, axis=0 ) self.paths += S
[docs] def report(self, *, target_count: int = 1_000) -> dict[str, Any]: """Return complete time-resolved coverage counts and probabilities.""" verify_inp(self.paths > 0 and self._shape is not None, "no coverage accumulated") times, expiries, strikes = self._shape reports = [] for time_index in range(times): reports.append( { "trading_time_index": time_index, **{ name: getattr(self, name)[time_index].tolist() for name in ( "crossing", "noncrossing", "raw_positive", "raw_negative", "delta_positive", "delta_negative", ) }, **{ f"weighted_P_{name}_probability": ( getattr(self, f"weighted_{name}")[time_index] / self.paths ).tolist() for name in ( "crossing", "noncrossing", "raw_positive", "raw_negative", "delta_positive", "delta_negative", ) }, } ) minima = { name: int(np.min(getattr(self, name))) for name in ( "crossing", "noncrossing", "raw_positive", "raw_negative", "delta_positive", "delta_negative", ) } return { "paths": self.paths, "trading_times": times, "expiries": expiries, "strikes": strikes, "target_proposal_count_per_side": target_count, "minimum_counts": minima, "all_strike_and_precost_sign_sides_meet_target": bool( all(value >= target_count for value in minima.values()) ), "times": reports, }
def _option_endpoint_scale( universe: Mapping[str, np.ndarray], ) -> tuple[np.ndarray, np.ndarray]: """Return unreduced option arithmetic scale and matched spot change.""" dC = np.asarray(universe["dC"], dtype=np.float32) C = np.asarray(universe["C"], dtype=np.float32) spot = np.asarray(universe["spot"], dtype=np.float32) log_strikes = np.asarray(universe["log_strikes"], dtype=np.float32) option_dS_name = "expiry_dS" if "expiry_dS" in universe else "option_dS" option_dS = np.asarray(universe[option_dS_name], dtype=np.float32) settlement_dS = np.asarray( universe.get("option_settlement_dS", option_dS), dtype=np.float32 ) # An option and its entry delta hedge close together. For an incremental # interval containing expiry, the matched hedge endpoint is therefore the # exact settlement spot rather than the later trading-time spot. if "expiry_dS" not in universe: option_dS = settlement_dS verify_inp( dC.shape == C.shape == log_strikes.shape, lambda: ( "option return, premium, and strike shapes differ: " f"{dC.shape}/{C.shape}/{log_strikes.shape}" ), ) verify_inp( option_dS.shape == dC.shape[:3], lambda: f"matched option spot return has invalid shape {option_dS.shape}", ) verify_inp( settlement_dS.shape == dC.shape[:3], lambda: ( "matched option settlement spot return has invalid shape " f"{settlement_dS.shape}" ), ) cash_strike = np.exp(log_strikes) * spot[..., None, None] endpoint_spot = spot[..., None] + settlement_dS expiry_scale = ( np.abs(endpoint_spot[..., None]) + np.abs(cash_strike) + np.abs(C) ) marked_scale = np.abs(C + dC) + np.abs(C) expired = np.asarray( universe.get( "option_expired", np.ones((1, 1, dC.shape[2]), dtype=bool), ), dtype=bool, ) verify_inp( expired.shape == (1, 1, dC.shape[2]), lambda: f"option expiry marker has invalid shape {expired.shape}", ) scale = np.where(expired[..., None], expiry_scale, marked_scale) return scale, option_dS
[docs] def derive_case_arrays( universe: Mapping[str, np.ndarray], *, hedge: Hedge, cost_rate: float, roundoff_multiplier: float = DEFAULT_ROUNDOFF_MULTIPLIER, ) -> DerivedCaseArrays: """Derive one case from a shared coherent path block. Expiry and incremental cases contain one spot instrument for every option expiry. For incremental returns the spot leg closes with its expiry group: at exact expiry when it occurs inside the interval and at the next trading time otherwise. Option costs are ``q*|C|`` when raw and ``q*(|C|+|delta*S|)`` when delta hedged. No option/spot notional is netted. """ verify_inp(hedge in {"raw", "delta"}, lambda: f"unknown hedge {hedge!r}") verify_inp( cost_rate in REPORTED_COST_RATES, lambda: f"unsupported reported cost rate {cost_rate!r}", ) verify_inp( math.isfinite(roundoff_multiplier) and roundoff_multiplier > 0.0, lambda: f"invalid roundoff multiplier {roundoff_multiplier!r}", ) dC = np.asarray(universe["dC"], dtype=np.float32) C = np.asarray(universe["C"], dtype=np.float32) delta = np.asarray(universe["delta"], dtype=np.float32) spot = np.asarray(universe["spot"], dtype=np.float32) verify_inp( dC.ndim == 4 and C.shape == delta.shape == dC.shape, lambda: f"option arrays must share shape (S,m,T,N), got {dC.shape}", ) S, times, expiries, strikes = dC.shape verify_inp( spot.shape == (S, times), lambda: f"entry spot has invalid shape {spot.shape}", ) option_scale, option_dS = _option_endpoint_scale(universe) option_return = dC.copy() option_cost_notional = np.abs(C) if hedge == "delta": option_return -= delta * option_dS[..., None] option_cost_notional = option_cost_notional + np.abs( delta * spot[..., None, None] ) endpoint_spot = spot[..., None] + option_dS option_scale = option_scale + np.abs(delta) * ( np.abs(endpoint_spot[..., None]) + np.abs(spot[..., None, None]) ) option_cost = np.float32(cost_rate) * option_cost_notional horizon: ReturnHorizon = ( "expiry" if "expiry_dS" in universe else "incremental" ) spot_return = option_dS spot_entry = np.broadcast_to(spot[..., None], spot_return.shape) spot_kind = ("spot",) * expiries spot_expiry = np.arange(expiries, dtype=np.int32) spot_endpoint = spot_entry + spot_return spot_cost = np.float32(cost_rate) * np.abs(spot_entry) spot_scale = np.abs(spot_endpoint) + np.abs(spot_entry) option_return = option_return.reshape(S, times, expiries * strikes) option_cost = option_cost.reshape(S, times, expiries * strikes) option_scale = option_scale.reshape(S, times, expiries * strikes) returns = np.concatenate((spot_return, option_return), axis=-1) costs = np.concatenate((spot_cost, option_cost), axis=-1) unreduced_scale = np.concatenate((spot_scale, option_scale), axis=-1) numerical_band = ( roundoff_multiplier * FLOAT32_UNIT_ROUNDOFF * np.maximum( unreduced_scale + np.abs(costs), np.finfo(np.float32).tiny, ) ) option_expiry = np.repeat(np.arange(expiries, dtype=np.int32), strikes) option_strike = np.tile(np.arange(strikes, dtype=np.int32), expiries) result = DerivedCaseArrays( returns=returns.astype(np.float32, copy=False), costs=costs.astype(np.float32, copy=False), numerical_band=numerical_band.astype(np.float32, copy=False), instrument_kind=spot_kind + ("option",) * (expiries * strikes), expiry_index=np.concatenate((spot_expiry, option_expiry)), strike_index=np.concatenate( ( np.full(len(spot_kind), -1, dtype=np.int32), option_strike, )), return_horizon=horizon, hedge=hedge, cost_rate=cost_rate, ) expected = (S, times, len(result.instrument_kind)) verify_inp( result.returns.shape == result.costs.shape == result.numerical_band.shape == expected, lambda: f"derived case geometry is inconsistent with {expected}", ) for name, value in ( ("returns", result.returns), ("costs", result.costs), ("numerical_band", result.numerical_band), ): if not np.all(np.isfinite(value)): raise FloatingPointError(f"derived case {name} contain NaN or infinity") verify_inp(np.all(result.costs >= 0.0), "transaction costs must be nonnegative") verify_inp( np.all(result.numerical_band > 0.0), "numerical bands must be strictly positive", ) return result
[docs] def propagated_basket_band( action: np.ndarray, returns: np.ndarray, costs: np.ndarray, instrument_band: np.ndarray, *, roundoff_multiplier: float = DEFAULT_ROUNDOFF_MULTIPLIER, ) -> np.ndarray: """Propagate instrument bands to a basket without a cash floor.""" action = np.asarray(action, dtype=np.float64) returns = np.asarray(returns, dtype=np.float64) costs = np.asarray(costs, dtype=np.float64) instrument_band = np.asarray(instrument_band, dtype=np.float64) verify_inp( action.ndim == 1 and returns.shape == costs.shape == instrument_band.shape and returns.shape[-1] == action.size, "basket action and case arrays have incompatible shapes", ) absolute_action = np.abs(action) return np.einsum("...j,j->...", instrument_band, absolute_action) + ( roundoff_multiplier * FLOAT32_UNIT_ROUNDOFF * ( np.einsum("...j,j->...", np.abs(returns), absolute_action) + np.einsum("...j,j->...", costs, absolute_action) ) )
[docs] def float64_replay_report( universe: Mapping[str, np.ndarray], case: DerivedCaseArrays, ) -> dict[str, Any]: """Replay return and gross-cost identities from primitive arrays in float64.""" dC = np.asarray(universe["dC"], dtype=np.float64) C = np.asarray(universe["C"], dtype=np.float64) delta = np.asarray(universe["delta"], dtype=np.float64) spot = np.asarray(universe["spot"], dtype=np.float64) option_dS = np.asarray( universe[ "expiry_dS" if "expiry_dS" in universe else ( "option_settlement_dS" if "option_settlement_dS" in universe else "option_dS" ) ], dtype=np.float64, ) option_return = dC - delta * option_dS[..., None] if case.hedge == "delta" else dC option_cost_notional = np.abs(C) if case.hedge == "delta": option_cost_notional += np.abs(delta * spot[..., None, None]) option_cost = case.cost_rate * option_cost_notional spot_return = option_dS spot_entry = np.broadcast_to(spot[..., None], spot_return.shape) replay_return = np.concatenate( ( spot_return, option_return.reshape(*option_return.shape[:2], -1), ), axis=-1, ) replay_cost = np.concatenate( ( case.cost_rate * np.abs(spot_entry), option_cost.reshape(*option_cost.shape[:2], -1), ), axis=-1, ) return_error = np.abs(replay_return - case.returns.astype(np.float64)) cost_error = np.abs(replay_cost - case.costs.astype(np.float64)) band = case.numerical_band.astype(np.float64) expiry_error = np.empty(0, dtype=np.float64) expiry_band = np.empty(0, dtype=np.float64) option_band = band[ ..., len(case.instrument_kind) - dC.shape[2] * dC.shape[3] : ].reshape(dC.shape) if case.return_horizon == "expiry": cash_strike = ( np.exp(np.asarray(universe["log_strikes"], dtype=np.float64)) * spot[..., None, None] ) payoff = np.maximum( spot[..., None, None] + option_dS[..., None] - cash_strike, 0.0, ) expiry_error = np.abs((payoff - C) - dC).reshape( *dC.shape[:2], -1 ) expiry_band = option_band.reshape(*dC.shape[:2], -1) else: expired = np.asarray(universe["option_expired"], dtype=bool) if np.any(expired): settlement_dS = np.asarray( universe["option_settlement_dS"], dtype=np.float64 ) cash_strike = ( np.exp(np.asarray(universe["log_strikes"], dtype=np.float64)) * spot[..., None, None] ) payoff = np.maximum( spot[..., None, None] + settlement_dS[..., None] - cash_strike, 0.0, ) expired_mask = np.broadcast_to(expired[..., None], dC.shape) expiry_error = np.abs((payoff - C) - dC)[expired_mask] expiry_band = option_band[expired_mask] passed = bool( np.all(return_error <= band) and np.all(cost_error <= band) and ( expiry_error.size == 0 or np.all(expiry_error <= expiry_band) ) ) return { "passed": passed, "precision": "float64 replay from stored float32 primitive operands", "maximum_absolute_return_identity_error": float(np.max(return_error)), "maximum_absolute_cost_identity_error": float(np.max(cost_error)), "maximum_absolute_expiry_payoff_identity_error": ( float(np.max(expiry_error)) if expiry_error.size else None ), "all_errors_within_observation_specific_float32_band": passed, }
[docs] @dataclass(frozen=True, kw_only=True) class PathSplit: """Disjoint proposal-mixture-stratified reference and audit paths.""" reference: np.ndarray audit: np.ndarray component_counts: dict[int, dict[str, int]] audit_fraction: float seed: int
[docs] def stratified_path_split( components: np.ndarray, *, audit_fraction: float = 0.2, seed: int, ) -> PathSplit: """Split complete paths 80:20 while preserving mixture proportions.""" components = np.asarray(components) verify_inp( components.ndim == 1 and components.size >= 2, lambda: f"mixture components must contain at least two paths, got {components.shape}", ) verify_inp( 0.0 < audit_fraction < 1.0, lambda: f"audit fraction must lie in (0,1), got {audit_fraction}", ) labels, counts = np.unique(components, return_counts=True) target = int(round(audit_fraction * components.size)) exact = audit_fraction * counts audit_counts = np.floor(exact).astype(np.int64) remainder = target - int(audit_counts.sum()) order = np.argsort(-(exact - audit_counts), kind="stable") audit_counts[order[:remainder]] += 1 rng = np.random.default_rng(seed) reference_parts: list[np.ndarray] = [] audit_parts: list[np.ndarray] = [] report: dict[int, dict[str, int]] = {} for label, count, audit_count in zip(labels, counts, audit_counts, strict=True): indices = np.flatnonzero(components == label) rng.shuffle(indices) selected = indices[:audit_count] retained = indices[audit_count:] audit_parts.append(selected) reference_parts.append(retained) report[int(label)] = { "total": int(count), "reference": int(retained.size), "audit": int(selected.size), } reference = np.sort(np.concatenate(reference_parts)).astype(np.int64) audit = np.sort(np.concatenate(audit_parts)).astype(np.int64) verify_inp( reference.size + audit.size == components.size and audit.size == target and np.intersect1d(reference, audit).size == 0, "stratified split is not a disjoint exhaustive partition", ) return PathSplit( reference=reference, audit=audit, component_counts=report, audit_fraction=audit_fraction, seed=seed, )
[docs] def clopper_pearson_one_sided( successes: int, observations: int, *, alpha: float = 0.05, ) -> tuple[float, float]: """Return exact one-sided lower and upper binomial confidence bounds.""" verify_inp( 0 <= successes <= observations and observations > 0, lambda: f"invalid binomial counts {successes}/{observations}", ) verify_inp(0.0 < alpha < 1.0, lambda: f"invalid alpha {alpha}") lower = ( 0.0 if successes == 0 else float(beta.ppf(alpha, successes, observations - successes + 1)) ) upper = ( 1.0 if successes == observations else float(beta.ppf(1.0 - alpha, successes + 1, observations - successes)) ) return lower, upper
def _weighted_moment(values: np.ndarray, weights: np.ndarray) -> dict[str, float]: """Return ``N^-1 sum(w*x)``, its path error, and effective size.""" values = np.asarray(values, dtype=np.float64) weights = np.asarray(weights, dtype=np.float64) verify_inp( values.shape == weights.shape and values.ndim == 1, "weighted moment requires equal one-dimensional arrays", ) mass = float(weights.sum()) square_mass = float(np.square(weights).sum()) verify_inp( math.isfinite(mass) and mass > 0.0 and square_mass > 0.0, "weighted moment has zero or non-finite mass", ) weighted_value = weights * values mean = float(np.mean(weighted_value)) error = float(np.std(weighted_value, ddof=0) / math.sqrt(values.size)) return { "mean": mean, "standard_error": error, "effective_sample_size": mass * mass / square_mass, }
[docs] def time_separated_unconditional_report( case: DerivedCaseArrays, *, log_path_weights: np.ndarray | None = None, importance_components: np.ndarray | None = None, alpha: float = 0.05, ) -> dict[str, Any]: """Report unit long/short screens separately at every trading time.""" S, times, instruments = case.returns.shape log_weights = ( np.zeros(S, dtype=np.float64) if log_path_weights is None else np.asarray(log_path_weights, dtype=np.float64) ) components = ( np.zeros(S, dtype=np.int16) if importance_components is None else np.asarray(importance_components) ) verify_inp( log_weights.shape == components.shape == (S,) and np.all(np.isfinite(log_weights)), "path likelihood/component arrays have invalid geometry", ) weights = np.exp(log_weights) verify_inp(np.all(np.isfinite(weights)), "path weights contain NaN or infinity") direct = components == 0 verify_inp(np.any(direct), "no direct-P paths are available for incidence checks") time_reports: list[dict[str, Any]] = [] for time_index in range(times): direction_reports: dict[str, list[dict[str, Any]]] = {} for direction in ("long", "short"): values = case.directional(direction)[:, time_index] band = case.numerical_band[:, time_index] loss = values < -band gain = values > band items: list[dict[str, Any]] = [] for instrument in range(instruments): weighted_value = _weighted_moment(values[:, instrument], weights) weighted_loss = float( np.dot(weights, loss[:, instrument]) / S ) weighted_gain = float( np.dot(weights, gain[:, instrument]) / S ) direct_loss = int(np.count_nonzero(loss[direct, instrument])) direct_gain = int(np.count_nonzero(gain[direct, instrument])) direct_count = int(np.count_nonzero(direct)) _, loss_upper = clopper_pearson_one_sided( direct_loss, direct_count, alpha=alpha ) gain_lower, _ = clopper_pearson_one_sided( direct_gain, direct_count, alpha=alpha ) items.append( { "instrument": instrument, "kind": case.instrument_kind[instrument], "expiry_index": int(case.expiry_index[instrument]), "strike_index": int(case.strike_index[instrument]), "proposal_loss_count": int(np.count_nonzero(loss[:, instrument])), "proposal_neutral_count": int( S - np.count_nonzero(loss[:, instrument]) - np.count_nonzero(gain[:, instrument]) ), "proposal_gain_count": int(np.count_nonzero(gain[:, instrument])), "weighted_P_loss_probability": weighted_loss, "weighted_P_gain_probability": weighted_gain, "weighted_P_mean": weighted_value["mean"], "weighted_P_path_standard_error": weighted_value[ "standard_error" ], "weighted_P_mean_over_standard_error": ( weighted_value["mean"] / weighted_value["standard_error"] if weighted_value["standard_error"] > 0.0 else math.copysign(math.inf, weighted_value["mean"]) if weighted_value["mean"] != 0.0 else 0.0 ), "direct_P_paths": direct_count, "direct_P_loss_count": direct_loss, "direct_P_gain_count": direct_gain, "direct_P_loss_probability_upper": loss_upper, "direct_P_gain_probability_lower": gain_lower, } ) direction_reports[direction] = items time_reports.append( {"trading_time_index": time_index, "directions": direction_reports} ) return { "definition": ( "pre-specified unit directions, reported separately by trading time; " "transaction cost is subtracted before comparison with eta" ), "paths": S, "trading_times": times, "instruments": instruments, "direct_P_paths": int(np.count_nonzero(direct)), "path_weight_mean": float(weights.mean()), "path_weight_effective_sample_size": float( np.square(weights.sum()) / np.square(weights).sum() ), "times": time_reports, }
[docs] def solve_constant_basket( case: DerivedCaseArrays, *, time_index: int, reference_paths: np.ndarray, log_path_weights: np.ndarray | None = None, feasibility_tolerance: float = 1.0e-10, constraints_per_iteration: int = 128, maximum_iterations: int = 50, ) -> dict[str, Any]: """Solve the constant-basket reference problem by constraint generation.""" paths = np.asarray(reference_paths, dtype=np.int64) verify_inp( paths.ndim == 1 and paths.size > 0, "constant-basket solver requires nonempty reference paths", ) verify_inp( 0 <= time_index < case.returns.shape[1], lambda: f"invalid trading time {time_index}", ) returns = case.returns[paths, time_index].astype(np.float64, copy=False) costs = case.costs[paths, time_index].astype(np.float64, copy=False) bands = case.numerical_band[paths, time_index].astype(np.float64, copy=False) S, instruments = returns.shape weights = ( np.ones(S, dtype=np.float64) if log_path_weights is None else positive_relative_weights( np.asarray(log_path_weights, dtype=np.float64)[paths] ) ) weights /= weights.sum() mean_return = weights @ returns mean_cost = weights @ costs zero_cost = not np.any(costs) if zero_cost: # Represent the signed action directly and bound its absolute value by # an auxiliary vector. This is exactly the zero-cost problem and # removes the a_plus/a_minus null directions which otherwise make the # LP highly degenerate. objective = np.concatenate((-mean_return, np.zeros(instruments))) l1 = np.concatenate( (np.zeros((1, instruments)), np.ones((1, instruments))), axis=1 ) identity = np.eye(instruments, dtype=np.float64) absolute_envelope = np.concatenate( ( np.concatenate((identity, -identity), axis=1), np.concatenate((-identity, -identity), axis=1), ), axis=0, ) bounds: tuple[float | None, float | None] | list[tuple[float | None, float | None]] = [ (None, None) ] * instruments + [(0.0, None)] * instruments else: objective = -np.concatenate( (mean_return - mean_cost, -mean_return - mean_cost) ) l1 = np.ones((1, 2 * instruments), dtype=np.float64) absolute_envelope = np.empty((0, 2 * instruments), dtype=np.float64) bounds = (0.0, None) selected = np.empty(0, dtype=np.int64) result = None action = np.zeros(instruments, dtype=np.float64) full_constraint_fallback = False highs_feasibility_tolerance = max(feasibility_tolerance, 1.0e-10) def result_action(optimized: Any) -> np.ndarray: return ( optimized.x[:instruments] if zero_cost else optimized.x[:instruments] - optimized.x[instruments:] ) def optimize(constraint_paths: np.ndarray) -> Any: if constraint_paths.size: R = returns[constraint_paths] C = costs[constraint_paths] # Enforce the economic non-loss condition -X <= 0. The numerical # band is used only when classifying and auditing the resulting # net action. Including it here can make the effective cost # negative and permits simultaneous positive a_plus and a_minus # to create an artificial tolerance without a net position. A = ( np.concatenate((-R, np.zeros_like(R)), axis=1) if zero_cost else np.concatenate((-R + C, R + C), axis=1) ) A_ub = np.concatenate((l1, absolute_envelope, A), axis=0) b_ub = np.concatenate( ( np.ones(1), np.zeros(absolute_envelope.shape[0] + constraint_paths.size), ) ) else: A_ub = np.concatenate((l1, absolute_envelope), axis=0) b_ub = np.concatenate( (np.ones(1), np.zeros(absolute_envelope.shape[0])) ) optimized = linprog( objective, A_ub=A_ub, b_ub=b_ub, bounds=bounds, method="highs", options={ "primal_feasibility_tolerance": highs_feasibility_tolerance, "dual_feasibility_tolerance": highs_feasibility_tolerance, "ipm_optimality_tolerance": highs_feasibility_tolerance, }, ) if not optimized.success: raise RuntimeError( f"constant-basket optimizer failed: {optimized.message}" ) return optimized for iteration in range(maximum_iterations): result = optimize(selected) action = result_action(result) pnl = returns @ action - costs @ np.abs(action) propagated = propagated_basket_band(action, returns, costs, bands) violation = -pnl violating = np.flatnonzero(violation > feasibility_tolerance) if violating.size == 0: break worst = violating[ np.argsort(-violation[violating], kind="stable")[:constraints_per_iteration] ] expanded = np.unique(np.concatenate((selected, worst))) if expanded.size == selected.size: full_constraint_fallback = True selected = np.arange(S, dtype=np.int64) result = optimize(selected) action = result_action(result) pnl = returns @ action - costs @ np.abs(action) propagated = propagated_basket_band(action, returns, costs, bands) if np.any(-pnl > feasibility_tolerance): raise RuntimeError( "constant-basket full-constraint solution is infeasible at " "the requested numerical tolerance" ) break selected = expanded else: full_constraint_fallback = True selected = np.arange(S, dtype=np.int64) result = optimize(selected) action = result_action(result) pnl = returns @ action - costs @ np.abs(action) propagated = propagated_basket_band(action, returns, costs, bands) if np.any(-pnl > feasibility_tolerance): raise RuntimeError( "constant-basket full-constraint solution is infeasible at the " "requested numerical tolerance" ) iteration = maximum_iterations assert result is not None pnl = returns @ action - costs @ np.abs(action) propagated = propagated_basket_band(action, returns, costs, bands) return { "time_index": time_index, "action": action, "l1_norm": float(np.abs(action).sum()), "objective_mean": float(np.dot(weights, pnl)), "minimum_economic_pnl": float(np.min(pnl)), "maximum_economic_pnl": float(np.max(pnl)), "minimum_pnl_minus_negative_band": float(np.min(pnl + propagated)), "gain_count": int(np.count_nonzero(pnl > propagated)), "gain_fraction": float(np.mean(pnl > propagated)), "binding_path_count": int( np.count_nonzero(np.abs(pnl + propagated) <= feasibility_tolerance) ), "constraints_retained": int(selected.size), "iterations": iteration + 1, "optimizer_status": int(result.status), "optimizer_message": result.message, "feasibility_tolerance": feasibility_tolerance, "reference_constraint": "economic P&L X >= 0", "highs_feasibility_tolerance": highs_feasibility_tolerance, "full_constraint_fallback": full_constraint_fallback, "zero_cost_signed_action_formulation": ( "free-signed-action-v2" if zero_cost else False ), }
[docs] def certify_unconditional_directions( case: DerivedCaseArrays, *, split: PathSplit, log_path_weights: np.ndarray, importance_components: np.ndarray, family_size: int = 131_472, alpha: float = 0.05, bootstrap_repetitions: int = 500, seed: int = 1, prerequisite_checks_passed: bool, ) -> dict[str, Any]: """Screen on reference paths and certify frozen unit directions on audit. The state region is the complete state space, so this is the independent audit for unconditional individual directions. Conditional regions and fitted baskets require their own frozen-region audit. """ verify_inp(family_size > 0, "candidate family size must be positive") verify_inp( bootstrap_repetitions > 0, "candidate bootstrap repetitions must be positive", ) S, times, instruments = case.returns.shape log_weights = np.asarray(log_path_weights, dtype=np.float64) components = np.asarray(importance_components) verify_inp( log_weights.shape == components.shape == (S,), "candidate likelihood arrays have invalid geometry", ) reference_values = np.stack( ( case.returns[split.reference] - case.costs[split.reference], -case.returns[split.reference] - case.costs[split.reference], ), axis=0, ) reference_band = case.numerical_band[split.reference][None] reference_loss = np.sum(reference_values < -reference_band, axis=1) reference_gain = np.sum(reference_values > reference_band, axis=1) screened = np.argwhere((reference_loss == 0) & (reference_gain > 0)) adjusted_alpha = alpha / family_size z_adjusted = float(norm.ppf(1.0 - adjusted_alpha)) audit_weights = positive_relative_weights(log_weights[split.audit]) audit_direct = components[split.audit] == 0 direct_count = int(np.count_nonzero(audit_direct)) verify_inp(direct_count > 1, "candidate audit requires two direct-P paths") rng = np.random.default_rng(seed) rejected: list[dict[str, Any]] = [] surviving: list[dict[str, Any]] = [] for direction, time_index, instrument in screened: sign = 1.0 if direction == 0 else -1.0 audit_value = ( sign * case.returns[split.audit, time_index, instrument] - case.costs[split.audit, time_index, instrument] ).astype(np.float64, copy=False) audit_band = case.numerical_band[ split.audit, time_index, instrument ].astype(np.float64, copy=False) loss = audit_value < -audit_band gain = audit_value > audit_band direct_value = audit_value[audit_direct] direct_loss = int(np.count_nonzero(loss[audit_direct])) direct_gain = int(np.count_nonzero(gain[audit_direct])) direct_mean = float(np.mean(direct_value)) direct_error = float(np.std(direct_value, ddof=0) / math.sqrt(direct_count)) direct_mean_lower = direct_mean - z_adjusted * direct_error direct_gain_lower, _ = clopper_pearson_one_sided( direct_gain, direct_count, alpha=adjusted_alpha ) _, direct_loss_upper = clopper_pearson_one_sided( direct_loss, direct_count, alpha=adjusted_alpha ) weighted_mass = float(audit_weights.sum()) weighted_mean = float(np.dot(audit_weights, audit_value) / weighted_mass) weighted_gain = float(np.dot(audit_weights, gain) / weighted_mass) weighted_loss = float(np.dot(audit_weights, loss) / weighted_mass) weighted_mean_error = float( np.sqrt( np.dot( np.square(audit_weights), np.square(audit_value - weighted_mean), ) ) / weighted_mass ) weighted_gain_error = float( np.sqrt( np.dot( np.square(audit_weights), np.square(gain.astype(np.float64) - weighted_gain), ) ) / weighted_mass ) weighted_mean_lower = weighted_mean - z_adjusted * weighted_mean_error weighted_gain_lower = weighted_gain - z_adjusted * weighted_gain_error bootstrap_mean = np.empty(bootstrap_repetitions, dtype=np.float64) bootstrap_gain = np.empty(bootstrap_repetitions, dtype=np.float64) for repetition in range(bootstrap_repetitions): multiplicity = rng.poisson(1.0, size=split.audit.size) bootstrap_weight = audit_weights * multiplicity mass = float(bootstrap_weight.sum()) if mass <= 0.0: bootstrap_mean[repetition] = weighted_mean bootstrap_gain[repetition] = weighted_gain else: bootstrap_mean[repetition] = float( np.dot(bootstrap_weight, audit_value) / mass ) bootstrap_gain[repetition] = float( np.dot(bootstrap_weight, gain) / mass ) pointwise_bootstrap_mean_lower = float( np.quantile(bootstrap_mean, alpha, method="linear") ) pointwise_bootstrap_gain_lower = float( np.quantile(bootstrap_gain, alpha, method="linear") ) conditions = { "no_audit_loss_beyond_band": int(np.count_nonzero(loss)) == 0, "adjusted_direct_P_gain_lower_positive": direct_gain_lower > 0.0, "adjusted_direct_P_mean_lower_positive": direct_mean_lower > 0.0, "adjusted_weighted_P_gain_lower_positive": weighted_gain_lower > 0.0, "adjusted_weighted_P_mean_lower_positive": weighted_mean_lower > 0.0, "direct_and_weighted_conclusions_agree": ( direct_gain_lower > 0.0 and direct_mean_lower > 0.0 and weighted_gain_lower > 0.0 and weighted_mean_lower > 0.0 ), "importance_coverage_and_replay_pass": prerequisite_checks_passed, } item = { "trading_time_index": int(time_index), "instrument": int(instrument), "kind": case.instrument_kind[instrument], "expiry_index": int(case.expiry_index[instrument]), "strike_index": int(case.strike_index[instrument]), "direction": "long" if direction == 0 else "short", "state_region": "complete state space", "strategy_class": "unconditional unit instrument direction", "reference_loss_count": int(reference_loss[direction, time_index, instrument]), "reference_gain_count": int(reference_gain[direction, time_index, instrument]), "audit_paths": int(split.audit.size), "audit_loss_count": int(np.count_nonzero(loss)), "audit_gain_count": int(np.count_nonzero(gain)), "direct_P_paths": direct_count, "direct_P_loss_count": direct_loss, "direct_P_gain_count": direct_gain, "adjusted_direct_P_loss_probability_upper": direct_loss_upper, "adjusted_direct_P_gain_probability_lower": direct_gain_lower, "direct_P_mean": direct_mean, "adjusted_direct_P_mean_lower": direct_mean_lower, "weighted_P_loss_probability": weighted_loss, "weighted_P_gain_probability": weighted_gain, "adjusted_weighted_P_gain_probability_lower": weighted_gain_lower, "weighted_P_mean": weighted_mean, "adjusted_weighted_P_mean_lower": weighted_mean_lower, "pointwise_bootstrap_weighted_P_gain_lower": ( pointwise_bootstrap_gain_lower ), "pointwise_bootstrap_weighted_P_mean_lower": ( pointwise_bootstrap_mean_lower ), "regional_effective_sample_size": float( weighted_mass**2 / np.square(audit_weights).sum() ), "conditions": conditions, "certified": bool(all(conditions.values())), } (surviving if item["certified"] else rejected).append(item) return { "strategy_class": "unconditional unit instrument directions", "state_region": "complete state space", "reference_screened_candidates": int(screened.shape[0]), "multiplicity": { "method": "Bonferroni familywise correction", "family_size": family_size, "pointwise_alpha": alpha, "adjusted_alpha": adjusted_alpha, }, "weighted_interval": { "adjusted": "normal path-level influence interval", "pointwise": ( f"Poisson complete-path bootstrap, {bootstrap_repetitions} repetitions" ), }, "surviving": surviving, "rejected": rejected, }
[docs] def audit_constant_basket( solution: Mapping[str, Any], case: DerivedCaseArrays, *, split: PathSplit, log_path_weights: np.ndarray, importance_components: np.ndarray, family_size: int = 480, alpha: float = 0.05, prerequisite_checks_passed: bool, ) -> dict[str, Any]: """Evaluate one frozen reference-fitted constant basket on audit paths.""" time_index = int(solution["time_index"]) action = np.asarray(solution["action"], dtype=np.float64) verify_inp( action.shape == (case.returns.shape[-1],), "constant basket action has invalid geometry", ) if np.abs(action).sum() <= 1.0e-14 or solution["gain_count"] == 0: return { **dict(solution), "action": action, "audit_status": "no nonzero reference candidate", "certified": False, } returns = case.returns[split.audit, time_index].astype(np.float64, copy=False) costs = case.costs[split.audit, time_index].astype(np.float64, copy=False) bands = case.numerical_band[split.audit, time_index].astype( np.float64, copy=False ) pnl = returns @ action - costs @ np.abs(action) band = propagated_basket_band(action, returns, costs, bands) loss = pnl < -band gain = pnl > band components = np.asarray(importance_components)[split.audit] direct = components == 0 direct_count = int(np.count_nonzero(direct)) verify_inp(direct_count > 1, "constant basket audit lacks direct-P paths") direct_loss = int(np.count_nonzero(loss[direct])) direct_gain = int(np.count_nonzero(gain[direct])) adjusted_alpha = alpha / family_size gain_lower, _ = clopper_pearson_one_sided( direct_gain, direct_count, alpha=adjusted_alpha ) _, loss_upper = clopper_pearson_one_sided( direct_loss, direct_count, alpha=adjusted_alpha ) direct_mean = float(np.mean(pnl[direct])) direct_error = float(np.std(pnl[direct], ddof=0) / math.sqrt(direct_count)) z = float(norm.ppf(1.0 - adjusted_alpha)) direct_mean_lower = direct_mean - z * direct_error weights = positive_relative_weights( np.asarray(log_path_weights, dtype=np.float64)[split.audit] ) mass = float(weights.sum()) weighted_mean = float(np.dot(weights, pnl) / mass) weighted_error = float( np.sqrt(np.dot(np.square(weights), np.square(pnl - weighted_mean))) / mass ) weighted_mean_lower = weighted_mean - z * weighted_error conditions = { "no_audit_loss_beyond_band": int(np.count_nonzero(loss)) == 0, "adjusted_direct_P_gain_lower_positive": gain_lower > 0.0, "adjusted_direct_P_mean_lower_positive": direct_mean_lower > 0.0, "adjusted_weighted_P_mean_lower_positive": weighted_mean_lower > 0.0, "importance_coverage_and_replay_pass": prerequisite_checks_passed, } return { **dict(solution), "action": action, "audit_status": "evaluated frozen reference basket", "audit_paths": int(split.audit.size), "audit_loss_count": int(np.count_nonzero(loss)), "audit_gain_count": int(np.count_nonzero(gain)), "direct_P_paths": direct_count, "direct_P_loss_count": direct_loss, "direct_P_gain_count": direct_gain, "adjusted_direct_P_loss_probability_upper": loss_upper, "adjusted_direct_P_gain_probability_lower": gain_lower, "direct_P_mean": direct_mean, "adjusted_direct_P_mean_lower": direct_mean_lower, "weighted_P_mean": weighted_mean, "adjusted_weighted_P_mean_lower": weighted_mean_lower, "regional_effective_sample_size": float(mass**2 / np.square(weights).sum()), "multiplicity": { "method": "Bonferroni familywise correction", "family_size": family_size, "adjusted_alpha": adjusted_alpha, }, "conditions": conditions, "certified": bool(all(conditions.values())), }
[docs] def convergence_report( small: Mapping[str, float], large: Mapping[str, float], ) -> dict[str, Any]: """Check the required importance and path-error convergence invariants.""" required = { "paths", "weight_mean", "weight_mean_standard_error", "effective_sample_size", "mean_standard_error", "conditional_radius", "conditional_effective_sample_size", } missing = required - small.keys() | required - large.keys() verify_inp(not missing, lambda: f"convergence inputs miss {sorted(missing)}") path_ratio = float(large["paths"]) / float(small["paths"]) expected_error_ratio = math.sqrt(path_ratio) checks = { "path_count_increased": path_ratio > 1.0, "weight_mean_consistent_with_one_small": abs(small["weight_mean"] - 1.0) <= 3.0 * small["weight_mean_standard_error"], "weight_mean_consistent_with_one_large": abs(large["weight_mean"] - 1.0) <= 3.0 * large["weight_mean_standard_error"], "effective_sample_size_increased": large["effective_sample_size"] > small["effective_sample_size"], "effective_sample_fraction_not_collapsed": ( large["effective_sample_size"] / large["paths"] >= 0.8 * small["effective_sample_size"] / small["paths"] ), "mean_standard_error_decreased": large["mean_standard_error"] < small["mean_standard_error"], "conditional_radius_shrank": large["conditional_radius"] < small["conditional_radius"], "conditional_effective_sample_size_increased": ( large["conditional_effective_sample_size"] > small["conditional_effective_sample_size"] ), } return { "checks": checks, "passed": bool(all(checks.values())), "path_count_ratio": path_ratio, "expected_standard_error_reduction": expected_error_ratio, "observed_mean_standard_error_reduction": ( small["mean_standard_error"] / large["mean_standard_error"] ), }
_FUNCTIONAL_GATE_CHECKS = ( "finite_arrays", "timing_identities", "float64_accounting_replay", "decoder_identity", "strike_and_sign_boundary_coverage", "importance_normalization_and_moment_recovery", "stratified_disjoint_split", "conditional_radius_and_ess", "extremes_replayed", "memory_within_limits", )
[docs] def functional_gate_report(checks: Mapping[str, bool | Mapping[str, Any]]) -> dict[str, Any]: """Evaluate the mandatory 100,000-to-one-million functional gate. A missing check fails closed. A detailed check mapping must contain a boolean ``passed`` field, allowing reports to retain the underlying measurements without weakening the gate. """ normalized: dict[str, dict[str, Any]] = {} for name in _FUNCTIONAL_GATE_CHECKS: value = checks.get(name, False) if isinstance(value, Mapping): detail = dict(value) passed = detail.get("passed") is True else: passed = value is True detail = {} normalized[name] = {"passed": passed, **detail} blockers = [name for name, value in normalized.items() if not value["passed"]] return { "passed": not blockers, "checks": normalized, "blockers": blockers, "action": ( "one-million stage authorized" if not blockers else "one-million stage blocked" ), }
[docs] def case_configuration(case: RequiredCase) -> dict[str, Any]: """Return a JSON-safe complete case configuration.""" return asdict(case)
__all__ = [ "DerivedCaseArrays", "GPU_ASSIGNMENT", "OptionCoverageAccumulator", "PathSplit", "REPORTED_COST_RATES", "REPORTED_PATH_COUNTS", "RequiredCase", "TimeSeparatedUnconditionalAccumulator", "case_configuration", "audit_constant_basket", "certify_unconditional_directions", "clopper_pearson_one_sided", "convergence_report", "derive_case_arrays", "functional_gate_report", "float64_replay_report", "propagated_basket_band", "positive_relative_weights", "required_cases", "solve_constant_basket", "stratified_path_split", "time_separated_unconditional_report", ]