Skip to content

Compute interval factors from cumulative log-discounts - #324

Merged
alecloudenback merged 6 commits into
masterfrom
feat/log-discount-intervals
Oct 1, 2026
Merged

alecloudenback merged 6 commits into
masterfrom
feat/log-discount-intervals

Conversation

@alecloudenback

@alecloudenback alecloudenback commented Sep 27, 2026 •

Copy link
Copy Markdown
Member

Merge map (updated 2026-10-01)

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. Automatic branch deletion is on, so after each merge GitHub retargets the next PR onto the default branch: check that its base says master and let its CI finish before merging it.

Order Package Merged Open, merge left to right Then
1 FinanceCore #56 — 2.8.0 registered (2026-09-30)
2 FinanceModels #311, #314, #295, #308, #315, #316 #327 → #317 → #318 → #319 → #320 → #322 → #323 → #324 → #325 → #326 (#315 and #316 were merged into stacked branches, not master; #327 lands them) register 7.0.0
3 ActuaryUtilities — #161 (includes #160's change, so #160 is closed; merges after FinanceModels 7.0.0 is registered) register 6.0.0
any MortalityTables #136, #137, #138, #139, #140, #141 #152 → #142 → #143 → #144 → #145 → #146 → #147 → #149 → #151 → #148 (#138–#141 were merged into stacked branches, not master; #152 lands them. Independent of the other three) register 3.0.0

This PR: FinanceModels #324, number 8 of 10 open (base #323; next #325).


Updated 2026-09-27. Rebased onto #323, plus two commits from the published-stack review and its follow-up:

  • Unknown growth at infinity (5698867). A curve without a closed-form tail contributes (0, z(∞), unknown). When z(∞) = ±Inf, the log-discount grows faster than t at an order the curve doesn't state, so the 0 in a₂ isn't known. The classifier read a₂ first, so a known quadratic of the other sign decided the limit. A TenorShift with zero rate t/32 minus a :linear curve with t/64 has L = t²/64 → +Inf, so its discount at infinity is 0; the old result was Inf, and the reverse gave 0 instead of Inf.
    • The classifier now reads the forward first. ±Inf there decides the limit unless a₂ has the other sign. Then the limit is unsupported and returns NaN, rather than a guess.
    • A zero a₂ carrying partials still throws "no derivative" (d8dc11f), as it does for a known tail. With L = t^1.5 + k·t²/64, the limit is 0 at k = 0 but Inf for every k < 0, so d/dk at 0 doesn't exist. 5698867 had returned 0.0 there.
    • The fallback's numbers don't change.
    • A fallback curve combined with a flat, linear or same-sign tail keeps FinanceModels 6's limit.
  • Internal curve capabilities are documented in a table at the top of Yield.jl. It covers __log_discount, __log_native, __log_interval and __log_tail: each one's meaning, its default and which types define it.

Verification (2026-09-27, at 5698867; the suites again at d8dc11f):

  • the full suite passes on Julia 1.10.10 and 1.12.5 (6,521 tests at 5698867, 6,525 at d8dc11f);
  • CI's Downgrade job emulated locally (Julia 1.10.10, every dependency pinned at its floor, including FinanceCore 2.6.0, DataInterpolations 9.2.0 and ForwardDiff 1.0.0): the full suite passes (6,521 tests);
  • Runic 1.11.1 is clean, and the docs build is clean;
  • the published review's probes:
    • 819 polynomial/wrapper checks, 25 signed-relative-factor checks and 1,215 upstream checks pass;
    • its two unknown-order cases now give NaN, the conservative answer it recommended, not the opposite limit;
  • ActuaryUtilities' full suite plus the 12 Downstream integration checks (4,668) pass against this tip and FinanceCore Let Rate do the trivial interest manipulations #56 at 0a2f2a4.

The rebase changed the earlier commits' SHAs: a96e0e3 → 8448cb1, f742b4e → 68ed969, 638c38f → 16685a6, 68ec1ed → a3bddf9. The 2026-09-26 verification below refers to the old ones.


Stacked on #323 (refactor/composite-yield-factor-ops). Review against that branch.

Interval factors are computed from cumulative log-discounts. discount(curve, from, to), accumulation(curve, from, to) and forward(curve, from, to) used to divide two discount factors. That is 0/0 = NaN once both underflow: discount(Yield.NelsonSiegel(1.0, 0.05, -0.02, 0.01), 20000, 20001) was NaN. They now take differences of L(t) = −log D(t), the force accumulated from valuation time 0:

discount(c, from, to)     = exp(L(from) − L(to))     # exactly 1 when from == to
accumulation(c, from, to) = exp(L(to) − L(from))
forward(c, from, to)      = (L(to) − L(from)) / (to − from)

The earlier review showed why this can't be the literal rate(zero(c, t))·t for every curve: Smith–Wilson's generic zero rate is 0/0 at the origin, so discount(c, 0, 1) would have become NaN. So L is an internal, per-model primitive, Yield.__log_discount(c, t). Whether a curve's intervals use it depends only on its type (Yield.__log_native), never on the values:

Curve L(t)
any curve (fallback) -log(discount(c, t)), used for zero and forward. Intervals of a curve that defines only discount stay the exact ratio D(to)/D(from), since its discount factor may be nonpositive or differ from 1 at 0
Constant, NelsonSiegel(Svensson), CairnsPritchard(Extended), MonotoneConvex, TenorShift/ProjectedShift z(t)·t from the curve's zero rate: exactly the exponent discount already used. At an exact zero time it is 0 (a wrapper over a discount-native curve has a 0/0 zero rate there); under ForwardDiff 1.x iszero needs zero partials, so a time derivative at 0 is kept
Yield.Spline _fn(t)·t, and the tail limit at Inf
SmithWilson ufr·t − log1p(s(t)) for zero/forward. Intervals are exp(-ufr·Δt)·(1+s(to))/(1+s(from)), exact for either sign: a fit to arbitrary prices can make the discount factor negative, as the bullet-bond round-trip test does
CompositeYield (+/-) L₁ ± L₂. The +/- restriction in the base PR is what makes this exact
ScaledYield k·L
ForwardStarting intervals delegate to the base curve's interval. For zero/forward, L is the base curve's log-discount over [τ, τ + t]: L(curve, τ + t) − L(curve, τ) for a log-native base, and otherwise the log of the base curve's own interval factor. So a rebased signed Smith–Wilson fit keeps zero, forward and scaling wherever its relative factor is positive, even where both absolute discount factors are negative. The cached discount-factor field is gone
Vasicek B·r − lnA; HullWhite: its curve's L and intervals; RatePath: the integrated short rate
CIR the fallback; its log-space form is in #299, not on this stack

Limits at infinity combine tails. A composite can't combine its components' limits: flat forwards of 4% and −2% have L = Inf and -Inf, and Inf + -Inf is NaN, though the sum tends to +Inf. Each curve therefore describes the long-run behavior of L, L(t) = a₂t² + a₁t + a₀ + o(1), and the limit is taken after combining:

  • Closed-form tails:
    • the knot-curve tails (ZeroRateCurve/Yield.Spline, MonotoneConvex): (γ, α − γtₙ, 0) under :linear, (0, α, βtₙ) under the flat policies;
    • Constant: (0, r, 0).
  • Wrappers:
    • CompositeYield combines componentwise with its +/-;
    • ScaledYield scales each coefficient;
    • ForwardStarting shifts the base tail;
    • HullWhite and the internal primal view delegate.
  • Every other curve contributes (0, its zero rate at infinity, unknown).
    • With a finite zero rate, that is exactly FinanceModels 6's sum of zero rates.
    • An infinite zero rate means L grows faster than t, at an order the curve doesn't state. It decides the limit against flat, linear and same-sign quadratic tails. Against a quadratic of the other sign, the limit is NaN, as FinanceModels 6's Inf − Inf was.
    • So no case gets worse.
  • Classification reads the forward first:
    • An unknown forward (NaN) gives NaN.
    • Unknown growth (±Inf) decides the limit unless a₂ has the other sign.
    • Otherwise the existing rule applies to the combined coefficients: the first nonzero of a₂ then a₁ decides 0 or Inf, and otherwise the limit is exp(−a₀). A deciding coefficient that is zero but carries partials still throws "no derivative".
  • What this changes: the reviewer's a + b, b + a and a − a/2 give 0.0 again. Cancellations that were NaN in FinanceModels 6 are now exact:
    • a flat-forward curve minus a Constant at its tail forward gives exp(−a₀);
    • two :linear tails with equal slopes;
    • ForwardStarting(c, τ) − c;
    • 0 * c gives 1.

What stays the same:

  • Each built-in curve's discount(c, t) is exactly exp(-L), so discount(c, 0, t) === discount(c, t) for every type. That covers every present_value of a contract (Projection evaluates discount(model, 0.0, t)). A test checks === for 18 curve types.
  • discount(curve, Inf) for a single knot curve keeps its documented limits (0, Inf, or the finite factor) and its AD rule, bit for bit; that classification now runs on the tail coefficients. Each result keeps its own type and partials.
  • Reversed intervals still invert, and accumulation(c, s, t) == discount(c, t, s).

What changes:

  • Intervals that start after 0 move by a few units in the last place; the largest relative change on a 25-curve grid is below 1e-15. For discount-native curves (Smith–Wilson, ForwardStarting, Vasicek, Hull–White), zero and forward move by at most about 5e-15 relative, because they no longer round-trip through -log(discount)/t.
  • Far-tail intervals are finite: Nelson–Siegel's 20000 → 20001 is exp(-0.05), and Smith–Wilson's 30000 → 30001 is exp(-ufr). So is zero(sw, 30000).
  • discount(c, t, t) is exactly 1, including t = Inf.
  • discount(sw, t) for Smith–Wilson is unchanged. Its intervals are exact and finite in the far tail (30000 → 30001 was NaN), and an interval from exactly 0 evaluates one sum, not two.

Out of scope (recorded; this PR doesn't make them worse):

  • A seeded time-dual exactly at 0 on NelsonSiegel/NSS/MonotoneConvex still hits their 0/0 zero-rate formulas.
  • The generic zero(c, 0) is still NaN. Both belong to the t = 0 limits item.

Tests (test/log_discount.jl):

  • far-tail intervals against closed-form long-run forwards;
  • the Smith–Wilson origin;
  • === from 0 for every type;
  • interval algebra: product, quotient and power for +, - and scaling; ForwardStarting as a shift; reversed = inverse; the composition law; forward = the interval's rate;
  • the identity at equal endpoints, including (Inf, Inf);
  • a custom curve's intervals stay the ratio, including negative discount factors, whose forward throws a DomainError;
  • Smith–Wilson intervals across a sign change of its discount factor, and a ForwardStarting over it. Rebased where both absolute factors are negative, zero, forward, scaling and + agree with the positive relative factor; rebased across the sign change, zero throws a DomainError;
  • limits at infinity (reviewer cases plus exact-binary closed forms):
    • opposite flat forwards: a + b, b + a and a − a/2, at Inf and at (1, Inf);
    • a cancelled slope that leaves exp(0.03125);
    • equal :linear slopes;
    • ForwardStarting(c, 3) − c;
    • 0 * a;
    • the "no derivative" throw on a combined zero forward that carries partials;
    • -Inf still rejected;
    • Nelson–Siegel and TenorShift composites equal to FinanceModels 6's zero-rate formula;
  • endpoint derivatives against central differences, including d/dh discount(c, t, t + h) at h = 0 = −(instantaneous forward) for linear, Nelson–Siegel and MonotoneConvex curves.

Verification (local, 2026-09-26, at a96e0e3):

  • full suite at 7.0.0-DEV: 6,506 pass, Aqua 10/10;

  • Runic 1.11.1 clean; docs build clean;

  • the plan-review probes: Smith–Wilson discount(c, 0, 1) is still 0.9704455335485082, and its 30000 → 30001 interval is finite (was NaN);

  • the implementation-rereview probe (review-artifacts/2026-09-26-implementation-rereview/fm/probe.jl):

    • discount(a + b, Inf), discount(b + a, Inf), discount(a − a/2, Inf) and their (1, Inf) intervals are 0.0 (were NaN);
    • the rebased signed Smith–Wilson gives zero(f, 1) = Continuous(-0.5222246045208919) = −log discount(f, 1), forward(f, 1, 2) = Continuous(-0.2949429547513457), discount(2f, 1) = discount(f, 1)² and discount(2f, 0) = 1.0 (all threw);
    • 56 ordinary/origin checks pass, with the 2 inherited origin-AD cases still marked broken;
  • ActuaryUtilities' full suite (4,638, Define an irr/YTM for quotes #161 at b45b9f6) plus the 12 Downstream integration checks, against a96e0e3 and FinanceCore Let Rate do the trivial interest manipulations #56 at 09a7b56;

  • the tails commit's finite-time cost (warmed loop, ns, f742b4e → a96e0e3):

    • intervals discount(c, 1.3, t): Linear 48 → 49, NelsonSiegel 10.3 → 10.4, SmithWilson 48 → 48, Linear + NS 69 → 68, ForwardStarting 47–48 → 47–48;
    • 2 * Linear 47 → 51, from the infinite-time branch in ScaledYield;
    • point discounts unchanged within noise; no allocations;
  • benchmark (ns, before → after):

    Curve present_value(curve, bond) discount(c, 1.3, 7.2)
    Linear spline 1045 → 1024 55.9 → 49.7
    NelsonSiegel 486 → 313 14.1 → 10.1
    MonotoneConvex 719 → 754 35.4 → 34.7
    SmithWilson 979 → 620 44.3 → 45.6

🤖 Generated with Claude Code

alecloudenback and others added 5 commits September 27, 2026 08:29
discount(curve, from, to), accumulation and forward divided two discount
factors, which is 0/0 = NaN once both underflow: an interval 20000 -> 20001
on a Nelson-Siegel curve, or ForwardStarting far into the tail.

An internal cumulative log-discount L(t) = -log D(t) now carries interval
quantities. Built-in curves compute it directly: z(t)·t for curves defined
by a zero rate (exactly the exponent their discount already used), the
spline tail limit at Inf, L1 ± L2 for CompositeYield, k·L for ScaledYield,
and closed forms for Vasicek and RatePath. Their discount factor is exp(-L),
so an interval from 0 reproduces discount(curve, t) bit for bit and every
present_value of a contract is unchanged.

Which formula applies depends only on the curve's type. A curve that
defines only discount keeps the exact ratio D(to)/D(from), since its
discount factor may be nonpositive or differ from 1 at 0. Smith-Wilson,
whose fit to arbitrary prices can make the discount factor negative, gets
an exact interval exp(-ufr·Δt)·(1+s(to))/(1+s(from)). ForwardStarting and
HullWhite delegate to their curve's interval. Empty intervals are exactly 1,
also at Inf; forward is the difference of L.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
NEWS, the migration guide and the models page: built-in curves compute
interval factors from their cumulative log-discount, intervals from 0 are
unchanged, far-tail intervals are finite, and a curve that defines only
discount keeps the ratio D(to)/D(from).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
s(0) = 0, so an interval from an exact 0 (every present value of a
contract) needs only s(to): the result is unchanged bit for bit and a
Smith-Wilson bond present value no longer pays for a second sum. A time
dual at 0 still takes the full ratio, so its derivative is kept.

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

A composite took its components' cumulative log-discounts at t = Inf and then combined them, so
flat forwards of 4% and -2% gave Inf + -Inf = NaN at infinity although the sum tends to +Inf
(FinanceModels 6, which summed zero rates, gave 0). Each curve now describes the tail of L,
L(t) = a2·t² + a1·t + a0 + o(1): the knot-curve tails (Spline, MonotoneConvex) and Constant in
closed form, CompositeYield combining componentwise with its + or -, ScaledYield scaling each
coefficient, ForwardStarting shifting the base tail, and HullWhite and the primal view
delegating. Any other curve contributes its zero rate at infinity as the slope with no known
intercept, which is exactly the previous sum of zero rates. The existing classification (the
first nonzero of a2 then a1 decides 0 or Inf, else exp(-a0); a deciding coefficient that is zero
but carries partials has no derivative) runs on the combined coefficients, so cancelling
long-run forwards leave their finite intercept instead of NaN, and a single knot curve's limits
are unchanged bit for bit. The wrappers' limits are out of line so the finite-time path stays
small.

ForwardStarting's log-discount subtracted the base curve's two absolute log-discounts, which
throw where a signed Smith-Wilson fit has negative discount factors at both ends although the
rebased factor is positive. It is now the base curve's log-discount over the interval: the
difference of L for a log-native curve, otherwise the log of the curve's own interval factor,
and for Smith-Wilson ufr·(b - a) - log((1 + s(b))/(1 + s(a))), which is also finite in the far
tail. A nonpositive rebased factor still raises the natural DomainError.

Tests: the reviewer's opposite flat forwards (a + b, b + a, a - a/2 at Inf and (1, Inf)); a
cancelled flat-forward slope leaving exp(0.03125); equal :linear slopes; ForwardStarting(c, 3) - c;
0 * a; the no-derivative throw on a combined zero forward; -Inf still rejected; Nelson-Siegel and
TenorShift composites equal to the zero-rate formula; and zero, forward, scaling and + of a
Smith-Wilson rebased where both absolute factors are negative, against the relative factor.

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

The fallback tail for a curve without a closed form is (0, z(∞), NaN). When
z(∞) = ±Inf, L grows faster than t at an order the curve doesn't state, so its
a2 = 0 is not a known coefficient. The classifier read a2 first, so a known
quadratic of the other sign decided the limit: a TenorShift with zero rate t/32
minus a `:linear` curve with t/64 (L = t²/64 → +Inf) gave discount Inf instead
of 0, and the reverse gave 0 instead of Inf.

The forward slot is now read first. NaN there is unknown. ±Inf is unknown
growth of that sign: it decides the limit unless a2 has the other sign, and
then the limit is NaN. Combining, scaling and rebasing already carry ±Inf
correctly (Inf − Inf is NaN), so the fallback's numbers don't change, and a
fallback curve plus a flat or same-sign tail keeps FinanceModels 6's limit.

Also documents the internal curve capabilities (`__log_discount`,
`__log_native`, `__log_interval`, `__log_tail`): what each means, its default,
and which types define it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
@alecloudenback
alecloudenback force-pushed the refactor/composite-yield-factor-ops branch from 51de88a to 32d1d0a Compare September 27, 2026 15:19
@alecloudenback
alecloudenback force-pushed the feat/log-discount-intervals branch from a96e0e3 to 5698867 Compare September 27, 2026 15:19
5698867 returned as soon as a tail with unknown growth had a primal zero
quadratic coefficient, so a coefficient that was zero only at the primal values
skipped the check that a deciding coefficient carrying partials has no
derivative. With L = t^1.5 + k·t²/64 the limit at infinity is 0 at k = 0 but Inf
for every k < 0, yet d/dk returned 0.0 at k = 0. The zero quadratic coefficient
now goes through the same check as a known tail's and throws; the check is one
shared helper. NEWS and the tests call the opposing-growth limit unsupported.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
This was referenced Sep 27, 2026
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