numpy_financial.irr

numpy_financial.irr(values: ~collections.abc.Sequence[float | ~numpy.float64 | ~numpy.float32 | ~numpy.float16 | ~numpy.integer[~typing.Any] | ~numpy.bool], *, raise_exceptions: bool = False, selection_logic: ~typing.Callable[[~numpy._typing._array_like.NDArray[~numpy.float64]], ~numpy._typing._array_like.NDArray[~numpy.float64]] = <function _irr_default_selection>) → float

numpy_financial.irr(values: ~collections.abc.Sequence[~collections.abc.Sequence[float | ~numpy.float64 | ~numpy.float32 | ~numpy.float16 | ~numpy.integer[~typing.Any] | ~numpy.bool]], *, raise_exceptions: bool = False, selection_logic: ~typing.Callable[[~numpy._typing._array_like.NDArray[~numpy.float64]], ~numpy._typing._array_like.NDArray[~numpy.float64]] = <function _irr_default_selection>) → NDArray[float64]

numpy_financial.irr(values: ~numpy._typing._array_like.ArrayLike | ~numpy._typing._nested_sequence._NestedSequence[~decimal.Decimal] | ~decimal.Decimal, *, raise_exceptions: bool = False, selection_logic: ~typing.Callable[[~numpy._typing._array_like.NDArray[~numpy.float64]], ~numpy._typing._array_like.NDArray[~numpy.float64]] = <function _irr_default_selection>) → Any

Return the Internal Rate of Return (IRR).

This is the “average” periodically compounded rate of return that gives a net present value of 0.0; for a more complete explanation, see Notes below.

decimal.Decimal type is not supported.

Parameters:

valuesarray_like, shape(N,)

Input cash flows per time period. By convention, net “deposits” are negative and net “withdrawals” are positive. Thus, for example, at least the first element of values, which represents the initial investment, will typically be negative.

raise_exceptions: bool, optional

Flag to raise an exception when the irr cannot be computed due to either having all cashflows of the same sign (NoRealSolutionException) or having reached the maximum number of iterations (IterationsExceededException). Set to False as default, thus returning NaNs in the two previous cases.

selection_logic: function, optional

Function for selection logic when more than 1 real solutions is found. User may insert their own customised function for selection of IRR values.The function should accept a one-dimensional array of numbers and return a number.

Returns:

outfloat

Internal Rate of Return for periodic input values.

Notes

The IRR is perhaps best understood through an example (illustrated using np.irr in the Examples section below). Suppose one invests 100 units and then makes the following withdrawals at regular (fixed) intervals: 39, 59, 55, 20. Assuming the ending value is 0, one’s 100 unit investment yields 173 units; however, due to the combination of compounding and the periodic withdrawals, the “average” rate of return is neither simply 0.73/4 nor (1.73)^0.25-1. Rather, it is the solution (for \(r\)) of the equation:

\[\begin{split}-100 + \\frac{39}{1+r} + \\frac{59}{(1+r)^2} + \\frac{55}{(1+r)^3} + \\frac{20}{(1+r)^4} = 0\end{split}\]

In general, for values \(= [v_0, v_1, ... v_M]\), irr is the solution of the equation: [G]

\[\begin{split}\\sum_{t=0}^M{\\frac{v_t}{(1+irr)^{t}}} = 0\end{split}\]

References

[G]

L. J. Gitman, “Principles of Managerial Finance, Brief,” 3rd ed., Addison-Wesley, 2003, pg. 348.

Examples

>>> import numpy_financial as npf

>>> round(npf.irr([-100, 39, 59, 55, 20]), 5)
0.28095
>>> round(npf.irr([-100, 0, 0, 74]), 5)
-0.0955
>>> round(npf.irr([-100, 100, 0, -7]), 5)
-0.0833
>>> round(npf.irr([-100, 100, 0, 7]), 5)
0.06206
>>> round(npf.irr([-5, 10.5, 1, -8, 1]), 5)
0.0886
>>> npf.irr([[-100, 0, 0, 74], [-100, 100, 0, 7]]).round(5)
array([-0.0955 ,  0.06206])