*Last updated: 2023-03-16.*
# tf_quant_finance.experimental.instruments.CapAndFloor
View source
Represents a batch of Caps and/or Floors.
```python
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.
```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
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
```python
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.