tf_quant_finance.experimental.instruments.CapAndFloor

Last updated: 2023-03-16.

tf_quant_finance.experimental.instruments.CapAndFloor#

View source

Represents a batch of Caps and/or Floors.

tf_quant_finance.experimental.instruments.CapAndFloor(
    start_date, maturity_date, reset_frequency, strike, daycount_convention=None,
    notional=None, is_cap=None, dtype=None, name=None
)

An interest Cap (or Floor) is a portfolio of call (or put) options where the underlying for the individual options are successive forward rates. The individual options comprising a Cap are called Caplets and the corresponding options comprising a Floor are called Floorlets. For example, a caplet on forward rate F(T_i, T_{i+1}) has the following payoff at time T_{i_1}:

caplet payoff = tau_i * max[F(T_i, T_{i+1}), 0]

where tau_i is the daycount fraction.

The CapAndFloor class can be used to create and price multiple Caps/Floors simultaneously. However all instruments within an object must be priced using common reference/discount curve.

Example:#

The following example illustrates the construction of an IRS instrument and calculating its price.

import numpy as np
import tensorflow as tf
import tf_quant_finance as tff
dates = tff.datetime
instruments = tff.experimental.instruments
rc = tff.experimental.instruments.rates_common

dtype = np.float64
notional = 100.0
maturity_date = dates.convert_to_date_tensor([(2022, 1, 15)])
start_date = dates.convert_to_date_tensor([(2021, 1, 15)])
valuation_date = dates.convert_to_date_tensor([(2021, 1, 1)])

period3m = dates.periods.months(3)
cap = instruments.CapAndFloor(
    start_date,
    maturity_date,
    period3m,
    0.005,
    daycount_convention=instruments.DayCountConvention.ACTUAL_365,
    notional=notional,
    dtype=dtype)
curve_dates = valuation_date + dates.periods.months([0, 3, 12, 24])
reference_curve = instruments.RateCurve(
    curve_dates,
    np.array([0.005, 0.01, 0.015, 0.02], dtype=np.float64),
    valuation_date=valuation_date,
    dtype=np.float64)
market = instruments.InterestRateMarket(
    reference_curve=reference_curve, discount_curve=reference_curve)

price = cap.price(
          valuation_date,
          market,
          model=instruments.InterestRateModelType.LOGNORMAL_RATE,
          pricing_context=0.5)
# Expected result: 1.0474063612452953

References:#

[1]: Leif B.G. Andersen and Vladimir V. Piterbarg. Interest Rate Modeling, Volume I: Foundations and Vanilla Models. Chapter 5. 2010.

Args:#

  • start_date: A scalar InterestRateSwap specifying the interest rate swaps underlying the swaptions. The batch size of the swaptions being created would be the same as the bacth size of the swap. For receiver swaptions the receive_leg of the underlying swaps should be

  • maturity_date: A rank 1 DateTensor specifying the expiry dates for each swaption. The shape of the input should be the same as the batch size of the swap input. Default value: None in which case the option expity date is the same as the start date of each underlying swap.

  • reset_frequency: A rank 1 PeriodTensor specifying the frequency of caplet resets and caplet payments.

  • strike: A scalar Tensor of real dtype specifying the strike rate against which each caplet within the cap are exercised. The shape should be compatible to the shape of start_date

  • daycount_convention: An optional DayCountConvention associated with the underlying rate for the cap. Daycount is assumed to be the same for all contracts in a given batch. Default value: None in which case the daycount convention will default to DayCountConvention.ACTUAL_360 for all contracts.

  • notional: An optional Tensor of real dtype specifying the notional amount for the cap. Default value: None in which case the notional is set to 1.

  • is_cap: An optional boolean Tensor of a shape compatible with start_date. Indicates whether to compute the price of a Cap (if True) or a Floor (if False). Default value: None, it is assumed that every element is a Cap.

  • dtype: tf.Dtype. If supplied the dtype for the real variables or ops either supplied to the Swaption object or created by the Swaption object. Default value: None which maps to the default dtype inferred by TensorFlow.

  • name: Python str. The name to give to the ops created by this class. Default value: None which maps to ‘cap_and_floor’.

Methods#

price

View source

price(
    valuation_date, market, model=None, pricing_context=None, name=None
)

Returns the present value of the Cap/Floor on the valuation date.

Args:#

  • valuation_date: A scalar DateTensor specifying the date on which valuation is being desired.

  • market: A namedtuple of type InterestRateMarket which contains the necessary information for pricing the Cap/Floor.

  • model: An optional input of type InterestRateModelType to specify which model to use for pricing. Default value: None in which case LOGNORMAL_RATE model is used.

  • pricing_context: An optional input to provide additional parameters (such as model parameters) relevant for pricing.

  • name: Python str. The name to give to the ops created by this function. Default value: None which maps to "price".

Returns:#

A Rank 1 Tensor of real type containing the modeled price of each cap (or floor) based on the input market data.

Raises:#

  • ValueError: If an unsupported model is supplied to the function.

Contents