"""Continuous total-variance interpolation for direct PCA IV surfaces."""
from __future__ import annotations
import math
from dataclasses import dataclass
import numpy as np
from cdxcore.bs import bs
from cdxcore.err import verify_inp
from cdxcore.version import version
from quantdata.biz_calendar import NMS, NormalizedStrikes
from .pca import LogIVPCA
[docs]
@dataclass(frozen=True, kw_only=True)
class WingHitDiagnostics:
"""Counts of flat normalized-moneyness extrapolation."""
queries: int
left_hits: int
right_hits: int
@property
def total_hits(self) -> int:
return self.left_hits + self.right_hits
@property
def hit_fraction(self) -> float:
return self.total_hits / self.queries if self.queries else 0.0
def __add__(self, other: WingHitDiagnostics) -> WingHitDiagnostics:
return WingHitDiagnostics(
queries=self.queries + other.queries,
left_hits=self.left_hits + other.left_hits,
right_hits=self.right_hits + other.right_hits,
)
def _linear_flat(
x_grid: np.ndarray,
values: np.ndarray,
query: np.ndarray,
) -> np.ndarray:
"""Vectorized linear interpolation with flat endpoint extrapolation."""
verify_inp(
x_grid.ndim == 1
and values.ndim == 2
and values.shape[1] == x_grid.size
and query.ndim == 2
and query.shape[0] == values.shape[0],
lambda: (
"invalid interpolation geometry "
f"{x_grid.shape}/{values.shape}/{query.shape}"
),
)
right = np.searchsorted(x_grid, query, side="right")
right = np.clip(right, 1, x_grid.size - 1)
left = right - 1
row = np.arange(values.shape[0])[:, None]
x_left = x_grid[left]
x_right = x_grid[right]
weight = (query - x_left) / (x_right - x_left)
output = values[row, left] + weight * (
values[row, right] - values[row, left]
)
output = np.where(query <= x_grid[0], values[:, :1], output)
output = np.where(query >= x_grid[-1], values[:, -1:], output)
return output
[docs]
@version("0.1", dependencies=[LogIVPCA])
class PCATotalVarianceDecoder:
"""Decode and interpolate a PCA state as a fixed-surface price map.
Total variance is linearly interpolated first in normalized moneyness and
then in maturity after adding ``w(0,z)=0``. The normalized-moneyness wings
are flat. Maturities outside ``[0, max(training_expiry)]`` are rejected.
Relative strikes use :class:`NormalizedStrikes` with the interpolated ATM
volatility at the query maturity. The epsilon-volatility scale is the ATM
volatility at the shortest decoded expiry, matching how the historical
regular grid is constructed.
"""
def __init__(
self,
pca: LogIVPCA,
*,
normalized_strikes: NormalizedStrikes | None = None,
) -> None:
self.pca = pca
self.normalized_strikes = (
NormalizedStrikes(EPS=NMS.EPS, SCALE=NMS.SCALE)
if normalized_strikes is None
else normalized_strikes
)
verify_inp(
isinstance(self.normalized_strikes, NormalizedStrikes),
lambda: (
"'normalized_strikes' must be a NormalizedStrikes instance, got "
f"{type(self.normalized_strikes)}"
),
)
def _scores_2d(self, scores: np.ndarray) -> tuple[np.ndarray, tuple[int, ...]]:
scores = np.asarray(scores)
verify_inp(
scores.ndim >= 1
and scores.shape[-1] == self.pca.num_components
and np.issubdtype(scores.dtype, np.floating)
and np.all(np.isfinite(scores)),
lambda: (
f"scores must be finite floating arrays ending in "
f"{self.pca.num_components}, got {scores.shape}/{scores.dtype}"
),
)
batch_shape = scores.shape[:-1]
return scores.reshape(-1, self.pca.num_components), batch_shape
@staticmethod
def _queries_2d(
values: tuple[np.ndarray | float, ...],
*,
batch_shape: tuple[int, ...],
) -> tuple[list[np.ndarray], tuple[int, ...]]:
arrays = [np.asarray(value, dtype=np.float64) for value in values]
verify_inp(
all(np.all(np.isfinite(value)) for value in arrays),
"decoder queries must be finite",
)
arrays = list(np.broadcast_arrays(*arrays))
common_shape = arrays[0].shape
batch_size = math.prod(batch_shape) if batch_shape else 1
# A query is batch-specific only when its broadcast shape contains the
# complete score-batch prefix and at least one additional query axis.
batch_specific = (
bool(batch_shape)
and len(common_shape) > len(batch_shape)
and common_shape[: len(batch_shape)] == batch_shape
)
if batch_specific:
query_shape = common_shape[len(batch_shape) :]
matrices = [value.reshape(batch_size, -1) for value in arrays]
else:
query_shape = common_shape
matrices = [
np.broadcast_to(value, (*batch_shape, *query_shape)).reshape(
batch_size, -1
)
for value in arrays
]
return matrices, query_shape
[docs]
def grid_implied_vols(self, scores: np.ndarray) -> np.ndarray:
return self.pca.decode(scores)
def _grid_total_variance(self, scores_2d: np.ndarray) -> np.ndarray:
vols = self.pca.decode(scores_2d)
return np.square(vols) * self.pca.expiries[None, :, None]
def _atm_terms(
self,
grid_total_variance: np.ndarray,
maturities: np.ndarray,
) -> tuple[np.ndarray, np.ndarray]:
"""Return query ATM vol and shortest-expiry epsilon ATM vol."""
batch_size, expiry_count, _ = grid_total_variance.shape
atm_grid = np.empty((batch_size, expiry_count), dtype=np.float64)
zero = np.zeros((batch_size, 1), dtype=np.float64)
for expiry_index in range(expiry_count):
atm_grid[:, expiry_index] = _linear_flat(
self.pca.nms[expiry_index],
grid_total_variance[:, expiry_index],
zero,
)[:, 0]
atm_w = self._interpolate_time(
np.broadcast_to(
atm_grid[:, :, None],
(batch_size, expiry_count, maturities.shape[1]),
),
maturities,
)
positive_t = maturities > 0.0
atm_vol = np.empty_like(atm_w)
atm_vol[positive_t] = np.sqrt(atm_w[positive_t] / maturities[positive_t])
shortest_atm = np.sqrt(atm_grid[:, 0] / self.pca.expiries[0])
atm_vol[~positive_t] = np.broadcast_to(shortest_atm[:, None], atm_vol.shape)[
~positive_t
]
verify_inp(
np.all(np.isfinite(atm_vol))
and np.all(atm_vol > 0.0)
and np.all(shortest_atm > 0.0),
"interpolated ATM volatility is non-finite or non-positive",
)
return atm_vol, shortest_atm[:, None]
def _interpolate_time(
self,
values: np.ndarray,
maturities: np.ndarray,
) -> np.ndarray:
"""Interpolate ``(B,T,Q)`` values from the zero anchor in maturity."""
batch_size, expiry_count, query_count = values.shape
verify_inp(
maturities.shape == (batch_size, query_count),
lambda: (
f"maturities must have shape {(batch_size, query_count)}, got "
f"{maturities.shape}"
),
)
tolerance = 64.0 * np.finfo(np.float64).eps * max(
1.0, float(self.pca.expiries[-1])
)
verify_inp(
np.all(maturities >= -tolerance)
and np.all(maturities <= self.pca.expiries[-1] + tolerance),
lambda: (
"maturities must lie inside the decoder domain "
f"[0,{self.pca.expiries[-1]:g}], got range "
f"[{np.min(maturities):g},{np.max(maturities):g}]"
),
)
maturities = np.clip(maturities, 0.0, self.pca.expiries[-1])
high = np.searchsorted(self.pca.expiries, maturities, side="left")
high = np.clip(high, 0, expiry_count - 1)
output = np.empty_like(maturities)
row, column = np.indices(maturities.shape)
high_t = self.pca.expiries[high]
high_value = values[row, high, column]
first = high == 0
low_t = np.where(first, 0.0, self.pca.expiries[np.maximum(high - 1, 0)])
low_value = np.where(first, 0.0, values[row, np.maximum(high - 1, 0), column])
weight = np.divide(
maturities - low_t,
high_t - low_t,
out=np.zeros_like(maturities),
where=high_t > low_t,
)
output[:] = low_value + weight * (high_value - low_value)
return output
[docs]
def total_variance(
self,
scores: np.ndarray,
maturities: np.ndarray | float,
normalized_moneyness: np.ndarray | float,
) -> tuple[np.ndarray, WingHitDiagnostics]:
"""Interpolate decoded total variance at arbitrary ``(T,z)`` queries."""
scores_2d, batch_shape = self._scores_2d(scores)
(maturity_2d, nms_2d), query_shape = self._queries_2d(
(maturities, normalized_moneyness),
batch_shape=batch_shape,
)
grid_w = self._grid_total_variance(scores_2d)
batch_size, expiry_count, _ = grid_w.shape
query_count = maturity_2d.shape[1]
by_expiry = np.empty(
(batch_size, expiry_count, query_count), dtype=np.float64
)
for expiry_index in range(expiry_count):
by_expiry[:, expiry_index] = _linear_flat(
self.pca.nms[expiry_index],
grid_w[:, expiry_index],
nms_2d,
)
output = self._interpolate_time(by_expiry, maturity_2d)
if not np.all(np.isfinite(output)) or np.any(output < 0.0):
raise FloatingPointError("interpolated PCA total variance is invalid")
minimum_nms = float(np.min(self.pca.nms))
maximum_nms = float(np.max(self.pca.nms))
wing_tolerance = 64.0 * np.finfo(np.float64).eps * max(
1.0, abs(minimum_nms), abs(maximum_nms)
)
diagnostics = WingHitDiagnostics(
queries=output.size,
left_hits=int(
np.count_nonzero(nms_2d < minimum_nms - wing_tolerance)
),
right_hits=int(
np.count_nonzero(nms_2d > maximum_nms + wing_tolerance)
),
)
return output.reshape(*batch_shape, *query_shape), diagnostics
[docs]
def relative_strikes_from_nms(
self,
scores: np.ndarray,
maturities: np.ndarray | float,
normalized_moneyness: np.ndarray | float,
) -> np.ndarray:
"""Convert NMS coordinates to relative strikes using decoded ATM IV."""
scores_2d, batch_shape = self._scores_2d(scores)
(maturity_2d, nms_2d), query_shape = self._queries_2d(
(maturities, normalized_moneyness), batch_shape=batch_shape
)
grid_w = self._grid_total_variance(scores_2d)
atm_vol, eps_vol = self._atm_terms(grid_w, maturity_2d)
output = self.normalized_strikes.from_nms(
z=nms_2d,
t=maturity_2d,
vol=atm_vol,
eps_vol=np.broadcast_to(eps_vol, atm_vol.shape),
)
if not np.all(np.isfinite(output)) or not np.all(output > 0.0):
raise FloatingPointError("NMS conversion produced invalid relative strikes")
return output.reshape(*batch_shape, *query_shape)
[docs]
def nms_from_relative_strikes(
self,
scores: np.ndarray,
maturities: np.ndarray | float,
relative_strikes: np.ndarray | float,
) -> np.ndarray:
"""Convert relative strikes to NMS using the decoded ATM IV."""
scores_2d, batch_shape = self._scores_2d(scores)
(maturity_2d, strike_2d), query_shape = self._queries_2d(
(maturities, relative_strikes), batch_shape=batch_shape
)
verify_inp(
np.all(strike_2d > 0.0),
"relative strikes must be strictly positive",
)
grid_w = self._grid_total_variance(scores_2d)
atm_vol, eps_vol = self._atm_terms(grid_w, maturity_2d)
output = self.normalized_strikes.to_nms(
k=strike_2d,
t=maturity_2d,
vol=atm_vol,
eps_vol=np.broadcast_to(eps_vol, atm_vol.shape),
)
if not np.all(np.isfinite(output)):
raise FloatingPointError("relative-strike conversion produced invalid NMS")
return output.reshape(*batch_shape, *query_shape)
[docs]
def implied_volatility(
self,
scores: np.ndarray,
maturities: np.ndarray | float,
relative_strikes: np.ndarray | float,
) -> tuple[np.ndarray, WingHitDiagnostics]:
"""Evaluate positive implied volatility at arbitrary fixed strikes."""
maturities_array = np.asarray(maturities, dtype=np.float64)
verify_inp(
np.all(maturities_array > 0.0),
"implied volatility is undefined at zero maturity",
)
nms = self.nms_from_relative_strikes(scores, maturities, relative_strikes)
total_variance, diagnostics = self.total_variance(scores, maturities, nms)
maturity = np.broadcast_to(maturities_array, total_variance.shape)
output = np.sqrt(total_variance / maturity)
if not np.all(np.isfinite(output)) or not np.all(output > 0.0):
raise FloatingPointError("interpolated PCA implied volatility is invalid")
return output, diagnostics
[docs]
def normalized_call_prices(
self,
scores: np.ndarray,
maturities: np.ndarray | float,
relative_strikes: np.ndarray | float,
) -> tuple[np.ndarray, WingHitDiagnostics]:
"""Price zero-rate normalized calls from the complete PCA surface."""
scores_2d, batch_shape = self._scores_2d(scores)
(maturity_2d, strike_2d), query_shape = self._queries_2d(
(maturities, relative_strikes), batch_shape=batch_shape
)
verify_inp(
np.all(maturity_2d >= 0.0) and np.all(strike_2d > 0.0),
"call maturities must be nonnegative and relative strikes positive",
)
output = np.maximum(1.0 - strike_2d, 0.0)
diagnostics = WingHitDiagnostics(queries=0, left_hits=0, right_hits=0)
positive = maturity_2d > 0.0
if np.any(positive):
nms = self.nms_from_relative_strikes(
scores_2d,
maturity_2d,
strike_2d,
).reshape(maturity_2d.shape)
total_variance, diagnostics = self.total_variance(
scores_2d,
maturity_2d,
nms,
)
total_variance = total_variance.reshape(maturity_2d.shape)
vol = np.zeros_like(total_variance)
vol[positive] = np.sqrt(total_variance[positive] / maturity_2d[positive])
output[positive] = bs(
k=strike_2d[positive],
vol=vol[positive],
sqrtT=np.sqrt(maturity_2d[positive]),
what=bs.PRICE,
)
intrinsic = np.maximum(1.0 - strike_2d, 0.0)
tolerance = 32.0 * np.finfo(output.dtype).eps * np.maximum(
1.0, np.abs(output) + np.abs(intrinsic)
)
if (
not np.all(np.isfinite(output))
or np.any(output < intrinsic - tolerance)
or np.any(output > 1.0 + tolerance)
):
raise FloatingPointError("Black--Scholes call price violates finite bounds")
return output.reshape(*batch_shape, *query_shape), diagnostics
[docs]
def cash_call_prices(
self,
scores: np.ndarray,
spots: np.ndarray | float,
maturities: np.ndarray | float,
cash_strikes: np.ndarray | float,
) -> tuple[np.ndarray, WingHitDiagnostics]:
"""Price fixed cash-strike contracts as ``S*c(T,k/S)``."""
spots = np.asarray(spots, dtype=np.float64)
cash_strikes = np.asarray(cash_strikes, dtype=np.float64)
verify_inp(
np.all(np.isfinite(spots))
and np.all(np.isfinite(cash_strikes))
and np.all(spots > 0.0)
and np.all(cash_strikes > 0.0),
"cash spots and strikes must be finite and strictly positive",
)
prices, diagnostics = self.normalized_call_prices(
scores,
maturities,
cash_strikes / spots,
)
return prices * np.broadcast_to(spots, prices.shape), diagnostics
[docs]
def cash_deltas(
self,
scores: np.ndarray,
spots: np.ndarray | float,
maturities: np.ndarray | float,
cash_strikes: np.ndarray | float,
*,
relative_step: float = 1.0e-5,
) -> tuple[np.ndarray, WingHitDiagnostics]:
"""Differentiate the complete fixed-surface cash price map centrally."""
verify_inp(
math.isfinite(relative_step) and 0.0 < relative_step < 1.0,
lambda: f"'relative_step' must lie in (0,1), got {relative_step}",
)
spots = np.asarray(spots, dtype=np.float64)
upper_spot = spots * (1.0 + relative_step)
lower_spot = spots * (1.0 - relative_step)
upper, upper_hits = self.cash_call_prices(
scores, upper_spot, maturities, cash_strikes
)
lower, lower_hits = self.cash_call_prices(
scores, lower_spot, maturities, cash_strikes
)
denominator = 2.0 * relative_step * np.broadcast_to(spots, upper.shape)
delta = (upper - lower) / denominator
if not np.all(np.isfinite(delta)):
raise FloatingPointError("fixed-surface cash delta is non-finite")
return delta, upper_hits + lower_hits
__all__ = ["PCATotalVarianceDecoder", "WingHitDiagnostics"]