"""Fixed-radius continuation models for conditional-arbitrage searches.
For every trading time, one network jointly trades all matched expiries and
instruments. Its unconstrained output ``v_t(x_t)`` is projected radially onto
an L1 ball of radius ``n``. The utility sees only the feasible action, while
an exterior quadratic penalty supplies a radial recovery gradient whenever
the unconstrained output leaves the ball.
"""
from __future__ import annotations
import math
from dataclasses import dataclass
from typing import Literal
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
from .arb_tracing import tracing_utility_objective
NormContinuationUtility = Literal["powerexp", "entropy"]
[docs]
@version("1.0")
@dataclass(frozen=True, kw_only=True)
class NormContinuationConfig:
"""Logical geometry and objective of one radius-continuation search."""
label: str
source_cache_uid: str
state_features: int
risk_aversion: float
utility: NormContinuationUtility
radii: tuple[float, ...]
exterior_penalty: float
trading_times: int = 10
expiries: int = 7
instruments_per_expiry: int = 21
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}"
),
)
verify_inp(
bool(self.radii)
and all(math.isfinite(radius) and radius > 0.0 for radius in self.radii)
and all(left < right for left, right in zip(self.radii, self.radii[1:])),
lambda: f"radii must be finite-positive and strictly increasing: {self.radii!r}",
)
for name in ("risk_aversion", "exterior_penalty", "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}"
),
)
@property
def filename(self) -> str:
return named_unique_filename48_8(self.label, self)
[docs]
@version("1.0")
@dataclass(frozen=True, kw_only=True)
class NormContinuationTrainConfig:
"""Operational settings shared by all continuation radii."""
batch_size: int = 4_096
valuation_batch_size: int = 16_384
epochs_per_radius: int = 10_000
minimum_epochs_per_radius: int = 1_500
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 = 10
convergence_relative_tolerance: float = 1.0e-4
seed: int = 94_103
def __post_init__(self) -> None:
for name in (
"batch_size",
"valuation_batch_size",
"epochs_per_radius",
"minimum_epochs_per_radius",
"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_radius <= self.epochs_per_radius,
"minimum epochs per radius cannot exceed the maximum",
)
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}",
)
def _radius_tensor(reference: Tensor, radius: float | Tensor) -> Tensor:
"""Return a scalar radius on ``reference``'s device without graph guards."""
if not isinstance(radius, Tensor):
verify_inp(
math.isfinite(radius) and radius > 0.0,
lambda: f"radius must be finite-positive, got {radius!r}",
)
result = torch.as_tensor(radius, dtype=reference.dtype, device=reference.device)
verify_inp(result.ndim == 0, lambda: f"radius must be scalar, got {result.shape}")
return result
[docs]
def radial_l1_clip(
raw: Tensor, radius: float | Tensor
) -> tuple[Tensor, Tensor, Tensor]:
"""Project each path/time action radially onto its L1 ball.
The final two axes are the expiry and within-expiry instrument axes. The
returned Boolean tensor identifies outputs in the exterior region where
the radial utility derivative is zero but tangential derivatives remain.
"""
verify_inp(raw.ndim >= 3, lambda: f"raw action has invalid shape {raw.shape}")
radius_tensor = _radius_tensor(raw, radius)
raw_l1 = raw.abs().sum(dim=(-1, -2))
scale = radius_tensor / raw_l1.clamp_min(radius_tensor)
action = raw * scale[..., None, None]
clipped = raw_l1 > radius_tensor
return action, raw_l1, clipped
[docs]
def exterior_l1_penalty(raw_l1: Tensor, radius: float | Tensor) -> Tensor:
r"""Return :math:`E[(\|v_t\|_1-n)_+^2]` separately by trading time."""
verify_inp(raw_l1.ndim == 2, lambda: f"raw L1 norm has invalid shape {raw_l1.shape}")
radius_tensor = _radius_tensor(raw_l1, radius)
result = torch.relu(raw_l1 - radius_tensor).square().mean(dim=0)
if not torch.isfinite(result).all().item():
raise FloatingPointError("exterior L1 penalty produced NaN or infinity")
return result
[docs]
def clipped_radius_pnl_derivative(
pnl: Tensor, clipped: Tensor, radius: float | Tensor
) -> Tensor:
"""Differentiate feasible P&L with respect to a frozen L1 radius.
Transaction costs are homogeneous in the action. Thus a clipped action
and its P&L scale linearly with the radius, while an interior action is
locally independent of the radius.
"""
verify_inp(
pnl.shape == clipped.shape,
lambda: f"P&L/clipping shapes differ: {pnl.shape}/{clipped.shape}",
)
radius_tensor = _radius_tensor(pnl, radius)
result = torch.where(clipped, pnl / radius_tensor, torch.zeros_like(pnl))
if not torch.isfinite(result).all().item():
raise FloatingPointError("radius P&L derivative produced NaN or infinity")
return result
[docs]
@version("1.0")
class NormContinuationAction(BaseModel):
"""Independent per-time action networks in physical orthogonal factors."""
def __init__(
self,
env: BaseEnvironment,
*,
config: NormContinuationConfig,
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 from no trade while retaining 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 raw_action(self, state: Tensor) -> Tensor:
"""Return the unconstrained action in whitened state coordinates."""
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,
)
self.verify(lambda: torch.isfinite(factor), "orthogonal state factor is non-finite")
self.verify(lambda: torch.isfinite(raw), "raw continuation action is non-finite")
return raw
[docs]
def forward(
self, state: Tensor, radius: float | Tensor
) -> tuple[Tensor, Tensor, Tensor]:
"""Return the feasible action, raw L1 norm, and clipping indicator."""
action, raw_l1, clipped = radial_l1_clip(self.raw_action(state), radius)
self.verify(lambda: torch.isfinite(action), "projected continuation action is non-finite")
self.verify(lambda: torch.isfinite(raw_l1), "raw continuation norm is non-finite")
return action, raw_l1, clipped
[docs]
def continuation_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("continuation P&L contains NaN or infinity")
return pnl
[docs]
def continuation_loss(
model: NormContinuationAction,
state: Tensor,
returns: Tensor,
costs: Tensor,
path_weight: Tensor,
*,
radius: float | Tensor,
) -> tuple[Tensor, dict[str, Tensor]]:
"""Return the penalized loss and its unpenalized components by time."""
action, raw_l1, clipped = model(state, radius)
pnl = continuation_pnl(action, returns, costs)
objective = tracing_utility_objective(
pnl,
path_weight,
utility=model.config.utility,
risk_aversion=model.config.risk_aversion,
)
penalty = exterior_l1_penalty(raw_l1, radius)
loss = (-objective + model.config.exterior_penalty * penalty).mean()
if not torch.isfinite(loss).item():
raise FloatingPointError("norm-continuation objective became NaN or infinity")
return loss, {
"objective": objective,
"penalty": penalty,
"action_l1_mean": action.abs().sum(dim=(-1, -2)).mean(dim=0),
"action_l1_maximum": action.abs().sum(dim=(-1, -2)).amax(dim=0),
"raw_l1_mean": raw_l1.mean(dim=0),
"raw_l1_maximum": raw_l1.amax(dim=0),
"clipped_fraction": clipped.to(dtype=state.dtype).mean(dim=0),
}
__all__ = [
"NormContinuationAction",
"NormContinuationConfig",
"NormContinuationTrainConfig",
"NormContinuationUtility",
"clipped_radius_pnl_derivative",
"continuation_loss",
"continuation_pnl",
"exterior_l1_penalty",
"radial_l1_clip",
]