*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/InterestRateSwap.md)
```python
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.
```python
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
```python
annuity(
valuation_date, market, model=None
)
```
Returns the annuity of each swap on the vauation date.
par_rate
View source
```python
par_rate(
valuation_date, market, model=None
)
```
Returns the par swap rate for the swap.
price
View source
```python
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.