*Last updated: 2023-03-16.*
# tf_quant_finance.experimental.instruments.Bond
View source
Represents a batch of fixed coupon bonds.
```python
tf_quant_finance.experimental.instruments.Bond(
settlement_date, maturity_date, coupon_spec, start_date=None,
first_coupon_date=None, penultimate_coupon_date=None, holiday_calendar=None,
dtype=None, name=None
)
```
Bonds are fixed income securities where the issuer makes periodic payments
(or coupons) on a principal amount (also known as the face value) based on a
fixed annualized interest rate. The payments are made periodically (for
example quarterly or semi-annually) where the last payment is typically made
at the maturity (or termination) of the contract at which time the principal
is also paid back.
For example, consider a fixed rate bond with settlement 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 coupon accrual begins on T_0, T_1, ..., T_(n-1) and the payments are made
on T_1, T_2, ..., T_n (payment dates). The principal is also paid at T_n.
The Bond class can be used to create and price multiple bond securities
simultaneously. However all bonds within a Bond object must be priced using
a common reference and 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
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=rc.DayCountConvention.ACTUAL_365,
businessday_rule=dates.BusinessDayConvention.NONE)
flt_spec = instruments.FloatCouponSpecs(
coupon_frequency=periods_3m, reference_rate_term=periods_3m,
reset_frequency=periods_3m, currency='usd', notional=1.,
businessday_rule=dates.BusinessDayConvention.NONE,
coupon_basis=0., coupon_multiplier=1.,
daycount_convention=rc.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),
dtype=dtype)
market = instruments.InterestRateMarket(
reference_curve=reference_curve, discount_curve=reference_curve)
price = swap.price(valuation_date, market)
# Expected result: 1e-7
```
#### References:
[1]: Leif B.G. Andersen and Vladimir V. Piterbarg. Interest Rate Modeling,
Volume I: Foundations and Vanilla Models. Chapter 5. 2010.
#### Args:
* `settlement_date`: A rank 1 `DateTensor` specifying the settlement date of
the bonds.
* `maturity_date`: A rank 1 `DateTensor` specifying the maturity dates of the
bonds. The shape of the input should be the same as that of
`settlement_date`.
* `coupon_spec`: A list of `FixedCouponSpecs` specifying the coupon payments.
The length of the list should be the same as the number of bonds
being created.
* `start_date`: An optional `DateTensor` specifying the dates when the
interest starts to accrue for the coupons. The input can be used to
specify a forward start date for the coupons. The shape of the input
correspond to the numbercof instruments being created.
Default value: None in which case the coupons start to accrue from the
`settlement_date`.
* `first_coupon_date`: An optional rank 1 `DateTensor` specifying the dates
when first coupon will be paid for bonds with irregular first coupon.
* `penultimate_coupon_date`: An optional rank 1 `DateTensor` specifying the
dates when the penultimate coupon (or last regular coupon) will be paid
for bonds with irregular last coupon.
* `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 bond object or created by the bond 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 'bond'.
## Methods
price
View source
```python
price(
valuation_date, market, model=None, name=None
)
```
Returns the dirty price of the bonds 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 bonds.
* `model`: Reserved for future use.
* `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 dtype containing the dirty price of each bond
based on the input market data.