Class FxVolSurface

java.lang.Object
com.quantfinlib.fx.FxVolSurface
public final class FxVolSurface extends Object
FX-style volatility surface built from the market's delta-quoted smile: ATM (delta-neutral straddle), 25-delta risk reversal and butterfly, optionally 10-delta wings.

FX options are not quoted by strike. A broker screen shows, per expiry: ATM vol, RR25 (call vol − put vol) and BF25 ((call+put)/2 − ATM). This class converts those quotes to the five pillar vols

   vol(25Δ call) = atm + bf25 + rr25 / 2
   vol(25Δ put)  = atm + bf25 − rr25 / 2      (same shape at 10Δ)

then solves each pillar's strike from its delta and its own vol, producing an absolute strike/vol smile that strike-based pricers (pricing.BlackScholes, pricing.VannaVolga) can consume.

Delta convention

Forward delta (N(d1)), the standard for long-dated and EM pairs. With FxVolSurface.Builder.premiumAdjusted, premium-adjusted forward delta ((K/F)·N(d2)) is used instead — the convention for pairs whose premium is paid in base currency (e.g. USDJPY). Premium-adjusted call deltas are non-monotone in strike; this class resolves the ambiguity the way the market does, taking the OTM (higher-strike) solution.

Interpolation

Within an expiry: linear in vol against log-moneyness, flat beyond the 10Δ (or 25Δ) wings. Across expiries: linear in total variance σ²τ, flat outside the quoted range. Forwards interpolate log-linearly in time. Lookups after FxVolSurface.Builder.build() are allocation-free.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    FxVolSurface.Builder
    Accumulates per-expiry delta quotes, then solves strikes once in FxVolSurface.Builder.build().
    static final record 
    FxVolSurface.SmilePillar
    One expiry's solved smile: absolute strikes and vols, low to high strike.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    atmVol(double expiryYears)
    ATM (delta-neutral straddle) vol at an expiry: the smile at zero skew.
    static FxVolSurface.Builder
    builder()
     
    static double
    dnsStrike(double forward, double vol, double tYears, boolean premiumAdjusted)
    Delta-neutral-straddle (ATM) strike: F·e^{+σ²τ/2} for forward delta, F·e^{−σ²τ/2} premium-adjusted.
    double
    forwardAt(double expiryYears)
    Log-linear interpolated forward at an expiry, flat outside pillars.
    boolean
    isPremiumAdjusted()
     
    FxVolSurface.SmilePillar
    pillar(int i)
    The solved pillar smile at index i (reporting, VannaVolga inputs).
    int
    pillarCount()
     
    static double
    strikeForDelta(double forward, double vol, double tYears, double delta, boolean isCall, boolean premiumAdjusted)
    Strike for a target forward delta (call delta in (0,1), put delta in (−1,0)).
    double
    vol(double expiryYears, double strike)
    Interpolated vol for an absolute strike at an expiry.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • builder

      public static FxVolSurface.Builder builder()

    • dnsStrike

      public static double dnsStrike(double forward, double vol, double tYears, boolean premiumAdjusted)
      Delta-neutral-straddle (ATM) strike: F·e^{+σ²τ/2} for forward delta, F·e^{−σ²τ/2} premium-adjusted. At this strike the call and put deltas cancel exactly.

    • strikeForDelta

      public static double strikeForDelta(double forward, double vol, double tYears, double delta, boolean isCall, boolean premiumAdjusted)
      Strike for a target forward delta (call delta in (0,1), put delta in (−1,0)). Unadjusted deltas invert in closed form; premium-adjusted deltas are solved by bisection on the OTM branch.

    • vol

      public double vol(double expiryYears, double strike)
      Interpolated vol for an absolute strike at an expiry. Wings are flat beyond the quoted pillars; time interpolation is linear in total variance and flat outside the quoted expiries.

    • atmVol

      public double atmVol(double expiryYears)
      ATM (delta-neutral straddle) vol at an expiry: the smile at zero skew.

    • forwardAt

      public double forwardAt(double expiryYears)
      Log-linear interpolated forward at an expiry, flat outside pillars.

    • pillar

      public FxVolSurface.SmilePillar pillar(int i)
      The solved pillar smile at index i (reporting, VannaVolga inputs).

    • pillarCount

      public int pillarCount()

    • isPremiumAdjusted

      public boolean isPremiumAdjusted()