quantfinlab Library

quantfinlab is the reusable Python library extracted from the Quantitative Finance Lab project series. It is not a general-purpose finance library. It is a focused package covering the methods developed across the twenty projects: fixed income, options pricing, portfolio construction, risk reporting, volatility modeling, hedging, macro indicators, dependence networks, and ML/RL components for finance.

The test suite checks real model properties rather than notebook snapshots: weights summing to one, CVaR behavior, curve/discount consistency, American option engine fallbacks, implied-volatility diagnostics, and PSD matrix reconstruction. The current package checks pass with a clean ruff lint pass.

Installation

From the repository root:

pip install -e .

Source installs build the optional C++ extension (quantfinlab._kernels) automatically via scikit-build-core, CMake, and pybind11 when a C++ compiler is available. The extension accelerates the heaviest American-option, Fourier/COS, Monte Carlo, and calibration kernels, but the package also works from a pure-Python wheel when native builds are not available.

To disable native kernels during a source install:

pip install . --config-settings=cmake.define.quantfinlab_build_cpp=off

Functions that accept engine="auto" prefer C++ when available, then Numba when installed, then NumPy/SciPy fallback paths where implemented. If you explicitly request engine="cpp" without the extension installed, quantfinlab raises MissingKernelsError with installation and fallback guidance.

Most of the library works with just the core dependencies (NumPy, pandas, SciPy, cvxpy, and scikit-learn). A handful of modules need optional extras, installed as needed:

pip install -e ".[numerics]"   # JAX / Numba acceleration (autodiff Greeks, fast IV)
pip install -e ".[volatility]" # arch, statsmodels (GARCH, HAR)
pip install -e ".[hedging]"    # statsmodels (dynamic hedge ratios)
pip install -e ".[ml]"         # PyTorch (sequence models, RL policies)
pip install -e ".[network]"    # networkx (dependence networks)
pip install -e ".[plotting]"   # matplotlib, seaborn
pip install -e ".[all]"        # everything above

Optional dependencies are checked at the point of use. Functions either fall back to a pure NumPy/SciPy implementation, or raise a clear, specific error telling you which extra to install, rather than failing on package import. Tests that need optional dependencies use pytest.importorskip and skip cleanly rather than fail when the dependency is absent.

Module map

The optional C++ pricing kernels (cpp/, exposed as quantfinlab._kernels) implement the LSM regression solver, the PSOR finite-difference PDE solver, the binomial tree, Monte Carlo paths, and the Fourier/COS pricer. They are written in C++ and bound via pybind11 for speed; pure-Python installs keep the public APIs importable and use automatic fallbacks where those methods exist.

Data loading

quantfinlab.dataio is what every notebook uses to turn a raw downloaded file into a clean, analysis-ready dataset. It is also the boundary the project series treats most carefully. see the project README and data README for how raw data is obtained in the first place, dataio is what runs after having the data files for turning them into analysis ready dataframes.

from quantfinlab.dataio import load_par_yield_curve, load_yfinance_panel

us_curve = load_par_yield_curve("data/us_treasury_yields.csv", source="us_treasury")
jp_curve = load_par_yield_curve("data/japan_mof_yields.csv", source="japan_mof")

panel = load_yfinance_panel(
    "data/core_cross_asset_etfs.csv", fields=("close", "volume"),
    source="yfinance_export", start="2010-01-01")

close, volume = panel["close"], panel["volume"]

Every loader in dataio normalizes to the same shape. par-yield curves come back as a DatetimeIndex-sorted DataFrame with standard tenor columns (1M...30Y) in decimal form. equities and prices come back as {field: DataFrame} with tickers as columns, numeric-coerced, deduplicated, sorted. This is what makes the "secondary market" repeat at the end of most notebooks possible with no extra glue code. swap the path/source, get the same schema back.

Examples

A few representative examples. See the notebooks for the full derivations behind each of these and the full repeat of each project completely using the library.

Mean-variance portfolio optimization with turnover control

from quantfinlab.portfolio import covariance, optimizers

cov_ann = covariance.estimate_covariance(returns_window, method="LedoitWolf", return_df=True)

weights = optimizers.mean_variance(
    mu_excess_ann=expected_excess_returns,
    cov_ann=cov_ann, mv_lambda=6.0,
    w_max=0.25, turnover_penalty_bps=10.0,
    long_only=True)

optimizers also exposes equal_weight, minimum_variance, ridge_mean_variance, max_sharpe_slsqp, and max_sharpe_frontier_grid with the same calling convention, plus a walkforward module that runs any of these through a full rolling rebalance/backtest loop given a returns panel and rebalance schedule.

Implied volatility from a market quote

from quantfinlab.options import iv

sigma = iv.implied_vol(
    option_type="call", price=4.35, forward=101.2,
    strike=100.0, tau=30 / 365,
    engine="auto", solver="lbr_lite")

For a full option-chain DataFrame at once, iv.compute_iv_table(quotes, ...) runs the same solver vectorized across all rows and returns solver-status diagnostics alongside the implied vols (used in the notebooks to check solver success rate and pricing residuals before trusting a fitted surface).

Risk parity and CVaR-aware allocation

from quantfinlab.portfolio import risk_parity, cvar

erc_weights = risk_parity.equal_risk_contribution_weights(cov_ann, tickers=cov_ann.index, w_max=0.40)
contrib_table = risk_parity.risk_contribution_table(erc_weights, cov_ann)

cvar_weights = cvar.min_cvar_weights(returns_window, alpha=0.95, w_max=0.40)
loss = cvar.portfolio_cvar_loss(returns_window, cvar_weights, alpha=0.95)

Yield curve construction and bond pricing

from quantfinlab.dataio import load_par_yield_curve
from quantfinlab.fixed_income import bootstrap, bond_pricing

curve = load_par_yield_curve("data/us_treasury_yields.csv", source="us_treasury")
discount_curve = bootstrap.bootstrap_discount_factors(curve.loc["2024-06-01"])

price = bond_pricing.bond_price(coupon=0.045, maturity_years=10.0, df_func=discount_curve, freq=2)

A full risk report

from quantfinlab.reports import risk_report

report = risk_report.risk_report(
    returns=strategy_returns, benchmark_returns=benchmark_returns,
    weights=weights_history, cov_ann=cov_ann)

This produces the same VaR/ES, drawdown, CAPM, and risk-contribution summary used throughout Project 03 and applied to every backtest in later projects — one call instead of re-deriving the report each time.

Testing

pip install -e ".[dev]"
pytest

Tests are organized to mirror the package layout (tests/portfolio, tests/options, tests/cpp, ...) and use a small set of deterministic synthetic-data generators (tests/synthetic/generators.py) rather than real market data, so the suite is fast, reproducible, and has no external data dependency.