Metadata-Version: 2.4
Name: aadc-quantlib-tracing
Version: 1.38.9
Summary: QuantLib 1.38 with AADC-NG source tracing -- attribute each recorded constant and frozen branch to its C++ line (Linux x86-64)
Author-email: Matlogica <info@matlogica.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://matlogica.com
Project-URL: Documentation, https://matlogica.com/docs
Keywords: quantlib,quantitative-finance,derivatives,pricing,greeks,risk,automatic-differentiation,algorithmic-differentiation,adjoint,AAD
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: C++
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: THIRD-PARTY-NOTICES.txt
Requires-Dist: aadc<3,>=2.18.0
Dynamic: license-file

# aadc-quantlib-tracing

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

This is the same QuantLib 1.38 with `Real = idoubleNG`, from the same sources as
[`aadc-quantlib`](https://matlogica.com), compiled through the AADC source-tracing
pass. The prices and sensitivities are identical. 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?".

## Install

```sh
pip install aadc-quantlib-tracing
```

**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`

```python
from aadc_quantlib_tracing import QuantLib as ql
```

## What it shows you

```python
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.
