tf_quant_finance.rates.analytics.cashflows.pv_from_yields

Last updated: 2023-03-16.

tf_quant_finance.rates.analytics.cashflows.pv_from_yields#

View source

Computes present value of cashflows given yields.

tf_quant_finance.rates.analytics.cashflows.pv_from_yields(
    cashflows, times, yields, groups=None, dtype=None, name=None
)

For a more complete description of the terminology as well as the mathematics of pricing bonds, see Ref [1]. In particular, 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 present value 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 yields to maturity (ytm) are 7% and 5% respectively.

  dtype = np.float64

  # The first element is the ytm of the first bond and the second is the
  # yield of the second bond.
  yields_to_maturity = np.array([0.07, 0.05], 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)

  # Produces [942.712, 1025.778] as the values of the two bonds.
  present_values = pv_from_yields(
      cashflows, times, yields_to_maturity, 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.

  • yields: Real rank 1 Tensor of size 1 if groups is None or of size k if the maximum value in the groups is of k-1. The continuously compounded yields to maturity/internal rate of returns corresponding to each of the cashflow groups. The ith component is the yield to apply to all the cashflows with group label i if groups is not None. If groups is None, then this is a Tensor of size [1] and the only component is the yield that applies to all the cashflows.

  • 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.

  • 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 ‘pv_from_yields’.

Returns:#

Real rank 1 Tensor of size k if groups is not None else of size [1]. The present value of the cashflows. The ith component is the present value of the cashflows in group i or to the entirety of the cashflows if groups is None.

Contents