Skip to content

Standardize selectable yield-curve extrapolation - #308

Merged
alecloudenback merged 8 commits into
masterfrom
fix/curve-extrapolation-policy
Oct 1, 2026
Merged

alecloudenback merged 8 commits into
masterfrom
fix/curve-extrapolation-policy

Conversation

@alecloudenback

@alecloudenback alecloudenback commented Sep 7, 2026 •

Copy link
Copy Markdown
Member

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: FinanceModels #308, number 4 of 15 (base #295; next #315).


Rebuilt 2026-09-24: one commit that folds in #312, rebuilt on #295 and #311. Policies: :flat_forward (default), :flat_zero, :linear, :extension (the previous DataInterpolations continuation) and Yield.FlatForwardAt(rate), which requires a FinanceCore.Rate. The default tail of DataInterpolations-backed curves holds the last discrete forward, so zero rates beyond the last knot change (:extension restores the old values; NEWS quantifies a 30y example); MonotoneConvex keeps its native boundary forward. #312's MonotoneConvex bootstrap route is removed (#311 wins): MonotoneConvex bootstrap throws with guidance to fit(Spline.MonotoneConvex(), quotes).


Summary

  • make flat-forward extrapolation the documented default for every knot-based yield curve
  • add an explicit extrapolation keyword to Yield.Spline, ZeroRateCurve, build_model, and spline fit paths
  • support flat_forward, flat_zero, linear, and the opt-in legacy extension behavior
  • preserve the selected policy through ZeroRateCurve reconstruction and Accessors updates
  • widen DataInterpolations compatibility to versions 9 and 10

Behavior

For a final knot (t_n, z_n), flat_forward anchors the tail to the left-hand boundary instantaneous forward and uses

z(t) = f_n + (z_n - f_n) * t_n / t

This preserves the final-knot discount factor and prevents a quadratic or cubic final polynomial piece from dominating at long horizons. MonotoneConvex supports flat_forward, flat_zero, and linear; extension is rejected because it has no DataInterpolations polynomial piece to continue.

The extension option deliberately restores the previous DataInterpolations behavior for users who require it, including its potentially extreme long-horizon values.

Testing

  • full FinanceModels package suite with DataInterpolations 9.3
  • selector and ForwardDiff matrix across all DataInterpolations-backed descriptors with DataInterpolations 10.1
  • updated Yield and ZeroRateCurve regression tests
  • documentation build and doctests

Stack

This PR targets feat/knot-grid-shared-storage and depends on the ZeroRateCurve/knot-grid stack in #294 and #295. PR #305 is already merged into that branch. It also incorporates the DataInterpolations 10 compatibility expansion proposed separately in #306.

@codecov

codecov Bot commented Sep 8, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (feat/knot-grid-shared-storage@ada2110). Learn more about missing BASE report.

Additional details and impacted files
@@                       Coverage Diff                        @@
##             feat/knot-grid-shared-storage     #308   +/-   ##
================================================================
  Coverage                                 ?   94.66%           
================================================================
  Files                                    ?       17           
  Lines                                    ?     1124           
  Branches                                 ?        0           
================================================================
  Hits                                     ?     1064           
  Misses                                   ?       60           
  Partials                                 ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

alecloudenback and others added 3 commits September 23, 2026 15:13
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
alecloudenback and others added 4 commits September 24, 2026 17:20
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
ActuaryUtilities depends on FinanceModels, and every registered version caps
it at 6, so once master is 7.0.0-DEV the test environment cannot resolve with
ActuaryUtilities as a test dependency. Drop it from test/Project.toml and run
test/downstream/ActuaryUtilities.jl in a separate Downstream workflow against
ActuaryUtilities' v6 development branch, with its FinanceModels compat bound
removed, until ActuaryUtilities 6 is registered.

The curve convexity expectation follows ActuaryUtilities 6: a continuous
zero-rate shift gives Σ cf·d·t²/V.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
ZeroRateCurve, Yield.Spline and Yield.MonotoneConvex now obtain their knots
through one internal Yield.KnotGrid construction that copies, promotes and
validates rates and tenors (length, emptiness, finiteness, ordering and the
interpolant's minimum knot count). Curves no longer alias caller vectors, so
mutating an input cannot leave stale cached coefficients or forwards.

- ZeroRateCurve and MonotoneConvex expose read-only knot vectors and rebuild
  their caches through the ConstructionBase protocol, so Accessors updates
  and fitting re-validate instead of keeping stale state.
- The public KnotGrid constructors always copy and validate. Optimizer trial
  curves use the internal KnotGrid(Yield.Unchecked(), ...) form, and curves
  built from a grid check their own minimum knot count.
- Fitting MonotoneConvex and ZeroRateCurve varies all knot rates through one
  batch KnotRatesOptic: one rebuild per optimizer candidate instead of one per
  knot. A regression test checks roughly linear allocation in knot count.
- Unsuccessful optimizer solves throw the new exported FitConvergenceError
  (carrying the solver return code) instead of returning an unfitted model.
- Spline.PolynomialSpline accepts only orders 1 to 3; Spline.BSpline
  requires degree 1 or more.
- __owned_float_vector rethrows unexpected exceptions and converts only
  method and conversion failures into ArgumentErrors.
- Docs describe the privacy of internal fields as conventional.

Version set to 7.0.0-DEV. Includes #294, #295 and #305, rebuilt on #311.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Knot curves take an `extrapolation` policy for the long end: `:flat_forward`
(default), `:flat_zero`, `:linear`, `:extension` (the previous
DataInterpolations continuation) or `Yield.FlatForwardAt(rate)`. Yield.Spline,
ZeroRateCurve, Yield.MonotoneConvex, Yield.build_model and the spline fit
methods accept it; ZeroRateCurve and MonotoneConvex keep it as a public
property that fitting and Accessors updates preserve. Spline and MonotoneConvex
tails share one coefficient representation, so a runtime policy Symbol does
not change the constructed type.

- The default `:flat_forward` tail of DataInterpolations-backed curves holds
  the last discrete forward (zₙtₙ - zₙ₋₁tₙ₋₁)/(tₙ - tₙ₋₁) (z₁ for a single
  knot). Discount factors stay continuous at the last knot; the forward may
  jump there. The end polynomial no longer drives the tail: on an
  upward-sloping 2% to 4% curve its endpoint forward is -6.8% for BSpline(3).
  MonotoneConvex keeps its native boundary instantaneous forward.
- This changes zero rates beyond the last knot for every
  DataInterpolations-backed curve and fit. `extrapolation = :extension`
  restores the previous values.
- `:extension` uses the same wrapper type as the other policies, so
  construction is concretely inferred for PCHIP, Akima and B-spline curves.
- `FlatForwardAt` requires a FinanceCore.Rate; a bare number throws with
  guidance to pass Continuous(x) or Periodic(x, m).
- A `:linear` tail with a zero boundary slope returns the flat value at
  t = Inf instead of 0 * Inf = NaN, for both spline and MonotoneConvex
  curves.
- Bootstrap (#311) keeps its strategy gate first, then the extrapolation
  policy, input checks and the post-solve repricing check. MonotoneConvex
  bootstrap throws with guidance to fit(Spline.MonotoneConvex(), quotes);
  the stack's MonotoneConvex bootstrap route is removed.
- MonotoneConvex equality and hashing use (rates, times, extrapolation).
- Migration guide and NEWS describe the anchor and quantify the changed
  numbers.

Includes #308 and #312, rebuilt on the knot-grid commit and #311.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@alecloudenback
alecloudenback force-pushed the feat/knot-grid-shared-storage branch from bbf5c19 to b36db41 Compare September 24, 2026 23:23
@alecloudenback
alecloudenback force-pushed the fix/curve-extrapolation-policy branch from a5af116 to 158ce30 Compare September 24, 2026 23:23
Base automatically changed from feat/knot-grid-shared-storage to master September 30, 2026 23:14
#311, #314 and #295 were squash-merged into master, so this branch still
carried their original commits and conflicted with the squashed versions.
master's tree is identical to b36db41, the #295 commit this branch builds
on (as #295's own merge of master, ae7d239, also was), so this merge keeps
the branch's tree unchanged: its diff against master is exactly this PR's
own changes (b36db41..158ce30).
@alecloudenback
alecloudenback merged commit f166f78 into master Oct 1, 2026
9 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