tf_quant_finance.experimental.instruments.CMSSwap

Last updated: 2023-03-16.

tf_quant_finance.experimental.instruments.CMSSwap#

View source

Represents a batch of CMS Swaps.

Inherits From: InterestRateSwap

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

A CMS swap is a swap contract where the floating leg payments are based on the constant maturity swap (CMS) rate. The CMS rate refers to a future fixing of swap rate of a fixed maturity, i.e. the breakeven swap rate on a standard fixed-to-float swap of the specified maturity [1].

Let S_(i,m) denote a swap rate with maturity m (years) on the fixing date `T_i. Consider a CMS swap with the starting date T_0 and maturity date T_n and regularly 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 CMS rate, S_(i, m), is fixed on T_0, T_1, …, T_(n-1) and floating payments made are on T_1, T_2, …, T_n (payment dates) with the i-th payment being equal to tau_i * S_(i, m) where tau_i is the year fraction between [T_i, T_(i+1)].

The CMSSwap class can be used to create and price multiple CMS swaps simultaneously. However all CMS swaps within an object must be priced using a common reference and discount curve.

Example:#

The following example illustrates the construction of an CMS swap 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
start_date = dates.convert_to_date_tensor([(2021, 1, 1)])
maturity_date = dates.convert_to_date_tensor([(2023, 1, 1)])
valuation_date = dates.convert_to_date_tensor([(2021, 1, 1)])
p3m = dates.months(3)
p6m = dates.months(6)
p1y = dates.year()
fix_spec = instruments.FixedCouponSpecs(
    coupon_frequency=p6m,
    currency='usd',
    notional=1.,
    coupon_rate=0.02,
    daycount_convention=instruments.DayCountConvention.ACTUAL_365,
    businessday_rule=dates.BusinessDayConvention.NONE)
flt_spec = instruments.FloatCouponSpecs(
    coupon_frequency=p3m,
    reference_rate_term=p3m,
    reset_frequency=p3m,
    currency='usd',
    notional=1.,
    businessday_rule=dates.BusinessDayConvention.NONE,
    coupon_basis=0.,
    coupon_multiplier=1.,
    daycount_convention=instruments.DayCountConvention.ACTUAL_365)
cms_spec = instruments.CMSCouponSpecs(
    coupon_frequency=p3m,
    tenor=p1y,
    float_leg=flt_spec,
    fixed_leg=fix_spec,
    notional=1.e6,
    coupon_basis=0.,
    coupon_multiplier=1.,
    businessday_rule=None,
    daycount_convention=instruments.DayCountConvention.ACTUAL_365)

cms = instruments.CMSSwap(
    start_date, maturity_date, [fix_spec],
    [cms_spec], dtype=dtype)

curve_dates = valuation_date + dates.years([0, 1, 2, 3, 5])
reference_curve = instruments.RateCurve(
    curve_dates,
    np.array([
        0.02, 0.02, 0.025, 0.03, 0.035
    ], dtype=np.float64),
    valuation_date=valuation_date,
    dtype=np.float64)
market = instruments.InterestRateMarket(
    reference_curve=reference_curve, discount_curve=reference_curve)

price = cms.price(valuation_date, market)
# Expected result: 16629.820479418966

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 cpntracts. The shape of the input correspond to the numbercof 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 list of either FixedCouponSpecs, FloatCouponSpecs or CMSCouponSpecs specifying the coupon payments for the payment leg of the swap. The length of the list should be the same as the number of instruments being created.

  • receive_leg: A list of either FixedCouponSpecs or FloatCouponSpecs or CMSCouponSpecs specifying the coupon payments for the receiving leg of the swap. The length of the list should be the same as the number of instruments being created.

  • 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 ‘cms_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: An optional input of type InterestRateModelType to specify the model to use for convexity correction while pricing individual swaplets of the cms swap. When model is InterestRateModelType.LOGNORMAL_SMILE_CONSISTENT_REPLICATION or InterestRateModelType.NORMAL_SMILE_CONSISTENT_REPLICATION, the function uses static replication (from lognormal and normal swaption implied volatility data respectively) as described in [1]. When model is InterestRateModelType.LOGNORMAL_RATE or InterestRateModelType.NORMAL_RATE, the function uses analytic approximations for the convexity adjustment based on lognormal and normal swaption rate dyanmics respectively [1]. Default value: None in which case convexity correction is not used.

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

References:#

[1]: Patrick S. Hagan. Convexity conundrums: Pricing cms swaps, caps and floors. WILMOTT magazine.

Contents