FXSabrSmile#

class rateslib.fx_volatility.FXSabrSmile(nodes, eval_date, expiry, delivery_lag=NoInput.blank, calendar=NoInput.blank, pair=NoInput.blank, id=NoInput.blank, ad=0)#

Bases: _BaseSmile

Create an FX Volatility Smile at a given expiry indexed by strike using SABR parameters.

Parameters:

  • nodes (dict[str, float]) – The parameters for the SABR model. Keys must be ‘alpha’, ‘beta’, ‘rho’, ‘nu’. See below.

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

  • expiry (datetime) – The expiry date of the options associated with this Smile

  • id (str, optional) – The unique identifier to distinguish between Smiles in a multicurrency framework and/or Surface.

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

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

  • 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

The keys for nodes are described as the following:

  • alpha: The initial volatility parameter (e.g. 0.10 for 10%) of the SABR model, in (0, inf).

  • beta: The scaling parameter between normal (0) and lognormal (1) of the SABR model in [0, 1].

  • rho: The correlation between spot and volatility of the SABR model, e.g. -0.10, in [-1.0, 1.0)

  • nu: The volatility of volatility parameter of the SABR model, e.g. 0.80.

The parameters \(\alpha, \rho, \nu\) will be calibrated/mutated by a Solver object. These should be entered as float and the argument ad can be used to automatically tag these as variables.

The parameter \(\beta\) will not be calibrated/mutated by a Solver. This value can be entered either as a float, or a Variable to capture exogenous sensivities.

The arguments delivery_lag, calendar and pair are only required if using an FXForwards object to forecast ATM-forward FX rates for pricing. If the forward rates are supplied directly as numeric values these arguments are not required.

Examples

See Constructing a Smile.

Attributes Summary

ad

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

id

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

meta

An instance of _FXSmileMeta.

nodes

An instance of _FXSabrSmileNodes.

Methods Summary

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

Given an option strike return the volatility.

plot([comparators, labels, x_axis, f])

Plot volatilities associated with the Smile.

update_node(key, value)

Update a single node value on the SABRSmile.

Attributes Documentation

ad#

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

id#

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

meta#

An instance of _FXSmileMeta.

nodes#

An instance of _FXSabrSmileNodes.

Methods Documentation

get_from_strike(k, f, expiry=NoInput.blank, 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) – Typically uses with Surfaces. If given, performs a check to ensure consistency of valuations. Raises if expiry requested and expiry of the Smile do not match. Used internally.

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

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

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.

plot(comparators=NoInput.blank, labels=NoInput.blank, x_axis=NoInput.blank, f=NoInput.blank)#

Plot volatilities associated with the Smile.

Warning

The ‘delta’ x_axis type for a SabrSmile is calculated based on a forward, unadjusted delta and is expressed as a negated put option delta consistent with the definition for a FXDeltaVolSmile.

Parameters:

  • comparators (list[Smile]) – A list of Smiles which to include on the same plot as comparators. Note the comments on FXDeltaVolSmile.plot.

  • labels (list[str]) – A list of strings associated with the plot and comparators. Must be same length as number of plots.

  • x_axis (str in {"strike", "moneyness", "delta"}) – ‘strike’ is the natural option for this SabrSmile types while ‘delta’ is the natural choice for DeltaVolSmile types. If ‘delta’ see the warning. If ‘moneyness’ the strikes are converted using f.

  • f (DualTypes) – The FX forward rate at delivery.

Returns:

(fig, ax, line)

Return type:

Matplotlib.Figure, Matplotplib.Axes, Matplotlib.Lines2D

update_node(key, value)#

Update a single node value on the SABRSmile.

Parameters:

  • key (str in {"alpha", "beta", "rho", "nu"}) – The node value to update.

  • value (float, Dual, Dual2, Variable) – Value to update on the Smile.

Return type:

None

Notes

Warning

Rateslib is an object-oriented library that uses complex associations. Although Python may not object to directly mutating attributes of a Curve instance, this should be avoided in rateslib. Only use official update methods to mutate the values of an existing Curve instance. This class is labelled as a mutable on update object.