tf_quant_finance.rates.analytics.cashflows.yields_from_pv

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.

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.

  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 ith 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 Tensors. 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 ith component is the yield to maturity of the cashflows in group i.

Contents