FXDeltaVolSurface#

class rateslib.fx_volatility.FXDeltaVolSurface(delta_indexes, expiries, node_values, eval_date, delta_type, weights=NoInput.blank, id=NoInput.blank, ad=0)#

Bases: _WithState, _WithCache[datetime, FXDeltaVolSmile]

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:

  • delta_indexes (list[float]) – Axis values representing the delta indexes on each cross-sectional Smile.

  • 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 node value on each cross-sectional Smile. Should be an array of size: (length of expiries, length of delta_indexes).

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

  • delta_type (str in {"spot", "spot_pa", "forward", "forward_pa"}) – The type of delta calculation that is used as the Smiles definition to obtain a delta index which is referenced by the node keys.

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

  • 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 FXDeltaVolSmile for a description of delta indexes and Smile construction.

Temporal Interpolation

Interpolation along the expiry axis occurs by performing total linear variance interpolation for each delta index and then dynamically constructing a Smile with the usual cubic interpolation.

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.

Calibration

Instruments that do not match the delta_type of this Surface can still be used within a Solver to calibrate the surface. This is quite common, when Options less than or equal to one year expiry might use a ‘spot’ delta type whilst longer expiries use ‘forward’ delta type.

Internally this is all handled appropriately with necessary conversions, but it is the users responsibility to label the Surface and Instrument with the correct types. Failing to take correct delta types into account often introduces a mismatch - large enough to be relevant for calibration and pricing, but small enough that it may not be noticed at first. Parametrising the Surface with a ‘forward’ delta type is the recommended choice because it is more standardised and the configuration of which delta types to use for the Instruments can be a separate consideration.

For performance reasons it is recommended to match unadjusted delta type Surfaces with calibrating Instruments that also have unadjusted delta types. And vice versa with premium adjusted delta types. However, rateslib has internal root solvers which can handle these cross-delta type specifications, although it degrades the performance of the Solver because the calculations are made more difficult. Mixing ‘spot’ and ‘forward’ is not a difficult distinction to refactor and that does not cause performance degradation.

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 _FXDeltaVolSurfaceMeta.

smiles

A list of cross-sectional FXDeltaVolSmile instances.

Methods Summary

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

Given an option strike and expiry return associated delta and vol values.

get_smile(expiry)

Construct a DeltaVolSmile with linear total variance interpolation over delta indexes.

plot()

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 _FXDeltaVolSurfaceMeta.

smiles#

A list of cross-sectional FXDeltaVolSmile instances.

Methods Documentation

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

Given an option strike and expiry return associated delta and vol values.

Parameters:

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

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

  • expiry (datetime) – Required to produce the cross-sectional Smile on the Surface.

  • w_deli (DualTypes, optional) – Required only for spot/forward conversions.

  • w_spot (DualTypes, optional) – Required only for spot/forward conversions.

Returns:

tuple of float, Dual, Dual2

Return type:

(delta index, vol, k)

Notes

This function will return a delta index associated with the FXDeltaVolSmile and the volatility attributed to the delta at that point. Recall that the delta index is the negated put option delta for the given strike k.

get_smile(expiry)#

Construct a DeltaVolSmile with linear total variance interpolation over delta indexes.

Parameters:

expiry (datetime) – The expiry for the Smile as cross-section of Surface.

Return type:

FXDeltaVolSmile

plot()#