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

"""Case C models and analytic gradients for conditional-arbitrage tracing.

Case C keeps the power-exponential utility parameter fixed at one and scales
the economic P&L by an externally supplied notional ``n``.  Long and short
notionals are separate nonnegative variables.  Optimization uses the true
utility gradient divided by expected marginal utility, which preserves every
stationary point while removing the common exponentially small scale.
"""

from __future__ import annotations

import math
from dataclasses import dataclass

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 torch import Tensor

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


[docs] @version("1.2") @dataclass(frozen=True, kw_only=True) class CaseCConfig: """Logical configuration of a deterministic/conditional Case C pair.""" label: str source_cache_uid: str state_features: int notionals: tuple[float, ...] deterministic_time: int = 0 conditional_time: int = 6 expiries: int = 7 instruments_per_expiry: int = 21 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", ) for name in ( "state_features", "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}" ), ) verify_inp( isinstance(self.deterministic_time, int) and isinstance(self.conditional_time, int) and 0 <= self.deterministic_time < self.conditional_time, "Case C trading-time indices must be ordered nonnegative integers", ) verify_inp( bool(self.notionals) and all(math.isfinite(value) and value > 0.0 for value in self.notionals) and all( left < right for left, right in zip(self.notionals, self.notionals[1:]) ), lambda: ( "notionals must be finite-positive and strictly increasing, " f"got {self.notionals!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 CaseCTrainConfig: """Operational settings for the notional continuation.""" batch_size: int = 4_096 valuation_batch_size: int = 16_384 epochs_per_notional: int = 20_000 minimum_epochs_per_notional: int = 2_000 value_update: int = 250 checkpoint_update: int = 2_000 convergence_points: int = 8 action_change_tolerance: float = 2.0e-5 lr: float = 3.0e-4 compile: bool = True seed: int = 182_071 def __post_init__(self) -> None: for name in ( "batch_size", "valuation_batch_size", "epochs_per_notional", "minimum_epochs_per_notional", "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_per_notional <= self.epochs_per_notional, "minimum epochs cannot exceed maximum epochs", ) for name in ("action_change_tolerance", "lr"): 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}" ), )
[docs] def projected_long_short(raw: Tensor) -> tuple[Tensor, Tensor, Tensor]: """Return nonnegative long/short actions with total gross norm at most one. The forward value is the radial projection of the positive part. At zero, a straight-through positive-part derivative keeps both long and short directions learnable. Outside the ball, the exact radial-projection derivative removes only the infeasible radial direction and preserves all tangential direction-changing gradients. No exterior penalty is used. """ verify_inp( raw.ndim >= 4 and raw.shape[-3] == 2, lambda: f"long/short raw action has invalid shape {raw.shape}", ) feasible_positive = torch.clamp_min(raw, 0.0) positive = raw + (feasible_positive - raw).detach() raw_gross = positive.sum(dim=(-3, -2, -1)) scale = torch.reciprocal(raw_gross.clamp_min(1.0)) action = positive * scale[..., None, None, None] gross = action.detach().sum(dim=(-3, -2, -1)) boundary = raw_gross >= 1.0 return action, gross, boundary
[docs] def simplex_long_short( logits: Tensor, *, expiries: int, instruments_per_expiry: int, ) -> tuple[Tensor, Tensor, Tensor]: """Map portfolio logits and one no-trade logit to the unit gross simplex. This is the mirror-descent geometry natural for separate nonnegative long and short notionals. The final coordinate is uninvested gross capacity, so an interior optimum is represented without clipping or a penalty. """ components = 2 * expiries * instruments_per_expiry verify_inp( logits.ndim >= 2 and logits.shape[-1] == components + 1, lambda: ( f"simplex logits must end in {components + 1}, got {logits.shape}" ), ) probability = torch.softmax(logits, dim=-1) flat_action = probability[..., :components] action = flat_action.reshape( *logits.shape[:-1], 2, expiries, instruments_per_expiry ) gross = flat_action.sum(dim=-1) boundary = probability[..., -1] <= 1.0e-6 return action, gross, boundary
[docs] def case_c_pnl(action: Tensor, returns: Tensor, costs: Tensor) -> Tensor: """Return per-unit net P&L for separate long and short notionals.""" expected = (*returns.shape[:-2], 2, *returns.shape[-2:]) assert action.shape == expected, f"expected action {expected}, got {action.shape}" assert returns.shape == costs.shape long = action[..., 0, :, :] short = action[..., 1, :, :] result = ( (long - short) * returns - (long + short) * costs ).sum(dim=(-1, -2)) if not torch.isfinite(result).all().item(): raise FloatingPointError("Case C P&L contains NaN or infinity") return result
[docs] def case_c_numerical_band( action: Tensor, returns: Tensor, costs: Tensor, instrument_band: Tensor, ) -> Tensor: """Propagate observation-specific float32 errors through one portfolio.""" assert returns.shape == costs.shape == instrument_band.shape expected = (*returns.shape[:-2], 2, *returns.shape[-2:]) assert action.shape == expected, f"expected action {expected}, got {action.shape}" gross = action[..., 0, :, :] + action[..., 1, :, :] accumulation = 32.0 * torch.finfo(torch.float32).eps * ( gross * (returns.abs() + costs) ).sum(dim=(-1, -2)) result = (gross * instrument_band).sum(dim=(-1, -2)) + accumulation if not torch.isfinite(result).all().item() or not torch.all(result >= 0.0).item(): raise FloatingPointError("Case C numerical band is not finite-nonnegative") return result
[docs] def powerexp_one(scaled_pnl: Tensor) -> tuple[Tensor, Tensor]: """Return fixed-lambda-one power-exp utility and marginal utility.""" positive = torch.clamp_min(scaled_pnl, 0.0) negative = torch.clamp_max(scaled_pnl, 0.0) utility = torch.where( scaled_pnl > 0.0, -torch.expm1(-positive), negative - 0.5 * negative.square(), ) marginal = torch.where( scaled_pnl > 0.0, torch.exp(-positive), 1.0 - negative, ) if not torch.isfinite(utility).all().item(): raise FloatingPointError("Case C utility contains NaN or infinity") # The exponential branch may legitimately underflow to exactly zero in # float32 at large notionals. Optimization does not use this raw value: # ``normalized_marginal_weights`` works directly in log space. if not torch.isfinite(marginal).all().item() or not torch.all(marginal >= 0.0).item(): raise FloatingPointError("Case C marginal utility is not finite-nonnegative") return utility, marginal
[docs] def normalized_marginal_weights( pnl: Tensor, path_weight: Tensor, *, notional: float | Tensor ) -> Tensor: """Return normalized physical marginal-utility weights in log space.""" assert pnl.ndim == 2 and path_weight.shape == pnl.shape[:1] if not isinstance(notional, Tensor): verify_inp( math.isfinite(notional) and notional > 0.0, lambda: f"invalid Case C notional {notional!r}", ) scale = torch.as_tensor(notional, dtype=pnl.dtype, device=pnl.device) scaled = scale * pnl # Clamp the inactive branch as well: ``torch.where`` evaluates both # branches, and log1p(-scaled) is otherwise invalid for positive scaled # P&L above one even though that value would not be selected. nonpositive_scaled = torch.clamp_max(scaled, 0.0) log_marginal = torch.where( scaled > 0.0, -scaled, torch.log1p(-nonpositive_scaled), ) log_density = torch.log(path_weight)[:, None] + log_marginal result = torch.softmax(log_density, dim=0) if not torch.isfinite(result).all().item(): raise FloatingPointError("Case C normalized marginal weights are non-finite") return result
[docs] def case_c_objective_and_surrogate( pnl: Tensor, path_weight: Tensor, *, notional: float | Tensor ) -> tuple[Tensor, Tensor, Tensor]: """Return economic utility and its normalized analytic-gradient surrogate. The surrogate has no economic interpretation as a level. Its derivative is exactly the true power-exp derivative divided by expected marginal utility, with the irrelevant positive notional factor omitted. """ scale = torch.as_tensor(notional, dtype=pnl.dtype, device=pnl.device) utility, _ = powerexp_one(scale * pnl) normalized_weight = path_weight / path_weight.sum() objective = (normalized_weight[:, None] * utility).sum(dim=0) marginal_weight = normalized_marginal_weights( pnl, path_weight, notional=scale ) surrogate = (marginal_weight.detach() * pnl).sum(dim=0) return objective, surrogate, marginal_weight
[docs] @version("1.0") class CaseCAction(BaseModel): """A deterministic ``t0`` action and a conditional ``t6`` action network.""" def __init__( self, env: BaseEnvironment, *, config: CaseCConfig, state_mean: Tensor, state_whitener: Tensor, ) -> None: super().__init__(env) verify_inp( state_mean.shape == (config.state_features,), lambda: f"invalid state mean shape {state_mean.shape}", ) verify_inp( state_whitener.shape == (config.state_features, config.state_features), lambda: f"invalid state whitener shape {state_whitener.shape}", ) self.config = config components = 2 * config.expiries * config.instruments_per_expiry output = components + 1 self.deterministic_logits = torch.nn.Parameter( torch.zeros( output, dtype=env.fdtype, device=env.device, ) ) self.conditional = FeedForward( env, num_input=config.state_features, num_output=output, config=config.network_config, ) self.register_buffer("state_mean", state_mean.detach().clone()) self.register_buffer("state_whitener", state_whitener.detach().clone()) self.initialize_output_layer()
[docs] @torch.no_grad() def initialize_output_layer(self) -> None: """Start at half gross with uniform long/short direction weights.""" output_layer = self.conditional.In[-1] if self.conditional.In else self.conditional.I0 output_layer.weight.zero_() if output_layer.bias is not None: output_layer.bias.zero_() output_layer.bias[-1] = math.log(output_layer.bias.numel() - 1) self.deterministic_logits.zero_() self.deterministic_logits[-1] = math.log( self.deterministic_logits.numel() - 1 )
[docs] def raw_action(self, conditional_state: Tensor) -> Tensor: """Return raw long/short variables for deterministic and conditional times.""" assert conditional_state.ndim == 2 assert conditional_state.shape[1] == self.config.state_features paths = conditional_state.shape[0] factor = (conditional_state - self.state_mean[None]) @ self.state_whitener conditional = self.conditional(factor) deterministic = self.deterministic_logits[None].expand(paths, -1) result = torch.stack((deterministic, conditional), dim=1) self.verify(lambda: torch.isfinite(factor), "Case C state factor is non-finite") self.verify(lambda: torch.isfinite(result), "Case C raw action is non-finite") return result
[docs] def forward(self, conditional_state: Tensor) -> tuple[Tensor, Tensor, Tensor, Tensor]: """Return feasible action, gross norm, boundary flag, and raw action.""" raw = self.raw_action(conditional_state) action, gross, boundary = simplex_long_short( raw, expiries=self.config.expiries, instruments_per_expiry=self.config.instruments_per_expiry, ) self.verify(lambda: torch.isfinite(action), "Case C action is non-finite") return action, gross, boundary, raw
[docs] @torch.no_grad() def project_parameters_(self) -> None: """Apply any direct parameter constraints after an optimizer step."""
# The feed-forward action is constrained by its forward map. Kernel # actions override this hook because their portfolio templates are # optimized directly in feasible coordinates. __all__ = [ "CaseCAction", "CaseCConfig", "CaseCTrainConfig", "case_c_numerical_band", "case_c_objective_and_surrogate", "case_c_pnl", "normalized_marginal_weights", "powerexp_one", "projected_long_short", "simplex_long_short", ]