Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(quantlib): survive long-horizon discount underflow in xirr and money-weighted return

Haozhe Wu51df06eeec35
diff --git a/agent/src/quantlib/performance.py b/agent/src/quantlib/performance.py
index 72e771ed4..6cec91170 100644
--- a/agent/src/quantlib/performance.py
+++ b/agent/src/quantlib/performance.py
@@ -147,6 +147,13 @@ _IRR_TOLERANCE = 1e-12
#: Hard iteration cap for the bisection, so a pathological input cannot spin.
_IRR_MAX_ITERATIONS = 400
+#: Magnitude returned in place of a diverging NPV term. At ``base`` just above
+#: zero and a horizon beyond ~51 years the discount factor underflows to 0.0 and
+#: the true term diverges to +/-inf. The bisection compares signs only, so a
+#: sign-preserving finite stand-in keeps the bracketing exact without letting
+#: :func:`math.fsum` overflow.
+_NPV_DIVERGED_MAGNITUDE = 1e300
+
class UnsolvableRateError(ValueError):
"""Raised when a cash-flow stream admits no single internal rate of return."""
@@ -715,15 +722,44 @@ def _npv(rate: float, years: Sequence[float], amounts: Sequence[float]) -> float
Returns:
The discounted sum. A term whose discount factor overflows to beyond
the float range contributes ``0.0``, which is its limit, rather than
- raising and aborting the search.
+ raising and aborting the search. A term whose discount factor
+ *underflows* to ``0.0`` -- or stays subnormal long enough that the
+ term itself leaves the float range -- diverges to +/-inf in truth;
+ such terms are represented by a sign-preserving stand-in of magnitude
+ :data:`_NPV_DIVERGED_MAGNITUDE`, which dominates every finite term
+ exactly as the limit does while keeping ``fsum`` finite.
"""
base = 1.0 + rate
terms: list[float] = []
+ diverged: dict[float, float] = {}
for exponent, amount in zip(years, amounts, strict=True):
try:
- terms.append(amount / (base**exponent))
+ factor = base**exponent
except OverflowError:
terms.append(0.0)
+ continue
+ if factor == 0.0:
+ # Underflow: the true term is infinite, so only its sign and its
+ # exponent rank matter. Group by exponent first, so several terms
+ # that share the largest exponent can still cancel before the sign
+ # of the limit is decided.
+ diverged[exponent] = diverged.get(exponent, 0.0) + amount
+ continue
+ term = amount / factor
+ if not math.isfinite(term):
+ # A subnormal factor (a horizon just short of the underflow point)
+ # can still push the term past the float range. It diverges in
+ # exactly the same sense and is grouped the same way; leaving it in
+ # ``terms`` would hand ``fsum`` an infinity and, with two opposite
+ # signs, raise ``-inf + inf in fsum``.
+ diverged[exponent] = diverged.get(exponent, 0.0) + amount
+ continue
+ terms.append(term)
+
+ for exponent in sorted(diverged, reverse=True):
+ grouped = diverged[exponent]
+ if grouped != 0.0:
+ return math.copysign(_NPV_DIVERGED_MAGNITUDE, grouped)
return math.fsum(terms)
diff --git a/agent/tests/quantlib/test_performance.py b/agent/tests/quantlib/test_performance.py
index c95a6fa0d..9b2f3c6a0 100644
--- a/agent/tests/quantlib/test_performance.py
+++ b/agent/tests/quantlib/test_performance.py
@@ -352,6 +352,73 @@ def test_xirr_discounts_by_actual_days() -> None:
assert (1.0 + half_year) ** (182 / 365) == pytest.approx(1.10, rel=1e-6)
+def test_xirr_survives_a_horizon_that_underflows_the_discount_factor() -> None:
+ """Sixty years underflows the factor at the solver's lower bracket.
+
+ The bisection starts just above -100%, where a 60-year discount factor
+ (``1e-6 ** 60 ~ 1e-360``) underflows to zero and the term diverges. The
+ search must still return the exact flat rate the dates imply,
+ ``3 ** (365 / 21915) - 1``, instead of crashing with a division by zero.
+ """
+ start, end = date(1965, 1, 1), date(2025, 1, 1)
+ days = (end - start).days # 21915 calendar days, 15 leap days included
+ rate = xirr([(start, -1000.0), (end, 3000.0)])
+ assert rate == pytest.approx(3.0 ** (365.0 / days) - 1.0, rel=1e-9)
+
+
+def test_a_long_horizon_loss_still_solves_to_a_negative_rate() -> None:
+ """The underflow stand-in must not flip the sign of a losing stream."""
+ start, end = date(1965, 1, 1), date(2025, 1, 1)
+ days = (end - start).days
+ rate = xirr([(start, -1000.0), (end, 500.0)])
+ assert rate == pytest.approx(0.5 ** (365.0 / days) - 1.0, rel=1e-9)
+
+
+def test_money_weighted_return_survives_the_same_long_horizon() -> None:
+ """The money-weighted path shares the NPV kernel and must not crash either."""
+ start, end = date(1965, 1, 1), date(2025, 1, 1)
+ result = money_weighted_return([(start, 1000.0), (end, 3000.0)])
+ assert result.period_return == pytest.approx(2.0, abs=1e-9)
+ assert result.annualized_return == pytest.approx(
+ 3.0 ** (365.0 / (end - start).days) - 1.0, rel=1e-9
+ )
+
+
+def test_xirr_survives_a_horizon_in_the_subnormal_discount_window() -> None:
+ """~52 years leaves the discount factor subnormal rather than zero.
+
+ At the lower bracket ``1e-6 ** 52 ~ 6e-313`` is a denormal, so the closing
+ term overflows to infinity before the factor underflows. The result must
+ still be the exact flat rate, and must not depend on ``fsum`` tolerating
+ infinity on any given platform.
+ """
+ start, end = date(1965, 1, 1), date(2017, 1, 1)
+ days = (end - start).days
+ rate = xirr([(start, -1000.0), (end, 3000.0)])
+ assert rate == pytest.approx(3.0 ** (365.0 / days) - 1.0, rel=1e-9)
+
+
+def test_long_horizon_opposite_signed_terms_do_not_cancel_to_nan() -> None:
+ """Two subnormal-window terms must resolve to the latest-dated flow.
+
+ With both the 2016 and 2017 terms overflowing, the old kernel sums
+ ``-inf + inf = nan`` and the bisection silently walks to its upper bracket.
+ Grouping diverging terms by exponent keeps the latest-dated flow dominant,
+ exactly as the limit requires, and the solver must return the rate that
+ zeroes the stream.
+ """
+ start, mid, end = date(1965, 1, 1), date(2016, 1, 1), date(2017, 1, 1)
+ rate = xirr([(start, -1000.0), (mid, -500.0), (end, 2000.0)])
+ years = [(day - start).days / 365.0 for day in (start, mid, end)]
+ residual = (
+ -1000.0
+ - 500.0 / (1.0 + rate) ** years[1]
+ + 2000.0 / (1.0 + rate) ** years[2]
+ )
+ assert abs(residual) < 1e-6
+ assert 0.0 < rate < 1.0
+
+
def test_a_one_directional_stream_has_no_irr() -> None:
"""Refusing is correct; there is no rate that zeroes an all-negative NPV."""
with pytest.raises(UnsolvableRateError, match="one-directional"):