This is documentation for an old release of NumPy (version 1.18). Read this page Search for this page in the documentation of the latest stable release (version 2.2).

numpy.fv

numpy.fv(rate, nper, pmt, pv, when='end')

Compute the future value.

Deprecated since version 1.18: fv is deprecated; for details, see NEP 32 [1]. Use the corresponding function in the numpy-financial library, https://pypi.org/project/numpy-financial.

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

1

NumPy Enhancement Proposal (NEP) 32, https://numpy.org/neps/nep-0032-remove-financial-functions.html

2

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

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?

>>>

>>> np.fv(0.05/12, 10*12, -100, -100)
15692.928894335748

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
>>> np.fv(a, 10*12, -100, -100)
array([ 15692.92889434,  16569.87435405,  17509.44688102]) # may vary