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

"""Orthogonal-state direction and notional tracing for conditional arbitrage.

Arb tracing separates the conditional portfolio into a bounded direction
function and an external scalar notional.  A direction is learned at a
moderate probe notional, after which its notional is traced explicitly.  A
finite utility optimum identifies a risky trade; a direction whose notional
can keep increasing is passed to the empirical no-loss audit.
"""

from __future__ import annotations

import math
from dataclasses import dataclass
from typing import Literal

import numpy as np
import torch
from cdxcore.err import verify_inp
from cdxcore.uniquehash import named_unique_filename48_8
from cdxcore.util import is_filename
from cdxcore.version import version
from scipy.special import logsumexp
from torch import Tensor

from quantdata.torch import BaseEnvironment, BaseModel
from quantdata.torch.ffw import FeedForward, FeedForwardConfig

from .required_runs import clopper_pearson_one_sided

ArbTracingUtility = Literal["powerexp", "entropy"]


[docs] @version("1.0") @dataclass(frozen=True, kw_only=True) class ArbTracingConfig: """Logical geometry and objective of one arb-tracing direction.""" label: str source_cache_uid: str state_features: int risk_aversion: float utility: ArbTracingUtility trading_times: int = 10 expiries: int = 7 instruments_per_expiry: int = 21 probe_notional: float = 2.0 raw_norm_penalty: float = 1.0e-5 raw_norm_soft_limit: float = 8.0 covariance_relative_floor: float = 1.0e-10 group: str = "" user_version: str = "0.1" network_config: FeedForwardConfig = FeedForwardConfig( num_depth=2, num_width=96, activation="SiLU", use_bias=True, ) def __post_init__(self) -> None: verify_inp( isinstance(self.label, str) and is_filename(self.label), lambda: f"'label' must be a filename, got {self.label!r}", ) verify_inp( isinstance(self.group, str) and not self.group.startswith("/"), lambda: f"'group' must be relative, got {self.group!r}", ) verify_inp( isinstance(self.source_cache_uid, str) and bool(self.source_cache_uid), "'source_cache_uid' must be a non-empty string", ) verify_inp( self.utility in {"powerexp", "entropy"}, lambda: f"unknown utility {self.utility!r}", ) for name in ( "state_features", "trading_times", "expiries", "instruments_per_expiry", ): 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}" ), ) for name in ( "risk_aversion", "probe_notional", "raw_norm_soft_limit", "covariance_relative_floor", ): value = getattr(self, name) verify_inp( math.isfinite(value) and value > 0.0, lambda name=name, value=value: ( f"'{name}' must be finite-positive, got {value!r}" ), ) verify_inp( math.isfinite(self.raw_norm_penalty) and self.raw_norm_penalty >= 0.0, lambda: f"invalid raw-norm penalty {self.raw_norm_penalty!r}", ) @property def filename(self) -> str: return named_unique_filename48_8(self.label, self)
[docs] @version("1.0") @dataclass(frozen=True, kw_only=True) class ArbTracingTrainConfig: """Operational settings which permit checkpoint warm starts.""" batch_size: int = 4_096 valuation_batch_size: int = 16_384 epochs: int = 20_000 minimum_epochs: int = 4_000 value_update: int = 250 checkpoint_update: int = 2_000 lr: float = 3.0e-4 weight_decay: float = 0.0 compile: bool = True convergence_points: int = 12 convergence_relative_tolerance: float = 1.0e-4 seed: int = 91_301 def __post_init__(self) -> None: for name in ( "batch_size", "valuation_batch_size", "epochs", "minimum_epochs", "value_update", "checkpoint_update", "convergence_points", ): 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.minimum_epochs <= self.epochs, "minimum epochs cannot exceed maximum epochs", ) for name in ("lr", "convergence_relative_tolerance"): value = getattr(self, name) verify_inp( math.isfinite(value) and value > 0.0, lambda name=name, value=value: ( f"'{name}' must be finite-positive, got {value!r}" ), ) verify_inp( math.isfinite(self.weight_decay) and self.weight_decay >= 0.0, lambda: f"invalid weight decay {self.weight_decay!r}", )
[docs] def fit_physical_state_whitener( state: Tensor, path_weight: Tensor, indices: Tensor, *, relative_eigenvalue_floor: float = 1.0e-10, ) -> tuple[Tensor, Tensor, dict[str, object]]: """Fit a time-specific physical-measure orthogonal state basis. The cached market is sampled under an importance proposal. Consequently the physical state covariance is estimated with ``p/q`` weights, using training paths only. A caller may replace these tensors with analytic Gaussian moments when they are persisted with a future universe cache. """ verify_inp(state.ndim == 3, lambda: f"state must have shape (S,T,F), got {state.shape}") verify_inp( path_weight.shape == (state.shape[0],), lambda: f"path weights have invalid shape {path_weight.shape}", ) verify_inp( indices.ndim == 1 and indices.numel() >= 2, lambda: f"whitening indices have invalid shape {indices.shape}", ) verify_inp( math.isfinite(relative_eigenvalue_floor) and relative_eigenvalue_floor > 0.0, lambda: f"invalid eigenvalue floor {relative_eigenvalue_floor!r}", ) sample = state[indices].double() weight = path_weight[indices].double() if not torch.isfinite(sample).all().item(): raise FloatingPointError("state whitening sample contains NaN or infinity") if not torch.isfinite(weight).all().item() or not torch.all(weight > 0.0).item(): raise FloatingPointError("state whitening weights are not finite-positive") normalized_weight = weight / weight.sum() mean = torch.einsum("s,stf->tf", normalized_weight, sample) centered = sample - mean[None, :, :] covariance = torch.einsum( "s,stf,stg->tfg", normalized_weight, centered, centered ) covariance = 0.5 * (covariance + covariance.transpose(-1, -2)) eigenvalue, eigenvector = torch.linalg.eigh(covariance) maximum = eigenvalue[:, -1].clamp_min(torch.finfo(eigenvalue.dtype).tiny) floor = relative_eigenvalue_floor * maximum clipped = torch.maximum(eigenvalue, floor[:, None]) # Rows are observations. Multiplying by Q Lambda^{-1/2} produces factors. whitener = eigenvector * torch.rsqrt(clipped)[:, None, :] factor = torch.einsum("stf,tfg->stg", centered, whitener) factor_mean = torch.einsum("s,stf->tf", normalized_weight, factor) factor_centered = factor - factor_mean[None, :, :] factor_covariance = torch.einsum( "s,stf,stg->tfg", normalized_weight, factor_centered, factor_centered ) identity = torch.eye( state.shape[-1], dtype=factor_covariance.dtype, device=state.device ) residual = factor_covariance - identity[None, :, :] diagnostics: dict[str, object] = { "definition": ( "xi_t=(x_t-m_t) Q_t Lambda_t^{-1/2}; m_t and covariance are " "estimated on training paths with physical p/q weights" ), "relative_eigenvalue_floor": relative_eigenvalue_floor, "training_path_count": int(indices.numel()), "training_weight_effective_sample_size": float( weight.sum().square().div(weight.square().sum()).cpu() ), "minimum_covariance_eigenvalue_by_time": eigenvalue[:, 0].cpu().tolist(), "maximum_covariance_eigenvalue_by_time": eigenvalue[:, -1].cpu().tolist(), "clipped_eigenvalue_count_by_time": (eigenvalue < floor[:, None]) .sum(dim=1) .cpu() .tolist(), "maximum_absolute_weighted_factor_mean": float(factor_mean.abs().max().cpu()), "maximum_absolute_weighted_factor_covariance_error": float( residual.abs().max().cpu() ), } result_mean = mean.to(dtype=state.dtype) result_whitener = whitener.to(dtype=state.dtype) if not torch.isfinite(result_mean).all().item() or not torch.isfinite( result_whitener ).all().item(): raise FloatingPointError("state whitener contains NaN or infinity") return result_mean, result_whitener, diagnostics
[docs] @version("1.0") class OrthogonalArbDirection(BaseModel): """Independent per-time direction networks in whitened state coordinates.""" def __init__( self, env: BaseEnvironment, *, config: ArbTracingConfig, state_mean: Tensor, state_whitener: Tensor, ) -> None: super().__init__(env) expected_mean = (config.trading_times, config.state_features) expected_whitener = ( config.trading_times, config.state_features, config.state_features, ) verify_inp( state_mean.shape == expected_mean, lambda: f"state mean must have shape {expected_mean}, got {state_mean.shape}", ) verify_inp( state_whitener.shape == expected_whitener, lambda: ( f"state whitener must have shape {expected_whitener}, " f"got {state_whitener.shape}" ), ) for name, value in (("state mean", state_mean), ("state whitener", state_whitener)): if not torch.isfinite(value).all().item(): raise ValueError(f"{name} contains NaN or infinity") self.config = config instruments = config.expiries * config.instruments_per_expiry self.networks = torch.nn.ModuleList( FeedForward( env, num_input=config.state_features, num_output=instruments, config=config.network_config, ) for _ in range(config.trading_times) ) self.register_buffer("state_mean", state_mean.detach().clone()) self.register_buffer("state_whitener", state_whitener.detach().clone()) self.zero_output_layers()
[docs] @torch.no_grad() def zero_output_layers(self) -> None: """Start at no trade while preserving the local output derivative.""" for network in self.networks: output_layer = network.In[-1] if network.In else network.I0 output_layer.weight.zero_() if output_layer.bias is not None: output_layer.bias.zero_()
[docs] def forward(self, state: Tensor) -> tuple[Tensor, Tensor]: expected = ( state.ndim == 3 and state.shape[1] == self.config.trading_times and state.shape[2] == self.config.state_features ) assert expected, ( "state must have shape (S,trading_times,state_features), found " f"{tuple(state.shape)}" ) centered = state - self.state_mean[None, :, :] factor = torch.einsum("btf,tfg->btg", centered, self.state_whitener) raw = torch.stack( [network(factor[:, time]) for time, network in enumerate(self.networks)], dim=1, ).reshape( state.shape[0], self.config.trading_times, self.config.expiries, self.config.instruments_per_expiry, ) raw_l1 = raw.abs().sum(dim=(-1, -2)) # The map has no exterior flat region. Scale is deliberately excluded # from the network and is searched as a separate scalar per time. direction = raw / (1.0 + raw_l1[..., None, None]) self.verify(lambda: torch.isfinite(factor), "orthogonal state factor is non-finite") self.verify(lambda: torch.isfinite(raw), "raw arb direction is non-finite") self.verify(lambda: torch.isfinite(direction), "arb direction is non-finite") return direction, raw_l1
[docs] def tracing_pnl(action: Tensor, returns: Tensor, costs: Tensor) -> Tensor: """Return exact net P&L for each path and trading time.""" assert action.shape == returns.shape == costs.shape pnl = (action * returns - action.abs() * costs).sum(dim=(-1, -2)) if not torch.isfinite(pnl).all().item(): raise FloatingPointError("arb-tracing P&L contains NaN or infinity") return pnl
[docs] def tracing_pnl_right_derivative( base_action: Tensor, direction: Tensor, notional: float, returns: Tensor, costs: Tensor, ) -> Tensor: """Return the right derivative of exact net P&L along one direction.""" assert base_action.shape == direction.shape == returns.shape == costs.shape verify_inp( math.isfinite(notional) and notional >= 0.0, lambda: f"invalid tracing notional {notional!r}", ) action = base_action + notional * direction zero = action == 0.0 cost_derivative = torch.where( zero, direction.abs(), torch.sign(action) * direction, ) result = (direction * returns - cost_derivative * costs).sum(dim=(-1, -2)) if not torch.isfinite(result).all().item(): raise FloatingPointError("arb-tracing P&L derivative contains NaN or infinity") return result
[docs] def tracing_numerical_band( action: Tensor, returns: Tensor, costs: Tensor, instrument_band: Tensor, *, roundoff_multiplier: float = 32.0, ) -> Tensor: """Propagate instrument arithmetic bands through a traced portfolio.""" assert action.shape == returns.shape == costs.shape == instrument_band.shape absolute_action = action.abs() eps32 = torch.finfo(torch.float32).eps result = (absolute_action * instrument_band).sum(dim=(-1, -2)) + ( roundoff_multiplier * eps32 * (absolute_action * (returns.abs() + costs)).sum(dim=(-1, -2)) ) if not torch.isfinite(result).all().item(): raise FloatingPointError("arb-tracing numerical band contains NaN or infinity") return result
[docs] def tracing_utility_objective( pnl: Tensor, path_weight: Tensor, *, utility: ArbTracingUtility, risk_aversion: float, ) -> Tensor: """Return the physical utility objective separately by trading time.""" assert pnl.ndim == 2 and path_weight.shape == pnl.shape[:1] verify_inp(utility in {"powerexp", "entropy"}, lambda: f"unknown utility {utility}") verify_inp( math.isfinite(risk_aversion) and risk_aversion > 0.0, lambda: f"invalid risk aversion {risk_aversion!r}", ) if not torch.isfinite(pnl).all().item(): raise FloatingPointError("utility P&L contains NaN or infinity") if not torch.isfinite(path_weight).all().item() or not torch.all(path_weight > 0.0).item(): raise FloatingPointError("utility weights are not finite-positive") if utility == "entropy": log_weight = torch.log(path_weight) log_normalizer = torch.logsumexp(log_weight, dim=0) log_moment = torch.logsumexp( log_weight[:, None] - risk_aversion * pnl, dim=0 ) - log_normalizer value = -log_moment / risk_aversion else: positive = torch.clamp_min(pnl, 0.0) negative = torch.clamp_max(pnl, 0.0) value_by_path = torch.where( pnl > 0.0, -torch.expm1(-risk_aversion * positive) / risk_aversion, negative - 0.5 * risk_aversion * negative.square(), ) value = (path_weight[:, None] * value_by_path).sum(dim=0) / path_weight.sum() if not torch.isfinite(value).all().item(): raise FloatingPointError(f"{utility} tracing objective contains NaN or infinity") return value
[docs] def tracing_raw_norm_penalty( raw_l1: Tensor, *, soft_limit: float, ) -> Tensor: """Keep the direction map away from its asymptotically flat radial tail.""" verify_inp(soft_limit > 0.0 and math.isfinite(soft_limit), "invalid soft limit") return torch.relu(raw_l1 - soft_limit).square().mean(dim=0)
[docs] def weighted_quantile(values: np.ndarray, weights: np.ndarray, probability: float) -> float: """Return a linearly interpolated quantile of a finite weighted sample.""" values = np.asarray(values, dtype=np.float64) weights = np.asarray(weights, dtype=np.float64) verify_inp( values.ndim == weights.ndim == 1 and values.shape == weights.shape, "weighted quantile inputs must be equal-length vectors", ) verify_inp(0.0 <= probability <= 1.0, lambda: f"invalid probability {probability}") if not np.all(np.isfinite(values)) or not np.all(np.isfinite(weights)): raise FloatingPointError("weighted quantile input contains NaN or infinity") verify_inp(np.all(weights >= 0.0) and np.any(weights > 0.0), "invalid weights") order = np.argsort(values, kind="stable") sorted_value = values[order] sorted_weight = weights[order] midpoint = np.cumsum(sorted_weight) - 0.5 * sorted_weight midpoint /= sorted_weight.sum() return float(np.interp(probability, midpoint, sorted_value))
def _weighted_mean_error(values: np.ndarray, normalized_weight: np.ndarray) -> tuple[float, float]: mean = float(np.dot(normalized_weight, values)) error = float( np.sqrt(np.sum(np.square(normalized_weight * (values - mean)))) ) return mean, error
[docs] def traced_scale_statistics( pnl: np.ndarray, band: np.ndarray, slope: np.ndarray, path_weight: np.ndarray, component: np.ndarray, *, utility: ArbTracingUtility, risk_aversion: float, loss_probability_epsilon: float, confidence_z: float = 3.0, loss_mc_multiplier: float = 1.0, ) -> list[dict[str, float | int | bool]]: """Measure utility, marginal scale value, losses, and finite-risk quality.""" pnl = np.asarray(pnl, dtype=np.float64) band = np.asarray(band, dtype=np.float64) slope = np.asarray(slope, dtype=np.float64) path_weight = np.asarray(path_weight, dtype=np.float64) component = np.asarray(component) verify_inp( pnl.shape == band.shape == slope.shape and pnl.ndim == 2, "scale-statistic arrays must share shape (paths,trading_times)", ) verify_inp( path_weight.shape == component.shape == pnl.shape[:1], "weight/component vectors have invalid shape", ) verify_inp( utility in {"powerexp", "entropy"}, lambda: f"unknown utility {utility!r}" ) verify_inp( math.isfinite(loss_probability_epsilon) and loss_probability_epsilon >= 0.0, lambda: f"invalid loss probability epsilon {loss_probability_epsilon!r}", ) verify_inp( math.isfinite(loss_mc_multiplier) and loss_mc_multiplier > 0.0, lambda: f"invalid loss MC multiplier {loss_mc_multiplier!r}", ) if not all(np.all(np.isfinite(value)) for value in (pnl, band, slope, path_weight)): raise FloatingPointError("scale statistic input contains NaN or infinity") verify_inp(np.all(path_weight > 0.0), "path weights must be positive") normalized_weight = path_weight / path_weight.sum() direct = component == 0 reports: list[dict[str, float | int | bool]] = [] for time in range(pnl.shape[1]): value = pnl[:, time] tolerance = band[:, time] derivative_path = slope[:, time] loss = value < -tolerance gain = value > tolerance probability, probability_error = _weighted_mean_error( loss.astype(np.float64), normalized_weight ) gain_probability, gain_probability_error = _weighted_mean_error( gain.astype(np.float64), normalized_weight ) mean, mean_error = _weighted_mean_error(value, normalized_weight) if utility == "entropy": log_weight = np.log(normalized_weight) log_tilt = log_weight - risk_aversion * value log_tilt -= logsumexp(log_tilt) tilted_weight = np.exp(log_tilt) objective = -( logsumexp(log_weight - risk_aversion * value) - logsumexp(log_weight) ) / risk_aversion marginal_normalizer = math.exp( min(700.0, logsumexp(log_weight - risk_aversion * value)) ) else: positive = np.maximum(value, 0.0) negative = np.minimum(value, 0.0) utility_value = np.where( value > 0.0, -np.expm1(-risk_aversion * positive) / risk_aversion, negative - 0.5 * risk_aversion * np.square(negative), ) marginal = np.where( value > 0.0, np.exp(-risk_aversion * positive), 1.0 - risk_aversion * negative, ) objective = float(np.dot(normalized_weight, utility_value)) marginal_weight = normalized_weight * marginal marginal_normalizer = float(marginal_weight.sum()) tilted_weight = marginal_weight / marginal_normalizer normalized_derivative, normalized_derivative_error = _weighted_mean_error( derivative_path, tilted_weight ) raw_derivative = marginal_normalizer * normalized_derivative objective_derivative = ( normalized_derivative if utility == "entropy" else raw_derivative ) direct_loss_count = int(np.sum(loss & direct)) direct_paths = int(np.sum(direct)) _, direct_loss_upper = ( clopper_pearson_one_sided(direct_loss_count, direct_paths) if direct_paths else (0.0, 1.0) ) direct_loss_probability = ( direct_loss_count / direct_paths if direct_paths else math.nan ) direct_loss_error = ( math.sqrt( direct_loss_probability * (1.0 - direct_loss_probability) / direct_paths ) if direct_paths else math.nan ) weighted_near_nonnegative = bool( probability <= loss_mc_multiplier * probability_error + loss_probability_epsilon ) direct_near_nonnegative = bool( direct_paths > 0 and direct_loss_probability <= loss_mc_multiplier * direct_loss_error + loss_probability_epsilon ) reports.append( { "trading_time_index": time, "objective": float(objective), "P_mean_pnl": mean, "P_mean_pnl_standard_error": mean_error, "P_mean_pnl_lower_confidence": mean - confidence_z * mean_error, "P_loss_probability": probability, "P_loss_probability_standard_error": probability_error, "P_gain_probability": gain_probability, "P_gain_probability_standard_error": gain_probability_error, "P_pnl_01_quantile": weighted_quantile(value, path_weight, 0.01), "P_pnl_05_quantile": weighted_quantile(value, path_weight, 0.05), "P_pnl_median": weighted_quantile(value, path_weight, 0.50), "proposal_minimum_pnl_minus_negative_band": float( np.min(value + tolerance) ), "direct_P_paths": direct_paths, "direct_P_loss_count": direct_loss_count, "direct_P_gain_count": int(np.sum(gain & direct)), "direct_P_loss_probability": direct_loss_probability, "direct_P_loss_probability_standard_error": direct_loss_error, "direct_P_loss_probability_upper_95": direct_loss_upper, "normalized_marginal_derivative": normalized_derivative, "normalized_marginal_derivative_standard_error": ( normalized_derivative_error ), "raw_marginal_derivative": raw_derivative, "objective_derivative": objective_derivative, "marginal_density_effective_sample_size": float( 1.0 / np.square(tilted_weight).sum() ), "maximum_marginal_density_weight_share": float( np.max(tilted_weight) ), "weighted_near_nonnegative": weighted_near_nonnegative, "direct_P_near_nonnegative": direct_near_nonnegative, "near_nonnegative_within_mc_noise": bool( weighted_near_nonnegative and direct_near_nonnegative ), "statistically_positive_mean": bool( mean - confidence_z * mean_error > 0.0 ), } ) return reports
__all__ = [ "ArbTracingConfig", "ArbTracingTrainConfig", "ArbTracingUtility", "OrthogonalArbDirection", "fit_physical_state_whitener", "traced_scale_statistics", "tracing_numerical_band", "tracing_pnl", "tracing_pnl_right_derivative", "tracing_raw_norm_penalty", "tracing_utility_objective", "weighted_quantile", ]