Horizon valuation and terminal laws¶
fast_vollib.pnl adds European model revaluation, explicit volatility assumptions,
position Greeks and analytic profit probability under a caller-specified terminal
law. These are separate from observed quotes and executable fills. Models reuse
instruments.price_instrument and greeks_instrument; no pricing formula is
reimplemented here. Reports own read-only host arrays and do not promise gradients.
See examples/horizon_pnl.py for an executable synthetic example.
Model horizons¶
from fast_vollib.pnl import FlatVol, HorizonMarket, pnl_at_horizon
market = HorizonMarket(rate=0.03, dividend_yield=0.01, volatility=FlatVol(0.20))
profile = pnl_at_horizon(snapshot, spot_grid, horizons=(0.0, 0.01),
market=market, model="black_scholes_merton", backend="numpy",
convention="act_365", future_costs=Decimal("4"), chunk_rows=65536)
All horizons are elapsed years from the snapshot valuation time. Every live leg needs an explicitly resolved expiry instant and a named actual-day convention. Remaining maturity is the valuation-origin maturity minus the horizon. Mixed expiries are supported through the earliest live expiry inclusive; crossing that boundary or reconstructing already-expired inventory is refused. Near zero, the existing intrinsic payoff is used with a tolerance respecting the input grid precision. Zero spot is supported for intrinsic-only rows; logarithmic surface and Black forward routes refuse zero live spot or mark it invalid in diagnostic mode.
model and backend are required. Black-Scholes requires explicit zero dividend
yield; Black-Scholes-Merton requires an explicit yield. Black-76 requires a named
mapping (spot, horizon, remaining_tenor) -> forward and
discount_convention="constant_continuous_rate". Spot models use their declared
rate/yield and refuse a separate Black mapping that would be ignored. Cash remains
nominal: only option values discount from the target horizon to expiry. Paid fees
remain in cash; future close costs are subtracted once.
FlatVol(sigma) uses decimal annualized volatility. PerLegVol(by_leg_id) must
cover exactly the live leg IDs. SurfaceVol requires all of:
- An evaluable surface and explicit reference
SurfaceMarket. spot_movement="sticky_strike"or"sticky_forward_moneyness".time_movement="fixed_expiry"or"constant_tenor".- A forward mapping, reproducibility policy ID and origin spot.
Reference tenor is the origin maturity for fixed expiry, and remaining maturity
for constant tenor. Sticky strike queries log(K / F_ref(reference_tenor));
sticky forward-moneyness queries log(K / F_h(remaining_tenor; spot)). The supplied
reference market must agree with the origin forward mapping and pricing rate/carry.
Reference points are immutable and no interpolation/extrapolation policy is inferred.
ProportionalCarry(origin_spot=S0, base_forward=..., policy_id=...) explicitly
implements F_h(tau; S) = base_forward(h, tau) * S / S0. The base forward can depend
on horizon. It is never silently replaced with an origin curve at h + tau.
A proportional mapping provides its origin spot to surface assumptions; other
callables require origin_spot separately. Callables are used only for evaluation
and are never serialized. Metadata retains named policies and evaluated-input
digests, not executable models.
Pricing rows flatten as ((horizon * n_spots) + spot) * n_legs + leg.
repricing_index exposes that map. Compatible rows use unit-notional columnar
batches, then signed quantity times multiplier exactly once. chunk_rows defaults
to 65,536 and bounds working pricing rows before Cartesian allocation. Returned
full arrays still require (horizon, spot, leg) output memory. Invalid surface
cells raise in complete mode; diagnostic mode retains per-leg/aggregate masks and
unavailable totals. It never fills an invalid leg with zero.
Coherent surface sensitivity¶
pnl_at_horizon_samples(..., volatility=SurfaceVolSamples(...), market=...)
returns SurfaceSensitivityBand. For this route, pass a HorizonMarket with
volatility=None: the sampled assumption is supplied separately rather than
silently overriding a second volatility choice.
The adapter deduplicates the required union of reference (k, T) points and calls
SurfaceDistribution.sample once over that union. Model pricing is then chunked
across both sample and valuation axes. No chunk, horizon or leg is resampled.
union_point_limit defaults to 65,536; a generator's own coherent-domain limit
still applies and may be lower. If the required union cannot be supplied, the
request is refused. Intrinsic-only rows need no volatility queries.
samples has axes (surface_sample, horizon, spot, leg) and contains signed
inventory values; total adds the same nominal cash and subtracts future costs.
Sample IDs, normalized weights and original weight mass are retained. Sensitivity
quantiles use the inverse weighted empirical CDF. A cell with invalid positive
weight remains unavailable rather than silently dropping or conditioning on it.
These vary surface assumptions at fixed spots. They are not joint spot/volatility
P&L probabilities and expose no probability of profit, VaR, ES or wealth-risk summary.
plot_pnl_band returns a Figure with that qualification. export_surface_band
writes JSON/CSV and an optional supplied figure. JSON uses the strict
pnl.surface_sensitivity/1 schema; values, masks, identities, weights, listed terms
and caveats survive export. Unknown fields or result types are refused.
American contracts and the separate proxy¶
Standard pnl_at_horizon, sampled model valuation and position_greeks refuse
American live legs. european_proxy_profile requires at least one American leg and
returns EuropeanProxyProfile, retaining the source designation and this caveat:
European surrogate illustration; not an American valuation or executable close estimate; early exercise, assignment and delivery lifecycle are not modelled
european_proxy_samples returns EuropeanProxySensitivityBand. Figures distinguish
proxy curves; JSON/CSV retain the proxy type and caveat. Relabelling a serialized
proxy as a standard result is refused. Proxy curves do not produce American Greeks,
profit probabilities or validated wealth-risk measures. There is no exercise,
assignment, settlement or funding lifecycle implementation. Observed quote marks
remain a separate supported route for American options.
Position Greeks¶
position_greeks(snapshot, VanillaMarketInputs(...), model=..., backend=...,
convention=..., report_units="existing") returns per-leg and net PositionGreeks.
It uses one unit-option batch and scales by signed inventory once. Expiries must
be resolved and live; closed complete inventory has zero Greeks. Under Black,
VanillaMarketInputs.underlying explicitly means forward and delta/gamma retain
that meaning.
The existing kernels report theta per 1/365 model year, and vega/rho per 0.01
change in volatility/rate. The default preserves those outputs. Choosing
report_units="annual_unit" explicitly multiplies theta by 365 and vega/rho by 100,
with delta/gamma unchanged. Units and conversion factors are stored in the report.
The maturity day count does not silently change this reporting convention. Neither
route introduces a notional or multiplier a second time. The strict Greek codec is
pnl.position_greeks/1.
Profit under a specified terminal law¶
LognormalTerminal(spot=..., drift=..., sigma=..., T=..., measure=...,
convention=...) declares S_T = S0 * exp((drift - sigma**2 / 2)*T + sigma*sqrt(T)*Z).
Drift is required; choosing r - q is the caller's explicit risk-neutral assumption.
Spot must be positive; horizon/volatility nonnegative; all parameters finite.
A physical or risk-neutral measure is required. Stress sets are not probabilities.
probability_of_profit(expiry_profile, law) integrates CDF mass over exact
strictly-profitable payoff intervals, independently of the plotting grid. The law
must match the resolved payoff horizon and day count. At zero horizon or zero
volatility it evaluates the deterministic atom, with equality at breakeven counting
as no profit. Initial float parameters retain their decimal representation when
evaluating degenerate atoms against exact payoff roots.
The result is titled Under the specified terminal law and retains the law,
measure, origin/cutoff and terminal exercise/delivery assumptions. It uses strict
pnl.terminal_probability/1 JSON. American terminal intrinsic illustrations retain
the hold-to-expiry caveat; European proxies are refused. This is not calibration
or evaluation of a learned forecaster and is not a probability derived from surface
sensitivity bands. Path risk, paired comparisons and lifecycle modelling are separate
capabilities.