qufin 0.3.0

Research-grade quantum algorithms for production-grade quant finance.

qufin - Quantum Finance

Research-Grade Quantum Algorithms for Production-Grade Quant Finance

---

116 modules • 10 subpackages • 1149 tests • 8 backends • 4 QAE variants

Every quantum algorithm ships with a classical baseline. No hype -- just reproducible results.

Installation • Quickstart • Modules • Architecture • Backends • Benchmarks • Docs • Contributing

---

Why qufin?

Most quantum finance libraries are either toy demos or tightly coupled to a single framework. qufin is different:

• Honest benchmarking -- every quantum result is compared head-to-head against the best classical solver on the same problem instance. No cherry-picked examples.
• Backend-agnostic -- swap between Qiskit Aer, IBM Runtime, PennyLane, Cirq, and Amazon Braket with one line. Your algorithms don't change.
• Production patterns -- pluggable backends, typed configs, reproducibility manifests, noise-aware simulation with real device profiles, and error mitigation built in.
• Research-ready -- implements algorithms from Brassard et al., Egger et al., and Farhi et al. with correct mathematical details (Grover global phase, IQAE multi-branch enumeration, canonical QPE).

---

Installation

pip install qufin

Optional extras

pip install "qufin[ibm]"        # IBM Quantum Runtime (Sampler/Estimator)
pip install "qufin[ml]"         # PyTorch for deep hedging and ML
pip install "qufin[viz]"        # Plotly interactive visualization
pip install "qufin[pennylane]"  # PennyLane Lightning backend
pip install "qufin[cirq]"       # Google Cirq backend
pip install "qufin[braket]"     # Amazon Braket backend
pip install "qufin[dev]"        # pytest, ruff, mypy, pre-commit
pip install "qufin[all]"        # Everything

Requires Python 3.10+

---

Quickstart

Price a European call with Black-Scholes

from qufin.options.classical.black_scholes import bs_price, bs_greeks

price = bs_price(s=100, k=105, sigma=0.2, r=0.05, T=1.0)
greeks = bs_greeks(s=100, k=105, sigma=0.2, r=0.05, T=1.0)
print(f"Price: {price:.4f}  Delta: {greeks['delta']:.4f}")
# Price: 8.0214  Delta: 0.5374

Price the same option with Quantum Amplitude Estimation

from qufin.options.amplitude_estimation.european_qae import european_qae_price
from qufin.options.amplitude_estimation.iqae import IQAEConfig
from qufin.backends.qiskit_backend import QiskitAerBackend

backend = QiskitAerBackend(shots=4096)
config = IQAEConfig(epsilon_target=0.01, shots_per_round=1024)
qae_price = european_qae_price(
    s=100, k=105, sigma=0.2, r=0.05, T=1.0,
    backend=backend, config=config
)
print(f"QAE Price: {qae_price:.4f}")

Optimize a portfolio with QAOA

from qufin.benchmarks.problems import make_benchmark
from qufin.portfolio.qubo import build_qubo
from qufin.portfolio.optimizers.qaoa import QAOAOptimizer
from qufin.backends.qiskit_backend import QiskitAerBackend

problem = make_benchmark(15)  # 15-asset benchmark
Q = build_qubo(problem.mu, problem.sigma, risk_aversion=0.5, k=5)
backend = QiskitAerBackend(shots=4096)
optimizer = QAOAOptimizer(backend=backend, p=2, mixer="xy_ring")
result = optimizer.solve(Q, n_assets=15, k=5)
print(f"Selected: {result.selected}  Objective: {result.objective:.4f}")

Run a backtest

from qufin.backtesting.engine import BacktestEngine
from qufin.backtesting.metrics import compute_metrics

engine = BacktestEngine(rebalance_freq="monthly", window=252)
portfolio_values = engine.run(prices_df, strategy_fn)
metrics = compute_metrics(portfolio_values)
print(f"Sharpe: {metrics['sharpe']:.2f}  Max DD: {metrics['max_drawdown']:.2%}")

Generate synthetic market data

from qufin.data.synthetic import gbm_paths, heston_paths, merton_jump_paths

# Geometric Brownian Motion
paths = gbm_paths(s0=100, mu=0.08, sigma=0.2, T=1.0, n_steps=252, n_paths=10_000)

# Heston stochastic volatility
from qufin.data.synthetic import HestonParams
params = HestonParams(v0=0.04, kappa=2.0, theta=0.04, xi=0.3, rho=-0.7)
paths = heston_paths(s0=100, mu=0.08, params=params, T=1.0, n_steps=252, n_paths=10_000)

---

Modules

Portfolio Optimization Classical: Mean-Variance (CVXPY), Black-Litterman, Risk Parity, HRP, Multi-Period, ADMM, Hybrid, Factor Models Quantum: QAOA (X / XY-ring / XY-full / Grover mixers), VQE, Warm-Start, Szegedy Quantum Walk, Robust CVaR QUBO, Sector Rotation (VQC) Features: CVaR objective, Dicke state init, QUBO with cardinality + sector + turnover + transaction cost constraints Option Pricing Classical: Black-Scholes (full Greeks + implied vol), Monte Carlo (European / Asian / Barrier, antithetic variates), CRR Binomial (European + American), American (LSM), Implied Vol Surface (SABR/SVI) Quantum: Canonical QAE, IQAE, MLAE, FQAE, Path-Dependent QAE, American QAE (Quantum LSM) Exotics: Bermudan (LSM), lookback, cliquet, autocallable, basket, path-dependent Risk Management Classical: VaR (historical / parametric / MC), CVaR, stress testing, counterparty CVA/DVA Quantum: Quantum VaR, Egger credit-risk, Quantum Stress Testing Credit: Gaussian copula, NIG copula models

Hedging Classical: Delta hedging, deep hedging (PyTorch) Quantum: Quantum deep hedging, RL-quantum hedging Machine Learning Classical: Standard classifiers Quantum: Kernel methods, VQC, qGAN, reservoir computing Data & Infrastructure Market Data: Yahoo Finance, FRED macroeconomic Synthetic: GBM, Heston stochastic vol, Merton jump-diffusion Backtesting: Walk-forward engine, 15+ performance metrics Benchmarks: Standardized problem sets (15 / 25 / 50 assets), reproducibility manifests, leaderboard

---

Architecture

src/qufin/
    backends/                  # Pluggable backend abstraction
        base.py                #   Backend ABC + registry
        mock.py                #   MockBackend (deterministic, no simulator)
        qiskit_backend.py      #   QiskitAerBackend + NoisyAerBackend
        ibm_runtime.py         #   IBM Quantum Runtime (Sampler/Estimator)
        cudaq_backend.py        #   CUDA-Q GPU-accelerated backend
        auto_select.py         #   Backend auto-selection + fallback chain
        transpiler.py          #   Finance circuit transpiler (QUBO-aware)
        noise_models.py        #   Depolarizing, thermal, device-calibrated
        error_mitigation.py    #   ZNE, TREX, readout calibration
        dynamical_decoupling.py #  XY4, CPMG, Uhrig DD sequences
        m3_mitigation.py       #   Matrix-free measurement mitigation
        noise_aware_optimizer.py #  Noise-aware variational optimizer
    options/
        classical/             #   Black-Scholes, CRR binomial, Monte Carlo
        amplitude_estimation/  #   Canonical, MLAE, IQAE, FQAE
            path_dependent_qae.py  #   Path-dependent QAE pricing
            american_qae.py    #   American option QAE (Quantum LSM)
        implied_vol_surface.py #   Implied vol surface (SABR/SVI)
    portfolio/
        classical/             #   Mean-Variance, Black-Litterman, HRP, Risk Parity
            factor_models.py   #   Factor-based portfolio models
        optimizers/            #   QAOA, VQE, warm-start, exhaustive, hybrid
            multi_period.py    #   Multi-period portfolio optimization
            robust.py          #   Robust CVaR QUBO optimizer
            quantum_walk.py    #   Szegedy quantum walk optimizer
            admm.py            #   ADMM decomposition optimizer
            hybrid.py          #   Hybrid classical-quantum optimizer
        sector_rotation.py     #   VQC-based sector rotation
        qubo.py                #   QUBO builder with constraints
        mixers.py              #   X, XY-ring, XY-full, Grover mixer circuits
    risk/                      #   VaR, CVaR, stress, counterparty
        quantum_stress.py      #   Quantum stress testing
        credit/                #   Egger quantum credit, Gaussian/NIG copula
    hedging/                   #   Delta, deep hedging, quantum RL
    ml/                        #   Quantum kernels, VQC, qGAN, reservoir
    derivatives/               #   Basket, autocallable, Bermudan LSM
    data/                      #   Yahoo Finance, FRED, synthetic generators
    backtesting/               #   Walk-forward engine + metrics
    benchmarks/                #   Problem sets, runner, leaderboard, manifests
    utils/                     #   Settings, logging, visualization, encoders

---

Backends

All quantum algorithms accept any backend implementing the Backend protocol. Swap backends without changing algorithm code:

from qufin.backends.qiskit_backend import QiskitAerBackend, NoisyAerBackend
from qufin.backends.mock import MockBackend

# Noiseless simulation
backend = QiskitAerBackend(shots=4096)

# Noisy simulation with a real device profile
backend = NoisyAerBackend(shots=4096, profile="melbourne")

# Deterministic mock for testing
backend = MockBackend()

Backend	Use Case
MockBackend	Unit tests, CI, deterministic results
QiskitAerBackend	Local simulation, research
NoisyAerBackend	Noise-aware development (4 device profiles)
IBMRuntimeBackend	Real quantum hardware via IBM Quantum
PennyLaneBackend	PennyLane ecosystem
CirqBackend	Google Cirq ecosystem
BraketBackend	Amazon Braket / AWS hardware
CudaQBackend	GPU-accelerated simulation, 30+ qubits

---

Benchmarks

qufin includes standardized benchmark suites for honest quantum-vs-classical comparison:

• Problem sets: 15, 25, and 50 asset portfolios with real covariance matrices
• Metrics: Solution quality, time-to-solution, circuit depth, approximation ratio vs exact classical optimum
• Reproducibility: Every run generates a manifest recording hardware, software versions, and random seeds
• Leaderboard: Track and compare results across backends and algorithm configurations
• Finance circuit transpiler: QUBO-aware ZZ optimization, commuting gate parallelization, connectivity-aware routing
• Hardware benchmarks: QAOA/QAE benchmark runners, error mitigation comparison, IonQ cost analysis

from qufin.benchmarks.runner import BenchmarkRunner
from qufin.benchmarks.problems import make_benchmark

runner = BenchmarkRunner()
results = runner.run(make_benchmark(15), algorithms=["qaoa", "vqe", "mean_variance"])
runner.summary(results)

---

Testing

# Run all tests
pytest

# Run specific suites
pytest tests/unit/              # Unit tests
pytest tests/integration/       # Integration tests (requires Qiskit Aer)
pytest tests/property/          # Property-based tests (Hypothesis)
pytest tests/stress/            # Stress tests
pytest -m "not slow"            # Skip slow tests
pytest -m "not hardware"        # Skip IBM hardware tests

---

Project Status

Component	Status
Portfolio Optimization (classical + QAOA/VQE)	Stable
Option Pricing (BS + QAE)	Stable
Risk Management (VaR/CVaR + quantum)	Stable
Noise Models + Error Mitigation (ZNE, TREX, PEC, CDR, DD, M3)	Stable
Backtesting Engine	Stable
Benchmarks & Leaderboard	Stable
Data Layer (Yahoo, FRED, synthetic)	Stable
Hedging (delta + deep)	Beta
ML (kernels, VQC, qGAN)	Beta
Documentation Site	Planned

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines on code style, testing, and pull request process.

---

License

Apache 2.0. See LICENSE for details.

---

Citation

@software{qufin,
  author       = {Adarsh Keshri},
  title        = {qufin: Research-Grade Quantum Algorithms for Quant Finance},
  year         = {2025},
  url          = {https://github.com/anonymousAAK/qufin},
  license      = {Apache-2.0}
}