tf_quant_finance.experimental.instruments.InterestRateSwap

Last updated: 2023-03-16.

tf_quant_finance.experimental.instruments.InterestRateSwap#

View source

Represents a batch of Interest Rate Swaps (IRS).

tf_quant_finance.experimental.instruments.InterestRateSwap(
    start_date, maturity_date, pay_leg, receive_leg, holiday_calendar=None,
    dtype=None, name=None
)

An Interest rate swap (IRS) is a contract between two counterparties for an exchange of a series of payments over a period of time. The payments are made periodically (for example quarterly or semi-annually) where the last payment is made at the maturity (or termination) of the contract. In the case of fixed-for-floating IRS, one counterparty pays a fixed rate while the other counterparty’s payments are linked to a floating index, most commonly the LIBOR rate. On the other hand, in the case of interest rate basis swap, the payments of both counterparties are linked to a floating index. Typically, the floating rate is observed (or fixed) at the beginning of each period while the payments are made at the end of each period [1].

For example, consider a vanilla swap with the starting date T_0 and maturity date T_n and equally spaced coupon payment dates T_1, T_2, …, T_n such that

T_0 < T_1 < T_2 < … < T_n and dt_i = T_(i+1) - T_i (A)

The floating rate is fixed on T_0, T_1, …, T_(n-1) and both the fixed and floating payments are made on T_1, T_2, …, T_n (payment dates).

The InterestRateSwap class can be used to create and price multiple IRS simultaneously. The class supports vanilla fixed-for-floating swaps as well as basis swaps. However all IRS within an IRS object must be priced using a common reference and discount curve.

Example (non batch):#

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

dtype = np.float64
start_date = dates.convert_to_date_tensor([(2020, 2, 8)])
maturity_date = dates.convert_to_date_tensor([(2022, 2, 8)])
valuation_date = dates.convert_to_date_tensor([(2020, 2, 8)])
period_3m = dates.periods.months(3)
period_6m = dates.periods.months(6)
fix_spec = instruments.FixedCouponSpecs(
            coupon_frequency=period_6m, currency='usd',
            notional=1., coupon_rate=0.03134,
            daycount_convention=instruments.DayCountConvention.ACTUAL_365,
            businessday_rule=dates.BusinessDayConvention.NONE)

flt_spec = instruments.FloatCouponSpecs(
            coupon_frequency=period_3m, reference_rate_term=period_3m,
            reset_frequency=period_3m, currency='usd', notional=1.,
            businessday_rule=dates.BusinessDayConvention.NONE,
            coupon_basis=0., coupon_multiplier=1.,
            daycount_convention=instruments.DayCountConvention.ACTUAL_365)

swap = instruments.InterestRateSwap([(2020,2,2)], [(2023,2,2)], [fix_spec],
                                    [flt_spec], dtype=np.float64)

curve_dates = valuation_date + dates.periods.years([1, 2, 3, 5, 7, 10, 30])
reference_curve = instruments.RateCurve(
    curve_dates,
    np.array([
      0.02834814, 0.03077457, 0.03113739, 0.03130794, 0.03160892,
      0.03213901, 0.03257991
      ], dtype=dtype),
    valuation_date=valuation_date,
    dtype=dtype)
market = instruments.InterestRateMarket(
    reference_curve=reference_curve, discount_curve=reference_curve)

price = swap.price(valuation_date, market)
# Expected result: 1e-7

Example (batch):#

The following example illustrates the construction and pricing of IRS using batches.

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

dtype = np.float64
notional = 1.0
maturity_date = dates.convert_to_date_tensor([(2023, 2, 8), (2027, 2, 8)])
start_date = dates.convert_to_date_tensor([(2020, 2, 8), (2020, 2, 8)])
valuation_date = dates.convert_to_date_tensor([(2020, 2, 8)])

period3m = dates.periods.months([3, 3])
period6m = dates.periods.months([6, 6])
fix_spec = instruments.FixedCouponSpecs(
    coupon_frequency=period6m, currency='usd',
    notional=notional,
    coupon_rate=[0.03134, 0.03181],
    daycount_convention=instruments.DayCountConvention.ACTUAL_365,
    businessday_rule=dates.BusinessDayConvention.NONE)
flt_spec = instruments.FloatCouponSpecs(
    coupon_frequency=period3m, reference_rate_term=period3m,
    reset_frequency=period3m, currency='usd',
    notional=notional,
    businessday_rule=dates.BusinessDayConvention.NONE,
    coupon_basis=0.0, coupon_multiplier=1.0,
    daycount_convention=instruments.DayCountConvention.ACTUAL_365)

swap = instruments.InterestRateSwap(start_date, maturity_date,
                                    fix_spec, flt_spec,
                                    dtype=dtype)
curve_dates = valuation_date + dates.periods.years([1, 2, 3, 5, 7, 10, 30])
reference_curve = instruments.RateCurve(
    curve_dates,
    np.array([
      0.02834814, 0.03077457, 0.03113739, 0.03130794, 0.03160892,
      0.03213901, 0.03257991
      ], dtype=dtype),
      valuation_date=valuation_date,
    dtype=dtype)
market = instruments.InterestRateMarket(
    reference_curve=reference_curve, discount_curve=reference_curve)

price = swap.price(valuation_date, market)
# Expected result: [1.0e-7, 1.0e-7]

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 rank 1 DateTensor specifying the dates for the inception (start of the accrual) of the swap contracts. The shape of the input correspond to the number of instruments being created.

  • maturity_date: A rank 1 DateTensor specifying the maturity dates for each contract. The shape of the input should be the same as that of start_date.

  • pay_leg: A scalar or a list of either FixedCouponSpecs or FloatCouponSpecs specifying the coupon payments for the payment leg of the swap. If specified as a list then the length of the list should be the same as the number of instruments being created. If specified as a scalar, then the elements of the namedtuple must be of the same shape as (or compatible to) the shape of start_date.

  • receive_leg: A scalar or a list of either FixedCouponSpecs or FloatCouponSpecs specifying the coupon payments for the receiving leg of the swap. If specified as a list then the length of the list should be the same as the number of instruments being created. If specified as a scalar, then the elements of the namedtuple must be of the same shape as (or compatible with) the shape of start_date.

  • holiday_calendar: An instance of dates.HolidayCalendar to specify weekends and holidays. Default value: None in which case a holiday calendar would be created with Saturday and Sunday being the holidays.

  • dtype: tf.Dtype. If supplied the dtype for the real variables or ops either supplied to the IRS object or created by the IRS 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 ‘interest_rate_swap’.

Attributes:#

  • fixed_rate

  • is_payer

  • notional

  • term

Methods#

annuity

View source

annuity(
    valuation_date, market, model=None
)

Returns the annuity of each swap on the vauation date.

par_rate

View source

par_rate(
    valuation_date, market, model=None
)

Returns the par swap rate for the swap.

price

View source

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

Returns the present value of the instrument 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 interest rate swap.

  • model: Reserved for future use.

  • pricing_context: Additional context 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 IRS contract based on the input market data.

Contents