NumPy is full of those little helper functions that boost your productivity and make coding a lot of fun. The NumPy’s `fv()`

function is one of those helpers for financial analysis that will save you a lot of time if you’re working in the financial sector—or if you’re just using NumPy to analyze your own financial assets.

## What’s the Purpose of the np.fv() Function?

It computes the future value of an asset assuming you know the growth rate of the asset (its *return on investment*), the size of your regular contributions, and the duration of the investment period.

## How Does the numpy.fv() Function Work?

Let’s check out the specification with all arguments. We assume that you expect to earn a 9% stock market return over 30 years, starting with an initial $1,000 without any regular contributions.

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

`rate`

: your return on investment. For example, stocks may have a historic return on investment of 9%. As an input, you give the respective floating point value: a return of 9% becomes`rate=0.09`

.`nper`

: the number of periods you compound your investment. For example, to calculate the 30-year return on investment, you’d use the input argument`nper=30`

.`pmt`

: the additional payments you contribute during your investment period. If you want to calculate the future value of a one-time investment, you’d use the input argument`pmt=0`

. If you want to calculate the future value of an investment where you contribute $1,000 per year, you’d use the input argument`pmt=-1000`

. An important note is that the input argument is, per convention, as contributing money to your investment would incur a negative cash flow pattern from the perspective of your cash accounts.**negative**`pv`

: the present value of your investment or asset. This is the starting point that will get compounded over the number of periods. If you start with $1,000 as an initial investment, you’d use the input argument`pv=-1000`

. Again, note that the input argument is negative because of the negative cash flow pattern you’ll experience when transferring cash into your investment.`when`

: represents when the payment is due—at the end of a period or at the beginning. If your payment is due at the beginning of a period, you’d use the input argument`when='begin'`

, otherwise you’d use`when='end'`

. This argument is**optional**.

Here’s an example of how you can calculate the future value of an investment into the stock market earning 9% yearly return over 30 years starting with an initial investment of $1,000:

>>> np.fv(0.09, 30, 0, -1000) 13267.678469131277

Your initial $1,000 investment would result in a whopping $13,267.68—time to get your investments going!

Note that an equivalent way of calculating the same thing in Python would be the following:

>>> 1000 * (1+0.09)**30 13267.678469131277

The `np.fv()`

function is just a convenient way of doing it. If you’ve got regular contributions, however, there’s no simple formula like this and I’d recommend you use the NumPy’s future value function `np.fv()`

.

## How to Plot the Future Value of an Investment?

We used the following code to plot the future value of the initial investment over the next 30 years:

import numpy as np import matplotlib.pyplot as plt y = [np.fv(0.09, i, 0, -1000) for i in range(30)] plt.plot(y) plt.ylabel("Investment Value") plt.xlabel("Years") plt.savefig("return.jpeg") plt.show()

You can try it yourself in our interactive Python shell:

## What Errors You Can Get?

The investment rate of the NumPy future value function `np.fv()`

cannot be zero. Otherwise, you’d get the following error:

import numpy as np y = np.fv(0, 30, 0, -1000) print(y) """ Warning (from warnings module): File "C:\Users\xcent\AppData\Local\Programs\Python\Python37\lib\site-packages\numpy\lib\financial.py", line 137 (1 + rate*when)*(temp - 1)/rate) RuntimeWarning: invalid value encountered in long_scalars """

## Which Formula is Used to Calculate the Future Value?

NumPy solves the following equation to calculate the future value of the investment:

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

Can you see why we use negative values for the initial investment `pv`

and the regular payments `pmt`

?