# lballabio/quantlib architecture

> Architecture diagram of the GitHub repository lballabio/quantlib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lballabio/quantlib
- Repository: https://github.com/lballabio/quantlib
- Video tour (about a minute): https://gitdiagram.com/lballabio/quantlib/video

## Overview

1. QuantLib is a C++ financial analytics library, not an application service. Its architecture is centered on reusable domain objects, pricing engines, numerical methods, and calibration structures, all compiled into a library consumed by examples and tests.

2. The deepest foundation is in `ql/time`, `ql/math`, `ql/patterns`, and `ql/utilities`. These provide dates/calendars/day-counts, interpolation/optimization/statistics/random numbers, the observer/lazy-object infrastructure, and general helpers used throughout the rest of the library.

3. Market data is modeled as first-class objects: `ql/quote`, `ql/quotes`, `ql/currency`, `ql/currencies`, `ql/index`, `ql/indexes`, and the various `ql/termstructures`. These represent observable inputs such as interest-rate curves, vol surfaces, inflation curves, credit curves, and index fixings.

4. The core financial abstraction layer is in `ql/instrument`, `ql/payoff`, `ql/exercise`, `ql/cashflow`, and `ql/settings`. Instruments are composed from schedules, cash flows, and payoff/exercise definitions, while `Settings` and observables coordinate evaluation dates and market updates.

5. Pricing is split into instrument definitions and pricing implementations. The `ql/pricingengines` subtree contains specialized engines for vanilla options, barriers, swaptions, bonds, credit, inflation, futures, forwards, basket/exotic products, and multi-method solvers. Instruments delegate valuation to an attached engine rather than pricing themselves.

6. Model and process layers sit between market inputs and engines. `ql/processes` defines stochastic processes such as Black-Scholes, Heston, Hull-White, CIR, and G2; `ql/models` wraps these into calibratable model families such as short-rate, equity, volatility, and market models. Engines depend on these processes/models for analytic, tree, finite-difference, or Monte Carlo valuation.

7. Numerical methods are a major subsystem. `ql/methods` and `ql/math` provide finite-difference operators/meshes/solvers, lattice trees, Monte Carlo path generation, root finding, optimization, and numerical integration. These are reused by engines rather than embedded inside instrument code.

8. Term-structure construction is a key data-flow boundary. The `ql/termstructures` tree contains bootstrapping helpers and interpolated structures for yield, credit, inflation, and volatility. These structures are typically built from quoted market instruments and then queried by pricing engines and instruments.

9. There is a clear separation between “core” and “specialized/experimental” code. `ql/experimental` contains additional models, products, and methods that extend the main library with less standard or newer techniques, while `ql/legacy` keeps older Libor Market Model components that remain supported but are architecturally isolated.

10. The repository also includes reference content and integration points for users. `Examples/` contains standalone sample programs for common products and workflows, while `test-suite/` provides extensive regression and validation coverage across pricing, curves, calendars, and numerical routines.

11. Build and packaging are multi-platform and multi-system. The repo supports CMake, autotools/Makefile.am, and Visual Studio project files, with configuration for MSVC, GCC/Clang, and generated headers. This is important architecturally because many directories include their own `CMakeLists.txt` or `Makefile.am`, reflecting a modular compilation model.

12. Documentation and validation are first-class maintenance subsystems. `Docs/` contains the generated reference/manual structure, `man/` contains command-line and example manpages, and `.github/workflows` plus `tools/` automate header checks, formatting, licenses, docs, CI builds, fuzzing, and test timing. The repo therefore emphasizes library correctness, reproducibility, and API consistency over runtime deployment.

Main entry points: [`ql/instruments`](https://github.com/lballabio/quantlib/tree/master/ql/instruments) (Instruments), [`ql/pricingengines`](https://github.com/lballabio/quantlib/tree/master/ql/pricingengines) (Pricing engines), [`ql/termstructures`](https://github.com/lballabio/quantlib/tree/master/ql/termstructures) (Term structures), [`test-suite`](https://github.com/lballabio/quantlib/tree/master/test-suite) (Test suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_time["Time<br/>dates/calendars"]
  node_patterns["Patterns<br/>observer/lazy"]
  node_utilities["Utilities<br/>helpers"]
end

subgraph group_market["Market data"]
  node_quotes["Quotes<br/>market inputs"]
  node_currencies["Currencies<br/>money units"]
  node_indexes["Indexes<br/>rate/index ref"]
  node_termstructures["Term structures<br/>curves/surfaces"]
end

subgraph group_pricing["Pricing stack"]
  node_cashflows["Cash flows<br/>coupon leg pieces"]
  node_instruments["Instruments<br/>product defs"]
  node_engines["Pricing engines<br/>valuation impls"]
  node_processes["Processes"]
  node_models["Models"]
end

subgraph group_numerics["Numerics"]
  node_math["Math<br/>numerical core"]
  node_methods["Methods<br/>algorithms"]
end

subgraph group_extras["Extensions"]
  node_experimental["Experimental<br/>extensions"]
  node_legacy["Legacy LMM<br/>older models"]
end

subgraph group_support["Support"]
  node_examples["Examples<br/>sample apps"]
  node_tests["Test suite<br/>regression tests"]
  node_docs["Docs"]
  node_build["Build/CI<br/>tooling"]
end

node_time -->|"schedules/dates"| node_instruments
node_patterns -->|"observes"| node_quotes
node_patterns -->|"notifies"| node_termstructures
node_patterns -->|"drives updates"| node_instruments
node_utilities -->|"supports"| node_build
node_math -->|"enables"| node_methods
node_math -->|"powers"| node_engines
node_methods -->|"implements"| node_engines
node_quotes -->|"bootstraps"| node_termstructures
node_currencies -->|"defines units"| node_indexes
node_indexes -->|"fixings/inputs"| node_termstructures
node_termstructures -->|"market data"| node_engines
node_cashflows -->|"compose"| node_instruments
node_instruments -->|"delegates pricing"| node_engines
node_processes -->|"model inputs"| node_engines
node_models -->|"wraps"| node_processes
node_models -->|"calibration/valuation"| node_engines
node_experimental -->|"extends"| node_engines
node_experimental -->|"adds algorithms"| node_methods
node_legacy -->|"isolates"| node_models
node_examples -->|"demonstrates"| node_instruments
node_tests -->|"validates"| node_instruments
node_tests -->|"validates"| node_termstructures
node_tests -->|"validates"| node_math
node_docs -->|"documents"| node_instruments
node_docs -->|"documents"| node_termstructures
node_build -->|"builds"| node_examples
node_build -->|"runs"| node_tests
node_build -->|"generates"| node_docs

click node_time "https://github.com/lballabio/quantlib/tree/master/ql/time"
click node_patterns "https://github.com/lballabio/quantlib/tree/master/ql/patterns"
click node_utilities "https://github.com/lballabio/quantlib/tree/master/ql/utilities"
click node_math "https://github.com/lballabio/quantlib/tree/master/ql/math"
click node_methods "https://github.com/lballabio/quantlib/tree/master/ql/methods"
click node_quotes "https://github.com/lballabio/quantlib/tree/master/ql/quotes"
click node_currencies "https://github.com/lballabio/quantlib/tree/master/ql/currencies"
click node_indexes "https://github.com/lballabio/quantlib/tree/master/ql/indexes"
click node_termstructures "https://github.com/lballabio/quantlib/tree/master/ql/termstructures"
click node_cashflows "https://github.com/lballabio/quantlib/tree/master/ql/cashflows"
click node_instruments "https://github.com/lballabio/quantlib/tree/master/ql/instruments"
click node_engines "https://github.com/lballabio/quantlib/tree/master/ql/pricingengines"
click node_processes "https://github.com/lballabio/quantlib/tree/master/ql/processes"
click node_models "https://github.com/lballabio/quantlib/tree/master/ql/models"
click node_experimental "https://github.com/lballabio/quantlib/tree/master/ql/experimental"
click node_legacy "https://github.com/lballabio/quantlib/tree/master/ql/legacy"
click node_examples "https://github.com/lballabio/quantlib/tree/master/Examples"
click node_tests "https://github.com/lballabio/quantlib/tree/master/test-suite"
click node_docs "https://github.com/lballabio/quantlib/tree/master/Docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_time,node_patterns,node_utilities toneBlue
class node_quotes,node_currencies,node_indexes,node_termstructures toneAmber
class node_cashflows,node_instruments,node_engines,node_processes,node_models toneMint
class node_math,node_methods toneRose
class node_experimental,node_legacy toneIndigo
class node_examples,node_tests,node_docs,node_build toneTeal
```

## Components

### Core library

Fundamental domain abstractions and shared infrastructure.

- [Time](https://github.com/lballabio/quantlib/tree/master/ql/time): dates/calendars · Dates, calendars, schedules, day counts, and time grids. · `ql/time`
- [Patterns](https://github.com/lballabio/quantlib/tree/master/ql/patterns): observer/lazy · Observable, lazy object, singleton, and visitor infrastructure. · `ql/patterns`
- [Utilities](https://github.com/lballabio/quantlib/tree/master/ql/utilities): helpers · General-purpose helpers, tracing, parsing, and data formatting. · `ql/utilities`

### Market data

Observable inputs, indexes, and term structures.

- [Quotes](https://github.com/lballabio/quantlib/tree/master/ql/quotes): market inputs · Observable quotes and derived market input helpers. · `ql/quotes`
- [Currencies](https://github.com/lballabio/quantlib/tree/master/ql/currencies): money units · Currencies and exchange-rate management. · `ql/currencies`
- [Indexes](https://github.com/lballabio/quantlib/tree/master/ql/indexes): rate/index ref · Interest-rate, inflation, equity, and swap index definitions. · `ql/indexes`
- [Term structures](https://github.com/lballabio/quantlib/tree/master/ql/termstructures): curves/surfaces · Yield, credit, inflation, and volatility curves and bootstrapping. · `ql/termstructures`

### Pricing stack

Instruments, models, processes, and engines.

- [Cash flows](https://github.com/lballabio/quantlib/tree/master/ql/cashflows): coupon leg pieces · Coupons, dividends, cashflow variants, and pricers. · `ql/cashflows`
- [Instruments](https://github.com/lballabio/quantlib/tree/master/ql/instruments): product defs · Financial products composed from payoffs, exercises, schedules, and cash flows. · `ql/instruments`
- [Pricing engines](https://github.com/lballabio/quantlib/tree/master/ql/pricingengines): valuation impls · Specialized valuation engines attached to instruments. · `ql/pricingengines`
- [Processes](https://github.com/lballabio/quantlib/tree/master/ql/processes): stochastic processes · Black-Scholes, Heston, Hull-White, CIR, G2, and related processes. · `ql/processes`
- [Models](https://github.com/lballabio/quantlib/tree/master/ql/models): calibratable models · Model families wrapping processes for short-rate, equity, volatility, and market models. · `ql/models`

### Numerics

Reusable numerical methods and algorithms.

- [Math](https://github.com/lballabio/quantlib/tree/master/ql/math): numerical core · Core math primitives, distributions, interpolation, solvers, and random numbers. · `ql/math`
- [Methods](https://github.com/lballabio/quantlib/tree/master/ql/methods): algorithms · Finite differences, lattices, and Monte Carlo method scaffolding. · `ql/methods`

### Extensions

Experimental and legacy subsystems.

- [Experimental](https://github.com/lballabio/quantlib/tree/master/ql/experimental): extensions · Additional products, methods, models, and term-structure extensions. · `ql/experimental`
- [Legacy LMM](https://github.com/lballabio/quantlib/tree/master/ql/legacy): older models · Isolated Libor Market Model components kept for compatibility. · `ql/legacy`

### Support

Examples, tests, docs, and build/CI tooling.

- [Examples](https://github.com/lballabio/quantlib/tree/master/Examples): sample apps · Standalone sample programs demonstrating common workflows. · `Examples`
- [Test suite](https://github.com/lballabio/quantlib/tree/master/test-suite): regression tests · Extensive regression and validation coverage for the library. · `test-suite`
- [Docs](https://github.com/lballabio/quantlib/tree/master/Docs): reference docs · Generated manuals, reference pages, and documentation sources. · `Docs`
- **Build/CI**: tooling · CMake, autotools, Visual Studio projects, CI workflows, and maintenance scripts.

## Connections

- Time → Instruments: schedules/dates · Instruments rely on shared date and schedule primitives.
- Patterns → Quotes: observes · Quotes propagate updates through the observer infrastructure.
- Patterns → Term structures: notifies · Curves and surfaces react to quote and settings changes.
- Patterns → Instruments: drives updates · Instruments and cashflows participate in observable recalculation.
- Utilities → Build/CI: supports · Helper scripts and tracing support maintenance workflows.
- Math → Methods: enables · Low-level math primitives are reused by higher-level numerical methods.
- Math → Pricing engines: powers · Engines use solvers, interpolation, statistics, and random numbers.
- Methods → Pricing engines: implements · Finite-difference, lattice, and Monte Carlo algorithms back valuation engines.
- Quotes → Term structures: bootstraps · Market quotes feed curve and surface construction.
- Currencies → Indexes: defines units · Index families are currency-aware where relevant.
- Indexes → Term structures: fixings/inputs · Indexes provide fixings and conventions used in curve and coupon construction.
- Term structures → Pricing engines: market data · Pricing engines query discount, credit, inflation, and volatility structures.
- Cash flows → Instruments: compose · Instruments are built from cash-flow legs and payoff schedules.
- Instruments → Pricing engines: delegates pricing · Instruments attach to pricing engines rather than pricing themselves.
- Processes → Pricing engines: model inputs · Analytic, tree, FD, and Monte Carlo engines depend on stochastic processes.
- Models → Processes: wraps · Models package processes into calibratable families.
- Models → Pricing engines: calibration/valuation · Some engines consume calibrated model objects directly.
- Experimental → Pricing engines: extends · Experimental engines and products supplement the main pricing stack.
- Experimental → Methods: adds algorithms · Experimental numerical techniques build on core methods and math.
- Legacy LMM → Models: isolates · Legacy LMM components remain separated from the main model stack.
- Examples → Instruments: demonstrates · Examples exercise major instrument families and workflows.
- Test suite → Instruments: validates · Regression tests cover product behavior across the library.
- Test suite → Term structures: validates · Tests cover curve construction and market data behavior.
- Test suite → Math: validates · Tests cover numerical routines and random-number infrastructure.
- Docs → Instruments: documents · Documentation describes instruments, pricing engines, and usage patterns.
- Docs → Term structures: documents · Reference pages cover curve and surface construction.
- Build/CI → Examples: builds · Build systems compile standalone example programs.
- Build/CI → Test suite: runs · CI and build tooling compile and execute the test suite.
- Build/CI → Docs: generates · Tooling generates API and reference documentation.
