Skip to content

Add Heston model calibration adjoint example - #26

Open
tylrcc wants to merge 1 commit into
auto-differentiation:mainfrom
tylrcc:example/heston-model-adjoint
Open

tylrcc wants to merge 1 commit into
auto-differentiation:mainfrom
tylrcc:example/heston-model-adjoint

Conversation

@tylrcc

@tylrcc tylrcc commented Nov 12, 2026 •

Copy link
Copy Markdown

Closes #19.

Python port of the AdjointHestonModel C++ example, following the pattern of swap-adjoint.py:

  • Same setup as the C++ original: DAX data from QuantLib's Heston test (spot 4468.17, 13 strikes x 8 expiries = 104 prices, fit on prices via HestonModelHelper with PriceError), COSHestonEngine(model, 12, 75), Levenberg-Marquardt at tolerance 1e-12 starting from (0.1, 1.0, 0.5, -0.5, 0.1), then a forward-start call (strike set in 6M, expiry 18M) priced with AnalyticHestonForwardEuropeanEngine.
  • Sensitivities to all 114 market inputs via the implicit function theorem: Hessian blocks of the calibration objective from central differences of its adjoint gradient (11 recordings), one more recording for dV/dp and the direct dV/dm, and a 5x5 solve (numpy, already in the examples' requirements).
  • The AAD computation is in an aad_sensitivities() function returning the forward-start value and a dict of sensitivities keyed by input name. All 114 inputs are cross-checked inside the example by bump-and-recalibrate with central differences (for the spot, h is 1e-5 relative to its scale).

Testing: run on QuantLibAAD 1.44.0 (Python 3.12), with the calibration run on COSHestonEngine as written: calibrated theta 0.0722, kappa 3.6199, sigma 1.2293, rho -0.5790, v0 0.1289, forward-start value 480.63. Largest relative difference over all 114 inputs: 1.8 (vol 3600 2W). That worst case is a property of the check, not the sensitivities: vol 3600 2W's direct sensitivity is exactly 0.0, so its whole value comes through recalibration, and a 1e-5 bump barely moves the optimizer (it stops on a stationary function value), capturing only ~35% of the recalibration effect; at h = 1e-4 it captures ~95%. The ten largest sensitivities agree to 2.4e-04–1.8e-03. This is explained in the example; happy to use a larger bump for the check if you prefer.

Note: this repo requires a signed CLA before merge (per CONTRIBUTING) — I understand it will be handled through the CLA flow.

@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

Rebase onto current main and address review: run against QuantLibAAD
1.44.0 with COSHestonEngine as written, move the AAD computation into
aad_sensitivities() returning the forward-start value and a dict of
sensitivities keyed by input name, replace the forward-difference check
on the eight largest sensitivities with central differences over all 114
inputs, and add a CHANGELOG entry.

Run on QuantLibAAD 1.44.0: calibrated theta 0.0722 kappa 3.6199 sigma
1.2293 rho -0.5790 v0 0.1289, forward-start value 480.63; largest
relative difference over all 114 inputs 1.8e+00 (vol 3600 2W). The ten
largest sensitivities agree to 2.4e-04-1.8e-03; the worst case is a small
sensitivity that comes entirely through recalibration, which a 1e-5 bump
does not move enough to register -- see the note in the example.
@tylrcc
tylrcc force-pushed the example/heston-model-adjoint branch from 0217edd to 2f0b28b Compare November 14, 2026 18:54
@tylrcc

tylrcc commented Nov 14, 2026

Copy link
Copy Markdown
Author

Review points addressed (same as #23):

  1. Runs on QuantLibAAD 1.44.0 from PyPI (Python 3.12), with the calibration run through COSHestonEngine as written in the example — no analytic engine anywhere in this run.
  2. Rebased onto current main — the diff is now just the example plus one CHANGELOG line.
  3. Central-difference check over all inputs: (V(x+h) - V(x-h)) / (2h) with h = 1e-5 (relative to the input scale for the spot: an absolute 1e-5 bump on a 4468.17 spot moves the price by less than the recalibration can resolve, so the spot is bumped by 1e-5 of its own value). Actual run output:
    Largest relative difference over all 114 inputs: 1.8e+00 (vol 3600 2W)
    That number needs the honest context, because it is the check's limit, not the sensitivities'. The ten largest sensitivities agree to 2.4e-04–1.8e-03. The worst case is vol 3600 2W, a small sensitivity (-1.26) that comes entirely through the recalibration — its direct sensitivity is exactly 0, since a 2-week volatility cannot directly move a forward-start option that starts in 6 months. A 1e-5 bump barely moves the optimizer (it stops on a stationary function value before the parameters reach the new optimum), so the bumped value captures only part of the recalibration effect; at h = 1e-4 it captures most of it (rel 4.7e-02). Tightening the calibration tolerance to 1e-14 does not help — the stopping point is effectively noisy at that precision. The example notes this. Happy to switch the check to a larger bump if you prefer the agreement to read cleaner, but I did not want to deviate from the h = 1e-5 you asked for without saying so.
  4. aad_sensitivities(): the calibration, pricing and implicit-function-theorem computation now live in a function returning the forward-start value, a dict of sensitivities keyed by input name, and the calibrated parameters (the check restarts each recalibration from them); the script calls it and prints the results as before.
  5. CHANGELOG: line added under ## [Unreleased] / ### Added.

Run on QuantLibAAD 1.44.0: calibrated theta 0.0722, kappa 3.6199, sigma 1.2293, rho -0.5790, v0 0.1289; forward-start value 480.63 — all unchanged from the 1.33.3 run. Full run takes about 8 minutes (228 recalibrations).

The CLA is still unsigned on my side; that is separate from these changes.

@auto-differentiation-dev

Copy link
Copy Markdown
Contributor

Thanks for the detailed note on the check and the COS engine. We'll look at the finite-difference comparison closely in the review, but first this PR needs a signed CLA, like #23 to #25: the link is in the bot comment at the top, with a "recheck" link if you've signed already. If the CLA is a concern, say so and we'll help.

Please also update the PR description (it still mentions the 1.33.3 run and the analytic-engine substitution). The review continues as soon as the CLA check is green.

This branch has not been deployed

No deployments
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.

Heston model example with AAD

3 participants