Metadata-Version: 2.2
Name: quantfinlab
Version: 0.6.0
Summary: Reusable quantitative finance research library extracted from the Quantitative Finance Lab notebook projects
Keywords: quantitative-finance,options-pricing,portfolio-optimization,risk-management,volatility-modeling,fixed-income,machine-learning,monte-carlo
Author-Email: Ramtin Asadi <ramtin.asadi01@gmail.com>
License: MIT License
         
         Copyright (c) 2026
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Project-URL: Homepage, https://github.com/ramtin-asadi/Quantitative-Finance-Lab
Project-URL: Documentation, https://ramtin-asadi.github.io/Quantitative-Finance-Lab/
Project-URL: Repository, https://github.com/ramtin-asadi/Quantitative-Finance-Lab.git
Project-URL: Issues, https://github.com/ramtin-asadi/Quantitative-Finance-Lab/issues
Requires-Python: <3.13,>=3.11
Requires-Dist: numpy<3.0.0,>=1.24.0
Requires-Dist: pandas<4.0.0,>=2.0.0
Requires-Dist: scipy<2.0.0,>=1.10.0
Requires-Dist: cvxpy<2.0.0,>=1.4.0
Requires-Dist: typing-extensions>=4.8.0
Requires-Dist: scikit-learn<2.0.0,>=1.3.0
Provides-Extra: speed
Requires-Dist: numba<0.65.0,>=0.58.0; extra == "speed"
Provides-Extra: numerics
Requires-Dist: jax<0.5.0,>=0.4.20; extra == "numerics"
Requires-Dist: jaxlib<0.5.0,>=0.4.20; extra == "numerics"
Requires-Dist: numba<0.65.0,>=0.58.0; extra == "numerics"
Provides-Extra: volatility
Requires-Dist: arch<7.0.0,>=6.0.0; extra == "volatility"
Requires-Dist: statsmodels<0.15.0,>=0.14.0; extra == "volatility"
Provides-Extra: hedging
Requires-Dist: statsmodels<0.15.0,>=0.14.0; extra == "hedging"
Provides-Extra: ml
Requires-Dist: torch<3.0,>=2.4; extra == "ml"
Provides-Extra: network
Requires-Dist: networkx<4.0,>=3.2; extra == "network"
Provides-Extra: plotting
Requires-Dist: matplotlib<4.0.0,>=3.7.0; extra == "plotting"
Requires-Dist: seaborn<0.14.0,>=0.13.0; extra == "plotting"
Provides-Extra: all
Requires-Dist: quantfinlab[numerics]; extra == "all"
Requires-Dist: quantfinlab[volatility]; extra == "all"
Requires-Dist: quantfinlab[hedging]; extra == "all"
Requires-Dist: quantfinlab[ml]; extra == "all"
Requires-Dist: quantfinlab[network]; extra == "all"
Requires-Dist: quantfinlab[plotting]; extra == "all"
Provides-Extra: dev
Requires-Dist: black<25.0.0,>=23.0.0; extra == "dev"
Requires-Dist: ruff<0.7.0,>=0.6.7; extra == "dev"
Requires-Dist: pytest<9.0.0,>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.3.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: pdoc>=14.0.0; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.0.0; extra == "notebooks"
Requires-Dist: ipykernel>=6.25.0; extra == "notebooks"
Requires-Dist: nbformat>=5.9.0; extra == "notebooks"
Requires-Dist: quarto>=1.4.0; extra == "notebooks"
Requires-Dist: xlrd<3.0.0,>=2.0.1; extra == "notebooks"
Requires-Dist: quantfinlab[all]; extra == "notebooks"
Description-Content-Type: text/markdown

# quantfinlab Library

`quantfinlab` is the reusable Python library extracted from the [Quantitative Finance Lab](https://github.com/ramtin-asadi/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:

```bash
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:

```bash
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:

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

| Module | Covers |
|---|---|
| `quantfinlab.dataio` | Source-normalized data loading: yield curves, equity/ETF panels, option chains, macro series, every loader returns a stable schema regardless of the underlying data vendor. See [Data loading](#data-loading) below. |
| `quantfinlab.fixed_income` | Curve bootstrapping, discounting, forward rates, bond pricing and cashflows, duration/convexity/key-rate duration, short-rate/term-structure models, swaps, scenario generation, duration-targeted laddering. |
| `quantfinlab.options` | Black–Scholes/Black-76 pricing, put-call parity, quote cleaning, implied volatility (Newton-bisection and "Let's Be Rational"-style solvers, with an optional Numba backend), analytic and autodiff Greeks (optional JAX), American option pricing (tree/PDE/LSM, C++ and numba backed), Fourier/COS pricing, Heston/SABR/SVI/SSVI/rough-volatility/Merton/variance-gamma models, local volatility, and model-risk diagnostics. |
| `quantfinlab.portfolio` | Expected-return models, covariance estimation (sample/Ledoit-Wolf/OAS/EWMA), mean-variance/min-variance/max-Sharpe/ridge optimizers, constraints, transaction costs, walk-forward backtesting harness, Black-Litterman (with learned-confidence views and factor/regime conditioning), HRP/NCO clustering allocation, risk parity, CVaR and robust (box/ellipsoid/Wasserstein) optimization, factor construction, regime models, dependence-network construction and network-based signals, universe selection and position sizing. |
| `quantfinlab.risk` | VaR/expected shortfall (historical, Cornish-Fisher, filtered historical simulation), VaR backtesting, drawdown analysis, performance metrics, CAPM beta, correlation diagnostics, stress testing, risk contribution/attribution. |
| `quantfinlab.volatility` | Realized-volatility estimators, GARCH/HAR forecasting, rough-volatility estimation, variance risk premium analysis. |
| `quantfinlab.hedging` | Dynamic hedge-ratio estimation, hedge policies, residual-spread construction, hedging performance metrics. |
| `quantfinlab.macro` | Macro indicator construction (financial-conditions index, NFCI-style PCA), macro-conditioned allocation models. |
| `quantfinlab.ml` | Feature engineering, forecasting evaluation (rank metrics, pinball loss, coverage), probabilistic/uncertainty models, sequence models (e.g. TCN-based forecasters), regime classifiers, RL environments, reward shaping (differential Sharpe ratio), and RL policies (PPO, recurrent PPO, SAC). |
| `quantfinlab.backtest` | Shared backtesting engines for portfolios, fixed income, hedging, and options strategies, with cost models and overlay support. |
| `quantfinlab.reports` | risk report generation, combining outputs from `risk`, `portfolio`, and `plotting` into a single executive summary. |
| `quantfinlab.numerics` | Finite-difference schemes, Fourier transforms, interpolation, Monte Carlo path generation. Shared numerical primitives used across `options` and `calibration`. |
| `quantfinlab.calibration` | Model calibration. American option numerics, FFT/COS calibration, jump-diffusion model fitting, LSM regression. |
| `quantfinlab.plotting` | Consistent plotting utilities per domain (curves, options, portfolio, risk, volatility, macro, regimes, ML, hedging, fixed income) and explanatory diagrams. |
| `quantfinlab.common` | Shared contracts/dataclasses (`Curve`, `Bond`, `PortfolioState`, `BacktestResult`, ...), error types, date utilities, and input validation used across every other module. |

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](https://github.com/ramtin-asadi/Quantitative-Finance-Lab#data-and-reproducibility) and [data README](https://github.com/ramtin-asadi/Quantitative-Finance-Lab/tree/main/data) 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.

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

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

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

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

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

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

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