Last updated: 2023-03-16.

tf_quant_finance.black_scholes.swaption_price

View source

Calculates the price of European Swaptions using the Black model.

tf_quant_finance.black_scholes.swaption_price(
    *, volatilities, expiries, floating_leg_start_times, floating_leg_end_times,
    fixed_leg_payment_times, floating_leg_daycount_fractions,
    fixed_leg_daycount_fractions, fixed_leg_coupon,
    floating_leg_start_times_discount_factors,
    floating_leg_end_times_discount_factors,
    fixed_leg_payment_times_discount_factors, notional=None, is_payer_swaption=None,
    is_normal_volatility=True, dtype=None, name=None
)

A European Swaption is a contract that gives the holder an option to enter a swap contract at a future date at a prespecified fixed rate. A swaption that grants the holder to pay fixed rate and receive floating rate is called a payer swaption while the swaption that grants the holder to receive fixed and pay floating payments is called the receiver swaption. Typically the start date (or the inception date) of the swap coincides with the expiry of the swaption.

Example

The example shows how value a batch of 1y x 1y and 1y x 2y swaptions using the Black (normal) model for the swap rate.

import numpy as np
import tensorflow as tf
import tf_quant_finance as tff

dtype = tf.float64

volatilities = [0.01, 0.005]
expiries = [1.0, 1.0]
float_leg_start_times = [[1.0, 1.25, 1.5, 1.75, 2.0, 2.0, 2.0, 2.0],
                          [1.0, 1.25, 1.5, 1.75, 2.0, 2.25, 2.5, 2.75]]
float_leg_end_times = [[1.25, 1.5, 1.75, 2.0, 2.0, 2.0, 2.0, 2.0],
                        [1.25, 1.5, 1.75, 2.0, 2.25, 2.5, 2.75, 3.0]]
fixed_leg_payment_times = [[1.25, 1.5, 1.75, 2.0, 2.0, 2.0, 2.0, 2.0],
                            [1.25, 1.5, 1.75, 2.0, 2.25, 2.5, 2.75, 3.0]]
float_leg_daycount_fractions = [[0.25, 0.25, 0.25, 0.25, 0.0, 0.0, 0.0, 0.0],
                                 [0.25, 0.25, 0.25, 0.25, 0.25, 0.25, 0.25,
                                 0.25]]
fixed_leg_daycount_fractions = [[0.25, 0.25, 0.25, 0.25, 0.0, 0.0, 0.0, 0.0],
                                 [0.25, 0.25, 0.25, 0.25, 0.25, 0.25, 0.25,
                                 0.25]]
fixed_leg_coupon = [0.011, 0.011]
discount_fn = lambda x: np.exp(-0.01 * np.array(x))
price = self.evaluate(
tff.black_scholes.swaption_price(
    volatilities=volatilities,
    expiries=expiries,
    floating_leg_start_times=float_leg_start_times,
    floating_leg_end_times=float_leg_end_times,
    fixed_leg_payment_times=fixed_leg_payment_times,
    floating_leg_daycount_fractions=float_leg_daycount_fractions,
    fixed_leg_daycount_fractions=fixed_leg_daycount_fractions,
    fixed_leg_coupon=fixed_leg_coupon,
    floating_leg_start_times_discount_factors=discount_fn(
        float_leg_start_times),
    floating_leg_end_times_discount_factors=discount_fn(
        float_leg_end_times),
    fixed_leg_payment_times_discount_factors=discount_fn(
        fixed_leg_payment_times),
    is_normal_volatility=is_normal_model,
    notional=100.,
    dtype=dtype))
# Expected value: [0.3458467885511461, 0.3014786656395892] # shape = (2,)

Args:

• volatilities: Real Tensor of any shape and dtype. The Black volatilities of the swaptions to price. The shape of this input determines the number (and shape) of swaptions to be priced and the shape of the output.

• expiries: A real Tensor of same shape and dtype as volatilities. The time to expiration of the swaptions.

• floating_leg_start_times: A real Tensor of the same dtype as volatilities. The times when accrual begins for each payment in the floating leg. The shape of this input should be expiries.shape + [m] or batch_shape + [m] where m denotes the number of floating payments in each leg.

• floating_leg_end_times: A real Tensor of the same dtype as volatilities. The times when accrual ends for each payment in the floating leg. The shape of this input should be batch_shape + [m] where m denotes the number of floating payments in each leg.

• fixed_leg_payment_times: A real Tensor of the same dtype as volatilities. The payment times for each payment in the fixed leg. The shape of this input should be batch_shape + [n] where n denotes the number of fixed payments in each leg.

• floating_leg_daycount_fractions: A real Tensor of the same dtype and compatible shape as floating_leg_start_times. The daycount fractions for each payment in the floating leg.

• fixed_leg_daycount_fractions: A real Tensor of the same dtype and compatible shape as fixed_leg_payment_times. The daycount fractions for each payment in the fixed leg.

• fixed_leg_coupon: A real Tensor of the same dtype and shape compatible to batch_shape. The fixed coupon rate for each payment in the fixed leg.

• floating_leg_start_times_discount_factors: A real Tensor of the same shape and dtype as floating_leg_start_times. The discount factors corresponding to floating_leg_start_times.

• floating_leg_end_times_discount_factors: A real Tensor of the same shape and dtype as floating_leg_end_times. The discount factors corresponding to floating_leg_end_times.

• fixed_leg_payment_times_discount_factors: A real Tensor of the same shape and dtype as fixed_leg_payment_times. The discount factors corresponding to fixed_leg_payment_times.

• notional: An optional Tensor of same dtype and compatible shape as volatilities specifying the notional amount for the underlying swap. Default value: None in which case the notional is set to 1.

• is_payer_swaption: A boolean Tensor of a shape compatible with expiries. Indicates whether the swaption is a payer (if True) or a receiver (if False) swaption. If not supplied, payer swaptions are assumed.

• is_normal_volatility: An optional Python boolean specifying whether the volatilities correspond to normal Black volatility (if True) or lognormal Black volatility (if False). Default value: True, which corresponds to normal volatility.

• dtype: The default dtype to use when converting values to Tensors. Default value: None which means that default dtypes inferred by TensorFlow are used.

• name: Python string. The name to give to the ops created by this function. Default value: None which maps to the default name hw_swaption_price.

Returns:

A Tensor of real dtype and shape batch_shape containing the computed swaption prices.