Documentation

MBB Risk Engine is a high-performance analytics platform for callable mortgage bonds: build portfolios, design prepayment models, and calibrate Z-SHIFT in milliseconds to reconcile model and market dirty prices. Compute a full AAD risk stack (BPV, smooth/stable convexity, and vega buckets) instantly—whether for pricing or large-scale scenario sweeps—so you can move from inputs to decisions in near real time, even on long-dated bonds.

Theory Risk Numbers Manuals & Samples API References
Callable Mortgage Bonds — book cover
Callable Mortgage Bonds
Click the cover to open the Springer page.

Theoretical documentation

High-level model overview, assumptions, and how prices/greeks are produced. For exact definitions of the output measures (units and sign conventions), see the Risk Numbers tab.

Interest rate model (Hull–White / GSR short-rate)

The engine uses a one-factor Gaussian short-rate model (Hull–White in time-dependent form, also known as GSR):
dr(t) = (θ(t) − κ·r(t)) dt + σ(t) dW(t)
  • κ is the mean-reversion speed (constant).
  • σ(t) is a term-structure of volatility implemented as piecewise-constant buckets over time.
  • θ(t) is chosen so the model fits the initial discount curve exactly.
Pricing is performed under the risk-neutral measure. Callable behavior is represented through a prepayment model evaluated on the cashflow schedule (backward induction over event dates), rather than assuming optimal exercise. Path dependency is introduced through the pool factor state carried between event dates.

Prepayment model

Prepayments are modeled explicitly (CPR logic + gating variables), applied on the cashflow schedule. The model consumes the relevant state (rates, incentive measures, time-dependent factors, etc.) and produces projected principal prepayments and updated pool factor.
  • Schedule-driven: applied at event dates alongside coupon/settlement logic.
  • Path dependent: the pool factor evolves over time and affects future cashflows.
  • Calibration link: Z-shift reconciliation: calibrate a constant parallel shift to the input yield curve; this shift affects both discounting and prepayment behavior (via incentive measures), and is solved so the schedule-driven model matches the market dirty price.
The active CPR logic can be inspected and edited in the Prepayment Model Builder.

Risk numbers

  • BPV / DV01: price sensitivity to small curve shocks (units: per 1bp, with your sign convention).
  • Convexity: second-order rate sensitivity (stable/consistent with the engine’s definition).
  • Vega: sensitivity to σ-bucket shocks (bucketed term-structure exposures).
  • Kappa sensitivity: shows the change in value with respect to the kappa parameter.
For exact definitions, units, and sign conventions, see the Risk Numbers tab.

Automatic differentiation (AAD)

Risk numbers are produced from the same pricing engine using algorithmic differentiation, so prices and sensitivities remain consistent across “live” pricing and scenario sweeps.
  • First-order: curve and σ-bucket sensitivities (and model parameter sensitivities where enabled).
  • Second-order: convexity-style measures via stable second-derivative workflows.
  • One engine: no separate “risk pricer” — sensitivities are tied to the exact schedule/PDE logic used for price.
More details are available in the References tab.

Performance

The pricing engine is optimized for speed. On a local laptop, a single pricing run (given a fixed Z-shift) including all risk numbers completes in ~60 ms for a 30-year bond with 120 payments and 3 additional time steps between payment dates.
Z-shift calibration, portfolio risk, and scenario sweeps are parallelized across multiple threads to reduce end-to-end runtime.
This is achieved using a single, consistent PDE/AAD implementation so pricing and risk are produced together (no separate “risk pricer” pass).