How lballabio/quantlib works
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: instruments Instruments · pricingengines Pricing engines · termstructures Term structures · test-suite Test suite
Components 20
Core library
Fundamental domain abstractions and shared infrastructure.
Market data
Observable inputs, indexes, and term structures.
- Quotes · Observable quotes and derived market input helpers.
ql/quotes - Currencies · Currencies and exchange-rate management.
ql/currencies - Indexes · Interest-rate, inflation, equity, and swap index definitions.
ql/indexes - Term structures · Yield, credit, inflation, and volatility curves and bootstrapping.
ql/termstructures
Pricing stack
Instruments, models, processes, and engines.
- Cash flows · Coupons, dividends, cashflow variants, and pricers.
ql/cashflows - Instruments · Financial products composed from payoffs, exercises, schedules, and cash flows.
ql/instruments - Pricing engines · Specialized valuation engines attached to instruments.
ql/pricingengines - Processes · Black-Scholes, Heston, Hull-White, CIR, G2, and related processes.
ql/processes - Models · Model families wrapping processes for short-rate, equity, volatility, and market models.
ql/models
Numerics
Reusable numerical methods and algorithms.
Extensions
Experimental and legacy subsystems.
- Experimental · Additional products, methods, models, and term-structure extensions.
ql/experimental - Legacy LMM · Isolated Libor Market Model components kept for compatibility.
ql/legacy
Support
Examples, tests, docs, and build/CI tooling.
- Examples · Standalone sample programs demonstrating common workflows.
Examples - Test suite · Extensive regression and validation coverage for the library.
test-suite - Docs · Generated manuals, reference pages, and documentation sources.
Docs - Build/CI · CMake, autotools, Visual Studio projects, CI workflows, and maintenance scripts.
Connections 29
- 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.