aadc-quantlib-tracing

The aadc-quantlib build that can tell you which line of C++ produced each number.

This is QuantLib 1.41 with Real = idoubleNG, the same AADC type as aadc-quantlib, compiled through the AADC source-tracing pass. What it adds is attribution: after recording, every hardcoded constant and every frozen branch inside the library can be traced back to the C++ file, line and enclosing function that produced it.

It is a diagnostic and model-validation build, not the production one. Install aadc-quantlib for pricing; install this alongside it when you need to answer "where did this number come from?".

How it differs from aadc-quantlib. This build is the level 1 integration: stock QuantLib with Real bound to the AADC type and nothing else changed, so the attribution points at QuantLib's own code. aadc-quantlib carries AAD-aware replacements for some numerics (solvers, bootstraps), which record fewer frozen branches. Prices and sensitivities agree at the point of recording. When a recorded tape is replayed far from that point, this build follows more frozen branches than aadc-quantlib and can drift where the production wheel would not — treat its tapes as a diagnostic of this recording, and re-record rather than reuse them for bump-and-replay at distant inputs.

Install

Pick the QuantLib line that matches your aadc-quantlib: the wheel's version starts with the QuantLib version it wraps (1.38.* is QuantLib 1.38, 1.41.* is QuantLib 1.41), and several lines are published under this one name.

pip install "aadc-quantlib-tracing==1.41.*"

An unpinned pip install aadc-quantlib-tracing resolves to the newest release across every line, which is not necessarily the line of the aadc-quantlib you already have.

Linux x86-64 only, CPython 3.10–3.14. There is no macOS, Windows or arm64 build: the tracing pass is an LLVM plugin that runs in one container image. aadc-quantlib itself ships on all four platforms — only this variant is restricted.

It installs beside aadc-quantlib rather than replacing it: separate distribution, separate import name, so both can be present in one environment and you choose per import. Do not expect import aadc_quantlib to pick this up.

The import is aadc_quantlib_tracing

from aadc_quantlib_tracing import QuantLib as ql

What it shows you

import aadc
from aadc_quantlib_tracing import QuantLib as ql

f = aadc.Functions()
f.start_recording(trace=True, trace_inputs_as_random=True)
# ... build and price an instrument with the QuantLib API ...
f.stop_recording()

for leaf in f.traced_leaves():
    print(f"{leaf['file']}:{leaf['line']}  {leaf['function']}  = {leaf['value']}")

for w in f.passive_warnings():
    print(f"frozen branch at {w['file']}:{w['line']}")

traced_leaves() reports the constants the library itself supplies — day-count denominators, tolerances, comparison epsilons — each with its declaration site and its record-time value. passive_warnings() reports every place a decision was frozen into the tape at recording time, which is where a replay at different inputs can silently follow the wrong branch.

Together they answer a question no amount of reading the Python can: what does this pricing actually depend on, including the parts nobody passed in?

Costs, stated plainly

• Size. ~43 MB per wheel against ~32 MB for aadc-quantlib, and the unpacked library is substantially larger — the attribution index is ~34 MB of the shipped libQuantLib.
• Not faster. Tracing changes what the recording remembers, not how fast it replays. Use aadc-quantlib for throughput.
• Attribution follows inlining. It is compiled -O2 -g, which is what makes the attribution point at real call sites. Do not expect debugger-grade stepping.

What it does not contain

The shipped library carries no DWARF debug sections and no symbol table — it is stripped like any release build. The attribution index stores source locations, not source text: no QuantLib or Matlogica source code is embedded in the wheel.

Licence

Proprietary — Matlogica. LICENSE.txt in the installed aadc_quantlib_tracing-<version>.dist-info/licenses/ is the AADC Community Edition Licence Agreement; non-commercial and academic use only, with commercial and full-performance academic licences available from info@matlogica.com. THIRD-PARTY-NOTICES.txt beside it covers QuantLib, Boost and the other bundled third-party components.

importlib.metadata.version("aadc-quantlib-tracing") reports the wheel version.