Skip to content

Add American option adjoint example - #24

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

tylrcc wants to merge 1 commit into
auto-differentiation:mainfrom
tylrcc:example/american-option-adjoint

Conversation

@tylrcc

@tylrcc tylrcc commented Nov 12, 2026 •

Copy link
Copy Markdown

Closes #16.

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

  • Same setup as the C++ original: American put, spot 36, strike 40, rate 0.06, vol 0.20, dividend yield 0.00, evaluation date 15 May 1998, maturity 17 May 1999, priced with FdBlackScholesVanillaEngine (801 time steps, 800 grid points).
  • All five inputs registered on the tape; rho, strike sensitivity, vega, delta, and dividend rho from a single adjoint pass.
  • The AAD computation is in an aad_sensitivities() function returning the option value and a dict of sensitivities keyed by input name. The example cross-checks the Greeks against central differences (h = 1e-5) over all five inputs.

Testing: run on QuantLibAAD 1.44.0 (Python 3.12): value 4.4861132726, largest relative difference over all 5 inputs: 9.8e-06 (risk-free rate). The residual is the 801-step FD grid's own noise rather than adjoint error — it does not shrink as h varies (checked at h = 1e-3/1e-4/1e-5/1e-6), while strike and underlying agree to ~1e-7; this is noted in the example.

Dividend rho: on 1.44.0 the adjoint dividend rho matches bumping (9.046355 vs 9.046284), so the earlier zero-dividend-rho caveat is removed from the example and dividend yield is included in the check.

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.

@auto-differentiation-dev

Copy link
Copy Markdown
Contributor

@tylrcc friendly reminder: the CLA (link in the bot comment above) is the only thing holding these four PRs. It takes a minute to sign, and then we can get CI going and review them.

Rebase onto current main and address review: run against QuantLibAAD
1.44.0, move the AAD computation into aad_sensitivities() returning the
option value and a dict of sensitivities keyed by input name, replace the
forward-difference check with central differences over all 5 inputs, and
add a CHANGELOG entry. QuantLibAAD 1.44.0 fixes the zero dividend rho
with finite-difference engines, so the caveat is removed and the dividend
yield is included in the check.

Run on QuantLibAAD 1.44.0: option value 4.4861132726; largest relative
difference over all 5 inputs 9.8e-06 (risk-free rate), limited by the
finite-difference engine's grid noise.
@tylrcc
tylrcc force-pushed the example/american-option-adjoint branch from adcac43 to 986e767 Compare November 14, 2026 18:30
@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).
  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, over all 5 inputs. Actual run output:
    Largest relative difference over all 5 inputs: 9.8e-06 (risk-free rate)
    One honest caveat: the agreement is at the 1e-5 level, not 1e-8, and that limit is the finite-difference engine, not the adjoints — repricing on the fixed 801-step grid carries grid noise of that size in the rate, volatility and dividend yield (the discrepancies do not shrink with smaller h; the strike and underlying agree to about 1e-7). The example notes this.
  4. aad_sensitivities(): the AAD computation now lives in a function returning the option value and a dict of sensitivities keyed by input name; the script calls it and prints the results as before.
  5. CHANGELOG: line added under ## [Unreleased] / ### Added.

American-specific point: the 1.44.0 fix is confirmed — the adjoint dividend rho is now 9.046355 against a bumped 9.046284, so the old zero-dividend-rho caveat is removed from the example and the dividend yield is included in the check. Option value 4.4861132726, unchanged from the 1.33.3 run.

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 update here too. Same as on #23: this PR needs a signed CLA before we can review or merge it. The link is in the bot comment at the top (and there's a "recheck" link if you've signed and it still shows pending). If the CLA itself is a problem, let us know.

Please also update the PR description, which still refers to the 1.33.3 run. We'll pick the review up 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.

Port the adjoint American option example

3 participants