Skip to content

About

Distributed QuantLib

Resources

Contributing

Stars

31 stars

Watchers

2 watching

Forks

Repository files navigation

Quantra

Quantra is a QuantLib-based pricing service built for parallel execution. It exposes pricing functionality over gRPC with FlatBuffers and through an HTTP/JSON gateway for easier integration and generated OpenAPI documentation.

Why This Exists

QuantLib is powerful, but it is not naturally suited to high-concurrency service workloads because important state such as Settings::instance().evaluationDate() is global to the process. Quantra works around that by running multiple isolated pricing workers and placing Envoy in front of them as a load balancer.

What You Get

  • A C++ pricing server built on QuantLib
  • A gRPC API using FlatBuffers messages, plus a Meta RPC and the standard grpc.health.v1.Health service
  • A JSON/HTTP gateway in jsonserver/
  • A C++ client in clients/cpp/
  • A Python client package in clients/python/

Supported Pricing Coverage

Priced instruments:

  • Fixed-rate bonds
  • Floating-rate bonds
  • Zero-coupon bonds
  • Callable / puttable fixed-rate bonds
  • Vanilla swaps (two SwapLeg legs: fixed vs IBOR or CMS coupons)
  • OIS swaps (two SwapLeg legs: fixed vs overnight coupons)
  • Basis swaps (two floating SwapLeg legs: IBOR or overnight coupons)
  • Zero-coupon swaps
  • Zero-coupon inflation swaps
  • Year-on-year inflation swaps
  • FRAs
  • Caps, floors and collars
  • Swaptions (on a vanilla or OIS underlying built from SwapLeg legs)
  • Year-on-year inflation caps, floors, and collars
  • CDS
  • Equity options
  • FX forwards
  • Cross-currency swaps (two SwapLeg legs in two currencies: fixed, IBOR or overnight coupons, principal exchanges)
  • Structured notes on equity-index baskets by Monte Carlo (worst-of / best-of / average autocallables, Phoenix and snowball coupons, low hurdles, step-downs, reverse convertibles, European or daily capital barriers, geared puts, upside participation; quanto underlyings; bump-and-reprice Greeks on common random numbers; opt-in diagnostics)

Utility endpoints cover yield- and inflation-curve bootstrapping, volatility surface sampling, Hull-White and SABR calibration, calendar date arithmetic, and the equity market-data chain for the option and structured-note pricers: implied forwards and dividends from listed option quotes (/calibrate-implied-forwards), a Black volatility surface (/calibrate-vol-surface, Andreasen-Huge, SVI per expiry or eSSVI), its validation against the quotes (/validate-vol-surface: fit, local-vol arbitrage scan, Monte Carlo repricing) and a correlation matrix from price histories (/calibrate-correlation, aligned returns, Ledoit-Wolf shrinkage, eigenvalue floor).

Features that apply across products:

  • Amortizing and step-up notionals on swap legs and bonds
  • CMS legs, including capped and floored CMS coupons
  • Stub periods (short/long first and last coupons) on every schedule
  • Bermudan and American swaption exercise on a Hull-White lattice
  • American and Bermudan equity exercise and digital payoffs

See examples/data/ for sample payloads. For a worked, QuantLib-verified example of every product — each one a complete request JSON whose response is asserted against an independent QuantLib reference in the test gate — browse the functional parity catalog.

Architecture

The main runtime model is a multi-process gRPC service fronted by Envoy:

JSON client -> json_server (:8080) -> Envoy (:50051) -> sync_server workers (:50055+)
gRPC client -----------------------> Envoy (:50051) -> sync_server workers (:50055+)

Performance

Measured on an AMD Ryzen 9 3900X (12 cores / 24 threads), 62 GiB RAM, Debian 13, Linux 6.1. Both benchmarks are informational (not part of the test gate) and live in tests/bench/.

Parallel throughput

Pricing the same request across N worker processes behind Envoy, versus pricing it single-threaded with QuantLib. Workload: one EUR multicurve swap (2 curves, 24 bootstrap helpers). Generated by tests/bench/run_throughput.sh.

Workers Throughput (req/s) Speedup vs 1 worker
1 8.5 1.0×
2 15.7 1.8×
4 31.0 3.6×
8 58.0 6.8×
12 75.4 8.9×

Single-threaded QuantLib reference: ~16 req/s. Scaling is near-linear up to the 12 physical cores.

Curve cache

Per-request latency with the curve cache off vs on (200 requests, mean). Generated by tests/bench/run_bench.sh. A cache hit reuses the bootstrapped curve and skips re-bootstrapping.

Workload No cache Cache Speedup
Bond (1 curve, 8 helpers) 2.11 ms 1.10 ms 1.9×
Swap (2 curves, 24 helpers) 117.12 ms 2.02 ms 57.9×

The stable quantity is the work removed: on a cache hit the curve set is not re-bootstrapped. The ratio above is not portable, because the cache removes bootstrapping but not a request's fixed transport overhead (parsing, gRPC, serialization). On this hardware that floor is ~1 ms, so a bootstrap-heavy multicurve request shows a large ratio; on a deployment with higher per-request overhead the same workload shows a smaller ratio, and a light single-curve request — whose bootstrap is a small share of the total — shows almost none regardless of hardware. Measure your own with tests/bench/run_bench.sh. The model-calibration cache behaves the same way for swaption Hull-White calibration.

Quick Start

Container Image

The published GHCR image starts both the JSON API and the gRPC/Envoy endpoint:

  • HTTP/JSON API: 8080
  • gRPC/Envoy endpoint: 50051
docker pull ghcr.io/joseprupi/quantra-server:0.16.10

docker run --rm \
  -p 8080:8080 \
  -p 50051:50051 \
  ghcr.io/joseprupi/quantra-server:0.16.10

Check the running service:

curl http://localhost:8080/health
curl http://localhost:8080/meta

By default the container runs one worker per CPU core (capped at 8). Each worker is a single-threaded pricing process, so sizing workers to cores is what gives you parallel throughput. Override the count with QUANTRA_WORKERS:

docker run --rm \
  -e QUANTRA_WORKERS=2 \
  -p 8080:8080 \
  -p 50051:50051 \
  ghcr.io/joseprupi/quantra-server:0.16.10

See docs/process-manager.md for the full scaling model (load balancing, health checks, and per-worker caches), and docs/configuration.md for every environment variable the image reads.

gRPC callers get the same coverage plus two service RPCs: Meta returns the API version, build metadata, dependency versions, and the product and RPC lists; grpc.health.v1.Health answers standard Check/Watch probes. See docs/client.md.

Request rules, HTTP status codes, the error body, and the X-Request-Id / X-Quantra-Api-Version headers are documented in docs/http-api.md, as are per-request calendar holiday overrides (calendar_overrides).

The public API reference is available at https://quantra.io/docs/api.

Local Build

See docs/build.md for environment setup details. Once dependencies are available:

./scripts/build.sh Release
./scripts/quantra start --workers 4 --foreground
./build/jsonserver/json_server localhost:50051 8080

You can then call the HTTP API with sample requests from examples/data/:

curl -X POST http://localhost:8080/price-fixed-rate-bond \
  -H "Content-Type: application/json" \
  -d @examples/data/bonds/fixed_rate_bond_request.json

The generated OpenAPI files live in jsonserver/openapi/.

Development Workflow

Build

./scripts/build.sh regenerates schemas, recreates build/, and compiles the project.

./scripts/build.sh
./scripts/build.sh Release

Regenerate Schemas Only

If you are editing FlatBuffers schemas and want to regenerate artifacts without a full build:

./scripts/generate_schemas.sh

Run Tests

The build dependencies live in the quantraserver:test image, so the gate runs in Docker — the same command CI runs:

docker run --rm -v "$(pwd):/workspace" -w /workspace quantraserver:test \
    bash -lc './scripts/build.sh Release && bash tests/run_all_tests.sh'

Inside an environment that already has the dependencies, bash tests/run_all_tests.sh runs the gate directly against an existing build.

The test suite exercises:

  • C++ pricing parity against QuantLib
  • C++ gRPC integration
  • JSON HTTP API scenarios, including the functional parity catalog
  • Python client scenarios

See tests/README.md for how the suites are organized and how to run the whole gate in Docker.

Compare Numbers Across Versions

tools/version_diff/ is a cross-version diff tool: it sends the same requests to two running servers (for example the published image of the release you run today and the one you are evaluating) and reports every response field that differs, with both values and the size of the move. Replay your own requests with it before adopting a release built on a newer QuantLib:

python3 tools/version_diff/quantra_version_diff.py --old http://localhost:8091 --new http://localhost:8093 --requests my_requests/ --md-out diff.md

See tools/version_diff/README.md for the options (including --catalog, which replays the functional catalog). What changed, and why, at each QuantLib upgrade shipped in a release is documented in docs/quantlib-upgrades/ (docs/quantlib-upgrades/1.41-to-1.44.md for 0.11.0, QuantLib 1.41 → 1.44).

Repository Map

  • src/: the pricing engine internals, in role-based folders — transport/ (per-product handlers, product catalog), decode/ (FlatBuffers → C++: decode/market/ for the market-data tables, decode/products/ for the per-product request/response tables), evaluators/ (pure QuantLib pricing), market/ (curves, indices, vol surfaces, correlation matrices, quanto curves, caches), mc/ (the shared Monte Carlo core: basket processes, time grids, the path engine), domain/ (plain types), common/ (enums, dates, errors). See src/README.md.
  • server/: gRPC pricing server executable
  • jsonserver/: HTTP/JSON gateway and generated OpenAPI docs
  • clients/cpp/: C++ client library
  • clients/python/: Python client package
  • flatbuffers/: schema sources plus generated C++, Python, and JSON artifacts; flatbuffers/grpc/ holds the gRPC service definition and its generated bindings
  • examples/data/: example JSON requests, one folder per product family (structured_note/ holds the two factsheet transcriptions with placeholder market data and their README)
  • examples/structured_note_workflow/: a structured note priced at three levels of market data, with a script that runs the option quotes → forwards → vol surface → note chain
  • tests/: parity, integration, and client tests
  • scripts/: build, code generation, and runtime helpers
  • tools/quantra-manager/: packaged process-manager implementation
  • tools/version_diff/: cross-version diff tool (same requests against two servers)
  • docs/: project documentation and reference notes

Documentation

  • docs/README.md: documentation index
  • docs/build.md: environment setup and build details
  • docs/configuration.md: every environment variable the runtime reads
  • docs/http-api.md: request rules, status codes, error body, and headers
  • docs/scripts.md: build and schema tooling
  • docs/testing.md: test suite details
  • docs/process-manager.md: process-manager behavior and runtime model
  • docs/client.md: C++ client, gRPC Meta, and health checking
  • docs/versioning.md: versioning policy
  • docs/quantlib-upgrades/: what changes in your numbers at each QuantLib upgrade, and why (docs/quantlib-upgrades/1.41-to-1.44.md for 0.11.0)
  • src/README.md: engine layering and the request flow
  • CONTRIBUTING.md: contribution workflow

Requirements

The repository currently documents and builds around:

  • CMake 3.16+
  • GCC 12+ or Clang 14+
  • gRPC v1.60.0
  • FlatBuffers v24.12.23
  • QuantLib 1.44 in Docker builds
  • Envoy for worker load balancing

License

BSD 3-Clause. See LICENSE.txt.

About

Distributed QuantLib

Resources

Contributing

Stars

31 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages