Class RatesOptions

java.lang.Object
com.quantfinlib.rates.RatesOptions
public final class RatesOptions extends Object
Rates volatility products priced off the curve: the bridge between YieldCurve (where forwards and discount factors live) and the option models on a forward rate, pricing.Black76 (lognormal and shifted lognormal) and pricing.Bachelier (normal).
  • Swaption: an option on a forward-starting swap. The underlying is the forward swap rate F = (DF(start) − DF(end)) / annuity, the natural numeraire is the annuity (the PV of the fixed leg's 1%-per-year), and the price is simply annuity × Black76(F, K, vol, expiry). Discounting lives entirely in the annuity, which is why the Black-76 leg is called with rate 0. A payer swaption (right to pay fixed) is a call on the swap rate: it pays when rates rise.
  • Cap / floor: a strip of independent options (caplets), one per accrual period, each a Black-76 call (put) on that period's simple forward rate f_i = (DF(t_{i-1})/DF(t_i) − 1)/τ, fixing at the period start and paying at its end. The first period's rate is already fixed today, so its caplet is pure intrinsic. It is included, as the market convention includes it unless the trade says otherwise.

Two identities hold for every vol model (both pinned by tests): payer − receiver = annuity·(F − K) (swaption put-call parity), and cap − floor = the PV of the matching vanilla swap.

Vol models (RatesOptions.VolModel). Since rates went negative in 2014-2015 the market quotes swaption and cap vols as normal (Bachelier) vols, in absolute rate units, or as shifted-lognormal vols (Black-76 on F + s and K + s, EUR shift typically 1-3%). Plain lognormal Black-76 needs F, K > 0 and is kept for positive-rate markets and older data. One flat vol per product; pricing.SabrModel is where the smile lives.

Schedules: the integer-year functions use annual periods (τ = 1); the overloads with paymentsPerYear use τ = 1/f on a curve in year fractions, which is exact for the curve's own time axis. Day-count accrual on real dates is not modelled here.

Multi-curve overloads (taking a discount and a projection DiscountCurve) work on real dates: the forward swap rate is the InterestRateSwap par rate (float leg projected off the projection curve, OIS annuity as numeraire) and each caplet's forward comes from the projection curve while its payment is discounted on the OIS curve. Expiry is the ACT/365F curve time of the swap start or caplet period start.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    RatesOptions.VolModel
    A vol type together with its displacement (0 unless shifted lognormal).
    static enum 
    RatesOptions.VolType
    Which vol a quote is: lognormal (Black-76), shifted lognormal (Black-76 on forward + shift and strike + shift) or normal (Bachelier).

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    annuity(YieldCurve curve, double startYears, double tenorYears, int paymentsPerYear)
    PV of 1 per year paid paymentsPerYear times a year (accrual τ = 1/f) over (start, start + tenor].
    static double
    annuity(YieldCurve curve, int startYears, int tenorYears)
    PV of 1 per year paid annually over (startYears, startYears+tenorYears].
    static double
    cap(YieldCurve curve, int maturityYears, double strike, double vol)
    Cap: strip of annual Black-76 caplets to maturityYears.
    static double
    capFloor(DiscountCurve discount, DiscountCurve projection, LocalDate start, LocalDate end, int paymentsPerYear, DayCount dayCount, BusinessCalendar calendar, BusinessCalendar.Roll roll, double strike, double vol, boolean cap, RatesOptions.VolModel model)
    Cap (or floor) on the projection index over the adjusted schedule from start to end: caplet j pays tau_j max(F_j - K, 0) at t_j, F_j the projection forward on its accrual period, fixing at the period start, discounted on discount.
    static double
    capFloor(YieldCurve curve, double maturityYears, int paymentsPerYear, double strike, double vol, boolean cap, RatesOptions.VolModel model)
    Cap (or floor, cap = false) with accrual τ = 1/f: caplet i fixes at (i−1)τ, pays τ·max(L_i − K, 0) at iτ, L_i the simple forward.
    static double
    floor(YieldCurve curve, int maturityYears, double strike, double vol)
    Floor: the matching strip of floorlets.
    static double
    forwardSwapRate(YieldCurve curve, double startYears, double tenorYears, int paymentsPerYear)
    Forward par swap rate with fixed-leg frequency paymentsPerYear.
    static double
    forwardSwapRate(YieldCurve curve, int startYears, int tenorYears)
    Forward par swap rate for a swap starting at startYears.
    static double
    swaption(DiscountCurve discount, DiscountCurve projection, InterestRateSwap underlying, double strike, double vol, boolean payer, RatesOptions.VolModel model)
    Swaption on underlying (its fixed rate is ignored; strike is used), expiring at the swap start: A_d * model(F, K) with F the multi-curve par rate and A_d the OIS annuity.
    static double
    swaption(YieldCurve curve, double startYears, double tenorYears, int paymentsPerYear, double strike, double vol, boolean payer, RatesOptions.VolModel model)
    Swaption price per unit notional under any RatesOptions.VolModel: annuity × model value on the forward swap rate, expiry = start.
    static double
    swaption(YieldCurve curve, int startYears, int tenorYears, double strike, double vol, boolean payer)
    Black-76 swaption price per unit notional.
    static double
    swaptionImpliedVol(YieldCurve curve, double startYears, double tenorYears, int paymentsPerYear, double strike, double price, boolean payer, RatesOptions.VolModel model)
    Implied vol (of the given model) of a swaption price per unit notional.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • annuity

      public static double annuity(YieldCurve curve, int startYears, int tenorYears)
      PV of 1 per year paid annually over (startYears, startYears+tenorYears].

    • forwardSwapRate

      public static double forwardSwapRate(YieldCurve curve, int startYears, int tenorYears)
      Forward par swap rate for a swap starting at startYears.

    • swaption

      public static double swaption(YieldCurve curve, int startYears, int tenorYears, double strike, double vol, boolean payer)
      Black-76 swaption price per unit notional.
      Parameters:
      vol - flat lognormal vol of the forward swap rate
      payer - true = payer swaption (call on the swap rate)

    • cap

      public static double cap(YieldCurve curve, int maturityYears, double strike, double vol)
      Cap: strip of annual Black-76 caplets to maturityYears.

    • floor

      public static double floor(YieldCurve curve, int maturityYears, double strike, double vol)
      Floor: the matching strip of floorlets.

    • annuity

      public static double annuity(YieldCurve curve, double startYears, double tenorYears, int paymentsPerYear)
      PV of 1 per year paid paymentsPerYear times a year (accrual τ = 1/f) over (start, start + tenor].

    • forwardSwapRate

      public static double forwardSwapRate(YieldCurve curve, double startYears, double tenorYears, int paymentsPerYear)
      Forward par swap rate with fixed-leg frequency paymentsPerYear.

    • swaption

      public static double swaption(YieldCurve curve, double startYears, double tenorYears, int paymentsPerYear, double strike, double vol, boolean payer, RatesOptions.VolModel model)
      Swaption price per unit notional under any RatesOptions.VolModel: annuity × model value on the forward swap rate, expiry = start. Normal and shifted models accept zero and negative strikes and forwards.

    • swaptionImpliedVol

      public static double swaptionImpliedVol(YieldCurve curve, double startYears, double tenorYears, int paymentsPerYear, double strike, double price, boolean payer, RatesOptions.VolModel model)
      Implied vol (of the given model) of a swaption price per unit notional.

    • capFloor

      public static double capFloor(YieldCurve curve, double maturityYears, int paymentsPerYear, double strike, double vol, boolean cap, RatesOptions.VolModel model)
      Cap (or floor, cap = false) with accrual τ = 1/f: caplet i fixes at (i−1)τ, pays τ·max(L_i − K, 0) at iτ, L_i the simple forward. The first caplet is already fixed and contributes intrinsic value.

    • swaption

      public static double swaption(DiscountCurve discount, DiscountCurve projection, InterestRateSwap underlying, double strike, double vol, boolean payer, RatesOptions.VolModel model)
      Swaption on underlying (its fixed rate is ignored; strike is used), expiring at the swap start: A_d * model(F, K) with F the multi-curve par rate and A_d the OIS annuity.

    • capFloor

      public static double capFloor(DiscountCurve discount, DiscountCurve projection, LocalDate start, LocalDate end, int paymentsPerYear, DayCount dayCount, BusinessCalendar calendar, BusinessCalendar.Roll roll, double strike, double vol, boolean cap, RatesOptions.VolModel model)
      Cap (or floor) on the projection index over the adjusted schedule from start to end: caplet j pays tau_j max(F_j - K, 0) at t_j, F_j the projection forward on its accrual period, fixing at the period start, discounted on discount. A caplet fixing at or before the valuation date is intrinsic on the projected forward.