"""Compare learned state partitions with independent feed-forward directions."""
from __future__ import annotations
import argparse
import gc
import heapq
import json
import math
import os
import time
from dataclasses import asdict
from pathlib import Path
from typing import Any
import numpy as np
import torch
from cdxcore.err import verify_inp
from filelock import FileLock
from scipy.special import logsumexp
from torch import Tensor
from quantdata.torch import BaseEnvironment
from .arb_tracing import fit_physical_state_whitener, weighted_quantile
from .case_c_partition import (
GatedParallelFeedForwardDirections,
LearnedPartitionDirections,
ParallelDirectionConfig,
ParallelFeedForwardDirections,
ParallelKernelDirections,
)
from .expiry_arbitrage import payoff_cone_values
from .required_runs import RequiredCase, stratified_path_split
from .run_case_c import _fit_kernel_basis
from .run_expiry_arbitrage_experiments import (
_DEFAULT_CACHE_ROOT,
DeviceExpiryCase,
_load_case,
_to_device,
)
_DEFAULT_OUTPUT_ROOT = Path(
"quantdata/dysanos/grid/gendysanos/reports/parallel-direction-comparison"
)
_DEFAULT_CHECKPOINT_ROOT = Path(
"/media/storage/tmp/quantdata/dysanos/parallel-direction-comparison/checkpoints"
)
DirectionModel = (
ParallelFeedForwardDirections
| GatedParallelFeedForwardDirections
| ParallelKernelDirections
| LearnedPartitionDirections
)
def _atomic_json(path: Path, value: dict[str, Any]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
try:
temporary.write_text(
json.dumps(value, indent=2, allow_nan=False), encoding="utf-8"
)
os.replace(temporary, path)
finally:
temporary.unlink(missing_ok=True)
def _atomic_torch_save(path: Path, value: dict[str, Any]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
try:
torch.save(value, temporary)
os.replace(temporary, path)
finally:
temporary.unlink(missing_ok=True)
@torch.no_grad()
def _initialize_gated_direction_from_report(
model: GatedParallelFeedForwardDirections,
report: dict[str, Any],
) -> dict[str, Any]:
"""Copy a trained feed-forward direction while retaining fresh gate rows."""
source_config = report.get("model_config", {})
verify_inp(
source_config.get("architecture") == "feedforward",
"gated initialization requires a feed-forward source report",
)
verify_inp(
len(source_config.get("notionals", ())) == len(model.config.notionals),
"source and target must contain the same number of independent heads",
)
checkpoint_path = Path(report["checkpoint"])
saved = torch.load(checkpoint_path, map_location=model.device, weights_only=False)
source = saved["model"]
target = model.state_dict()
copied: list[str] = []
for name, destination in target.items():
if name not in source:
continue
value = source[name].to(dtype=destination.dtype, device=destination.device)
if value.shape == destination.shape:
destination.copy_(value)
copied.append(name)
model.load_state_dict(target)
verify_inp(
any(name.startswith("conditional.") for name in copied),
"source did not contain compatible direction outputs",
)
verify_inp(
all(torch.isfinite(value).all().item() for value in model.state_dict().values()),
"gated direction initialization produced non-finite parameters",
)
return {
"source_report": report.get("report_path"),
"source_checkpoint": str(checkpoint_path),
"source_checkpoint_step": int(saved.get("step", -1)),
"copied_parameter_tensors": copied,
"separate_gate_parameter_tensors_retained": [
name for name in target if name.startswith("gate.")
],
"gate_initialization_retained": "sigmoid(-3)",
}
def _select_times_and_fold(
data: DeviceExpiryCase,
*,
deterministic_time: int,
conditional_time: int,
fold: int,
seed: int,
) -> tuple[DeviceExpiryCase, dict[str, Any]]:
"""Select t0/t6 and construct reciprocal component-stratified half samples."""
split = stratified_path_split(
data.component.cpu().numpy(), audit_fraction=0.5, seed=seed
)
first = torch.as_tensor(split.reference, dtype=torch.int64, device=data.state.device)
second = torch.as_tensor(split.audit, dtype=torch.int64, device=data.state.device)
reference, validation = (first, second) if fold == 0 else (second, first)
times = torch.as_tensor(
(deterministic_time, conditional_time),
dtype=torch.int64,
device=data.state.device,
)
result = DeviceExpiryCase(
state=data.state.index_select(1, times),
returns=data.returns.index_select(1, times),
costs=data.costs.index_select(1, times),
numerical_band=data.numerical_band.index_select(1, times),
path_weight=data.path_weight,
component=data.component,
reference=reference,
validation=validation,
option_price=(
None
if data.option_price is None
else data.option_price.index_select(1, times)
),
delta=None if data.delta is None else data.delta.index_select(1, times),
cash_strike=(
None
if data.cash_strike is None
else data.cash_strike.index_select(1, times)
),
spot=None if data.spot is None else data.spot.index_select(1, times),
option_is_put=(
None
if data.option_is_put is None
else data.option_is_put.index_select(1, times)
),
portfolio_barrier_rate=data.portfolio_barrier_rate,
portfolio_normalization=data.portfolio_normalization,
)
diagnostics = {
"definition": (
"component-stratified reciprocal 50/50 folds; fold 0 trains on "
"the first half and fold 1 trains on the second"
),
"seed": seed,
"fold": fold,
"training_paths": int(reference.numel()),
"validation_paths": int(validation.numel()),
"training_direct_P_paths": int((data.component[reference] == 0).sum().cpu()),
"validation_direct_P_paths": int(
(data.component[validation] == 0).sum().cpu()
),
"component_counts": split.component_counts,
}
return result, diagnostics
def _to_itm_dollar_portfolio(
data: DeviceExpiryCase,
*,
cost_rate: float,
vector_barrier: bool,
) -> tuple[DeviceExpiryCase, dict[str, Any]]:
"""Use entry-time ITM options and express every position in dollars.
Calls below spot are retained. Calls above spot are replaced by puts using
zero-rate put-call parity, ``P=C+K-S`` and ``dP=dC-dS``. The choice is made
at entry and remains fixed through expiry. Dividing every return by its
entry price makes a signed action coordinate a dollar investment.
"""
verify_inp(
data.option_price is not None
and data.cash_strike is not None
and data.spot is not None,
"ITM dollar normalization requires expiry option primitives",
)
verify_inp(
data.returns.shape == data.costs.shape == data.numerical_band.shape,
"ITM dollar normalization received inconsistent market arrays",
)
verify_inp(
data.returns.shape[-1] == data.option_price.shape[-1] + 1,
"expiry portfolios must contain one spot followed by their option strikes",
)
verify_inp(
math.isfinite(cost_rate) and cost_rate >= 0.0,
lambda: f"ITM dollar cost rate must be nonnegative, got {cost_rate!r}",
)
verify_inp(
not vector_barrier or cost_rate > 0.0,
"the logarithmic vector barrier requires a positive cost rate",
)
spot = data.spot[..., None, None]
call_price = data.option_price
put_price = call_price + data.cash_strike - spot
option_is_put = data.cash_strike >= spot
selected_price = torch.where(option_is_put, put_price, call_price)
price_scale = torch.maximum(
torch.maximum(call_price.abs(), data.cash_strike.abs()), spot.abs()
)
price_floor = 64.0 * torch.finfo(selected_price.dtype).eps * price_scale
verify_inp(
bool(torch.isfinite(selected_price).all().item())
and bool(torch.all(selected_price > price_floor).item()),
lambda: (
"entry-time ITM option prices must be finite and numerically positive; "
f"minimum price={float(selected_price.min().item()):g}, "
f"maximum floor={float(price_floor.max().item()):g}"
),
)
spot_return = data.returns[..., :1]
call_return = data.returns[..., 1:]
put_return = call_return - spot_return
selected_return = torch.where(option_is_put, put_return, call_return)
normalized_spot_return = spot_return / spot
normalized_option_return = selected_return / selected_price
normalized_return = torch.cat(
(normalized_spot_return, normalized_option_return), dim=-1
)
spot_band = data.numerical_band[..., :1]
call_band = data.numerical_band[..., 1:]
put_band = call_band + spot_band
selected_band = torch.where(option_is_put, put_band, call_band)
normalized_band = torch.cat(
(spot_band / spot, selected_band / selected_price), dim=-1
)
normalized_cost = torch.full_like(normalized_return, cost_rate)
for name, value in (
("returns", normalized_return),
("costs", normalized_cost),
("numerical_band", normalized_band),
):
if not torch.isfinite(value).all().item():
raise FloatingPointError(
f"ITM dollar-normalized {name} contains NaN or infinity"
)
result = DeviceExpiryCase(
state=data.state,
returns=normalized_return,
costs=normalized_cost,
numerical_band=normalized_band,
path_weight=data.path_weight,
component=data.component,
reference=data.reference,
validation=data.validation,
option_price=selected_price,
delta=None,
cash_strike=data.cash_strike,
spot=data.spot,
option_is_put=option_is_put,
portfolio_barrier_rate=cost_rate if vector_barrier else None,
portfolio_normalization="entry-time ITM call-or-put dollars",
)
paths, times, expiries, strikes = selected_price.shape
return result, {
"definition": (
"calls with K<S are retained; calls with K>=S are replaced at entry "
"by puts through P=C+K-S and dP=dC-dS; spot and option returns are "
"divided by their positive entry prices"
),
"paths": paths,
"times": times,
"expiries": expiries,
"strikes_per_expiry": strikes,
"put_coordinate_fraction": float(option_is_put.float().mean().item()),
"minimum_selected_option_price": float(selected_price.min().item()),
"maximum_selected_option_price": float(selected_price.max().item()),
"cost": (
(
"one vector barrier B_X(a)=-c X log(1-||a||_1/X), applied "
"to the signed net dollar portfolio rather than coordinatewise"
)
if vector_barrier
else "coordinatewise proportional cost after entry-value normalization"
),
"cost_rate": cost_rate,
}
def _to_itm_dollar_vector_barrier(
data: DeviceExpiryCase,
*,
cost_rate: float,
) -> tuple[DeviceExpiryCase, dict[str, Any]]:
"""Use ITM dollar instruments with one barrier on signed net investment."""
return _to_itm_dollar_portfolio(
data,
cost_rate=cost_rate,
vector_barrier=True,
)
def _parallel_pnl(
action: Tensor,
returns: Tensor,
costs: Tensor,
*,
portfolio_barrier_rate: float | None = None,
) -> Tensor:
"""Return unit P&L with shape ``(S,N,T)`` for parallel directions."""
assert action.ndim == 6 and action.shape[-3] == 2
assert returns.shape == costs.shape
assert action.shape[0] == returns.shape[0]
assert action.shape[2] == returns.shape[1]
market_return = returns[:, None]
market_cost = costs[:, None]
long = action[..., 0, :, :]
short = action[..., 1, :, :]
if portfolio_barrier_rate is not None:
signed = long - short
relative_notional = signed.abs().sum(dim=(-1, -2))
if not torch.all(relative_notional < 1.0).item():
raise FloatingPointError(
"vector-barrier relative notional reached or exceeded one"
)
result = (signed * market_return).sum(dim=(-1, -2))
result = result + portfolio_barrier_rate * torch.log1p(
-relative_notional
)
if not torch.isfinite(result).all().item():
raise FloatingPointError("vector-barrier P&L contains NaN or infinity")
return result
result = (
(long - short) * market_return - (long + short) * market_cost
).sum(dim=(-1, -2))
return result
def _parallel_band(
action: Tensor,
returns: Tensor,
costs: Tensor,
instrument_band: Tensor,
*,
portfolio_barrier_rate: float | None = None,
) -> Tensor:
"""Propagate observation errors through all parallel unit-gross directions."""
assert returns.shape == costs.shape == instrument_band.shape
gross = (
(action[..., 0, :, :] - action[..., 1, :, :]).abs()
if portfolio_barrier_rate is not None
else action[..., 0, :, :] + action[..., 1, :, :]
)
accumulation = 32.0 * torch.finfo(torch.float32).eps * (
gross * (returns[:, None].abs() + costs[:, None])
).sum(dim=(-1, -2))
return (gross * instrument_band[:, None]).sum(dim=(-1, -2)) + accumulation
def _exact_expiry_lower_bound(
action: Tensor,
data: DeviceExpiryCase,
indices: Tensor,
) -> tuple[Tensor, Tensor] | None:
"""Return the all-spot payoff-cone lower bound for every action head."""
if (
data.option_price is None
or data.cash_strike is None
or data.spot is None
or (data.option_is_put is None and data.delta is None)
):
return None
if data.option_is_put is not None:
paths, heads, times = action.shape[:3]
signed = action[..., 0, :, :] - action[..., 1, :, :]
relative_notional = signed.abs().sum(dim=(-1, -2))
if data.portfolio_barrier_rate is not None:
verify_inp(
bool(torch.all(relative_notional < 1.0).item()),
"exact vector-barrier audit reached its open notional boundary",
)
lower = data.portfolio_barrier_rate * torch.log1p(
-relative_notional
)
else:
representation_gross = action[..., 0, :, :] + action[..., 1, :, :]
lower = -(
representation_gross * data.costs[indices, None]
).sum(dim=(-1, -2))
slope_ok = torch.ones_like(lower, dtype=torch.bool)
for time_index in range(times):
selected_action = signed[:, :, time_index]
selected_spot = data.spot[indices, time_index]
selected_option = data.option_price[indices, time_index]
selected_strike = data.cash_strike[indices, time_index]
selected_put = data.option_is_put[indices, time_index]
for expiry_index in range(selected_option.shape[1]):
strike = selected_strike[:, expiry_index]
option_price = selected_option[:, expiry_index]
is_put = selected_put[:, expiry_index]
terminal_spot = torch.cat(
(
torch.zeros_like(strike[:, :1]),
strike,
),
dim=-1,
)
call_payoff = torch.clamp_min(
terminal_spot[:, :, None] - strike[:, None, :], 0.0
)
put_payoff = torch.clamp_min(
strike[:, None, :] - terminal_spot[:, :, None], 0.0
)
payoff = torch.where(is_put[:, None, :], put_payoff, call_payoff)
normalized_option_return = (
payoff - option_price[:, None, :]
) / option_price[:, None, :]
normalized_spot_return = (
terminal_spot - selected_spot[:, None]
) / selected_spot[:, None]
expiry_action = selected_action[:, :, expiry_index]
scenario_value = (
expiry_action[..., :1]
* normalized_spot_return[:, None]
+ (
expiry_action[..., 1:, None]
* normalized_option_return[:, None].transpose(-1, -2)
).sum(dim=-2)
)
lower[:, :, time_index] += scenario_value.amin(dim=-1)
tail_slope = expiry_action[..., 0] / selected_spot[:, None]
call_slope = torch.where(
is_put,
torch.zeros_like(option_price),
option_price.reciprocal(),
)
tail_slope = tail_slope + (
expiry_action[..., 1:] * call_slope[:, None]
).sum(dim=-1)
slope_tolerance = (
32.0
* torch.finfo(action.dtype).eps
* expiry_action.abs().sum(dim=-1)
/ selected_spot[:, None]
)
valid_slope = tail_slope >= -slope_tolerance
lower[:, :, time_index] = torch.where(
valid_slope,
lower[:, :, time_index],
torch.full_like(lower[:, :, time_index], -torch.inf),
)
slope_ok[:, :, time_index] &= valid_slope
return lower, slope_ok
paths, heads, times = action.shape[:3]
lower = torch.empty(
(paths, heads, times), dtype=action.dtype, device=action.device
)
slope_ok = torch.empty(
(paths, heads, times), dtype=torch.bool, device=action.device
)
signed = action[..., 0, :, :] - action[..., 1, :, :]
for time_index in range(times):
selected_action = signed[:, :, time_index]
selected_spot = data.spot[indices, time_index, None].expand(-1, heads)
selected_option = data.option_price[
indices, time_index, None
].expand(-1, heads, -1, -1)
selected_delta = data.delta[
indices, time_index, None
].expand_as(selected_option)
selected_strike = data.cash_strike[
indices, time_index, None
].expand_as(selected_option)
selected_cost = data.costs[
indices, time_index, None
].expand_as(selected_action)
values, tail_slope = payoff_cone_values(
selected_action,
spot=selected_spot,
option_price=selected_option,
delta=selected_delta,
cash_strike=selected_strike,
costs=selected_cost,
hedge="raw",
)
slope_tolerance = (
32.0
* torch.finfo(action.dtype).eps
* selected_action.abs().sum(dim=-1)
)
valid_slope = tail_slope >= -slope_tolerance
expiry_lower = values.amin(dim=-1)
expiry_lower = torch.where(
valid_slope,
expiry_lower,
torch.full_like(expiry_lower, -torch.inf),
)
lower[:, :, time_index] = expiry_lower.sum(dim=-1)
slope_ok[:, :, time_index] = valid_slope.all(dim=-1)
return lower, slope_ok
def _powerexp(value: Tensor) -> tuple[Tensor, Tensor]:
positive = torch.clamp_min(value, 0.0)
negative = torch.clamp_max(value, 0.0)
utility = torch.where(
value > 0.0,
-torch.expm1(-positive),
negative - 0.5 * negative.square(),
)
marginal = torch.where(value > 0.0, torch.exp(-positive), 1.0 - negative)
return utility, marginal
def _squared_downside(value: Tensor) -> Tensor:
"""Return the C1 squared loss below zero and zero otherwise."""
return torch.clamp_max(value, 0.0).square()
def _bucket_downside_loss(
pnl: Tensor,
path_weight: Tensor,
bucket_index: Tensor,
*,
buckets: int,
gain_tiebreak: float,
relative_temperature: float = 0.0,
) -> tuple[Tensor, Tensor, Tensor]:
"""Minimize the worst weighted squared downside across path buckets."""
assert pnl.shape[0] == path_weight.shape[0] == bucket_index.shape[0]
assert bucket_index.dtype == torch.int64
assert buckets > 1
tail = pnl.shape[1:]
weight = path_weight.reshape(-1, *(1 for _ in tail))
expanded_bucket = bucket_index.reshape(-1, *(1 for _ in tail)).expand_as(pnl)
bucket_sum = torch.zeros(
(buckets, *tail), dtype=pnl.dtype, device=pnl.device
)
bucket_sum.scatter_add_(
0, expanded_bucket, weight * _squared_downside(pnl)
)
bucket_weight = torch.zeros(
buckets, dtype=pnl.dtype, device=pnl.device
).scatter_add_(0, bucket_index, path_weight)
assert torch.all(bucket_weight > 0.0)
bucket_risk = bucket_sum / bucket_weight.reshape(
buckets, *(1 for _ in tail)
)
if relative_temperature > 0.0:
scale = bucket_risk.mean(dim=0).detach().clamp_min(
torch.finfo(pnl.dtype).tiny
)
temperature = relative_temperature * scale
worst_risk = temperature * (
torch.logsumexp(bucket_risk / temperature, dim=0)
- math.log(buckets)
)
else:
worst_risk = bucket_risk.amax(dim=0)
physical = path_weight / path_weight.sum()
mean_gain = (
physical.reshape(-1, *(1 for _ in tail)) * torch.clamp_min(pnl, 0.0)
).sum(dim=0)
loss = worst_risk.mean() - gain_tiebreak * mean_gain.mean()
return loss, worst_risk, bucket_risk
def _normalized_marginal_weight(
pnl: Tensor,
path_weight: Tensor,
notionals: Tensor,
*,
translation: Tensor | None = None,
responsibility: Tensor | None = None,
) -> Tensor:
"""Normalize physical marginal-utility weights over the sample axis."""
assert pnl.shape[0] == path_weight.shape[0]
reshape = (1, notionals.numel(), *(1 for _ in range(pnl.ndim - 2)))
scaled = pnl * notionals.reshape(reshape)
if translation is not None:
assert translation.shape == pnl.shape[1:]
scaled = scaled + translation[None]
nonpositive = torch.clamp_max(scaled, 0.0)
log_marginal = torch.where(
scaled > 0.0,
-scaled,
torch.log1p(-nonpositive),
)
extra = 0.0
if responsibility is not None:
assert responsibility.shape == pnl.shape
extra = torch.log(responsibility.clamp_min(torch.finfo(pnl.dtype).tiny))
log_density = (
torch.log(path_weight)[:, None]
.reshape(path_weight.shape[0], 1, *(1 for _ in range(pnl.ndim - 2)))
+ log_marginal
+ extra
)
return torch.softmax(log_density, dim=0)
def _feedforward_loss(
model: (
ParallelFeedForwardDirections
| GatedParallelFeedForwardDirections
| ParallelKernelDirections
),
state: Tensor,
returns: Tensor,
costs: Tensor,
path_weight: Tensor,
notionals: Tensor,
*,
objective: str,
bucket_index: Tensor | None,
buckets: int,
gain_tiebreak: float,
bucket_temperature: float,
portfolio_barrier_rate: float | None,
) -> tuple[Tensor, dict[str, Tensor]]:
action, logits = model(state)
pnl = _parallel_pnl(
action,
returns,
costs,
portfolio_barrier_rate=portfolio_barrier_rate,
)
physical = path_weight / path_weight.sum()
bucket_risk: Tensor | None = None
if objective in {"powerexp", "oce-powerexp"}:
use_translation = objective == "oce-powerexp"
translation = model.oce_translation if use_translation else None
assert (translation is not None) == use_translation
marginal_weight = _normalized_marginal_weight(
pnl,
path_weight,
notionals,
translation=translation,
)
surrogate = (marginal_weight.detach() * pnl).sum(dim=0)
scaled = pnl * notionals[None, :, None]
if translation is not None:
scaled = scaled + translation[None]
utility, _ = _powerexp(scaled)
reported_objective = (physical[:, None, None] * utility).sum(dim=0)
loss = -surrogate.mean()
translation_first_order_condition: Tensor | None = None
if translation is not None:
# Detaching P&L makes this term train y only. The normalized
# marginal surrogate above trains a without exponentially small
# gradients and has the same action first-order condition.
translated_detached = (
pnl.detach() * notionals[None, :, None] + translation[None]
)
translation_utility, translation_marginal = _powerexp(
translated_detached
)
translation_objective = (
physical[:, None, None] * translation_utility
).sum(dim=0) - translation
loss = loss - translation_objective.mean()
reported_objective = reported_objective - translation
translation_first_order_condition = (
physical[:, None, None] * translation_marginal
).sum(dim=0) - 1.0
elif objective == "downside2":
downside = _squared_downside(pnl)
risk = (physical[:, None, None] * downside).sum(dim=0)
reported_objective = -risk
loss = risk.mean()
else:
assert objective == "bucket-downside2" and bucket_index is not None
loss, risk, bucket_risk = _bucket_downside_loss(
pnl,
path_weight,
bucket_index,
buckets=buckets,
gain_tiebreak=gain_tiebreak,
relative_temperature=bucket_temperature,
)
reported_objective = -risk
result = {
"action": action,
"objective": reported_objective,
"pnl": pnl,
"raw_maximum": logits.abs().amax(dim=-1),
}
if objective == "oce-powerexp":
assert model.oce_translation is not None
assert translation_first_order_condition is not None
result["oce_translation"] = model.oce_translation
result["oce_translation_first_order_condition"] = (
translation_first_order_condition
)
if bucket_risk is not None:
result["bucket_downside"] = bucket_risk
return loss, result
def _expert_pnl(
expert_action: Tensor,
returns: Tensor,
costs: Tensor,
) -> Tensor:
"""Return conditional expert P&L with shape ``(S,N,K)``."""
long = expert_action[..., 0, :, :]
short = expert_action[..., 1, :, :]
return (
(long[None] - short[None]) * returns[:, None, None]
- (long[None] + short[None]) * costs[:, None, None]
).sum(dim=(-1, -2))
def _partition_loss(
model: LearnedPartitionDirections,
state: Tensor,
returns: Tensor,
costs: Tensor,
path_weight: Tensor,
notionals: Tensor,
*,
balance_coefficient: float,
objective: str,
) -> tuple[Tensor, dict[str, Tensor]]:
action, responsibility, logits = model(state)
deterministic_pnl = _parallel_pnl(
action[:, :, :1], returns[:, :1], costs[:, :1]
)[..., 0]
expert_pnl = _expert_pnl(
model.expert_actions(), returns[:, 1], costs[:, 1]
)
physical = path_weight / path_weight.sum()
physical_responsibility = physical[:, None, None] * responsibility
mass = physical_responsibility.sum(dim=0)
balance = (
model.config.partitions * mass - 1.0
).square().mean()
actual_pnl = _parallel_pnl(action, returns, costs)
if objective == "powerexp":
deterministic_weight = _normalized_marginal_weight(
deterministic_pnl, path_weight, notionals
)
deterministic_surrogate = (
deterministic_weight.detach() * deterministic_pnl
).sum(dim=0)
expert_weight = _normalized_marginal_weight(
expert_pnl,
path_weight,
notionals,
responsibility=responsibility,
)
expert_surrogate = (expert_weight.detach() * expert_pnl).sum(dim=0)
expert_utility, _ = _powerexp(expert_pnl * notionals[None, :, None])
router_objective = (
physical_responsibility * expert_utility.detach()
).sum(dim=0) / mass.clamp_min(torch.finfo(mass.dtype).tiny)
actual_utility, _ = _powerexp(actual_pnl * notionals[None, :, None])
actual_objective = (physical[:, None, None] * actual_utility).sum(dim=0)
loss = (
-deterministic_surrogate.mean()
-expert_surrogate.mean()
-router_objective.mean()
+ balance_coefficient * balance
)
else:
assert objective == "downside2"
deterministic_risk = (
physical[:, None] * _squared_downside(deterministic_pnl)
).sum(dim=0)
expert_downside = _squared_downside(expert_pnl)
expert_risk = (
physical_responsibility * expert_downside
).sum(dim=0) / mass.clamp_min(torch.finfo(mass.dtype).tiny)
# The detached local risk lets the state-only router learn regions while
# the expert directions independently minimize downside within them.
router_risk = (
physical_responsibility * expert_downside.detach()
).sum(dim=0) / mass.clamp_min(torch.finfo(mass.dtype).tiny)
actual_risk = (
physical[:, None, None] * _squared_downside(actual_pnl)
).sum(dim=0)
actual_objective = -actual_risk
loss = (
deterministic_risk.mean()
+ expert_risk.mean()
+ router_risk.mean()
+ balance_coefficient * balance
)
return loss, {
"action": action,
"objective": actual_objective,
"pnl": actual_pnl,
"raw_maximum": logits.abs().amax(dim=-1),
"partition_mass": mass,
"partition_balance": balance,
"responsibility": responsibility,
}
def _model_loss(
model: DirectionModel,
state: Tensor,
returns: Tensor,
costs: Tensor,
path_weight: Tensor,
notionals: Tensor,
*,
balance_coefficient: float,
objective: str = "powerexp",
bucket_index: Tensor | None = None,
buckets: int = 0,
gain_tiebreak: float = 0.0,
bucket_temperature: float = 0.0,
portfolio_barrier_rate: float | None = None,
) -> tuple[Tensor, dict[str, Tensor]]:
assert objective in {
"powerexp",
"oce-powerexp",
"downside2",
"bucket-downside2",
}
if model.config.architecture == "partition":
assert portfolio_barrier_rate is None
assert objective not in {"oce-powerexp", "bucket-downside2"}
return _partition_loss(
model,
state,
returns,
costs,
path_weight,
notionals,
balance_coefficient=balance_coefficient,
objective=objective,
)
return _feedforward_loss(
model,
state,
returns,
costs,
path_weight,
notionals,
objective=objective,
bucket_index=bucket_index,
buckets=buckets,
gain_tiebreak=gain_tiebreak,
bucket_temperature=bucket_temperature,
portfolio_barrier_rate=portfolio_barrier_rate,
)
def _checkpoint(
path: Path,
*,
model: DirectionModel,
optimizer: torch.optim.Optimizer,
generator: torch.Generator,
step: int,
tracker: list[dict[str, Any]],
completed: bool,
) -> None:
_atomic_torch_save(
path,
{
"model_code_version": type(model).version.unique_id48,
"config_code_version": type(model.config).version.unique_id48,
"user_version": model.config.user_version,
"model": model.state_dict(),
"optimizer": optimizer.state_dict(),
"generator_state": generator.get_state(),
"step": step,
"tracker": tracker,
"completed": completed,
},
)
def _stratified_bucket_assignment(
data: DeviceExpiryCase,
indices: Tensor,
*,
buckets: int,
seed: int,
) -> Tensor:
"""Assign positions to physical-weight-balanced proposal-component buckets."""
assert buckets > 1 and indices.numel() >= buckets
component = data.component[indices].cpu().numpy()
weight = data.path_weight[indices].double().cpu().numpy()
assignment = _balanced_component_bucket_assignment(
component,
weight,
buckets=buckets,
seed=seed,
)
return torch.as_tensor(
assignment, dtype=torch.int64, device=indices.device
)
def _balanced_component_bucket_assignment(
component: np.ndarray,
path_weight: np.ndarray,
*,
buckets: int,
seed: int,
) -> np.ndarray:
"""Greedily balance physical mass within each proposal component."""
assert component.ndim == path_weight.ndim == 1
assert component.shape == path_weight.shape and component.size >= buckets
assert np.all(np.isfinite(path_weight)) and np.all(path_weight > 0.0)
generator = np.random.default_rng(seed)
assignment = np.full(component.shape, -1, dtype=np.int64)
for value in np.unique(component):
positions = np.flatnonzero(component == value)
generator.shuffle(positions)
order = np.argsort(-path_weight[positions], kind="stable")
positions = positions[order]
priority = generator.permutation(buckets)
heap = [(0.0, int(priority[bucket]), bucket) for bucket in range(buckets)]
heapq.heapify(heap)
for position in positions:
mass, tie_break, bucket = heapq.heappop(heap)
assignment[position] = bucket
heapq.heappush(
heap,
(mass + float(path_weight[position]), tie_break, bucket),
)
assert np.all(assignment >= 0)
assert np.unique(assignment).size == buckets
return assignment
def _stratified_bucket_members(
data: DeviceExpiryCase,
*,
buckets: int,
seed: int,
) -> list[Tensor]:
"""Partition training positions while spreading proposal components."""
assignment = _stratified_bucket_assignment(
data, data.reference, buckets=buckets, seed=seed
)
members = [
torch.nonzero(assignment == bucket, as_tuple=False).flatten()
for bucket in range(buckets)
]
assert all(value.numel() > 0 for value in members)
return members
def _draw_bucketed_indices(
reference: Tensor,
members: list[Tensor],
*,
size: int,
generator: torch.Generator,
) -> tuple[Tensor, Tensor]:
"""Draw an equal-size weighted-training sample from every fixed bucket."""
buckets = len(members)
assert size >= buckets
quotient, remainder = divmod(size, buckets)
draws: list[Tensor] = []
labels: list[Tensor] = []
for bucket, positions in enumerate(members):
count = quotient + int(bucket < remainder)
selected = positions[
torch.randint(
positions.numel(),
(count,),
generator=generator,
device=positions.device,
)
]
draws.append(reference[selected])
labels.append(
torch.full(
(count,), bucket, dtype=torch.int64, device=reference.device
)
)
return torch.cat(draws), torch.cat(labels)
def _train(
model: DirectionModel,
callable_model: DirectionModel,
data: DeviceExpiryCase,
notionals: Tensor,
*,
checkpoint_path: Path,
batch_size: int,
valuation_batch_size: int,
epochs: int,
value_update: int,
checkpoint_update: int,
lr: float,
seed: int,
balance_coefficient: float,
objective: str,
buckets: int,
gain_tiebreak: float,
bucket_temperature: float,
) -> dict[str, Any]:
"""Cold-train every notional simultaneously on one half sample."""
optimizer = torch.optim.AdamW(model.parameters(), lr=lr, weight_decay=0.0)
generator = torch.Generator(device=model.device)
generator.manual_seed(seed)
tracker: list[dict[str, Any]] = []
start_step = 0
if checkpoint_path.exists():
saved = torch.load(checkpoint_path, map_location=model.device, weights_only=False)
compatible = (
saved.get("model_code_version") == type(model).version.unique_id48
and saved.get("config_code_version")
== type(model.config).version.unique_id48
and saved.get("user_version") == model.config.user_version
)
if compatible:
model.load_state_dict(saved["model"])
optimizer.load_state_dict(saved["optimizer"])
generator.set_state(saved["generator_state"].cpu())
tracker = list(saved.get("tracker", []))
start_step = int(saved["step"])
if bool(saved.get("completed")) and start_step >= epochs:
calibration = (
_calibrate_model_oce_translation(
model,
data,
data.reference,
tuple(float(value) for value in notionals.cpu().tolist()),
batch_size=valuation_batch_size,
)
if objective == "oce-powerexp"
else None
)
if calibration is not None:
_checkpoint(
checkpoint_path,
model=model,
optimizer=optimizer,
generator=generator,
step=start_step,
tracker=tracker,
completed=True,
)
return {
"steps": start_step,
"resumed_complete_checkpoint": True,
"final_oce_translation_calibration": calibration,
"tracker": tracker,
}
if bool(saved.get("completed")):
print(
f"Extending completed checkpoint {checkpoint_path} from "
f"{start_step:,} to {epochs:,} steps",
flush=True,
)
else:
print(f"Ignoring incompatible checkpoint {checkpoint_path}", flush=True)
bucket_members = (
_stratified_bucket_members(data, buckets=buckets, seed=seed + 20_000)
if objective == "bucket-downside2"
else None
)
fixed_generator = torch.Generator(device=model.device)
fixed_generator.manual_seed(seed + 10_000)
fixed_size = min(valuation_batch_size, data.reference.numel())
if bucket_members is None:
fixed_draw = torch.randperm(
data.reference.numel(), generator=fixed_generator, device=model.device
)[:fixed_size]
fixed = data.reference[fixed_draw]
fixed_bucket = None
else:
fixed, fixed_bucket = _draw_bucketed_indices(
data.reference,
bucket_members,
size=fixed_size,
generator=fixed_generator,
)
started = time.monotonic()
for step in range(start_step + 1, epochs + 1):
if bucket_members is None:
draw = torch.randint(
data.reference.numel(),
(batch_size,),
generator=generator,
device=model.device,
)
indices = data.reference[draw]
batch_bucket = None
else:
indices, batch_bucket = _draw_bucketed_indices(
data.reference,
bucket_members,
size=batch_size,
generator=generator,
)
optimizer.zero_grad(set_to_none=True)
loss, _ = _model_loss(
callable_model,
data.state[indices, 1],
data.returns[indices],
data.costs[indices],
data.path_weight[indices],
notionals,
balance_coefficient=balance_coefficient,
objective=objective,
bucket_index=batch_bucket,
buckets=buckets,
gain_tiebreak=gain_tiebreak,
bucket_temperature=bucket_temperature,
portfolio_barrier_rate=data.portfolio_barrier_rate,
)
loss.backward()
for parameter in model.parameters():
if parameter.grad is not None and not torch.isfinite(parameter.grad).all().item():
raise FloatingPointError("parallel direction gradient is non-finite")
optimizer.step()
model.project_parameters_()
if step % value_update == 0 or step == epochs:
with torch.no_grad():
fixed_loss, values = _model_loss(
model,
data.state[fixed, 1],
data.returns[fixed],
data.costs[fixed],
data.path_weight[fixed],
notionals,
balance_coefficient=balance_coefficient,
objective=objective,
bucket_index=fixed_bucket,
buckets=buckets,
gain_tiebreak=gain_tiebreak,
bucket_temperature=bucket_temperature,
portfolio_barrier_rate=data.portfolio_barrier_rate,
)
item: dict[str, Any] = {
"step": step,
"loss": float(fixed_loss.cpu()),
"objective_by_notional_and_time": values["objective"].cpu().tolist(),
"raw_maximum_by_notional": values["raw_maximum"].amax(dim=0).cpu().tolist(),
"elapsed_seconds": time.monotonic() - started,
}
if "partition_mass" in values:
item["partition_mass_minimum_by_notional"] = (
values["partition_mass"].amin(dim=-1).cpu().tolist()
)
item["partition_mass_maximum_by_notional"] = (
values["partition_mass"].amax(dim=-1).cpu().tolist()
)
item["partition_balance"] = float(
values["partition_balance"].cpu()
)
if "bucket_downside" in values:
item["maximum_bucket_downside_by_notional_and_time"] = (
values["bucket_downside"].amax(dim=0).cpu().tolist()
)
if "oce_translation" in values:
item["oce_translation_by_notional_and_time"] = (
values["oce_translation"].cpu().tolist()
)
item["oce_translation_first_order_condition"] = (
values["oce_translation_first_order_condition"].cpu().tolist()
)
tracker.append(item)
print(
f"step {step:,}: loss={item['loss']:.7g}, "
f"objectives={item['objective_by_notional_and_time']}",
flush=True,
)
if step % checkpoint_update == 0:
_checkpoint(
checkpoint_path,
model=model,
optimizer=optimizer,
generator=generator,
step=step,
tracker=tracker,
completed=False,
)
calibration = (
_calibrate_model_oce_translation(
model,
data,
data.reference,
tuple(float(value) for value in notionals.cpu().tolist()),
batch_size=valuation_batch_size,
)
if objective == "oce-powerexp"
else None
)
_checkpoint(
checkpoint_path,
model=model,
optimizer=optimizer,
generator=generator,
step=epochs,
tracker=tracker,
completed=True,
)
return {
"steps": epochs,
"resumed_complete_checkpoint": False,
"elapsed_seconds_this_invocation": time.monotonic() - started,
"constant_learning_rate": lr,
"gradient_clipping": False,
"cold_independent_notional_parameters": True,
"optimization_objective": objective,
"buckets": buckets if objective == "bucket-downside2" else None,
"gain_tiebreak": gain_tiebreak,
"bucket_relative_temperature": bucket_temperature,
"final_oce_translation_calibration": calibration,
"tracker": tracker,
}
def _weighted_mean_error(
value: np.ndarray, normalized_weight: np.ndarray
) -> tuple[float, float]:
mean = float(np.dot(normalized_weight, value))
error = float(
np.sqrt(np.sum(np.square(normalized_weight * (value - mean))))
)
return mean, error
def _finite_maximum_or_none(value: np.ndarray) -> float | None:
"""Return the largest finite value, leaving unbounded diagnostics as JSON null."""
finite = np.isfinite(value)
return float(np.max(value[finite])) if np.any(finite) else None
def _bucket_pnl_audit(
pnl: np.ndarray,
weight: np.ndarray,
assignment: np.ndarray,
*,
buckets: int,
) -> dict[str, Any]:
"""Audit P&L means and squared downside within every fixed path bucket."""
assert pnl.ndim == 3 and weight.shape == assignment.shape == pnl.shape[:1]
bucket_mean = np.empty((buckets, *pnl.shape[1:]), dtype=np.float64)
bucket_downside = np.empty_like(bucket_mean)
bucket_loss_probability = np.empty_like(bucket_mean)
bucket_paths: list[int] = []
for bucket in range(buckets):
selected = assignment == bucket
bucket_paths.append(int(selected.sum()))
assert selected.any()
local_weight = weight[selected]
local_weight = local_weight / local_weight.sum()
local_pnl = pnl[selected]
shaped_weight = local_weight.reshape(-1, 1, 1)
bucket_mean[bucket] = np.sum(shaped_weight * local_pnl, axis=0)
bucket_downside[bucket] = np.sum(
shaped_weight * np.square(np.minimum(local_pnl, 0.0)), axis=0
)
bucket_loss_probability[bucket] = np.sum(
shaped_weight * (local_pnl < 0.0), axis=0
)
return {
"paths_per_bucket_minimum": min(bucket_paths),
"paths_per_bucket_maximum": max(bucket_paths),
"minimum_bucket_P_mean_pnl_by_notional_and_time": bucket_mean.min(
axis=0
).tolist(),
"maximum_bucket_P_squared_downside_by_notional_and_time": (
bucket_downside.max(axis=0).tolist()
),
"maximum_bucket_P_loss_probability_by_notional_and_time": (
bucket_loss_probability.max(axis=0).tolist()
),
}
def _powerexp_numpy(value: np.ndarray) -> np.ndarray:
positive = np.maximum(value, 0.0)
negative = np.minimum(value, 0.0)
return np.where(
value > 0.0,
-np.expm1(-positive),
negative - 0.5 * np.square(negative),
)
def _powerexp_marginal_numpy(value: np.ndarray) -> np.ndarray:
"""Evaluate PowerExp's positive marginal without eager branch overflow."""
result = np.empty_like(value, dtype=np.float64)
positive = value > 0.0
result[positive] = np.exp(-value[positive])
result[~positive] = 1.0 - value[~positive]
return result
def _recalibrate_oce_translation(
value: np.ndarray,
normalized_weight: np.ndarray,
notional: float,
) -> float:
"""Solve E_P[u'(y+n*pi)]=1 for one scalar translation y."""
assert value.ndim == normalized_weight.ndim == 1
assert value.shape == normalized_weight.shape
scaled = notional * value.astype(np.float64, copy=False)
lower = float(-np.max(scaled) - 1.0)
upper = float(-np.min(scaled) + 1.0)
def condition(translation: float) -> float:
marginal = _powerexp_marginal_numpy(translation + scaled)
return float(np.dot(normalized_weight, marginal) - 1.0)
assert condition(lower) > 0.0 and condition(upper) < 0.0
for _ in range(80):
middle = 0.5 * (lower + upper)
if condition(middle) > 0.0:
lower = middle
else:
upper = middle
return 0.5 * (lower + upper)
def _oce_numpy_statistics(
value: np.ndarray,
weight: np.ndarray,
notional: float,
translation: float,
) -> dict[str, float | np.ndarray]:
"""Return OCE value and both scalar and action first-order conditions."""
normalized_weight = weight / weight.sum()
shifted = translation + notional * value
marginal = _powerexp_marginal_numpy(shifted)
marginal_weight = normalized_weight * marginal
marginal_expectation = float(marginal_weight.sum())
marginal_weight /= marginal_expectation
derivative, derivative_error = _weighted_mean_error(value, marginal_weight)
objective, objective_error = _weighted_mean_error(
_powerexp_numpy(shifted), normalized_weight
)
return {
"objective": objective - translation,
"objective_standard_error": objective_error,
"translation_first_order_condition": marginal_expectation - 1.0,
"normalized_notional_derivative": derivative,
"normalized_notional_derivative_standard_error": derivative_error,
"marginal_weight": marginal_weight,
}
@torch.no_grad()
def _calibrate_model_oce_translation(
model: DirectionModel,
data: DeviceExpiryCase,
indices: Tensor,
notionals: tuple[float, ...],
*,
batch_size: int,
) -> dict[str, Any]:
"""Exactly calibrate each scalar y on the full frozen-action training set."""
verify_inp(model.oce_translation is not None, "model has no OCE translation")
paths = int(indices.numel())
pnl = np.empty((paths, len(notionals), 2), dtype=np.float64)
for start in range(0, paths, batch_size):
stop = min(paths, start + batch_size)
batch = indices[start:stop]
action = model(data.state[batch, 1])[0]
pnl[start:stop] = _parallel_pnl(
action,
data.returns[batch],
data.costs[batch],
portfolio_barrier_rate=data.portfolio_barrier_rate,
).cpu().double().numpy()
weight = data.path_weight[indices].cpu().double().numpy()
normalized_weight = weight / weight.sum()
before = model.oce_translation.detach().cpu().double().numpy()
calibrated = np.empty_like(before)
residual = np.empty_like(before)
for notional_index, notional in enumerate(notionals):
for time_index in range(2):
value = pnl[:, notional_index, time_index]
calibrated[notional_index, time_index] = _recalibrate_oce_translation(
value,
normalized_weight,
notional,
)
residual[notional_index, time_index] = _oce_numpy_statistics(
value,
weight,
notional,
calibrated[notional_index, time_index],
)["translation_first_order_condition"]
model.oce_translation.copy_(
torch.as_tensor(
calibrated,
dtype=model.fdtype,
device=model.device,
)
)
return {
"definition": (
"one-dimensional full-training-set solution of E_P[u'(y+n*pi)]=1 "
"after freezing the action"
),
"before": before.tolist(),
"after": calibrated.tolist(),
"maximum_absolute_first_order_residual": float(np.max(np.abs(residual))),
}
def _activity_threshold_report(
value: np.ndarray,
tolerance: np.ndarray,
activity: np.ndarray,
weight: np.ndarray,
direct: np.ndarray,
*,
notional: float,
exact_lower: np.ndarray | None,
use_oce_translation: bool,
) -> list[dict[str, Any]]:
"""Audit the admissible hard gate obtained from a learned soft activity."""
normalized_weight = weight / weight.sum()
result: list[dict[str, Any]] = []
for threshold in (0.01, 0.1, 0.5, 0.9, 0.99):
active = activity >= threshold
gated_value = np.where(active, value, 0.0)
gated_tolerance = np.where(active, tolerance, 0.0)
loss = gated_value < -gated_tolerance
active_mass = float(np.dot(normalized_weight, active.astype(np.float64)))
if active.any() and active_mass > 0.0:
active_weight = normalized_weight[active] / active_mass
conditional_mean, conditional_mean_error = _weighted_mean_error(
value[active], active_weight
)
conditional_loss, conditional_loss_error = _weighted_mean_error(
(value[active] < -tolerance[active]).astype(np.float64),
active_weight,
)
else:
conditional_mean = conditional_mean_error = 0.0
conditional_loss = conditional_loss_error = 0.0
translation = (
_recalibrate_oce_translation(
gated_value,
normalized_weight,
notional,
)
if use_oce_translation
else 0.0
)
utility_statistics = _oce_numpy_statistics(
gated_value,
weight,
notional,
translation,
)
result.append(
{
"activity_threshold": threshold,
"active_path_count": int(active.sum()),
"direct_P_active_path_count": int(np.sum(active & direct)),
"P_active_probability": active_mass,
"P_mean_pnl": _weighted_mean_error(
gated_value, normalized_weight
)[0],
"P_active_conditional_mean_pnl": conditional_mean,
"P_active_conditional_mean_pnl_standard_error": (
conditional_mean_error
),
"P_loss_probability": _weighted_mean_error(
loss.astype(np.float64), normalized_weight
)[0],
"P_active_conditional_loss_probability": conditional_loss,
"P_active_conditional_loss_probability_standard_error": (
conditional_loss_error
),
"objective": utility_statistics["objective"],
"objective_standard_error": utility_statistics[
"objective_standard_error"
],
"oce_translation": translation if use_oce_translation else None,
"oce_translation_first_order_condition": (
utility_statistics["translation_first_order_condition"]
if use_oce_translation
else None
),
"normalized_notional_derivative": utility_statistics[
"normalized_notional_derivative"
],
"normalized_notional_derivative_standard_error": (
utility_statistics[
"normalized_notional_derivative_standard_error"
]
),
"proposal_minimum_pnl_plus_band": float(
np.min(gated_value + gated_tolerance)
),
"exact_payoff_cone": (
None
if exact_lower is None
else {
"active_numerically_nonnegative_count": int(
np.sum(active & (exact_lower >= -tolerance))
),
"active_strict_nonnegative_count": int(
np.sum(active & (exact_lower >= 0.0))
),
"all_active_numerically_nonnegative": bool(
active.any()
and np.all(exact_lower[active] >= -tolerance[active])
),
}
),
}
)
return result
@torch.no_grad()
def _evaluate_partition_candidates(
model: LearnedPartitionDirections,
data: DeviceExpiryCase,
indices: Tensor,
notionals: tuple[float, ...],
*,
batch_size: int,
) -> dict[str, Any]:
"""Audit each hard-routed local direction as a separate conditional strategy."""
paths = int(indices.numel())
num_notionals = len(notionals)
partitions = model.config.partitions
pnl = np.empty((paths, num_notionals, partitions), dtype=np.float64)
band = np.empty_like(pnl)
cone_lower = (
np.empty_like(pnl) if data.option_price is not None else None
)
assignment = np.empty((paths, num_notionals), dtype=np.int16)
expert_action = model.expert_actions()
expert_gross = expert_action[..., 0, :, :] + expert_action[..., 1, :, :]
for start in range(0, paths, batch_size):
stop = min(paths, start + batch_size)
batch = indices[start:stop]
factor = model.factor(data.state[batch, 1])
responsibility, _ = model.responsibilities(factor)
assignment[start:stop] = responsibility.argmax(dim=-1).cpu().numpy()
batch_returns = data.returns[batch, 1]
batch_costs = data.costs[batch, 1]
pnl[start:stop] = _expert_pnl(
expert_action, batch_returns, batch_costs
).cpu().double().numpy()
accumulation = 32.0 * torch.finfo(torch.float32).eps * (
expert_gross[None]
* (batch_returns[:, None, None].abs() + batch_costs[:, None, None])
).sum(dim=(-1, -2))
batch_band = (
expert_gross[None] * data.numerical_band[batch, 1, None, None]
).sum(dim=(-1, -2)) + accumulation
band[start:stop] = batch_band.cpu().double().numpy()
if cone_lower is not None:
assert (
data.option_price is not None
and data.delta is not None
and data.cash_strike is not None
and data.spot is not None
)
flat_action = (
expert_action[..., 0, :, :] - expert_action[..., 1, :, :]
).reshape(num_notionals * partitions, *expert_action.shape[-2:])
heads = num_notionals * partitions
flat_lower = torch.empty(
(batch.numel(), heads),
dtype=expert_action.dtype,
device=expert_action.device,
)
for head_start in range(0, heads, 16):
head_stop = min(head_start + 16, heads)
selected_action = flat_action[None, head_start:head_stop].expand(
batch.numel(), -1, -1, -1
)
selected_spot = data.spot[batch, 1, None].expand(
-1, head_stop - head_start
)
selected_option = data.option_price[
batch, 1, None
].expand(-1, head_stop - head_start, -1, -1)
values, tail_slope = payoff_cone_values(
selected_action,
spot=selected_spot,
option_price=selected_option,
delta=data.delta[batch, 1, None].expand_as(selected_option),
cash_strike=data.cash_strike[batch, 1, None].expand_as(
selected_option
),
costs=data.costs[batch, 1, None].expand_as(selected_action),
hedge="raw",
)
slope_tolerance = (
32.0
* torch.finfo(expert_action.dtype).eps
* selected_action.abs().sum(dim=-1)
)
expiry_lower = values.amin(dim=-1)
expiry_lower = torch.where(
tail_slope >= -slope_tolerance,
expiry_lower,
torch.full_like(expiry_lower, -torch.inf),
)
flat_lower[:, head_start:head_stop] = expiry_lower.sum(dim=-1)
cone_lower[start:stop] = (
flat_lower.reshape(batch.numel(), num_notionals, partitions)
.cpu()
.double()
.numpy()
)
weight = data.path_weight[indices].cpu().double().numpy()
component = data.component[indices].cpu().numpy()
total_weight = weight.sum()
reports: list[list[dict[str, Any]]] = []
for notional_index, notional in enumerate(notionals):
by_partition: list[dict[str, Any]] = []
for partition in range(partitions):
selected = assignment[:, notional_index] == partition
selected_paths = int(selected.sum())
if selected_paths == 0:
by_partition.append(
{
"partition": partition,
"paths": 0,
"physical_mass": 0.0,
"physical_ESS": 0.0,
"numerically_nonnegative": False,
}
)
continue
local_weight = weight[selected]
normalized_weight = local_weight / local_weight.sum()
value = pnl[selected, notional_index, partition]
tolerance = band[selected, notional_index, partition]
loss = value < -tolerance
gain = value > tolerance
scaled = notional * value
log_marginal = np.where(
scaled > 0.0,
-scaled,
np.log1p(-np.minimum(scaled, 0.0)),
)
log_density = np.log(local_weight) + log_marginal
log_density -= logsumexp(log_density)
derivative, derivative_error = _weighted_mean_error(
value, np.exp(log_density)
)
mean, mean_error = _weighted_mean_error(value, normalized_weight)
loss_probability, loss_error = _weighted_mean_error(
loss.astype(np.float64), normalized_weight
)
by_partition.append(
{
"partition": partition,
"paths": selected_paths,
"direct_P_paths": int(np.sum(component[selected] == 0)),
"physical_mass": float(local_weight.sum() / total_weight),
"physical_ESS": float(
np.square(local_weight.sum()) / np.square(local_weight).sum()
),
"P_mean_unit_pnl": mean,
"P_mean_unit_pnl_standard_error": mean_error,
"P_loss_probability": loss_probability,
"P_loss_probability_standard_error": loss_error,
"proposal_loss_count": int(loss.sum()),
"direct_P_loss_count": int(
np.sum(loss & (component[selected] == 0))
),
"P_gain_probability": _weighted_mean_error(
gain.astype(np.float64), normalized_weight
)[0],
"proposal_minimum_unit_pnl_plus_band": float(
np.min(value + tolerance)
),
"numerically_nonnegative": bool(np.all(~loss)),
"normalized_notional_derivative": derivative,
"normalized_notional_derivative_standard_error": (
derivative_error
),
"exact_payoff_cone": (
None
if cone_lower is None
else {
"unbounded_below_path_count": int(
np.sum(
~np.isfinite(
cone_lower[
selected, notional_index, partition
]
)
)
),
"nonnegative_path_count": int(
np.sum(
cone_lower[
selected, notional_index, partition
]
>= -tolerance
)
),
"strict_nonnegative_path_count": int(
np.sum(
cone_lower[
selected, notional_index, partition
]
>= 0.0
)
),
"maximum_finite_lower_bound": _finite_maximum_or_none(
cone_lower[selected, notional_index, partition]
),
"P_numerically_nonnegative_probability": (
_weighted_mean_error(
(
cone_lower[
selected, notional_index, partition
]
>= -tolerance
).astype(np.float64),
normalized_weight,
)[0]
),
"all_selected_paths_nonnegative": bool(
np.all(
cone_lower[
selected, notional_index, partition
]
>= -tolerance
)
),
}
),
}
)
reports.append(by_partition)
return {
"definition": (
"for each notional and learned partition, trade its unit-gross local "
"direction only when that partition has the largest state-only router "
"probability; all other states hold zero"
),
"by_notional_and_partition": reports,
}
@torch.no_grad()
def _evaluate(
model: DirectionModel,
data: DeviceExpiryCase,
indices: Tensor,
notionals: tuple[float, ...],
*,
batch_size: int,
objective: str,
evaluation_notionals: tuple[float, ...] | None = None,
audit_buckets: int | None = None,
bucket_seed: int = 0,
) -> dict[str, Any]:
paths = int(indices.numel())
num_notionals = len(notionals)
pnl = np.empty((paths, num_notionals, 2), dtype=np.float64)
band = np.empty_like(pnl)
gross = np.empty_like(pnl)
exact_lower = (
np.empty_like(pnl) if data.option_price is not None else None
)
exact_slope_ok = (
np.empty(pnl.shape, dtype=np.bool_) if data.option_price is not None else None
)
responsibility: np.ndarray | None = None
if isinstance(model, LearnedPartitionDirections):
responsibility = np.empty(
(paths, num_notionals, model.config.partitions), dtype=np.float32
)
for start in range(0, paths, batch_size):
stop = min(paths, start + batch_size)
batch = indices[start:stop]
if isinstance(model, LearnedPartitionDirections):
action, batch_responsibility, _ = model(data.state[batch, 1])
assert responsibility is not None
responsibility[start:stop] = batch_responsibility.cpu().numpy()
else:
action, _ = model(data.state[batch, 1])
pnl[start:stop] = _parallel_pnl(
action,
data.returns[batch],
data.costs[batch],
portfolio_barrier_rate=data.portfolio_barrier_rate,
).cpu().double().numpy()
gross_action = (
(action[..., 0, :, :] - action[..., 1, :, :]).abs()
if data.portfolio_barrier_rate is not None
else action[..., 0, :, :] + action[..., 1, :, :]
)
gross[start:stop] = gross_action.sum(
dim=(-1, -2)
).cpu().double().numpy()
band[start:stop] = _parallel_band(
action,
data.returns[batch],
data.costs[batch],
data.numerical_band[batch],
portfolio_barrier_rate=data.portfolio_barrier_rate,
).cpu().double().numpy()
exact = _exact_expiry_lower_bound(action, data, batch)
if exact is not None:
assert exact_lower is not None and exact_slope_ok is not None
batch_lower, batch_slope_ok = exact
exact_lower[start:stop] = batch_lower.cpu().double().numpy()
exact_slope_ok[start:stop] = batch_slope_ok.cpu().numpy()
weight = data.path_weight[indices].cpu().double().numpy()
normalized_weight = weight / weight.sum()
component = data.component[indices].cpu().numpy()
direct = component == 0
use_oce_translation = objective == "oce-powerexp"
learned_translation = (
model.oce_translation.detach().cpu().double().numpy()
if use_oce_translation
else np.zeros((num_notionals, 2), dtype=np.float64)
)
assert learned_translation.shape == (num_notionals, 2)
by_notional: list[dict[str, Any]] = []
for notional_index, notional in enumerate(notionals):
by_time: list[dict[str, Any]] = []
for time_index, name in enumerate(("t0_deterministic", "t6_conditional")):
value = pnl[:, notional_index, time_index]
tolerance = band[:, notional_index, time_index]
loss = value < -tolerance
gain = value > tolerance
translation = float(learned_translation[notional_index, time_index])
learned_statistics = _oce_numpy_statistics(
value,
weight,
notional,
translation,
)
recalibrated_translation = (
_recalibrate_oce_translation(value, normalized_weight, notional)
if use_oce_translation
else 0.0
)
recalibrated_statistics = _oce_numpy_statistics(
value,
weight,
notional,
recalibrated_translation,
)
mean, mean_error = _weighted_mean_error(value, normalized_weight)
loss_probability, loss_error = _weighted_mean_error(
loss.astype(np.float64), normalized_weight
)
marginal_weight = learned_statistics["marginal_weight"]
assert isinstance(marginal_weight, np.ndarray)
by_time.append(
{
"name": name,
"objective": learned_statistics["objective"],
"objective_standard_error": learned_statistics[
"objective_standard_error"
],
"learned_oce_translation": (
translation if use_oce_translation else None
),
"learned_oce_translation_first_order_condition": (
learned_statistics["translation_first_order_condition"]
if use_oce_translation
else None
),
"recalibrated_oce_translation": (
recalibrated_translation if use_oce_translation else None
),
"recalibrated_oce_objective": (
recalibrated_statistics["objective"]
if use_oce_translation
else None
),
"recalibrated_oce_translation_first_order_condition": (
recalibrated_statistics[
"translation_first_order_condition"
]
if use_oce_translation
else None
),
"recalibrated_normalized_notional_derivative": (
recalibrated_statistics["normalized_notional_derivative"]
if use_oce_translation
else None
),
"recalibrated_normalized_notional_derivative_standard_error": (
recalibrated_statistics[
"normalized_notional_derivative_standard_error"
]
if use_oce_translation
else None
),
"P_mean_unit_pnl": mean,
"P_mean_unit_pnl_standard_error": mean_error,
"P_loss_probability": loss_probability,
"P_loss_probability_standard_error": loss_error,
"P_gain_probability": _weighted_mean_error(
gain.astype(np.float64), normalized_weight
)[0],
"P_mean_gross_activity": _weighted_mean_error(
gross[:, notional_index, time_index], normalized_weight
)[0],
"P_gross_activity_01_quantile": weighted_quantile(
gross[:, notional_index, time_index], weight, 0.01
),
"P_gross_activity_median": weighted_quantile(
gross[:, notional_index, time_index], weight, 0.50
),
"P_gross_activity_99_quantile": weighted_quantile(
gross[:, notional_index, time_index], weight, 0.99
),
"activity_threshold_audit": _activity_threshold_report(
value,
tolerance,
gross[:, notional_index, time_index],
weight,
direct,
notional=notional,
use_oce_translation=use_oce_translation,
exact_lower=(
None
if exact_lower is None
else exact_lower[:, notional_index, time_index]
),
),
"P_unit_pnl_01_quantile": weighted_quantile(
value, weight, 0.01
),
"P_unit_pnl_05_quantile": weighted_quantile(
value, weight, 0.05
),
"P_unit_pnl_median": weighted_quantile(value, weight, 0.50),
"proposal_minimum_unit_pnl_plus_band": float(
np.min(value + tolerance)
),
"proposal_numerically_nonnegative": bool(np.all(~loss)),
"direct_P_loss_count": int(np.sum(loss & direct)),
"direct_P_gain_count": int(np.sum(gain & direct)),
"normalized_notional_derivative": learned_statistics[
"normalized_notional_derivative"
],
"normalized_notional_derivative_standard_error": (
learned_statistics[
"normalized_notional_derivative_standard_error"
]
),
"marginal_density_effective_sample_size": float(
1.0 / np.square(marginal_weight).sum()
),
"exact_payoff_cone": (
None
if exact_lower is None
else {
"unbounded_below_path_count": int(
np.sum(
~np.isfinite(
exact_lower[
:, notional_index, time_index
]
)
)
),
"minimum_finite_lower_bound": (
None
if not np.any(
np.isfinite(
exact_lower[
:, notional_index, time_index
]
)
)
else float(
np.min(
exact_lower[
:, notional_index, time_index
][
np.isfinite(
exact_lower[
:, notional_index, time_index
]
)
]
)
)
),
"nonnegative_path_count": int(
np.sum(
exact_lower[:, notional_index, time_index]
>= -band[:, notional_index, time_index]
)
),
"strict_nonnegative_path_count": int(
np.sum(
exact_lower[:, notional_index, time_index]
>= 0.0
)
),
"maximum_finite_lower_bound": _finite_maximum_or_none(
exact_lower[:, notional_index, time_index]
),
"P_numerically_nonnegative_probability": (
_weighted_mean_error(
(
exact_lower[
:, notional_index, time_index
]
>= -band[
:, notional_index, time_index
]
).astype(np.float64),
normalized_weight,
)[0]
),
"direct_P_nonnegative_path_count": int(
np.sum(
(
exact_lower[:, notional_index, time_index]
>= -band[:, notional_index, time_index]
)
& direct
)
),
"all_expiry_tail_slopes_valid_count": int(
np.sum(
exact_slope_ok[
:, notional_index, time_index
]
)
),
}
),
}
)
by_notional.append({"notional": notional, "times": by_time})
evaluation_notionals = (
notionals if evaluation_notionals is None else evaluation_notionals
)
cross_objective: list[list[list[float]]] = []
cross_derivative: list[list[list[float]]] = []
cross_derivative_error: list[list[list[float]]] = []
for direction_index in range(num_notionals):
by_scale: list[list[float]] = []
derivative_by_scale: list[list[float]] = []
derivative_error_by_scale: list[list[float]] = []
for scale in evaluation_notionals:
scale_objective: list[float] = []
scale_derivative: list[float] = []
scale_derivative_error: list[float] = []
for time_index in range(2):
value = pnl[:, direction_index, time_index]
translation = (
_recalibrate_oce_translation(
value,
normalized_weight,
scale,
)
if use_oce_translation
else 0.0
)
statistics = _oce_numpy_statistics(
value,
weight,
scale,
translation,
)
scale_objective.append(float(statistics["objective"]))
scale_derivative.append(
float(statistics["normalized_notional_derivative"])
)
scale_derivative_error.append(
float(
statistics[
"normalized_notional_derivative_standard_error"
]
)
)
by_scale.append(scale_objective)
derivative_by_scale.append(scale_derivative)
derivative_error_by_scale.append(scale_derivative_error)
cross_objective.append(by_scale)
cross_derivative.append(derivative_by_scale)
cross_derivative_error.append(derivative_error_by_scale)
partition: dict[str, Any] | None = None
if responsibility is not None:
weighted_responsibility = normalized_weight[:, None, None] * responsibility
mass = weighted_responsibility.sum(axis=0)
local_weight = weighted_responsibility / np.maximum(
mass[None], np.finfo(np.float64).tiny
)
entropy = -np.sum(
responsibility * np.log(np.maximum(responsibility, np.finfo(np.float32).tiny)),
axis=-1,
)
partition = {
"physical_mass_by_notional_and_partition": mass.tolist(),
"physical_ESS_by_notional_and_partition": (
1.0 / np.square(local_weight).sum(axis=0)
).tolist(),
"mean_router_entropy_by_notional": np.sum(
normalized_weight[:, None] * entropy, axis=0
).tolist(),
"effective_soft_partition_count_by_notional": np.exp(
np.sum(normalized_weight[:, None] * entropy, axis=0)
).tolist(),
}
candidates = None
if isinstance(model, LearnedPartitionDirections):
candidates = _evaluate_partition_candidates(
model,
data,
indices,
notionals,
batch_size=batch_size,
)
bucket_audit = None
if audit_buckets is not None:
assignment = _stratified_bucket_assignment(
data,
indices,
buckets=audit_buckets,
seed=bucket_seed,
).cpu().numpy()
bucket_audit = {
"definition": (
"fixed buckets balanced by physical probability mass within each "
"importance-sampling component; all reported moments use normalized "
"physical weights within each bucket"
),
"buckets": audit_buckets,
"seed": bucket_seed,
**_bucket_pnl_audit(
pnl,
weight,
assignment,
buckets=audit_buckets,
),
}
return {
"paths": paths,
"direct_P_paths": int(direct.sum()),
"physical_weight_effective_sample_size": float(
np.square(weight.sum()) / np.square(weight).sum()
),
"by_notional": by_notional,
"cross_objective_definition": (
"[direction_notional_index][evaluation_notional_index][time_index]; "
+ (
"the scalar OCE translation is recalibrated separately for every "
"evaluation notional and sample set"
if use_oce_translation
else "no OCE translation"
)
),
"cross_objective_evaluation_notionals": list(evaluation_notionals),
"cross_objective": cross_objective,
"cross_normalized_notional_derivative": cross_derivative,
"cross_normalized_notional_derivative_standard_error": (
cross_derivative_error
),
"partition": partition,
"hard_partition_candidates": candidates,
"bucket_audit": bucket_audit,
}
[docs]
def run(args: argparse.Namespace) -> dict[str, Any]:
verify_inp(
args.objective != "bucket-downside2"
or args.architecture in {"feedforward", "gated-feedforward", "kernel"},
"bucket-downside2 is defined for feed-forward and kernel architectures",
)
verify_inp(
args.objective != "oce-powerexp" or args.architecture != "partition",
"oce-powerexp is defined for feed-forward and kernel architectures",
)
verify_inp(
isinstance(args.buckets, int) and 1 < args.buckets <= args.batch_size,
lambda: f"invalid bucket count {args.buckets} for batch {args.batch_size}",
)
verify_inp(
math.isfinite(args.gain_tiebreak) and args.gain_tiebreak >= 0.0,
lambda: f"invalid gain tie-break {args.gain_tiebreak}",
)
verify_inp(
math.isfinite(args.bucket_temperature) and args.bucket_temperature >= 0.0,
lambda: f"invalid bucket temperature {args.bucket_temperature}",
)
vector_barrier = args.portfolio_convention == "itm-dollar-vector-barrier"
itm_dollar = args.portfolio_convention in {
"itm-dollar-linear-cost",
"itm-dollar-vector-barrier",
}
verify_inp(
not vector_barrier
or (
args.return_horizon == "expiry"
and args.hedge == "raw"
and args.architecture != "partition"
and args.cost_bps > 0.0
),
(
"ITM dollar vector-barrier experiments require raw expiry returns, "
"a positive cost rate, and a non-partition architecture"
),
)
verify_inp(
math.isfinite(args.barrier_interior_epsilon)
and 0.0 < args.barrier_interior_epsilon < 0.1,
lambda: (
"barrier interior epsilon must lie in (0,0.1), got "
f"{args.barrier_interior_epsilon!r}"
),
)
initialization_report: dict[str, Any] | None = None
initialization_id = ""
if args.initialize_report:
initialization_path = Path(args.initialize_report)
initialization_report = json.loads(
initialization_path.read_text(encoding="utf-8")
)
initialization_report["report_path"] = str(initialization_path)
verify_inp(
args.architecture == "gated-feedforward",
"direction initialization is only valid for gated-feedforward",
)
initialization_id = Path(initialization_report["checkpoint"]).stem.split()[-1]
verify_inp(
not args.freeze_initialized_direction or initialization_report is not None,
"freezing an initialized direction requires --initialize-report",
)
notionals = tuple(float(value) for value in args.notionals)
audit_notionals = (
tuple(float(value) for value in args.audit_notionals)
if args.audit_notionals
else None
)
verify_inp(
audit_notionals is None
or (
all(math.isfinite(value) and value > 0.0 for value in audit_notionals)
and all(
left < right
for left, right in zip(audit_notionals, audit_notionals[1:])
)
),
lambda: f"audit notionals must be finite-positive and increasing: {audit_notionals}",
)
case = RequiredCase(
generator=args.generator,
trading_frequency=args.frequency,
return_horizon=args.return_horizon,
hedge=args.hedge,
cost_rate=args.cost_bps * 1.0e-4,
path_count=args.paths,
)
loaded = _load_case(
case,
cache_root=Path(args.cache_root),
need_primitives=args.return_horizon == "expiry",
)
source_cache = str(loaded.source_cache)
source_cache_uid = loaded.source_cache_uid
if initialization_report is not None:
verify_inp(
initialization_report.get("source_cache_uid") == source_cache_uid
and initialization_report.get("fold", {}).get("fold") == args.fold,
"direction initialization must use the same universe and reciprocal fold",
)
env = BaseEnvironment(
precision=args.precision, device=args.device, debug=args.debug
)
full_data, source_split = _to_device(loaded, case=case, env=env)
del loaded
gc.collect()
data, fold_diagnostics = _select_times_and_fold(
full_data,
deterministic_time=0,
conditional_time=6,
fold=args.fold,
seed=args.split_seed,
)
del full_data
portfolio_normalization = None
if vector_barrier:
data, portfolio_normalization = _to_itm_dollar_vector_barrier(
data,
cost_rate=case.cost_rate,
)
elif itm_dollar:
data, portfolio_normalization = _to_itm_dollar_portfolio(
data,
cost_rate=case.cost_rate,
vector_barrier=False,
)
torch.manual_seed(args.seed)
if torch.device(env.device).type == "cuda":
torch.cuda.manual_seed_all(args.seed)
torch.cuda.reset_peak_memory_stats(env.device)
horizon_label = "period" if args.return_horizon == "incremental" else "expiry"
default_notionals = (1.0, 2.0, 4.0, 8.0, 16.0, 32.0, 64.0, 128.0, 256.0)
notional_label = ""
if notionals != default_notionals:
notional_label = "-n-" + "-".join(f"{value:g}" for value in notionals)
partition_label = ""
if args.architecture == "partition" and args.partitions != 16:
partition_label = f"-k-{args.partitions}"
if args.architecture == "kernel":
partition_label = f"-bounded-learned-k-{args.kernels}"
objective_label = "" if args.objective == "powerexp" else f"-{args.objective}"
if args.objective == "bucket-downside2":
objective_label += (
f"-balanced-m-{args.buckets}-g-{args.gain_tiebreak:g}"
f"-tau-{args.bucket_temperature:g}"
)
label = (
f"parallel-directions-{args.generator}-{args.frequency}-{horizon_label}-"
f"{args.hedge}-{args.cost_bps:g}bps-{args.paths}-{args.architecture}-"
f"fold-{args.fold}"
f"{partition_label}{objective_label}{notional_label}"
)
if vector_barrier:
label += "-itm-dollar-vector-barrier"
elif itm_dollar:
label += "-itm-dollar-linear-cost"
if initialization_report is not None:
label += f"-init-{initialization_id}"
if args.freeze_initialized_direction:
label += "-freeze-direction"
config = ParallelDirectionConfig(
label=label,
source_cache_uid=source_cache_uid,
architecture=args.architecture,
state_features=data.state.shape[-1],
notionals=notionals,
partitions=args.partitions,
kernels=args.kernels,
learn_oce_translation=args.objective == "oce-powerexp",
action_radius=(
1.0 - args.barrier_interior_epsilon if vector_barrier else 1.0
),
group=(
"gendysanos/parallel-direction-comparison/"
f"{args.generator}/{args.frequency}/{args.architecture}/"
f"{args.cost_bps:g}bps/fold-{args.fold}"
),
user_version=args.user_version,
)
state_mean, state_whitener, whitening = fit_physical_state_whitener(
data.state,
data.path_weight,
data.reference,
relative_eigenvalue_floor=args.covariance_relative_floor,
)
kernel_basis = None
if args.architecture == "partition":
model: DirectionModel = (
LearnedPartitionDirections(
env,
config=config,
state_mean=state_mean[1],
state_whitener=state_whitener[1],
)
)
elif args.architecture == "gated-feedforward":
model = GatedParallelFeedForwardDirections(
env,
config=config,
state_mean=state_mean[1],
state_whitener=state_whitener[1],
)
elif args.architecture == "kernel":
centers, inverse_bandwidth, kernel_basis = _fit_kernel_basis(
data,
state_mean=state_mean[1],
state_whitener=state_whitener[1],
kernels=args.kernels,
seed=args.seed,
)
model = ParallelKernelDirections(
env,
config=config,
state_mean=state_mean[1],
state_whitener=state_whitener[1],
centers=centers,
inverse_bandwidth=inverse_bandwidth,
)
else:
model = ParallelFeedForwardDirections(
env,
config=config,
state_mean=state_mean[1],
state_whitener=state_whitener[1],
)
initialization = (
_initialize_gated_direction_from_report(model, initialization_report)
if isinstance(model, GatedParallelFeedForwardDirections)
and initialization_report is not None
else None
)
if args.freeze_initialized_direction:
assert isinstance(model, GatedParallelFeedForwardDirections)
for parameter in model.conditional.parameters():
parameter.requires_grad_(False)
assert all(parameter.requires_grad for parameter in model.gate.parameters())
assert initialization is not None
initialization["direction_frozen_during_training"] = True
notionals_tensor = torch.as_tensor(
notionals, dtype=env.fdtype, device=env.device
)
callable_model = torch.compile(model, dynamic=False) if not args.no_compile else model
checkpoint_path = Path(args.checkpoint_root) / config.group / f"{config.filename}.pt"
checkpoint_lock = FileLock(f"{checkpoint_path}.lock")
with checkpoint_lock:
training = _train(
model,
callable_model,
data,
notionals_tensor,
checkpoint_path=checkpoint_path,
batch_size=args.batch_size,
valuation_batch_size=args.valuation_batch_size,
epochs=args.epochs,
value_update=args.value_update,
checkpoint_update=args.checkpoint_update,
lr=args.lr,
seed=args.seed,
balance_coefficient=args.balance_coefficient,
objective=args.objective,
buckets=args.buckets,
gain_tiebreak=args.gain_tiebreak,
bucket_temperature=args.bucket_temperature,
)
training_set = _evaluate(
model,
data,
data.reference,
notionals,
batch_size=args.valuation_batch_size,
objective=args.objective,
evaluation_notionals=(
audit_notionals
),
audit_buckets=(args.buckets if args.objective == "bucket-downside2" else None),
bucket_seed=args.seed + 20_000,
)
validation_set = _evaluate(
model,
data,
data.validation,
notionals,
batch_size=args.valuation_batch_size,
objective=args.objective,
evaluation_notionals=(
audit_notionals
),
audit_buckets=(args.buckets if args.objective == "bucket-downside2" else None),
bucket_seed=args.seed + 30_000,
)
fitted_kernel = None
if isinstance(model, ParallelKernelDirections):
with torch.no_grad():
fitted_inverse_bandwidth = torch.exp(model.log_inverse_bandwidth)
fitted_kernel = {
"definition": (
"physical-weighted K-means initializes z_k and w_k; both are "
"subsequently learned jointly with the local directions"
),
"center_root_mean_square_displacement": float(
torch.sqrt(
torch.mean((model.centers - model.initial_centers).square())
).cpu()
),
"minimum_inverse_bandwidth": float(
fitted_inverse_bandwidth.min().cpu()
),
"median_inverse_bandwidth": float(
fitted_inverse_bandwidth.median().cpu()
),
"maximum_inverse_bandwidth": float(
fitted_inverse_bandwidth.max().cpu()
),
}
report = {
"status": "complete",
"schema_version": "1.2" if vector_barrier else "1.1",
"experiment": (
"independent fixed-notional conditional directions trained in parallel"
),
"definition": {
"objective": (
(
"OCE power-exp lambda=1: sup_y E[u(y+n*pi)]-y, with one "
"learned real y per independent (n,trading-time) portfolio; "
"after action training each y is solved exactly on the full "
"training half before validation"
if args.objective == "oce-powerexp"
else "power-exp lambda=1 applied to n times unit-gross net P&L"
)
if args.objective in {"powerexp", "oce-powerexp"}
else (
(
"negative worst fixed-bucket physical expected squared "
"downside, with a full-sample positive-gain tie-break"
if args.objective == "bucket-downside2"
else (
"negative physical expected squared downside of "
"unit-gross net P&L"
)
)
+ "; the repeated heads are independent cold restarts"
)
),
"action": (
(
"the signed net action is an entry-value dollar portfolio; "
"its L1 norm is strictly below one and one logarithmic barrier "
"is applied to that full vector"
if vector_barrier
else (
(
"the signed action is an entry-value dollar portfolio "
"with separate nonnegative long/short parameters"
if itm_dollar
else (
"separate nonnegative long/short positions; gross sum "
"is at most one for kernel and gated-feedforward, and "
"exactly one for the other direction-only architectures"
)
)
)
)
),
"notional_independence": (
"every notional has cold-started parameters and no gradient sharing"
),
"OCE_validation": (
"the action and training y are frozen on validation; the report also "
"recalibrates one scalar y on each sample set for a proper fixed-action "
"OCE valuation"
if args.objective == "oce-powerexp"
else None
),
"partition": (
"state-only learned soft router; local direction objectives are summed "
"and physical partition masses are regularized towards equal mass"
),
"validation": (
"the entire fitted action is frozen and evaluated on the reciprocal half"
),
},
"configuration": asdict(case),
"source_cache": source_cache,
"source_cache_uid": source_cache_uid,
"source_split_ignored_for_this_experiment": source_split,
"fold": fold_diagnostics,
"portfolio_normalization": portfolio_normalization,
"model_config": asdict(config),
"training_configuration": {
"batch_size": args.batch_size,
"valuation_batch_size": args.valuation_batch_size,
"epochs": args.epochs,
"lr": args.lr,
"compile": not args.no_compile,
"seed": args.seed,
"balance_coefficient": args.balance_coefficient,
"optimization_objective": args.objective,
"buckets": args.buckets if args.objective == "bucket-downside2" else None,
"bucket_construction": (
"fixed training-fold buckets balanced by physical probability mass "
"within each importance component; every minibatch draws equally "
"from every bucket"
if args.objective == "bucket-downside2"
else None
),
"gain_tiebreak": args.gain_tiebreak,
"bucket_relative_temperature": args.bucket_temperature,
"freeze_initialized_direction": args.freeze_initialized_direction,
},
"initialization": initialization,
"whitening": whitening,
"kernel_basis": kernel_basis,
"fitted_kernel": fitted_kernel,
"training": training,
"training_set": training_set,
"validation_set": validation_set,
"checkpoint": str(checkpoint_path),
"device": str(env.device),
"peak_gpu_memory_bytes": (
int(torch.cuda.max_memory_allocated(env.device))
if torch.device(env.device).type == "cuda"
else 0
),
}
audit_label = ""
if audit_notionals:
audit_label = "-audit-n-" + "-".join(
f"{value:g}" for value in audit_notionals
)
report_path = Path(args.output_root) / f"{config.label}{audit_label}.json"
_atomic_json(report_path, report)
print(f"Completed parallel-direction report {report_path}", flush=True)
return report
def _parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--generator", choices=("pca-iv", "dysanos"), default="pca-iv")
parser.add_argument("--frequency", choices=("daily", "weekly"), default="weekly")
parser.add_argument("--paths", type=int, choices=(100_000, 1_000_000), default=100_000)
parser.add_argument(
"--architecture",
choices=("feedforward", "gated-feedforward", "kernel", "partition"),
required=True,
)
parser.add_argument("--fold", type=int, choices=(0, 1), required=True)
parser.add_argument("--cost-bps", type=float, choices=(0.0, 1.0, 10.0), required=True)
parser.add_argument("--hedge", choices=("raw", "delta"), default="raw")
parser.add_argument(
"--return-horizon", choices=("incremental", "expiry"), default="incremental"
)
parser.add_argument(
"--objective",
choices=("powerexp", "oce-powerexp", "downside2", "bucket-downside2"),
default="powerexp",
)
parser.add_argument(
"--portfolio-convention",
choices=("native", "itm-dollar-linear-cost", "itm-dollar-vector-barrier"),
default="native",
)
parser.add_argument("--barrier-interior-epsilon", type=float, default=1.0e-5)
parser.add_argument("--device", choices=("cpu", "cuda:0", "cuda:1", "cuda:2"), required=True)
parser.add_argument("--precision", type=int, choices=(32, 64), default=32)
parser.add_argument("--partitions", type=int, default=16)
parser.add_argument("--kernels", type=int, default=64)
parser.add_argument(
"--notionals",
type=float,
nargs="+",
default=[1.0, 2.0, 4.0, 8.0, 16.0, 32.0, 64.0, 128.0, 256.0],
)
parser.add_argument("--audit-notionals", type=float, nargs="+")
parser.add_argument("--epochs", type=int, default=20_000)
parser.add_argument("--batch-size", type=int, default=4_096)
parser.add_argument("--valuation-batch-size", type=int, default=16_384)
parser.add_argument("--value-update", type=int, default=500)
parser.add_argument("--checkpoint-update", type=int, default=2_000)
parser.add_argument("--lr", type=float, default=3.0e-4)
parser.add_argument("--balance-coefficient", type=float, default=1.0)
parser.add_argument("--buckets", type=int, default=32)
parser.add_argument("--gain-tiebreak", type=float, default=1.0e-8)
parser.add_argument("--bucket-temperature", type=float, default=0.0)
parser.add_argument("--initialize-report")
parser.add_argument("--freeze-initialized-direction", action="store_true")
parser.add_argument("--covariance-relative-floor", type=float, default=1.0e-10)
parser.add_argument("--seed", type=int, default=182_071)
parser.add_argument("--split-seed", type=int, default=100_097)
parser.add_argument("--user-version", default="0.1")
parser.add_argument("--cache-root", default=str(_DEFAULT_CACHE_ROOT))
parser.add_argument("--output-root", default=str(_DEFAULT_OUTPUT_ROOT))
parser.add_argument("--checkpoint-root", default=str(_DEFAULT_CHECKPOINT_ROOT))
parser.add_argument("--no-compile", action="store_true")
parser.add_argument("--debug", action="store_true")
return parser
if __name__ == "__main__":
run(_parser().parse_args())