[lcrmorin]

rate can converge to an algebraic root below -100% for the cash flows in #126. This PR restricts accepted results to r > -1: it keeps Newton for ordinary cases and adds a bracket-search/bisection fallback when Newton converges at or below -1.

For the inputs matching the reported IRR cash flows, rate(8, 263175, -440000, 25500) returns approximately 0.583878 instead of -1.855744. For the original, different inputs, the result is approximately 1.671184 instead of -1.896442.

The fallback searches around the supplied guess, uses the remaining per-element iteration budget, and checks both bracket width and a scaled equation residual. It evaluates the zero-rate residual explicitly and uses log1p/expm1 for floating-point inputs. Nonfinite guesses and guesses at or below -1 now raise ValueError.

The fallback normalizes cash flows before evaluating the equation, so changing currency scale does not cause large finite Decimal inputs to be rejected. Bracket expansion continues in either direction when the other has reached its representable limit; bisection also detects when its endpoints are adjacent representable values and validates the residual before accepting a result.

Compatibility and scope

This intentionally excludes roots at or below -100%, which can be algebraically valid for integer periods but fall outside the positive compounding-factor model for conventional loans and annuities. Newton's intermediate steps are not constrained; this restriction applies to accepted results and the fallback search.

The change targets converged out-of-domain roots, rather than generally retrying Newton failures. Bracket discovery is heuristic: it may miss tangent roots and does not guarantee the root nearest the guess. If both search directions find brackets in the same expansion, the left bracket is selected first. The existing Newton stopping criterion is unchanged.

Validation

• Built and installed package: 140 tests pass on Python 3.14.7 / NumPy 2.5.4.
• Ruff, Pyright, and Mypy pass.
• Practitioner scenarios: a £250,000 mortgage over 25 years at nominal annual rates of 4% and 6%; a £15,000 personal loan over four years at 8%; and a £20,000 four-year loan at 7% with an £8,000 balloon. Both payment timings are covered. Unrounded payments are calculated independently with 60-digit Decimal arithmetic, then the recovered rate is checked using a month-by-month balance schedule to within one penny.
• 30 added cases in total also cover both issue reproductions with float and Decimal, discounted cash-flow residuals, broadcasting, mixed feasible/infeasible inputs, invalid guesses, and iteration limits. Extreme currency scales and bracket boundaries are secondary numerical stress tests.

Refs #126.

AI assistance was used to implement this change, run validation, and prepare this description.

[milliondreamsblog]

I checked an additional example against this PR's current head, 2fb0f61, and the fallback recovers the positive rate:

import numpy_financial as npf

print(npf.rate(10, 400, -1000, 0))
print(npf.irr([-1000] + [400] * 10))

With this PR's financial module:

0.3845481157302857
0.3845481952109686

Released 1.1.0 and current main return -1.8416830443720684 for the first call with the default guess. The inputs represent an initial payment of 1000 followed by ten receipts of 400, so the agreement with IRR is useful to check.

Could this go into the regression set if useful? The default-guess result is within 1e-6 of the independently computed IRR, and the discounted cash-flow residual is about 0.000184. Decimal inputs and a two-element broadcast of the same example also return the positive rate.

These were focused checks of the pinned source module on Python 3.13.5 / NumPy 2.5.3, not a full package build or test-suite run.

[lcrmorin]

I investigated the difference between the two results using a high-precision reference:

r = 0.384548195210968772655873676531…

The irr result is closer. The fallback in rate stops earlier because it meets the default tol=1e-6; its absolute error is about 7.95e-8. With tol=1e-12, that drops to about 1.46e-13.

So this is a stopping-tolerance difference. Your example would make a useful regression test: I’ll check it against the high-precision reference at both default and tighter tolerances.

[milliondreamsblog]

Thanks for checking it against the high-precision value. Testing it at both the default and a tighter tolerance sounds good to me.