FXSabrSurface#

class rateslib.fx_volatility.FXSabrSurface(expiries, node_values, eval_date, weights=NoInput.blank, delivery_lag=NoInput.blank, calendar=NoInput.blank, pair=NoInput.blank, id=NoInput.blank, ad=0)#

Bases: _WithState, _WithCache[datetime, FXSabrSmile]

Create an FX Volatility Surface parametrised by cross-sectional Smiles at different expiries.

See also the FX Vol Surfaces section in the user guide.

Parameters:

  • expiries (list[datetime]) – Datetimes representing the expiries of each cross-sectional Smile, in ascending order.

  • node_values (2d-shape of float, Dual, Dual2) – An array of values representing each alpha, beta, rho, nu node value on each cross-sectional Smile. Should be an array of size: (length of expiries, 4).

  • eval_date (datetime) – Acts as the initial node of a Curve. Should be assigned today’s immediate date.

  • weights (Series, optional) – Weights used for temporal volatility interpolation. See notes.

  • delivery_lag (int, optional) – The number of business days after expiry that the physical settlement of the FX exchange occurs. Uses defaults.fx_delivery_lag. Used in determination of ATM forward rates for different expiries.

  • calendar (calendar or str, optional) – The holiday calendar object to use for FX delivery day determination. If str, looks up named calendar from static data.

  • pair (str, optional) – The FX currency pair used to determine ATM forward rates.

  • id (str, optional) – The unique identifier to label the Surface and its variables.

  • ad (int, optional) – Sets the automatic differentiation order. Defines whether to convert node values to float, Dual or Dual2. It is advised against using this setting directly. It is mainly used internally.

Notes

See FXSabrSmile for a description of SABR parameters for Smile construction.

Temporal Interpolation

Interpolation along the expiry axis occurs by performing total linear variance interpolation for a given strike measured on neighboring Smiles.

If weights are given this uses the scaling approach of forward volatility (as demonstrated in Clark’s FX Option Pricing) for calendar days (different options ‘cuts’ and timezone are not implemented). A datetime indexed Series must be provided, where any calendar date that is not included will be assigned the default weight of 1.0.

See constructing FX volatility surfaces for more details.

Extrapolation

When an expiry is sought that is prior to the first parametrised Smile expiry or after the final parametrised Smile expiry extrapolation is required. This is not recommended, however. It would be wiser to create parameterised Smiles at expiries which suit those one wishes to obtian values for.

When seeking an expiry beyond the final expiry, a new SabrSmile is created at that specific expiry using the same SABR parameters as matching the final parametrised Smile. This will capture the evolution of ATM-forward rates through time.

When seeking an expiry prior to the first expiry, the volatility found on the first Smile will be used an interpolated, using total linear variance accooridng to the given weights. If weights are not used then this will return the same value as obtained from that first parametrised Smile. This does not account any evolution of ATM-forward rates.

Attributes Summary

ad

Int in {0,1,2} describing the AD order associated with the Surface.

id

A str identifier to name the Surface used in Solver mappings.

meta

An instance of _FXSabrSurfaceMeta.

smiles

A list of cross-sectional FXSabrSmile instances.

Methods Summary

get_from_strike(k, f, expiry[, w_deli, w_spot])

Given an option strike return the volatility.

Attributes Documentation

ad#

Int in {0,1,2} describing the AD order associated with the Surface.

id#

A str identifier to name the Surface used in Solver mappings.

meta#

An instance of _FXSabrSurfaceMeta.

smiles#

A list of cross-sectional FXSabrSmile instances.

Methods Documentation

get_from_strike(k, f, expiry, w_deli=NoInput.blank, w_spot=NoInput.blank)#

Given an option strike return the volatility.

Parameters:

  • k (float, Dual, Dual2) – The strike of the option.

  • f (float, Dual, Dual2) – The forward rate at delivery of the option.

  • expiry (datetime, optional) – The expiry of the option. Required for temporal interpolation between cross-sectional Smiles.

  • w_deli (DualTypes, optional) – Not used by SabrSurface

  • w_spot (DualTypes, optional) – Not used by SabrSurface

Returns:

tuple of DualTypes

Return type:

(placeholder, vol, k)

Notes

This function returns a tuple consistent with an FXDeltaVolSmile, however since the FXSabrSmile has no concept of a delta index the first element returned is always zero and can be effectively ignored.