explain multiple IRR problem; brentq grid search

Author: Anexen

README.md

@@ -38,7 +38,7 @@ Powered by [github-action-benchmark](https://github.com/rhysd/github-action-benc
 
 Live benchmarks are hosted on [Github Pages](https://anexen.github.io/pyxirr/bench).
 
-# Examples
+# Example
 
 ```python
 from datetime import date
@@ -59,6 +59,69 @@ xirr(dict(zip(dates, amounts)))
 xirr(['2020-01-01', '2021-01-01'], [-1000, 1200])
 ```
 
+# Multiple IRR problem
+
+The multiple internal rates of return problem occur when the signs of cash
+flows change more than once. In this case, we say that the project has
+non-conventional cash flows. This leads to situation, where it can have more
+the one (X)IRR or have no (X)IRR at all.
+
+PyXIRR's approach to the Multiple IRR problem: select the lowest IRR to be conservative
+
+```python
+import pandas as pd
+import pyxirr
+
+cf = pd.read_csv("tests/samples/30-22.csv", names=["date", "amount"])
+# check whether the cash flow is conventional:
+print(pyxirr.is_conventional_cash_flow(cf["amount"]))  # false
+
+r1 = pyxirr.xirr(cf)
+print("r1: ", r1)  # -0.31540826742734207
+# check using NPV
+print("XNPV(r1): ", pyxirr.xnpv(r1, cf)) # -2.3283064365386963e-10
+
+# the second root
+r2 = pyxirr.xirr(cf, guess=0.0)  # -0.028668460065441048
+print("r2: ", r2)
+print("XNPV(r2): ", pyxirr.xnpv(r2, cf))  # 0.0
+
+# print NPV profile
+import numpy as np
+
+rates = np.linspace(-0.5, 0.5, 50)
+values = pyxirr.xnpv(rates, cf)
+series = pd.Series(values, index=rates)
+
+print("Zero crossing points:")
+for idx in pyxirr.zero_crossing_points(values):
+    print(series.iloc[[idx, idx+1]])
+
+# NPV changes sign two times:
+#   1) between -0.316 and -0.295
+#   2) between -0.03 and -0.01
+
+print(series)
+# -0.500000   -8.962169e+08
+# ...
+# -0.336735   -5.895002e+05
+# -0.316327   -1.457451e+04
+# -0.295918    1.801890e+05
+# -0.275510    2.175858e+05
+# ...
+# -0.051020    2.612340e+03
+# -0.030612    1.857505e+02
+# -0.010204   -1.452180e+03
+#  0.010204   -2.533466e+03
+# ...
+#  0.500000   -2.358226e+03
+
+# plot NPV profile
+pd.DataFrame(series[series > -1e6]).assign(zero=0).plot()
+```
+
+# More Examples
+
 ### Numpy and Pandas
 
 ```python
@@ -99,6 +162,16 @@ xirr(dates, amounts, day_count=DayCount.ACT_360)
 xirr(dates, amounts, day_count="30E/360")
 ```
 
+### Private equity performance metrics
+
+```python
+from pyxirr import pe
+
+pe.pme_plus([-20, 15, 0], index=[100, 115, 130], nav=20)
+
+pe.direct_alpha([-20, 15, 0], index=[100, 115, 130], nav=20)
+```
+
 ### Other financial functions
 
 ```python

docs/functions.md

@@ -24,6 +24,20 @@ CashFlowDict = Dict[DateLike, Amount]
 CashFlow = Union[CashFlowSeries, CashFlowTable, CashFlowDict]
 ```
 
+## Multiple IRR problem
+
+The multiple internal rates of return problem occur when the signs of cash
+flows change more than once. In this case, we say that the project has
+non-conventional cash flows. This leads to situation, where it can have more
+the one (X)IRR or have no (X)IRR at all.
+
+PyXIRR's approach to the Multiple IRR problem: select the lowest IRR to be conservative
+
+See also:
+
+- <https://crystalsofeconomics.wordpress.com/2015/10/25/why-multiple-irr/>
+- <http://financialmanagementpro.com/multiple-irr-problem/>
+
 ## Day Count Conventions
 
 {% include_relative _inline/day_count_conventions.md %}

pyproject.toml

@@ -31,3 +31,13 @@ include = [
     { path = "Cargo.lock", format = "sdist" },
     { path = ".cargo/*", format = "sdist" },
 ]
+
+[tool.black]
+line-length = 79
+target-version = ["py311"]
+
+[tool.isort]
+profile = "black"
+atomic = true
+line_length = 79
+lines_after_imports = 2

python/pyxirr/_pyxirr.pyi

@@ -1,7 +1,7 @@
 import sys
+from collections.abc import Iterable, Sequence
 from datetime import date, datetime
 from decimal import Decimal
-from collections.abc import Iterable, Sequence
 from typing import (
     Any,
     Dict,
@@ -14,6 +14,7 @@ from typing import (
     overload,
 )
 
+
 if sys.version_info >= (3, 8):
     from typing import Literal, Protocol
 else:
@@ -130,7 +131,11 @@ _ArrayLike = Union[
     Sequence[Sequence[Sequence[Sequence[Sequence[_T]]]]],
     Sequence[Sequence[Sequence[Sequence[Sequence[Sequence[_T]]]]]],
     Sequence[Sequence[Sequence[Sequence[Sequence[Sequence[Sequence[_T]]]]]]],
-    Sequence[Sequence[Sequence[Sequence[Sequence[Sequence[Sequence[Sequence[_T]]]]]]]],
+    Sequence[
+        Sequence[
+            Sequence[Sequence[Sequence[Sequence[Sequence[Sequence[_T]]]]]]
+        ]
+    ],
 ]
 _ScalarOrArrayLike = Union[_T, _ArrayLike[_T]]
 
@@ -260,6 +265,7 @@ def pv(
     ...
 
 
+@overload
 def npv(
     rate: _Rate,
     amounts: _AmountArray,
@@ -269,6 +275,16 @@ def npv(
     ...
 
 
+@overload
+def npv(
+    rate: Iterable[_Rate],
+    amounts: _AmountArray,
+    *,
+    start_from_zero: bool = True,
+) -> List[Optional[float]]:
+    ...
+
+
 @overload
 def xnpv(
     rate: _Rate,
@@ -292,6 +308,17 @@ def xnpv(
     ...
 
 
+@overload
+def xnpv(
+    rate: Iterable[_Rate],
+    dates: _CashFlow,
+    *,
+    silent: bool = False,
+    day_count: _DayCount = DayCount.ACT_365F,
+) -> List[Optional[float]]:
+    ...
+
+
 @overload
 def rate(  # type: ignore[misc]
     nper: _Period,
@@ -482,3 +509,11 @@ def xirr(
     day_count: _DayCount = DayCount.ACT_365F,
 ) -> Optional[float]:
     ...
+
+
+def is_conventional_cash_flow(cf: _AmountArray) -> bool:
+    ...
+
+
+def zero_crossing_points(cf: _AmountArray) -> list[int]:
+    ...

src/core/mod.rs

@@ -7,5 +7,5 @@ mod scheduled;
 
 pub use models::{DateLike, InvalidPaymentsError};
 pub use periodic::*;
-pub use scheduled::{days_between, xfv, xirr, xnfv, xnpv, year_fraction, DayCount};
+pub use scheduled::*;
 pub mod private_equity;

src/core/models.rs

@@ -46,7 +46,7 @@ impl FromStr for DateLike {
 }
 
 /// An error returned when the payments do not contain both negative and positive payments.
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct InvalidPaymentsError(String);
 
 impl InvalidPaymentsError {

src/core/optimize.rs

@@ -1,7 +1,7 @@
 const MAX_ERROR: f64 = 1e-9;
 const MAX_ITERATIONS: u32 = 50;
 
-pub fn newton_raphson<Func, Deriv>(start: f64, f: Func, d: Deriv) -> f64
+pub fn newton_raphson<Func, Deriv>(start: f64, f: &Func, d: &Deriv) -> f64
 where
     Func: Fn(f64) -> f64,
     Deriv: Fn(f64) -> f64,
@@ -38,11 +38,12 @@ where
 
     // https://programmingpraxis.com/2012/01/13/excels-xirr-function/
 
-    newton_raphson(start, &f, |x: f64| (f(x + MAX_ERROR) - f(x - MAX_ERROR)) / (2.0 * MAX_ERROR))
+    let df = |x| (f(x + MAX_ERROR) - f(x - MAX_ERROR)) / (2.0 * MAX_ERROR);
+    newton_raphson(start, &f, &df)
 }
 
 // https://github.com/scipy/scipy/blob/39bf11b96f771dcecf332977fb2c7843a9fd55f2/scipy/optimize/Zeros/brentq.c
-pub fn brentq<Func>(f: Func, xa: f64, xb: f64, iter: usize) -> f64
+pub fn brentq<Func>(f: &Func, xa: f64, xb: f64, iter: usize) -> f64
 where
     Func: Fn(f64) -> f64,
 {
@@ -135,3 +136,16 @@ where
 
     f64::NAN
 }
+
+pub fn brentq_grid_search<'a, Func>(
+    breakpoints: &'a [&[f64]],
+    f: &'a Func,
+) -> impl Iterator<Item = f64> + 'a
+where
+    Func: Fn(f64) -> f64 + 'a,
+{
+    breakpoints
+        .into_iter()
+        .flat_map(|x| x.windows(2).map(|pair| brentq(f, pair[0], pair[1], 100)))
+        .filter(|r| r.is_finite() && f(*r).abs() < 1e-3)
+}

src/core/periodic.rs

@@ -4,7 +4,7 @@ use ndarray::{ArrayD, ArrayViewD};
 
 use super::{
     models::{validate, InvalidPaymentsError},
-    optimize::{brentq, newton_raphson, newton_raphson_with_default_deriv},
+    optimize::{brentq_grid_search, newton_raphson, newton_raphson_with_default_deriv},
 };
 use crate::{broadcast_together, broadcasting::BroadcastingError};
 
@@ -449,23 +449,13 @@ pub fn irr(values: &[f64], guess: Option<f64>) -> Result<f64, InvalidPaymentsErr
         return Ok(rate);
     }
 
-    #[rustfmt::skip]
-    let breakpoint_list = [
-        &[0.0, 0.5, 1.0, 1e9],
-        &[0.0, -0.5, -0.9, -0.99999999999999]
-    ];
+    // strategy: closest to zero
+    // let breakpoints: &[f64] = &[0.0, 0.25, -0.25, 0.5, -0.5, 1.0, -0.9, -0.99999999999999, 1e9];
+    // strategy: pessimistic
+    let breakpoints: &[f64] = &[-0.99999999999999, -0.75, -0.5, -0.25, 0., 0.25, 0.5, 1.0, 1e6];
+    let rate = brentq_grid_search(&[breakpoints], &f).next();
 
-    for breakpoints in breakpoint_list {
-        for pair in breakpoints.windows(2) {
-            let rate = brentq(f, pair[0], pair[1], 100);
-
-            if is_good_rate(rate) {
-                return Ok(rate);
-            }
-        }
-    }
-
-    Ok(f64::NAN)
+    Ok(rate.unwrap_or(f64::NAN))
 }
 
 pub fn mirr(

src/core/scheduled/mod.rs

@@ -3,5 +3,5 @@ mod xirr;
 mod xnfv;
 
 pub use day_count::{days_between, year_fraction, DayCount};
-pub use xirr::{xirr, xnpv};
-pub use xnfv::{xfv, xnfv};
+pub use xirr::*;
+pub use xnfv::*;