Metadata-Version: 2.4
Name: qufin
Version: 0.1.0
Summary: Research-grade quantum algorithms for production-grade quant finance.
Project-URL: Homepage, https://github.com/qufinance/qufin
Project-URL: Documentation, https://qufinance.github.io/qufin
Project-URL: Issues, https://github.com/qufinance/qufin/issues
Project-URL: Changelog, https://github.com/qufinance/qufin/blob/main/CHANGELOG.md
Author-email: Adarsh <adarsh@example.com>
Maintainer: anonymousAAK
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: amplitude-estimation,finance,option-pricing,portfolio-optimization,qaoa,quantum
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: arch>=6.3
Requires-Dist: cvxpy>=1.4
Requires-Dist: fredapi>=0.5
Requires-Dist: matplotlib>=3.8
Requires-Dist: networkx>=3.2
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow>=15.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Requires-Dist: qiskit-aer>=0.14
Requires-Dist: qiskit<3.0,>=1.0
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.11
Requires-Dist: statsmodels>=0.14
Requires-Dist: yfinance>=0.2.40
Provides-Extra: all
Requires-Dist: amazon-braket-sdk>=1.80; extra == 'all'
Requires-Dist: cirq-core>=1.3; extra == 'all'
Requires-Dist: pennylane-lightning>=0.36; extra == 'all'
Requires-Dist: pennylane>=0.36; extra == 'all'
Requires-Dist: plotly>=5.20; extra == 'all'
Requires-Dist: qiskit-ibm-runtime>=0.20; extra == 'all'
Requires-Dist: torch>=2.2; extra == 'all'
Provides-Extra: braket
Requires-Dist: amazon-braket-sdk>=1.80; extra == 'braket'
Provides-Extra: cirq
Requires-Dist: cirq-core>=1.3; extra == 'cirq'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: hypothesis>=6.99; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: nbstripout; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-benchmark; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-nb; extra == 'docs'
Requires-Dist: sphinx-book-theme; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: ibm
Requires-Dist: qiskit-ibm-runtime>=0.20; extra == 'ibm'
Provides-Extra: ml
Requires-Dist: torch>=2.2; extra == 'ml'
Provides-Extra: pennylane
Requires-Dist: pennylane-lightning>=0.36; extra == 'pennylane'
Requires-Dist: pennylane>=0.36; extra == 'pennylane'
Provides-Extra: viz
Requires-Dist: plotly>=5.20; extra == 'viz'
Description-Content-Type: text/markdown

# qufin

![CI](https://github.com/anonymousAAK/qufin/actions/workflows/ci.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/qufin)
![Python](https://img.shields.io/pypi/pyversions/qufin)
![License](https://img.shields.io/badge/license-Apache--2.0-blue)
![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)

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

qufin bridges the gap between quantum computing research and quantitative finance practice.
Every quantum algorithm ships with a classical baseline on the same problem, and a standardized
benchmark harness for honest quantum-vs-classical comparison. No hype -- just reproducible results.

---

## Features

| Module | Classical | Quantum | Status |
|---|---|---|---|
| **Portfolio Optimization** | Mean-Variance (CVXPY), Black-Litterman, Risk Parity, HRP | QAOA (X / XY-ring / XY-full / Grover mixers, CVaR objective, Dicke init), VQE, Warm-Start | Active |
| **Option Pricing** | Black-Scholes (full Greeks + implied vol), Monte Carlo (European / Asian / Barrier, antithetic), CRR Binomial (European + American) | QAE: Canonical, MLAE, IQAE, FQAE | In Progress |
| **Risk Management** | VaR (historical / parametric / MC), CVaR, stress testing, counterparty CVA/DVA, credit (Gaussian / NIG copula) | Quantum VaR, Egger credit-risk | In Progress |
| **Hedging** | Delta hedging, deep hedging (PyTorch) | Quantum deep hedging, RL-quantum hedging | Planned |
| **Machine Learning** | Classical classifiers | Quantum kernels, VQC, qGAN, reservoir computing | Planned |
| **Derivatives** | Bermudan (LSM), basket, autocallable, path-dependent | -- | Planned |
| **Backtesting** | Walk-forward engine, 15+ performance metrics | -- | Active |
| **Data** | Yahoo Finance, FRED, synthetic generators (GBM, Heston, Merton), asset universes | -- | Active |
| **Benchmarks** | Standardized problem sets (15 / 25 / 50 assets), runner, metrics, leaderboard, reproducibility manifests | -- | Active |

---

## Quickstart

### Install

```bash
pip install qufin
```

### Price a European call with Black-Scholes

```python
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}  Gamma: {greeks['gamma']:.6f}")
```

### Optimize a portfolio with QAOA

```python
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 assets: {result.selected}  Objective: {result.objective:.4f}")
```

### Run a backtest

```python
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 Drawdown: {metrics['max_drawdown']:.2%}")
```

---

## Architecture

```
src/qufin/
    backends/           # Pluggable backend abstraction (ABC)
        base.py         #   Backend protocol + registry
        mock.py         #   MockBackend (deterministic, no simulator)
        qiskit_backend.py  QiskitAerBackend + NoisyAerBackend (4 noise profiles)
        ibm_runtime.py  #   IBM Quantum Runtime (Sampler/Estimator)
        pennylane_backend.py
        cirq_backend.py
        braket_backend.py
        noise_models.py #   Depolarizing, thermal, device-calibrated
        error_mitigation.py
    backtesting/        # Walk-forward engine + metrics
    benchmarks/         # Standardized problems, runner, leaderboard
    data/               # Yahoo Finance, FRED, synthetic generators, caching
    derivatives/        # Exotic derivatives (basket, autocallable, Bermudan LSM)
    hedging/            # Delta, deep hedging, quantum deep hedging
    ml/                 # Quantum kernels, VQC, qGAN, reservoir
    options/            # European, Asian, barrier, Bermudan
        classical/      #   Black-Scholes, CRR binomial, Monte Carlo
        amplitude_estimation/  # Canonical, MLAE, IQAE, FQAE
    portfolio/          # Portfolio optimization
        classical/      #   Mean-Variance, Black-Litterman, HRP, Risk Parity
        optimizers/     #   QAOA, VQE, warm-start, exhaustive, hybrid
        qubo.py         #   QUBO builder (cardinality, sector, turnover, tx cost)
        encodings.py    #   One-hot, binary encoding
        mixers.py       #   X, XY-ring, XY-full, Grover mixer circuits
    risk/               # VaR, CVaR, stress, counterparty
        credit/         #   Egger quantum credit risk, Gaussian/NIG copula
    utils/              # Settings, logging, visualization, encoders
```

---

## Installation

```bash
# Core (includes Qiskit Aer, NumPy, SciPy, pandas, CVXPY)
pip install qufin

# With IBM Quantum Runtime
pip install "qufin[ibm]"

# With PyTorch for deep hedging and ML
pip install "qufin[ml]"

# With Plotly for interactive visualization
pip install "qufin[viz]"

# Development (pytest, ruff, mypy, pre-commit)
pip install "qufin[dev]"

# Everything
pip install "qufin[all]"
```

Requires Python 3.10 or later.

---

## Backends

qufin uses a pluggable backend architecture. All quantum algorithms accept any backend that
implements the `Backend` protocol defined in `qufin.backends.base`.

| Backend | Description | Use Case |
|---|---|---|
| `MockBackend` | Deterministic, no simulator dependency | Unit tests, CI |
| `QiskitAerBackend` | Qiskit Aer statevector and QASM simulator | Local development, research |
| `NoisyAerBackend` | Aer with configurable noise (4 built-in profiles) | Noise-aware algorithm development |
| `IBMRuntimeBackend` | IBM Quantum Platform via Sampler/Estimator | Cloud execution, real hardware |
| `PennyLaneBackend` | PennyLane Lightning | Cross-framework interop |
| `CirqBackend` | Google Cirq | Cirq ecosystem integration |
| `BraketBackend` | Amazon Braket | AWS quantum hardware access |

---

## Benchmarks

qufin includes standardized benchmark problem sets (15, 25, and 50 assets) with real covariance
matrices and expected return vectors. The benchmark runner measures solution quality, time-to-solution,
circuit depth, and approximation ratio against the exact classical optimum.

Results are tracked via reproducibility manifests that record hardware, software versions, and
random seeds. The framework is designed for honest assessment of quantum advantage -- every
quantum result is compared head-to-head against the best available classical solver on the same
problem instance.

---

## Documentation

Full documentation: [https://anonymousAAK.github.io/qufin](https://anonymousAAK.github.io/qufin) *(coming soon)*

---

## Contributing

Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on
code style, testing, and pull request process.

---

## License

Apache 2.0. See [LICENSE](LICENSE) for details.

---

## Citation

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