*Last updated: 2023-03-16.*
# tf_quant_finance.rates.analytics.cashflows.yields_from_pv
View source
Computes yields to maturity from present values of cashflows.
```python
tf_quant_finance.rates.analytics.cashflows.yields_from_pv(
cashflows, times, present_values, groups=None, tolerance=1e-08,
max_iterations=10, dtype=None, name=None
)
```
For a complete description of the terminology as well as the mathematics
of computing bond yields, see Ref [1]. Note that `yields` here refers
to the yield of the bond as defined in Section 4.4 of Ref [1]. This is
sometimes also referred to as the internal rate of return of a bond.
#### Example
The following example demonstrates the yield computation for two
bonds. Both bonds have 1000 face value with semi-annual coupons. The first
bond has 4% coupon rate and 2 year expiry. The second has 6% coupon rate and
3 year expiry. The true yields to maturity (ytm) are 7% and 5% respectively.
```python
dtype = np.float64
# The first element is the present value (PV) of the first bond and the
# second is the PV of the second bond.
present_values = np.array([942.71187528177757, 1025.7777300221542],
dtype=dtype)
# 2 and 3 year bonds with 1000 face value and 4%, 6% semi-annual coupons.
# Note that the first four entries in the cashflows are the cashflows of
# the first bond (group=0) and the next six are the cashflows of the second
# bond (group=1).
cashflows = np.array([20, 20, 20, 1020, 30, 30, 30, 30, 30, 1030],
dtype=dtype)
# The times of the cashflows.
times = np.array([0.5, 1, 1.5, 2, 0.5, 1, 1.50, 2, 2.5, 3], dtype=dtype)
# Group entries take values between 0 and 1 (inclusive) as there are two
# bonds. One needs to assign each of the cashflow entries to one group or
# the other.
groups = np.array([0] * 4 + [1] * 6)
# Expected yields = [0.07, 0.05]
yields = yields_from_pv(
cashflows, times, present_values, groups=groups, dtype=dtype)
```
#### References:
[1]: John C. Hull. Options, Futures and Other Derivatives. Ninth Edition.
June 2006.
#### Args:
* `cashflows`: Real rank 1 `Tensor` of size `n`. The set of cashflows underlying
the bonds.
* `times`: Real positive rank 1 `Tensor` of size `n`. The set of times at which
the corresponding cashflows occur quoted in years.
* `present_values`: Real rank 1 `Tensor` of size `k` where `k-1` is the maximum
value in the `groups` arg if supplied. If `groups` is not supplied, then
this is a `Tensor` of size `1`. The present values corresponding to each
of the cashflow groups. The `i`th component is the present value of all
the cashflows with group label `i` (or the present value of all the
cashflows if `groups=None`).
* `groups`: Optional int `Tensor` of size `n` containing values between 0 and
`k-1` where `k` is the number of related cashflows.
Default value: None. This implies that all the cashflows are treated as a
single group.
* `tolerance`: Positive real scalar `Tensor`. The tolerance for the estimated
yields. The yields are computed using a Newton root finder. The iterations
stop when the inferred yields change by less than this tolerance or the
maximum iterations are exhausted (whichever is earlier).
Default value: 1e-8.
* `max_iterations`: Positive scalar int `Tensor`. The maximum number of
iterations to use to compute the yields. The iterations stop when the max
iterations is exhausted or the tolerance is reached (whichever is
earlier). Supply `None` to remove the limit on the number of iterations.
Default value: 10.
* `dtype`: `tf.Dtype`. If supplied the dtype for the input and output `Tensor`s.
Default value: None which maps to the default dtype inferred from
`cashflows`.
* `name`: Python str. The name to give to the ops created by this function.
Default value: None which maps to 'yields_from_pv'.
#### Returns:
Real rank 1 `Tensor` of size `k`. The yield to maturity of the cashflows.
The `i`th component is the yield to maturity of the cashflows in group
`i`.