AADC Tracer

Understand why your numerical result changed.

A library upgrade, a model change, a price you cannot explain. AADC Tracer records the calculation and links its inputs, constants and executed branches to the source code. Follow the result back to the lines that produced it.

Investigate an unexpected result. Follow the calculation through the model and the libraries it calls.
Review a code change. Compare recorded runs with the same inputs to see where their calculations differ.
Give a reviewer the evidence. Keep the recorded inputs and source references alongside your findings.

Start with a calculation you know

Run a prepared QuantLib example in the browser and inspect the source locations behind its result. For your own model, start with a question: an unexpected price, a change after an upgrade, or an assumption a reviewer needs to check. The recorded run gives you evidence to investigate that question.

Which assumptions reached this price?

A swaption calculation uses a search interval, numerical cut-offs and day-count conventions. The trace below shows where some of those choices enter the calculation. This QuantLib 1.41 run recorded 150 constant sites and 59 branch sites across 40 source files. The snippet calls these frozen-branch sites: branch decisions fixed for this recorded run. A recorded constant or branch is something to inspect; its presence alone does not establish a defect.

NPV 16912.75857915684
150 constant sites, 59 frozen-branch sites, 40 source files

jamshidianswaptionengine.cpp:102   minStrike = -10
jamshidianswaptionengine.cpp:103   maxStrike = 10
vasicek.cpp:51                     B = 1.4901e-08    (x264)
errorfunction.cpp:209              0.84375           (x10)
actual365fixed.hpp:57              / 365.0

59 frozen-branch sites, e.g. brent.hpp:106, brent.hpp:110 ...

QuantLib 1.41, measured 22 October 2026 on the public packages: pip install "aadc==2.25.2" "aadc-quantlib-tracing==1.41.4" (Python 3.11, Linux x86-64). The swaption from the video is swaption.py (25 lines, ordinary QuantLib calls); swaption_trace.py records it and prints the price and the two counts above. Use the same approach for supported QuantLib calculations of your own.

Ask the record

The price comes with the record of how the library computed it, and the record answers questions without re-running the library.

Where did this number come from?
The operation that produced it, the formula behind it, and its source line.
Which decisions nearly went the other way?
Every input-dependent decision the calculation took, with the margin it was decided by.
What if an input were different?
The record reprices in milliseconds without re-running the library, or declines and names the decision that would go the other way, rather than return a wrong number.
Show me the line as it ran.
The source with the recorded values under it, verified against the file the library was compiled from.
Can I keep the record?
It is a small file that loads back into the engine and answers the same questions later.

Try each one on a trade in the live demo

Run with tracing enabled

Tracing requires a library built with the AADC compiler. QuantLib 1.41 is available ready to use on Linux x86-64 and macOS (Apple silicon) with Python 3.10 to 3.14. With that build installed, set AADC_TRACE=1 when you run the pricing program. For an in-house library, we first check the code and build requirements with you.

What you can inspect

Where the result came from

Follow recorded operations to their source file, line and function. Inspect the inputs and intermediate values used on that execution path.

Constants used in the calculation

Find tolerances, cut-offs, day-count denominators and solver brackets, with their values and source locations.

Decisions made during the run

See how close a recorded comparison was to choosing the other branch. Further runs with different inputs let you examine other paths within the agreed test range.

Review the findings against the record

An AI agent can use the trace to help investigate the calculation and draft a report. A reviewer can follow its source references, inspect the recorded values and check the explanation.

  • Keep the build version and inputs with each recorded run.
  • Link findings to the operations and source locations that support them.
  • Record the scenarios tested and the questions that still need review.

Run it now

Four commands reproduce the figures above on the public package. The Community Edition is free for non-commercial and academic use. Contact us about a commercial evaluation.

python3 -m venv tracer && . tracer/bin/activate
pip install "aadc==2.25.2" "aadc-quantlib-tracing==1.41.4"
curl -O https://matlogica.com/downloads/swaption.py -O https://matlogica.com/downloads/swaption_trace.py
python swaption_trace.py        # prints 16912.75857915684, then 150, then 59

Use it from your coding agent

aadc-mcp is a local MCP server that runs inside your own Python environment. Your coding agent can trace an unmodified QuantLib or Python pricer and ask the record where a price came from, which decisions were closest to going the other way, and what the price is at new inputs: exact when every recorded decision holds, withheld with the decision named when one does not. Every number in an answer is the engine's own output.

python3 -m venv aadc-env && . aadc-env/bin/activate
pip install "aadc-mcp[quantlib]"
aadc-mcp --check

AADC runs here as Community Edition: free for non-commercial and academic use; commercial use, including evaluation inside a company, needs a licence from MatLogica.

Work with your existing library

Tracer records calculations in supported C++ and Python code. Your model stays in its existing library; the library is built with the AADC compiler to enable tracing.

For an assessment, we agree the model, inputs and question to investigate before work starts. The report gives your developers and reviewers a common record to examine.

For model validation teams

Validation has to establish what pricing code actually does. Tracer records the calculation as it runs and turns it into evidence a validator can check line by line.

Validation taskReading the sourceWith Tracer
Establish the formula implemented Inferred from code and documentation Read from the operations that ran, each tied to file and line
List inputs and hard-coded constants Manual trace across files Enumerated automatically, with values and source lines
Verify model dependencies Taken from the model inventory and documentation Confirmed from what the calculation actually used
Find market-dependent branches Search for conditionals; easy to miss inside utilities Every decision listed, with the inputs that switch it
Test scenarios and compute Greeks Reprice and bump each scenario Replay with exact AAD Greeks
See where the work concentrates Separate profiling Operation counts per function and line
Keep model documentation current Written once; drifts as the code changes Drafted from each recorded run, so it describes the build that ran; a reviewer signs it off
Use an AI assistant in the review The assistant reads source and infers what the code probably does The assistant reads what the code did; every claim cites a file and line the validator can check

What a source review would likely miss, in the QuantLib case study

  • A day count that comes from the market objects, not the trade. Time to maturity follows the day counters on the curves and volatility surface the caller passes in, Actual/365 Fixed in this example. Set the curves and the volatility surface to Actual/360 and the price moves from 10.2777 to 10.3393. The recording names the convention each term actually used.
  • A sign decision inside Φ. errorfunction.cpp:225 chooses the sign of erf in the region 0.84375 ≤ |x| < 1.25; every Φ in the price is evaluated through this function.
  • A switch to an asymptotic expansion. normaldistribution.cpp:36 replaces the error-function result with an asymptotic series once the cumulative normal falls to 10−8 or below, which deep out-of-the-money terms can reach.

The evidence is verifiable (each claim cites a file and line), reproducible (recordings are kept) and complete within the tested scope, in line with the expectations of PRA SS1/23, Fed SR 26-2 and the ECB Guide to internal models.

Read the case study: QuantLib barrier option, five engines (PDF) ↓

A report your reviewer can follow

The case study records the model and inputs, maps dependencies and branches, and presents numerical checks alongside the findings. Source references let a reviewer investigate each finding. It describes the runs and scenarios examined; model approval remains with your team.

Read the barrier-option case study (PDF) ↓

Where it helps

Investigating a discrepancy

Developers can follow an unexpected result through the recorded calculation to its source.

Reviewing a model change

Compare the evidence from selected runs before and after a change to the model or its libraries.

Preparing validation evidence

Give validators the recorded inputs, source references and numerical checks behind a finding.

Bring us a calculation to investigate

Tell us which model or library you use, what changed and the result you need to understand. We will check compatibility and agree the scope of an assessment with you. Commercial use requires a licence.

AADC Tracer FAQ

What does AADC Tracer record?

It records operations, comparisons and inputs in a supported numerical calculation, with source file, line and function references. You can inspect the dependencies and constants on the recorded execution path.

What do I need to run it?

A library built with the AADC compiler. The aadc-quantlib-tracing package includes QuantLib 1.41 ready to trace on Linux x86-64 and macOS (Apple silicon) with Python 3.10 to 3.14. An in-house library needs a compatibility and build check. Setting AADC_TRACE=1 on an ordinary QuantLib installation does not add tracing.

Can I compare two versions of a model?

Yes. Record selected calculations in each supported build using the same inputs, then compare their results and execution evidence. The assessment covers the versions and scenarios you test.

Does one run cover every branch?

A run records the path taken for its inputs. Exploring other paths requires further runs. Keep the tested input ranges and any unexplored paths with the findings.

Can an AI agent use the trace?

Yes. An agent can inspect the recorded calculation and help draft findings with source references. A reviewer checks those findings against the evidence and decides what they mean for the model.

How does it fit alongside tests and a debugger?

Tests check selected behaviours and a debugger lets you inspect execution. Tracer adds a source-linked record of the numerical calculation that you can query and retain with the investigation.

Can it generate model documentation?

The record can support documentation of the calculation that ran. Keep the build version and inputs with that document, and update the evidence when the model or tested scenarios change.

What is in an assessment?

We agree a model, a question and a set of inputs with you. The resulting report brings together the recorded evidence, the checks performed and the findings for your team to review. The case study shows this evidence for a barrier option.

Is there a worked validation example?

Yes. The case study records QuantLib's down-and-out barrier call under five engines and lists every input and market-dependent decision, with findings graded by severity. It is illustrative: the validation decision stays with the validator.

What does it cost?

The Community Edition is free for non-commercial and academic use. Contact MatLogica for a commercial evaluation, a model assessment, commercial licensing or full-performance academic licensing.

Who makes it?

MatLogica Ltd, London, the company behind the AADC compiler.