Module hw_calibration 

Calibrating Hull-White’s volatility to a co-terminal swaption strip — flat, by least squares, or as a piecewise-constant term, bootstrapped exactly.

The strip a callable bond implies — one ATM payer swaption per exercisable call date, expiring at the call and running to the bond’s maturity — is priced two ways: the market leg from a quoted normal volatility through Bachelier, the model leg under Hull-White through Jamshidian. The fit minimizes the squared price differences over σ.

It is the sequential-calibration precedent applied to a one-parameter least squares: one unknown, and a residual vector whose derivative comes from a single Jet1 seed on σ — every model price and its ∂/∂σ in one forward pass, nothing recorded, a Gauss-Newton step from the two sums. The reference library searched the same objective by golden section, ~40 evaluations to reach 1e-8; this converges in a handful.

What the fit hands back is more than the number. At the optimum the condition g(σ, ν) = Σ r_i ∂r_i/∂σ = 0 defines σ implicitly in the quotes, so ∂σ/∂ν_i is available from quantities the passes already hold — and that is what turns the σ row of an ordinary risk pass into market vega per quote by arithmetic, with no re-calibration.

The piecewise shape places one piece on each interval between strip expiries. A point’s price depends on the volatility only through the total variance to its expiry, so in expiry order each point fixes exactly one new piece: a one-dimensional monotone solve, and every point repriced. The price Jacobian is then lower-triangular, and the quote sensitivities of every piece follow by forward substitution.

Structs

CalibratedSigma

The calibration result: the fitted volatility, its sensitivity to every quote, and the per-instrument report.

InstrumentFit

One instrument’s fit quality in the calibration report.

MarketLegs 🔒

The strip’s market legs: per point its underlying, ATM forward, annuity, quote and Bachelier price, against the passive view.

StripPoint

One strip point: an ATM payer swaption expiring at expiry on an underlying running to end.

Underlying 🔒

The calibration underlying at one strip point: annual fixed periods between expiry and end on Act/365F dates. Convention-lean by design, and identical on the market and model legs, so the fit compares like with like.

Enums

SigmaShape

The shape a Hull-White volatility is calibrated in.

Constants

PHI_0 🔒

φ(0): the ATM Bachelier price per unit annuity is ν·√T·φ(0).

SIGMA_HI

The upper σ bracket — far above any plausible short-rate volatility.

Functions

atm_forward 🔒

The ATM forward swap rate and annuity of u, passive (they set the strike and the market leg’s scale; neither carries the fit’s derivative).

bisect_gradient 🔒

Bisection on the least-squares gradient over the bracket — the fallback when Gauss-Newton keeps leaving it.

calibrate_and_pin

Calibrates and pins: the returned market carries the fitted volatility — flat under HW-{CCY}-SIGMA, or one HW-{CCY}-SIGMA-{expiry} label per piece — and the exogenous mean reversion under the canonical labels, any label of the other spelling removed, so the callable pricer reads them unchanged.

calibrate_hull_white

Fits σ in shape to the strip bond implies, against market’s discount curve and its pinned normal-vol quotes, with mean_reversion exogenous.

calibrate_hull_white_to_strip

Fits σ in shape to an explicit swaption strip, against market’s discount curve under collateral and its pinned normal-vol quotes, with mean_reversion exogenous.

calibrate_piecewise 🔒

The piecewise shape: one piece per strip expiry, solved in expiry order so each point fixes exactly its own piece and reprices.

gauss_newton 🔒

Gauss-Newton on σ, clamped to the bracket; a second clamp hands over to a bisection on the gradient, which cannot leave the bracket.

market_legs 🔒

market_vega

Market vega per strip quote, as a chain rule on an ordinary risk vector: for each quote, the sum over pieces of the piece’s risk row times ∂σ_j/∂ν_i. Nothing is re-priced or re-calibrated. Returns an empty vector when the risk pass carried no row for any of the fit’s labels.

normal_equivalent 🔒

The normal vol whose at-the-money Bachelier price is Black’s at vol.

strip_from_callable

The co-terminal ATM strip a callable bond implies: one point per exercisable entry strictly inside (valuation, maturity) — expiry at the call date, underlying to the bond’s maturity. Make-whole entries are skipped; duplicate dates dedup.

strip_vol 🔒

A strip point’s normal vol, and whether the surface supplied it: the flat vol pinned under the point’s label where one is, else the at-the-money vol the currency’s swaption surface reads at the point’s expiry and tenor. A lognormal surface’s read is its at-the-money normal equivalent, the vol whose Bachelier price is the Black one: F·(2N(σ√T/2) − 1) / (√T·φ(0)).

underlying 🔒

yf 🔒

Act/365F year fraction — the strip’s time metric.