Skip to content

Define empty cashflow policy for IRR and PV - #56

Merged
alecloudenback merged 21 commits into
mainfrom
fix/empty-cashflow-policy
Sep 30, 2026
Merged

alecloudenback merged 21 commits into
mainfrom
fix/empty-cashflow-policy

Conversation

@alecloudenback

@alecloudenback alecloudenback commented Aug 23, 2026 •

Copy link
Copy Markdown
Member

End-state summary and rationale

This PR defines consistent empty-stream semantics, makes IRR calculations and sensitivities more reliable, and simplifies the shared implementation. This summary describes the final behavior at 9ab7186; the detailed change history and verification remain below.

Situation End-state behavior Plain-language rationale
Present value of an empty stream Exactly zero (positive zero) No payments means no value. An empty policy or portfolio should work naturally in aggregation.
Numeric type of that zero Follows the amount, time and discounting types; when the collection provides no useful type, the rate or curve supplies it An empty book should preserve the valuation's precision and automatic-differentiation compatibility instead of arbitrarily becoming Float64 or throwing because its container is abstract.
IRR of an empty or all-zero stream nothing Every rate satisfies the pricing equation, so the cashflows identify no particular return. Returning 0% would invent an answer. This preserves released behavior.
IRR sensitivity at a repeated or numerically singular root Throws an ArgumentError The return is not locally determined well enough to report a reliable sensitivity. A plausible-looking number would mislead.

The other substantive changes are:

  • IRR handles economically irrelevant details more reliably. Zero payments no longer distort the solver's time origin. Moving [-100, 110] from years [0, 1] to [1000, 1001] still gives 10%. Integer times are subtracted before conversion to floating point, preserving one-period differences beyond 2^53.
  • Extreme amounts no longer trick Newton into accepting certain wrong answers. Overflowed or underflowed derivative sums cause it to use the existing scaled fallback solver. Multiplying an investment's amounts by a common factor should not change its return.
  • IRR derivatives describe the financial answer rather than the solver's execution. Both solver stages first find the ordinary rate, then derive its sensitivities from the pricing equation. This fixes silently zero fallback gradients and preserves Hessians and higher derivatives. A zero-valued payment carrying a sensitivity is retained: its current value is zero, but changing it can affect the return.
  • The implementation is more consistent. Amount/time inputs and Cashflow inputs share the solving machinery; abstract containers work again. Rate comparisons are consolidated without changing their semantics. ForwardDiff support is optional, and Downgrade CI compiles without the problematic cache.

Two qualifications remain: finding the empty PV's type still evaluates the curve at time zero, so that evaluation can throw; and IRR remains a numerical root search, not a guarantee of finding every possible root. Its existing return convention (Periodic(rate, 1) when a root is found, otherwise nothing) and fallback root-selection policy are unchanged.


Merge map (updated 2026-09-29)

Part of the coordinated FinanceCore 2.8, FinanceModels 7.0, ActuaryUtilities 6.0 and MortalityTables 3.0 releases. Merge each stack bottom-up with Create a merge commit, delete each merged branch so GitHub retargets the next PR onto the default branch, and let the retargeted PR's CI finish before merging it.

Order Package PRs, merged left to right Then
1 FinanceCore #56 register 2.8.0
2 FinanceModels #311 → #314 → #295 → #308 → #315 → #316 → #317 → #318 → #319 → #320 → #322 → #323 → #324 → #325 → #326 register 7.0.0
3 ActuaryUtilities #160 → #161 (#160 is a draft, proposed to merge first with #161 rebased onto it; #161 merges after FinanceModels 7.0.0 is registered) register 6.0.0
any MortalityTables #136 → #137 → #138 → #139 → #140 → #141 → #142 → #143 → #144 → #145 → #146 → #147 → #149 → #151 → #148 (independent of the other three) register 3.0.0

This PR: FinanceCore #56, the only PR for FinanceCore in this release.


Updated 2026-09-28 (thermo-nuclear review): six commits from the 2026-09-28 code-quality review of the whole upgrade.

  • irr accepts abstract element types again (6e18db8). Since Optimize PV and generalize IRR numerics #59 (merged, unreleased), irr(Any[-100, 110], [0, 1]), Any times, and Any amounts with a range threw MethodError: zero(::Type{Any}); 2.7 returned 10%. The times kernel and the Cashflow kernel had drifted apart in how they typed their sums.
    • One solve flow now reads either input through _flow(cashflows, times, i), with nothing as the times of a Cashflow vector.
    • There is one SIMD kernel and one accumulator rule: the element types' promotion, or the rate's type when that isn't concrete.
    • Regression tests cover Any amounts and times, Real[], Cashflow[] and Cashflow{Real,Real}.
  • The empty and all-zero policy is one early return (2f078e6). _irr_force returns nothing when no amount is nonzero, and takes Newton's origin from the first nonzero flow. Before, the policy emerged from a chain: a placeholder origin, a zero derivative sum, Newton's NaN step, and the robust solver's sign check.
  • The implicit step reuses the primal flows (0fe8c8b) instead of filtering zeros and stripping duals again. _primal_values is one line that decides from the element type.
  • Rate comparisons are defined once (85dc8e5). <, isless, ==, isequal and isapprox had four identical methods each, and hash two. @snoop_invalidations finds no invalidations either way.
  • Small follow-ups. The LoopVectorization kernel subtracts the origin directly (e8cbfb2). 9ab7186 iterates the flows instead of indexing them, so the dual-number scan stays free for ranges.
  • Results are unchanged except the four Any inputs:
    • IRR values match on 9,089 primal cases and 1,502 gradient and Hessian cases, with and without LoopVectorization.
    • Rate comparisons match on 10,240 pairs.
  • Timings are unchanged for IRR at n = 3, 30 and 360, the far-dated and shifted cases, and the LV kernels. The Hessian with respect to amounts is 10–15% faster.
  • irr.jl goes from 290 to 265 lines, Rates.jl from 619 to 565.

Full suite: 2,140 tests pass on Julia 1.12.5 and 1.10.10. ActuaryUtilities #161 passes against this head together with FinanceModels #326.


Updated 2026-09-27 (benchmark review). One more commit, from the 2026-09-27 benchmark review:

  • IRR times are differenced exactly before rounding (53d3d90). Newton's kernels negate the time
    in the derivative sum (a * -t), and an unsigned time wraps: irr([-100, 110], UInt[1000, 1001])
    returned 0.1% instead of 10%, as in 2.7. The origin shift (0dc5749) added a subtraction that also
    wraps for an unsigned time before the origin, and narrow signed times could overflow in either.
    • Every kernel, the robust solver and the implicit-function step take the time from the origin as
      _elapsed(t, t0). Integer times are differenced in the unsigned type of their width, the larger
      minus the smaller, which is exact for any two times of that type, and converted to floating
      point once. Other times (floating point, dual, rational) subtract in their own type, as before.
    • Converting each time to floating point first would also avoid the wrap, but it rounds times
      beyond 2^53: irr([-100, 110], [2^53 + 1, 2^53 + 2]) would be 4.9%. (A first version did this;
      the local rereview caught it before any push.)
    • The LoopVectorization kernel converted the origin to floating point, so a range of integer times
      beyond 2^53 rounded there too (since 0dc5749). It now subtracts in the times' own type: integers
      for an integer range, exact for any span below 2^63.
    • Tests: UInt, UInt16, Int16, UInt8 and Int8 times; origins at 2^53 and at typemax(UInt64), as
      vectors, ranges (the LoopVectorization kernel) and Cashflows, forward and reversed; the robust
      solver; gradients with a zero amount before the origin; and _elapsed directly.
    • IRR timings are unchanged, including integer times: 30 flows at collect(0:29) 660 → 658 ns and at
      0:29 652 → 655 ns (2.7: 635 and 642 ns).

Full suite: 2,126 tests pass on Julia 1.12.5 and 1.10.10.


Updated 2026-09-27 (speed). Two more commits, from profiling against FinanceCore 2.7:

  • Newton measures times from the first cashflow (0dc5749). With times measured from 0, cashflows
    that are all near t = 1000 moved each Newton step by about 1/1000. Newton ran out of iterations and
    the robust solver ran: 26 μs for two cashflows, where 2.7 returned its unconverged iterate (9.99%
    for 10%).
    • Newton now solves Σ cf·exp(−r(t − t0)) = 0, which has the same roots (the factor exp(r·t0) is
      positive), with t0 at the first nonzero amount's time.
    • For flows starting at time 0 the origin is 0, so the arithmetic is unchanged. For ordinary inputs
      the origin is found in O(1).
    • The SIMD, Cashflow and LoopVectorization kernels take the origin explicitly.
    • Measured (BenchmarkTools, Julia 1.12.5; 2.7 / before / after):
      • two flows near t = 1000: 1.84 μs (wrong answer) / 26.3 μs / 100 ns;
      • 30 flows 50 years out: 1.02 / 1.02 μs / 623 ns;
      • 3 and 30 flows from time 0 are unchanged.
    • The tests that relied on Newton failing far from time 0 now use cases that still reach the
      fallback: an overflowed or subnormal derivative sum, the fallback's choice among multiple roots
      (tested directly), and a Hessian through it.
    • One reference value now uses expm1, because exp(x) - 1 lost about five digits at x = 4e-6.
  • IRR primal copies are inferred from the element type (29661e5). _primal_values returned its
    input or a primal copy, so for dual inputs its inferred type was a two-member Union, split
    statically. It is now concrete. Run time is unchanged.
    • JET reports runtime dispatch when it analyzes from ForwardDiff.gradient, but that comes from
      ForwardDiff choosing its chunk size at run time.
    • irr with concrete dual inputs analyzes clean.

Full suite: 2,089 tests pass on Julia 1.12.5 and 1.10.10 (2,086 at 0dc5749). Runic 1.11.1 is clean.

Found, not changed: the robust solver can miss roots of widely spaced flows at extreme notionals.
irr(1e307 .* [-1, 2.3, -1.32], [0, 100, 200]) returns nothing, because over a 200-year span its
[-5, 3] force range overflows. 2.7 does the same.

Updated 2026-09-27. Two commits after the September 26 published review:

  • Tiny notionals (68dea4e). Putting the scale in the exponent overflowed at M ≈ 1e-309: for
    amounts 1e-309 .* [-1, x] a year apart, differentiating the rate x - 1 threw instead of
    returning 1. Each sensitivity term now divides the amount by M first, and puts the scale in the
    exponent only where exp(-r·τ) itself overflows (the far-origin zero amount below). The choice
    is made on primal values, so every step evaluates the same form.

  • Newton on overflowed or underflowed sums (0a2f2a4). This predates this PR. Newton sums
    unscaled amounts, so it silently accepted wrong roots at extreme notionals:

    • irr(1e307 .* [-1, 1.1], [0, 100]) gave 0.00100 instead of 0.000954, because the
      derivative sum overflowed and the step was 0;
    • amounts of 1e-300 a thousand years out gave 0.056 instead of 0.1, because the sums
      underflowed into the subnormals.

    All three Newton kernels now return NaN when the derivative sum isn't a finite normal number.
    The robust solver, which scales the amounts, then finds the root.

  • Downgrade: a clean run passed on this PR, which supports the cache explanation below.

Full suite: 2,053 tests pass on Julia 1.12.5 and 1.10.10. Runic 1.11.1 is clean.

Updated 2026-09-26. The policy was revised after the September 25 review:

  • empty IRR now returns nothing instead of throwing;
  • untyped empty collections now have a present value;
  • there is an IRR fix for zero amounts;
  • the Downgrade job no longer uses the cache;
  • IRR derivatives of every order, including the Hessians that released 2.7 computed correctly.

Each change is a separate commit on top of the earlier two.

An empty cashflow stream got a different answer from each entry point:

Call (before) Result
pv(r, Float64[], Float64[]) 0.0
pv(r, Float64[]), pv(r, Cashflow[]) Julia's generic "reducing over an empty collection" error
irr(Float64[]), irr(Cashflow[]) nothing

Policy

present_value of an empty collection is exactly zero, from every entry point. Projection and
portfolio code produce empty streams legitimately, such as a policy with no remaining cashflows. The
value is fixed by linearity; its numeric type is a convention:

  • For concrete amount, time and rate types, it has the type a present value of such cashflows would
    have: Float64 for Float32 amounts at a Float64 rate, BigFloat at a BigFloat rate, and a dual
    number under ForwardDiff.
  • When the element type says nothing about the amounts (Any[], Number[], Cashflow[], (), an
    empty generator), the rate or curve decides the type. pv(0.05, Any[]) === 0.0, and
    pv(big"0.05", Cashflow[]) is a BigFloat zero. These inputs previously threw a MethodError.
  • It is zero of the present value of a zero amount at time zero, so it has the valuation's type
    but does not depend on the rate's value:
    • it is always a positive zero, and pv(Continuous(Inf), Float64[]) === 0.0 rather than NaN;
    • the rate or curve is still evaluated at time zero to find that type, so the empty value can
      throw where that evaluation throws.

internal_rate_of_return of an empty collection returns nothing, as it does for an all-zero
stream. There is no identifiable IRR, because every rate solves an identically zero pricing equation.
The earlier revision of this PR threw an ArgumentError. That was an early manual check where the
solver already reaches nothing on its own, and it treated empty streams differently from all-zero
ones.

Both are documented in the docstrings. Tests cover:

  • the real-valued, explicit-timepoint and Cashflow-vector entry points;
  • Float32, BigFloat, integer and dual-number amounts and rates;
  • untyped, tuple, generator and Dict inputs;
  • the infinite-force case.

Also in this PR

  • IRR with zero amounts. irr([0., -100., 110.], [0., 1000., 1001.]) threw a DomainError,
    although the IRR is 10%. The zero at t = 0 set the fallback search's time origin, so every other
    term underflowed.
    • The fallback now drops exact-zero amounts from its sign scan, scaling, origin and discounted
      terms. Moving only the origin would still evaluate the zero term as 0 * exp(3000) = NaN.
    • A zero dual number with nonzero partials is kept.
    • Tests put zeros at the start, middle and end.
  • IRR derivatives: one mechanism for both solver stages, of every order.
    • Before: the fallback stage returned a plain Float64 root, so ForwardDiff partials were
      silently dropped (ForwardDiff.gradient(a -> rate(irr(a, [1000., 1001.])), [-100., 110.]) == [0, 0]).
      The Newton stage differentiated through its iterations, which at a repeated root returned finite
      nonsense (about -1.5e6 for [-100, 210, -110.25]).
    • Now: when the amounts or times carry dual numbers, the whole solve runs on their primal
      values. Implicit-function steps r ← r - (g(r) - g₀) / g′ then give the root its partials, where
      g₀ and g′ are the residual's primal value and primal slope at the root, as in FinanceModels.
      • Each repetition with the dual iterate adds one derivative order, so the step is taken once per
        dual layer: first-order inputs take one step, a Hessian takes two.
      • The value is the primal IRR exactly.
      • Partials match analytic values and central differences, for amounts and timepoints.
      • Well-conditioned Newton-path gradients equal the previous ones to 1e-14.
    • Higher orders are preserved. Released 2.7 computed correct Hessians of ordinary IRRs by
      differentiating Newton's iterations, and they keep working.
      • The amount and time Hessians of [-100, 110] match their closed forms (-a₂/a₁ - 1 and
        1.1^(1/(t₂ - t₁)) - 1) on both solver stages. The fallback stage previously gave zero.
      • A third derivative matches 6a₂/a₁⁴.
      • A three-cashflow Hessian through the fallback matches the closed form of its quadratic.
      • A repeated root throws an ArgumentError at any order, since its sensitivity is undefined.
    • Extreme scales. For [0, -1e300, e²·1e300] at times 0, 400 and 401, a zero amount carrying
      partials used to make the step form 0 * exp(800) and throw.
      • The slope now skips zero primal amounts, as the time origin and scale already did.
      • Each term divides its amount by the scale first, and puts the scale in the exponent
        (exp(-r·τ - log M)) only where exp(-r·τ) overflows, as for this zero amount. A tiny
        notional (1e-309 .* [-1, x]) needs the division, since exp(-log M) overflows there.
      • The gradient is the finite exp(802)/1e300 ≈ 2.0145e48, matching a BigFloat reference to
        1e-16. At 1e-309 the derivative of the rate x - 1 is 1. Amount and time Hessians are the
        same at notionals of 1e-300, 1 and 1e300 on both stages.
    • Primal inputs keep their code path and results, except where Newton's sums overflow or
      underflow (see below). The added check costs about 2 ns per solve (70 ns vs 68 ns for three
      cashflows). First-order gradients are 3–6% slower from dividing each dual term by the scale
      (4.35 vs 4.2 μs for 30 cashflows).
    • New weak dependency: the hooks live in FinanceCoreForwardDiffExt (ForwardDiff, floor
      0.10.39). Under ForwardDiff 0.10, iszero(Dual(0, 1)) is true, so the exact-zero filter also
      checks the partials.
  • Newton at extreme notionals. This predates this PR. Newton sums unscaled amounts. When
    the derivative sum overflows (irr(1e307 .* [-1, 1.1], [0, 100])), the step is 0. When the sums
    underflow into the subnormals (amounts of 1e-300 at t = 1000), the step is a ratio of a few bits.
    Either way Newton accepted a wrong rate silently.
    • The SIMD, Cashflow and LoopVectorization kernels now return NaN for a derivative sum that
      isn't a finite normal number.
    • Newton then gives up, and the robust solver, which scales the amounts, finds the root.
    • An ordinary stream's step is unchanged.
  • Downgrade CI.
    • main at 82b0985 passed Downgrade with no cache. Both earlier runs on this PR restored that
      run's cache (run 36096654113), HostCPUFeatures reported stale CPU information, and LLVM aborted
      in the LoopVectorization testset.
    • The Downgrade job no longer uses julia-actions/cache, so the floor build compiles fresh on its
      own runner.
    • A clean Downgrade run has since passed (run 36297465188). That supports this explanation, but
      doesn't prove it was the only cause.

Release notes (2.8): every change is additive or a correction, and none is breaking.

  • pv of untyped empty collections now returns zero instead of throwing. Typed empties already
    returned zero from the explicit-timepoint form.
  • irr of an empty collection returns nothing, as in 2.7.
  • irr with exact-zero amounts far from the other cashflows now solves.
  • irr derivatives:
    • The fallback stage now propagates partials instead of silently returning zero gradients.
    • Both stages share one implicit-function mechanism.
    • Derivatives of any order work, including the Hessians 2.7 computed through Newton.
    • A repeated root throws instead of returning finite nonsense.
    • Derivatives no longer overflow at tiny notionals.
  • irr no longer accepts a wrong Newton root when the amounts are so large or so small that
    Newton's sums overflow or underflow. The robust solver finds the rate instead.
  • irr of cashflows far from time 0 converges in Newton, which now measures times from the first
    nonzero cashflow. For example, two flows near t = 1000 take 100 ns instead of the fallback's 26 μs.
  • irr with unsigned, narrow or very large integer times returns the right rate. In 2.7 an unsigned
    time wrapped when Newton negated it.
  • There is a new weak dependency on ForwardDiff.

🤖 Generated with Claude Code

An empty cashflow stream got a different answer from each entry point:
`pv(r, Float64[], Float64[])` returned 0.0, `pv(r, Float64[])` and
`pv(r, Cashflow[])` threw Julia's generic "reducing over an empty collection"
error, and `irr` returned `nothing`, the value that means no rate solves the
cashflows.

- present_value of an empty collection is zero from every entry point: the
  empty sum, typed as a present value of the collection's cashflows would be
  (a dual number under ForwardDiff, for example). Projection and portfolio code
  produce empty streams legitimately.
- internal_rate_of_return of an empty collection throws an ArgumentError. Its
  present value is zero at every rate, so no rate is its IRR; returning
  `nothing` would pass that off as an ordinary unsolved stream.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@alecloudenback
alecloudenback force-pushed the fix/empty-cashflow-policy branch from 6a7f7f5 to 29828bd Compare September 25, 2026 05:11
alecloudenback and others added 20 commits September 25, 2026 08:01
An empty collection has a typed zero only when its element type is concrete
(numbers or Cashflow{N,T}). Abstract element types such as Cashflow[] or Any[]
throw a MethodError; the docstring now says so, and a test pins the behavior so
that any future fallback type is a deliberate change.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Hypothesis for the Downgrade failures on this PR: main at 82b0985 passed
Downgrade with no cache ("Cache not found"), while both #56 runs (29828bd,
fe932da) restored that run's cache (run 36096654113). HostCPUFeatures then
reported stale CPU information and LLVM aborted in the LoopVectorization
testset. A cache precompiled for another runner's CPU features is the
likely cause; the floor job now builds fresh on its own runner. A clean
Downgrade run is needed to confirm it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
An empty stream, like an all-zero one, has no identifiable IRR: every rate
solves its identically zero pricing equation. The explicit ArgumentError is
removed; the solver already returns nothing for such a stream (Newton sees
0/0, and the fallback finds no positive and negative amounts), matching the
existing all-zero behaviour.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
irr([0., -100., 110.], [0., 1000., 1001.]) threw a DomainError although the
IRR is 10%: the zero amount at t = 0 set the fallback's time origin, so every
nonzero term was shifted by 1000 years and underflowed. Choosing the origin
from nonzero amounts alone is not enough, because the zero term would then
evaluate as 0 * exp(3000) = NaN. The fallback now drops exact-zero amounts
from the stream it uses for the sign scan, scaling, origin and terms. A zero
dual number with nonzero partials is kept (iszero checks the partials).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
The value of an empty collection is fixed by linearity at zero; its numeric
type is a convention. It is now computed as
false * present_value(r, zero_amount, zero_time), taking the amount type from
eltype(values(x)) and the time type from eltype(times) or eltype(keys(x)):

- for concrete amount, time and rate types, the result has the type a present
  value of such cashflows would have (Float64 for Float32 amounts at a
  Float64 rate, BigFloat for a BigFloat rate, a dual number under ForwardDiff);
- an element type that says nothing about the amounts or times (Any, Number,
  abstract Cashflow, Union{} for an empty tuple, an empty generator)
  contributes false, which promotes away, so the rate or curve decides the
  type. These inputs previously threw a MethodError;
- the rate or curve is still evaluated at time zero, so the empty value can
  throw where that evaluation throws; false's strong zero discards a NaN from
  it, so present_value(Continuous(Inf), Float64[]) is zero rather than NaN.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
The fallback stage solved with Roots.find_zeros, which returns a Float64
root, so any ForwardDiff partials of the cashflows or timepoints were
dropped without an error: ForwardDiff.gradient(a -> rate(irr(a, [1000.,
1001.])), [-100., 110.]) returned [0, 0] instead of [0.011, 0.01].

The fallback now searches on primal values and, when the inputs carry
dual numbers, applies one implicit-function step to the root, as
FinanceModels does for its solved quantities:

    r = r0 - (g(r0) - primal(g(r0))) / g′(r0)

g is the scaled, zero-filtered, origin-shifted residual evaluated with the
dual inputs, and g′ its primal derivative in the rate. The value stays r0
exactly and the partials are dr = -(∂g/∂θ)/(∂g/∂r). Nested dual numbers,
and a slope that vanishes relative to the size of its terms (a repeated
root), throw an ArgumentError instead of returning wrong derivatives.
Primal inputs give bit-for-bit the same results as before (checked on
twelve fallback cases through both entry points).

The dual hooks live in a new FinanceCoreForwardDiffExt (ForwardDiff weak
dependency, compat floor 0.10.39, the version the Downgrade job already
resolves). One of them, _is_exact_zero, also checks the partials: under
ForwardDiff 0.10, iszero(Dual(0, 1)) is true, so the previous commit's
iszero filter silently dropped a zero amount that carries partials there.
Such an amount now contributes its (here enormous) derivative on both
ForwardDiff 0.10 and 1.x.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
Dual inputs previously went through Newton's method as dual numbers, so
its derivative was the derivative of the iterations. At a repeated root,
where the IRR has no derivative, that returned finite nonsense: for
[-100, 210, -110.25] at times 1000-1002 the gradient was about -1.5e6.
The fallback already solved on primal values and applied one
implicit-function step (e1e1ad2).

IRR now has a single differentiation mechanism. When the amounts or times
carry dual numbers, the whole solve (Newton, then the fallback) runs on
their primal values, and the same step r0 - (g - primal(g)) / g′ gives the
root first-order partials. Consequences:

- a repeated root with dual inputs throws the vanishing-derivative
  ArgumentError on either stage;
- second derivatives (nested duals, e.g. ForwardDiff.hessian) throw on
  either stage; the docstring states first-order derivatives as a
  capability boundary, as for FinanceModels' implicit solves;
- well-conditioned Newton-path gradients equal the previous ones to 1.2e-14
  relative (seven cases, with respect to amounts and times) and central
  differences;
- the value under AD is the primal IRR exactly.

Primal inputs take the unchanged code path, with bit-for-bit identical
results (Newton-path and fallback cases checked) and no measurable
overhead at 3, 30 or 300 cashflows. _irr_robust is primal-only again.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
The empty present value is now zero(present_value(r, zero_amount,
zero_time)) instead of false * present_value(...). The type and AD
behaviour are unchanged (a dual number with zero partials under
ForwardDiff), but the value no longer depends on the rate's value at all:
no NaN, and no -0.0 from a negatively signed NaN. This matches
ActuaryUtilities' zero-stream construction, which promises positive
zeros. present_value(Continuous(Inf), Float64[]) === 0.0, and the result's
sign bit is clear for rates of ±Inf and ±NaN.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
… layer

f80bfee made every derivative of the IRR come from one implicit-function
step on the primal root, and nested duals threw. Released 2.7 computed
correct Hessians of ordinary IRRs by differentiating Newton's iterations
(the amount Hessian of [-100, 110] at times 0 and 1, and the time Hessian,
match their closed forms), so that rejection would have removed a working
capability.

The step r ← r - (g(r) - g₀) / g′, with the primal value g₀ and primal
slope g′ at the root, gains one derivative order each time it is repeated
with the dual iterate. It is now taken once per dual layer: first-order
inputs take one step as before, and a Hessian takes two. Every step keeps
the value the primal root exactly. Hessians now agree with the closed forms
on both solver stages (amounts to 1e-12 relative, times likewise), a third
derivative matches 6a₂/a₁⁴, and a three-cashflow Hessian through the
fallback matches the quadratic's closed form. A repeated root still throws.

A zero amount that carries partials far before the other cashflows made
the step form 0 * exp(800): for [0, -1e300, e²·1e300] at times 0, 400, 401
the gradient threw although d(rate)/da₁ = exp(802)/1e300 ≈ 2.0145e48. The
slope now skips primal-zero amounts, as the time origin and scale already
did, and the scale enters the exponent, exp(-r·τ - log M), so the term is
formed without overflow. The gradient matches the BigFloat reference to
1.1e-16.

First-order gradient timings are unchanged (Newton and fallback paths,
amounts and times). Tests pass on Julia 1.12.5 and 1.10.10, and the IRR
tests also pass under ForwardDiff 0.10.39.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
09a7b56 moved the notional scale into the exponent, exp(-r⋅τ - log M), so that a
zero amount far before the time origin stays finite once scaled. At a tiny
notional that same exponential overflows: for amounts 1e-309⋅[-1, x] a year
apart, exp(-log M) exceeds floatmax, the slope is NaN, and differentiating the
rate x - 1 threw instead of returning 1.

Each term cf⋅exp(-r⋅τ)/M now divides the amount by M first, and folds the scale
into the exponent only where exp(-r⋅τ) itself overflows. The choice is made on
primal values, so every implicit step evaluates the same form and the value
stays the primal root.

Tests: the tiny-notional derivative (1) and second derivative (0), a zero amount
carrying partials at that scale against its closed form, the far-origin zero
amount still at exp(802)/1e300, and amount and time Hessians at notionals of
1e-300 and 1e300.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
Newton's kernels sum unscaled amounts. For irr(1e307 .* [-1, 1.1], [0, 100])
the derivative sum overflows, the step n/d is 0, and Newton accepted its
starting guess: 0.00100 instead of 0.000954. For amounts of 1e-300 a thousand
years out, the sums underflow into the subnormals and the step is a ratio of a
few bits: Newton accepted 0.056 instead of 0.1. Both were silent wrong rates.

The three kernels (the SIMD kernels for amounts with times and for Cashflows,
and the LoopVectorization kernel) now return NaN when the derivative sum isn't
a finite normal number. Newton then gives up, and the robust solver, which
scales the amounts, finds the root. An ordinary stream's step is unchanged.

Tests: both streams, as amounts with times and as Cashflows, the turbo kernel's
overflow case, and the amount and time Hessians at notionals of 1e-300 and 1e300
on the fallback stage as well.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
Newton solved sum(cf * exp(-r*t)) = 0 with times measured from 0. For cashflows all near
t = 1000 each step moved the rate by about 1/1000, so Newton ran out of iterations and the robust
solver ran instead (22 us for two cashflows; FinanceCore 2.7 returned the unconverged iterate,
9.99% for 10%). Newton now solves sum(cf * exp(-r*(t - t0))) = 0, which has the same roots (the
factor exp(r*t0) is positive), with t0 at the first nonzero amount's time.

- For flows that start at time 0 the origin is 0 and the arithmetic is unchanged. For ordinary
  inputs the origin is found in O(1).
- `_pv_ratio` computes the origin once and returns the closure, so no captured variable is
  reassigned (that would box it).
- The SIMD, Cashflow, and LoopVectorization kernels take the origin explicitly.

Measured: two cashflows near t = 1000 take 57 ns (was 22 us), and 30 cashflows 50 years out take
528 ns (was 880). Ordinary inputs are unchanged (within 1%).

Tests: far-dated flows converge in Newton and equal the unshifted rate. Leading zero amounts don't
set the origin, and unsorted times work. The fallback keeps its own cases: an overflowed or
subnormal derivative sum, its choice among multiple roots, and a Hessian through it. Comments that
said Newton could not finish far-dated flows are corrected. One reference value now uses `expm1`:
`exp(x) - 1` lost about five digits at x = 4e-6.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
`_primal_values` returned either its input or a primal copy, decided by scanning the values, so
for dual inputs its inferred type was a Union of the two vectors, and the solver was compiled for
both. A concrete element type now decides it without a scan, and the result is inferred concretely
(`Vector{Float64}` for dual amounts). Only an abstract element type is still scanned.

The union was split statically, so run time is unchanged: IRR Hessian and gradient timings are
within noise of the previous ones. (JET reports runtime dispatch when it analyzes from
`ForwardDiff.gradient`, but that comes from ForwardDiff choosing its chunk size at run time. With
concrete dual inputs, `irr` analyzes clean before and after this change.)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
Newton's kernels negated the time in the derivative sum (`a * -t`), and
an unsigned time wraps: irr([-100, 110], UInt[1000, 1001]) returned
0.1% instead of 10%, as in 2.7. The origin shift (0dc5749) added a
subtraction that also wraps for an unsigned time before the origin, and
narrow signed times could overflow in either. Converting each time to
floating point first would fix those but round times beyond 2^53:
irr([-100, 110], [2^53 + 1, 2^53 + 2]) would be 4.9%.

The time from the origin is now `_elapsed(t, t0)`, used by every
kernel, the robust solver and the implicit-function step. Integer times
are differenced in the unsigned type of their width, the larger minus
the smaller, which is exact for any two times of that type, and
converted once; the sign is applied to the float. Other times (floating
point, dual, rational) subtract in their own type, as before.

The LoopVectorization kernel converted the origin to floating point, so
a range of integer times beyond 2^53 rounded there too (since 0dc5749).
It now subtracts in the times' own type: integers for an integer range
(exact for any span below 2^63).

Found by the 2026-09-27 benchmark review (unsigned times, inherited)
and its local rereview (large integer origins).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
The amounts-and-times and Cashflow entry methods each repeated the choice between the primal and
dual paths, and each had its own Newton kernel. The kernels were the same loop apart from reading
an element and typing their sums, and those rules had diverged: the Cashflow kernel fell back to
the rate's type for an abstract element type, while the other called
`zero(promote_type(...))`, so irr(Any[-100, 110], [0, 1]), irr([-100.0, 110.0], Any[0, 1]) and
irr(Any[-100, 110], 0:1) threw `MethodError: zero(::Type{Any})` (since aa9589b). FinanceCore 2.7
returned 10% for all of them.

Both forms now go through `_irr(cashflows, times)`, where a Cashflow vector's times are `nothing`
and `_flow(cashflows, times, i)` reads flow `i`'s amount and time. One kernel, one `_pv_ratio`
and one accumulator rule remain; the Cashflow kernel, its dispatcher and backend method, and the
second `_pv_ratio` and `_irr_accumulator_type` methods are gone. Primal copies of Cashflows go
through `_primal_values` too; they are always made, since in the dual path the Cashflows are the
whole input, and a concrete `Cashflow{Real, Real}` can hold dual numbers its type doesn't show.

The robust solver now pairs amounts and times by index, as Newton's kernel always has, instead of
by `zip`; for ordinary vectors the pairs are the same. `_flow` propagates `@inbounds`, so the
kernel's loop is unchanged and the solver's generators keep their bounds checks.

A snapshot of 9,089 primal results and 1,502 gradients and Hessians, with and without
LoopVectorization, is identical (`isequal`, with types) to the previous commit's except for the
`Any` inputs, which now return the 2.7 value. Regression tests cover those, `Real` and abstract
Cashflow vectors, and `Cashflow{Real, Real}` with dual amounts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
The empty and all-zero policy was emergent: `_newton_origin` fell back to a dummy origin (a zero of
the time type, found through `_zero_time`, which pv.jl defined for Cashflow element types only for
this), Newton's derivative sum was then zero, `_newton_step` made it NaN, Newton gave up, and the
robust solver found no sign change. The dummy existed only to give the closure a concrete type.

The primal solve, `_irr_force(cashflows, times)`, now looks for the first nonzero amount itself:
with none it returns `nothing`, and otherwise that amount's time is Newton's origin. Newton takes
the input and origin directly, so the `_pv_ratio` closure, `_newton_origin` and pv.jl's Cashflow
method of `_zero_time` are gone. The nonzero filter is shared with the robust solver as
`_nonzero`.

Results are unchanged: the same snapshot of 9,089 primal results and 1,502 derivatives, with and
without LoopVectorization, is identical to the previous commit's. The tests that read the origin
from `_newton_origin` now compare the primal solve with Newton from the expected origin, and check
that from time 0 Newton does not converge on the far-dated case, so the comparison can't pass
through the fallback.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
The dual path built primal copies of the input for the solve, then `_irr_dual` rebuilt primal
values from the dual flows to find the scale and time origin, filtering them twice (exact zeros,
then primal zeros, which already excludes them), and `_irr_implicit` stripped the duals and
filtered the zeros a third time for its slope. The implicit step now takes the dual flows and the
primal flows of the same copies: the scale, origin and slope come from `_nonzero(primal_flows)`,
shared with the robust solver, and only the residual `g` reads the dual flows. `_irr_dual` is
gone; `_irr` returns `nothing` for a missing root itself.

`_primal_values` no longer scans a vector of an abstract element type for dual numbers: it copies
it. Such a copy is made only on the dual path, and only for the input without partials; the values
are the same, and the element type alone now decides, as it already did for concrete types.

Results are unchanged: the snapshot of 9,089 primal results and 1,502 gradients and Hessians, with
and without LoopVectorization, is identical to the previous commit's.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
`<`, `isless`, `==` and `isequal` each had four methods, one per pair of Periodic and Continuous
operands, with identical bodies; `hash` had two, and `isapprox` four whose bodies were equivalent
(converting to Continuous keeps the stored force, so its Continuous pair needed no special case).
The split was said to avoid invalidating compiled code, but a signature on `Rate` intersects the
same call sites whatever its compounding parameter, and the file already defines Rate `+` and `-`
generically. Measured with SnoopCompile, loading FinanceCore invalidates nothing before or after
this change, in a fresh session and after loading SnoopCompile, Roots and Dates.

Each is now one method on `Rate`, and the comments that justified the split, two of which still
pointed to `>` methods removed in aa9589b, are gone. The three-argument `convert` stays: its
comment offers it as the extension point for other `Frequency` types, so a minor release keeps it.

A snapshot of `<`, `>`, `<=`, `isless`, `==`, `isequal`, `isapprox` (with and without `atol`)
and `hash` over 1,024 pairs of rates (Periodic and Continuous; Float64, Float32, BigFloat and dual
values; NaN, ±0 and ±Inf), plus `sort` and `unique`, is identical before and after, and Test's
ambiguity and unbound-argument checks find nothing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
The turbo kernel converted the origin to the times' element type before subtracting it, with a
comment about keeping integer ranges exact. The origin is always one of the times (the first
nonzero amount's), so the conversion never changed anything. The kernel now subtracts `t0`
directly, and one comment says why that stands in for `_elapsed`, whose branch `@turbo` can't
take: float times subtract as floats there too, and an Int range's span fits in an Int.

The snapshot of 9,089 primal results and 1,502 derivatives with LoopVectorization loaded is
identical to the previous commit's.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
6e18db8 made the amount-and-time stream `_flows` an indexed generator, which the check for dual
numbers scans. When the element types rule duals out, the compiler dropped that scan over the
previous `zip`, but indexing a range of times kept a bounds-checked loop: 157 ns at 360 flows
(1.7 ns before), and irr(cashflows) with its default range of times ran about 3% slower at 30
and 360 flows. Vectors cost 6 to 10 ns.

`_flows` iterates again, as before 6e18db8: `zip` for amounts and times, and a generator over the
Cashflows. The scan is 1.7 ns in every form. `_flow` still reads flow `i` for Newton's kernel.
The robust solver pairs amounts and times by `zip` again, as in FinanceCore 2.7.

The snapshot of 9,089 primal results and 1,502 derivatives, with and without LoopVectorization,
is identical to 53d3d90's apart from the `Any` inputs fixed in 6e18db8.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
This was referenced Sep 30, 2026
@alecloudenback
alecloudenback merged commit 443c160 into main Sep 30, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant