Merge pull request #62 from 101AlexMartin/irr-fix

Small addition to IRR function

Author: Kai-Striega

numpy_financial/_financial.py

@@ -17,7 +17,8 @@
 import numpy as np
 
 __all__ = ['fv', 'pmt', 'nper', 'ipmt', 'ppmt', 'pv', 'rate',
-           'irr', 'npv', 'mirr']
+           'irr', 'npv', 'mirr',
+           'NoRealSolutionException', 'IterationsExceededException']
 
 _when_to_num = {'end': 0, 'begin': 1,
                 'e': 0, 'b': 1,
@@ -26,6 +27,18 @@
                 'start': 1,
                 'finish': 0}
 
+# Define custom Exceptions
+
+class NoRealSolutionException(Exception):
+    """ No real solution to the problem. """
+
+    pass
+
+class IterationsExceededException(Exception):
+    """ Maximum number of iterations reached. """
+
+    pass
+
 
 def _convert_when(when):
     # Test to see if when has already been converted to ndarray
@@ -598,7 +611,7 @@ def _g_div_gp(r, n, p, x, y, w):
 #     where
 #  g(r) is the formula
 #  g'(r) is the derivative with respect to r.
-def rate(nper, pmt, pv, fv, when='end', guess=None, tol=None, maxiter=100):
+def rate(nper, pmt, pv, fv, when='end', guess=None, tol=None, maxiter=100, *, raise_exceptions=False):
     """
     Compute the rate of interest per period.
 
@@ -620,6 +633,11 @@ def rate(nper, pmt, pv, fv, when='end', guess=None, tol=None, maxiter=100):
         Required tolerance for the solution, default 1e-6
     maxiter : int, optional
         Maximum iterations in finding the solution
+    raise_exceptions: bool, optional
+        Flag to raise an exception when at least one of the rates
+        cannot be computed due to having reached the maximum number of
+        iterations (IterationsExceededException). Set to False as default,
+        thus returning NaNs for those rates.
 
     Notes
     -----
@@ -666,15 +684,20 @@ def rate(nper, pmt, pv, fv, when='end', guess=None, tol=None, maxiter=100):
 
     if not np.all(close):
         if np.isscalar(rn):
+            if raise_exceptions:
+                raise IterationsExceededException('Maximum number of iterations exceeded.')
             return default_type(np.nan)
         else:
             # Return nan's in array of the same shape as rn
             # where the solution is not close to tol.
+            if raise_exceptions:
+                raise IterationsExceededException(f'Maximum number of iterations exceeded in '
+                                                  f'{len(close)-close.sum()} rate(s).')
             rn[~close] = np.nan
     return rn
 
 
-def irr(values, guess=None, tol=1e-12, maxiter=100):
+def irr(values, guess=None, *, tol=1e-12, maxiter=100, raise_exceptions=False):
     """
     Return the Internal Rate of Return (IRR).
 
@@ -699,6 +722,12 @@ def irr(values, guess=None, tol=1e-12, maxiter=100):
         Required tolerance to accept solution. Default is 1e-12.
     maxiter : int, optional
         Maximum iterations to perform in finding a solution. Default is 100.
+    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.
 
     Returns
     -------
@@ -753,6 +782,9 @@ def irr(values, guess=None, tol=1e-12, maxiter=100):
     # we don't perform any further calculations and exit early
     same_sign = np.all(values > 0) if values[0] > 0 else np.all(values < 0)
     if same_sign:
+        if raise_exceptions:
+            raise NoRealSolutionException('No real solution exists for IRR since all '
+                                          'cashflows are of the same sign.')
         return np.nan
 
     # If no value is passed for `guess`, then make a heuristic estimate
@@ -789,6 +821,9 @@ def irr(values, guess=None, tol=1e-12, maxiter=100):
             return g - 1
         g -= delta
 
+    if raise_exceptions:
+        raise IterationsExceededException('Maximum number of iterations exceeded.')
+
     return np.nan
 
 
@@ -871,7 +906,7 @@ def npv(rate, values):
         return npv
 
 
-def mirr(values, finance_rate, reinvest_rate):
+def mirr(values, finance_rate, reinvest_rate, *, raise_exceptions=False):
     """
     Modified internal rate of return.
 
@@ -885,6 +920,11 @@ def mirr(values, finance_rate, reinvest_rate):
         Interest rate paid on the cash flows
     reinvest_rate : scalar
         Interest rate received on the cash flows upon reinvestment
+    raise_exceptions: bool, optional
+        Flag to raise an exception when the mirr cannot be computed due to
+        having all cashflows of the same sign (NoRealSolutionException).
+        Set to False as default, thus returning NaNs in the previous
+        case.
 
     Returns
     -------
@@ -904,6 +944,9 @@ def mirr(values, finance_rate, reinvest_rate):
     pos = values > 0
     neg = values < 0
     if not (pos.any() and neg.any()):
+        if raise_exceptions:
+            raise NoRealSolutionException('No real solution exists for MIRR since'
+                                          ' all cashflows are of the same sign.')
         return np.nan
     numer = np.abs(npv(reinvest_rate, values*pos))
     denom = np.abs(npv(finance_rate, values*neg))

numpy_financial/tests/test_financial.py

@@ -5,7 +5,7 @@
 # the versions in numpy instead of numpy_financial.
 import numpy
 from numpy.testing import (
-    assert_, assert_almost_equal, assert_allclose, assert_equal
+    assert_, assert_almost_equal, assert_allclose, assert_equal, assert_raises
     )
 import pytest
 
@@ -136,6 +136,26 @@ def test_gh48(self):
         actual = npf.rate(nper, pmt, pv, fv)
         assert_allclose(actual, des)
 
+    def test_rate_maximum_iterations_exception_scalar(self):
+        # Test that if the maximum number of iterations is reached,
+        # then npf.rate returns IterationsExceededException
+        # when raise_exceptions is set to True.
+        assert_raises(npf.IterationsExceededException, npf.rate, Decimal(12.0),
+                      Decimal(400.0), Decimal(10000.0), Decimal(5000.0),
+                      raise_exceptions=True)
+
+    def test_rate_maximum_iterations_exception_array(self):
+        # Test that if the maximum number of iterations is reached in at least
+        # one rate, then npf.rate returns IterationsExceededException
+        # when raise_exceptions is set to True.
+        nper = 2
+        pmt = 0
+        pv = [-593.06, -4725.38, -662.05, -428.78, -13.65]
+        fv = [214.07, 4509.97, 224.11, 686.29, -329.67]
+        assert_raises(npf.IterationsExceededException, npf.rate, nper,
+                      pmt, pv, fv,
+                      raise_exceptions=True)
+
 
 class TestNpv:
     def test_npv(self):
@@ -248,6 +268,13 @@ def test_mirr_decimal(self):
                Decimal('37000'), Decimal('46000')]
         assert_(numpy.isnan(npf.mirr(val, Decimal('0.10'), Decimal('0.12'))))
 
+    def test_mirr_no_real_solution_exception(self):
+        # Test that if there is no solution because all the cashflows
+        # have the same sign, then npf.mirr returns NoRealSolutionException
+        # when raise_exceptions is set to True.
+        val = [39000, 30000, 21000, 37000, 46000]
+        assert_raises(npf.NoRealSolutionException, npf.mirr, val, 0.10, 0.12, raise_exceptions=True)
+
 
 class TestNper:
     def test_basic_values(self):
@@ -575,6 +602,7 @@ def test_some_rates_zero(self):
 
 
 class TestIrr:
+
     def test_npv_irr_congruence(self):
         # IRR is defined as the rate required for the present value of
         # a series of cashflows to be zero, so we should have
@@ -671,3 +699,18 @@ def test_gh_44(self):
         # "true" value as calculated by Google sheets
         cf = [-1678.87, 771.96, 1814.05, 3520.30, 3552.95, 3584.99, 4789.91, -1]
         assert_almost_equal(npf.irr(cf), 1.00426, 4)
+
+    def test_irr_no_real_solution_exception(self):
+        # Test that if there is no solution because all the cashflows
+        # have the same sign, then npf.irr returns NoRealSolutionException
+        # when raise_exceptions is set to True.
+        cashflows = numpy.array([40000, 5000, 8000, 12000, 30000])
+        assert_raises(npf.NoRealSolutionException, npf.irr, cashflows, raise_exceptions=True)
+
+    def test_irr_maximum_iterations_exception(self):
+        # Test that if the maximum number of iterations is reached,
+        # then npf.irr returns IterationsExceededException
+        # when raise_exceptions is set to True.
+        cashflows = numpy.array([-40000, 5000, 8000, 12000, 30000])
+        assert_raises(npf.IterationsExceededException, npf.irr, cashflows,
+                      maxiter=1, raise_exceptions=True)