numpy_financial.fv#

numpy_financial.fv(rate: float | float64, nper: float | float64 | float32 | float16 | integer[Any] | bool, pmt: float | float64 | float32 | float16 | integer[Any] | bool, pv: float | float64 | float32 | float16 | integer[Any] | bool, when: str | int | NDArray[Any] | Iterable[str | int] = 'end') → float#
numpy_financial.fv(rate: Decimal, nper: Decimal | int, pmt: Decimal | int, pv: Decimal | int, when: str | int | NDArray[Any] | Iterable[str | int] = 'end') → Decimal
numpy_financial.fv(rate: _CanArrayAndLen[float64] | Sequence[float | float64], nper: float | _CanArray[float64 | float32 | float16 | integer[Any] | bool] | Sequence[float | float64 | float32 | float16 | integer[Any] | bool], pmt: float | _CanArray[float64 | float32 | float16 | integer[Any] | bool] | Sequence[float | float64 | float32 | float16 | integer[Any] | bool], pv: float | _CanArray[float64 | float32 | float16 | integer[Any] | bool] | Sequence[float | float64 | float32 | float16 | integer[Any] | bool], when: str | int | NDArray[Any] | Iterable[str | int] = 'end') → NDArray[float64]
numpy_financial.fv(rate: ArrayLike | _NestedSequence[Decimal] | Decimal, nper: ArrayLike | _NestedSequence[Decimal] | Decimal, pmt: ArrayLike | _NestedSequence[Decimal] | Decimal, pv: ArrayLike | _NestedSequence[Decimal] | Decimal, when: str | int | NDArray[Any] | Iterable[str | int] = 'end') → Any

Compute the future value.

Given:

  • a present value, pv

  • an interest rate compounded once per period, of which there are

  • nper total

  • a (fixed) payment, pmt, paid either

  • at the beginning (when = {‘begin’, 1}) or the end (when = {‘end’, 0}) of each period

Return:

the value at the end of the nper periods

Parameters:
ratescalar or array_like of shape(M, )

Rate of interest as decimal (not per cent) per period

nperscalar or array_like of shape(M, )

Number of compounding periods

pmtscalar or array_like of shape(M, )

Payment

pvscalar or array_like of shape(M, )

Present value

when{{‘begin’, 1}, {‘end’, 0}}, {string, int}, optional

When payments are due (‘begin’ (1) or ‘end’ (0)). Defaults to {‘end’, 0}.

Returns:
outndarray

Future values. If all input is scalar, returns a scalar float. If any input is array_like, returns future values for each input element. If multiple inputs are array_like, they all must have the same shape.

Notes

The future value is computed by solving the equation:

fv +
pv*(1+rate)**nper +
pmt*(1 + rate*when)/rate*((1 + rate)**nper - 1) == 0

or, when rate == 0:

fv + pv + pmt * nper == 0

References

[WRW]

Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May). Open Document Format for Office Applications (OpenDocument)v1.2, Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version, Pre-Draft 12. Organization for the Advancement of Structured Information Standards (OASIS). Billerica, MA, USA. [ODT Document]. Available: http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formula OpenDocument-formula-20090508.odt

Examples

>>> import numpy as np
>>> import numpy_financial as npf

What is the future value after 10 years of saving $100 now, with an additional monthly savings of $100. Assume the interest rate is 5% (annually) compounded monthly?

>>> npf.fv(0.05/12, 10*12, -100, -100)
15692.92889433575

By convention, the negative sign represents cash flow out (i.e. money not available today). Thus, saving $100 a month at 5% annual interest leads to $15,692.93 available to spend in 10 years.

If any input is array_like, returns an array of equal shape. Let’s compare different interest rates from the example above.

>>> a = np.array((0.05, 0.06, 0.07))/12
>>> npf.fv(a, 10*12, -100, -100)
array([15692.92889434, 16569.87435405, 17509.44688102])
On this page