Skip to content

Derivatives at interpolation kinks; notional-independent solver checks; discount at Inf - #320

Merged
alecloudenback merged 3 commits into
masterfrom
fix/interpolation-kinks
Oct 1, 2026
Merged

alecloudenback merged 3 commits into
masterfrom
fix/interpolation-kinks

Conversation

@alecloudenback

@alecloudenback alecloudenback commented Sep 24, 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 #320, number 5 of 10 open (base #319; next #322).


Stacked on #319. Review against fix/swaption-critical-rate-derivatives. Three commits from an external review of the FM 7 work and two rereviews.

Derivatives at interpolation kinks. Spline.MonotoneConvex(), PCHIP() and Akima() are only piecewise smooth in their knot rates. Where they switch formula (a flat stretch, equal adjacent forwards, a straight run of Akima knots), ForwardDiff returned a derivative that matched neither an up nor a down bump: flat MonotoneConvex knot sensitivities could be off by a factor of two, flat PCHIP gave NaN, and a flat MonotoneConvex curve on a dense grid gave derivatives driven by rounding noise.

  • MonotoneConvex reports, for each partial, the limit of a centered bump in its direction. On a flat stretch these partials need not sum to the parallel-shift derivative (documented prominently).
  • PCHIP and Akima throw when dual knot rates move a kink, including Akima's 1e-9 weight cutoff, where DataInterpolations' value jumps. These rules copy DataInterpolations internals; they live in src/model/Yield/Kinks.jl, and a grouped testset checks them against the installed version.
  • A differentiated fit throws when its fitted curve lies on, or within its precision of, a kink.

Notional-independent solver checks. implied_quote, the swaption critical rate and differentiated fits judged vanishing slopes and conditioning on an absolute scale, and bootstrap solved each quote to an absolute tolerance (a 1e-10 notional fitted its zero rate only to about 1e-5). Every check and solve is now relative to the size of the quote. A differentiated loss fit's accuracy check bounds one Newton correction of its knot rates (≤ 1e-6).

discount(curve, Inf) returns the tail's limit instead of NaN for a zero tail forward, and throws under AD where a zero tail slope or forward carries partials.

Docs: the sensitivity contract (first order; risk to the quotes passed vs. a synthetic quote family; exact fits; kinks) is summarized on the calibration page, in the migration guide, in the fit and reconstruct docstrings, and on the home page.

🤖 Generated with Claude Code

alecloudenback and others added 3 commits September 24, 2026 19:29
…tional-independent

MonotoneConvex, PCHIP and Akima are only piecewise smooth in their knot
rates. Where they switch formula, ForwardDiff returned derivatives that
matched neither an up nor a down bump. A flat MonotoneConvex curve was off
by up to a factor of two per knot; on a dense grid rounding picked the
sector and the error reached 3.4. Flat PCHIP gave NaN, and a straight run
of Akima knots a fallback formula's derivative.

- MonotoneConvex: each partial is the limit of a centered bump in its
  direction. Where two sectors meet (adjacent discrete forwards equal)
  that is the average of their partials, which stays additive. On a flat
  interval it is the sector formula evaluated at the tangent. A
  collar tie averages the raw and bound forwards. Ties within rounding of
  the discrete forwards count, and unresolvable ties or second
  derivatives throw. Primal values are unchanged.
- PCHIP and Akima: the public constructors throw when dual knot rates
  move a kink. FinanceModels' own trial curves are not checked.
- Differentiated fits throw when the fitted curve lies on a kink, or
  within the fit's precision of one.

Also:
- implied_quote, the swaption critical rate, and differentiated fits now
  judge vanishing slopes and conditioning relative to the quote's size.
  A bootstrap solves each quote relative to its size too: at a 1e-10
  notional it had fitted only to about 1e-5 in its zero rate.
- discount(curve, Inf) returns the tail's limit; with a zero tail forward
  it was NaN.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…he infinite tail under AD

Rereview of 9b26de3:

- A first knot at t = 0 leaves a zero-width interval. The rounding
  tolerances divided by it: PCHIP/Akima threw on smooth curves (Inf) and a
  flat MonotoneConvex gave NaN gradients (0/0). Both now skip it.
- DataInterpolations (9.2 to 10.1) switches an Akima node to its fallback
  slope where the node's weight is at most 1e-9 of the largest, and the
  curve's value jumps there. The kink quantities now include that cutoff, so
  dual knots and differentiated fits at it throw. A test checks that the
  quantity changes sign exactly where the installed version switches.
- discount(curve, Inf) classifies its limit on primal values. A zero
  `:linear` slope or tail forward that carries partials throws instead of
  returning 1.0 for 0.0.
- A differentiated fit's accuracy check bounds one Newton step (the knot
  rates' distance from the exact fit), not the row-scaled residual, which an
  ill-conditioned family can keep small while a knot is far off.
- Docs no longer say market curves essentially never sit on a kink; the kink
  tests no longer overwrite local methods.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- Move the kink logic to src/model/Yield/Kinks.jl, with the copies of
  DataInterpolations' PCHIP and Akima branch rules in one marked block.
  Differentiated fits call a single `Yield.__near_kink(curve, z[, δ])`
  instead of handling kink quantities and rounding tolerances themselves.
- Group the tests that tie those copies to the installed DataInterpolations,
  and add PCHIP's end-slope limit |d| = 3|δ₁| to them.
- State the fit accuracy criterion precisely: the largest absolute component
  of one Newton correction of the knot rates must be at most 1e-6, a local
  error estimate rather than a guaranteed distance to the exact fit.
- Summarize the sensitivity contract (first order; risk to the quotes passed
  versus a synthetic quote family; exact fits; kinks, including that
  MonotoneConvex's responses on flat stretches do not aggregate like a
  gradient) on the calibration page, in the migration guide, in the `fit`
  and `reconstruct` docstrings, in NEWS, and on the home page and README.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@alecloudenback
alecloudenback force-pushed the fix/swaption-critical-rate-derivatives branch from 24e157e to 58d6923 Compare September 25, 2026 01:30
This was referenced Sep 25, 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