Metadata-Version: 2.4
Name: vqe-portfolio
Version: 0.3.1
Summary: VQE-based portfolio optimization with PennyLane
Author: Sid Richards
License-Expression: MIT
Project-URL: Repository, https://github.com/SidRichardsQuantum/VQE_Portfolio_Optimization
Project-URL: Issues, https://github.com/SidRichardsQuantum/VQE_Portfolio_Optimization/issues
Keywords: quantum,vqe,portfolio-optimization,pennylane,finance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: matplotlib<4.0,>=3.8
Requires-Dist: pennylane<1.0,>=0.35
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: nbmake<2.0,>=1.5; extra == "dev"
Requires-Dist: ruff<1.0,>=0.6; extra == "dev"
Requires-Dist: black<26.0,>=24.0; extra == "dev"
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Requires-Dist: tomli<3.0,>=2.0; python_version < "3.11" and extra == "dev"
Provides-Extra: classical
Requires-Dist: scipy<2.0,>=1.11; extra == "classical"
Requires-Dist: cvxpy<2.0,>=1.4; extra == "classical"
Requires-Dist: osqp<1.0,>=0.6; extra == "classical"
Provides-Extra: markowitz
Requires-Dist: cvxpy<2.0,>=1.4; extra == "markowitz"
Requires-Dist: osqp<1.0,>=0.6; extra == "markowitz"
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.0; extra == "notebooks"
Requires-Dist: jupytext<2.0,>=1.16; extra == "notebooks"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=8; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser<5,>=4; extra == "docs"
Provides-Extra: data
Requires-Dist: pandas<3.0,>=2.0; extra == "data"
Requires-Dist: yfinance<0.3.0,>=0.2.40; extra == "data"
Requires-Dist: scikit-learn<2.0,>=1.4; extra == "data"
Provides-Extra: all
Requires-Dist: scipy<2.0,>=1.11; extra == "all"
Requires-Dist: cvxpy<2.0,>=1.4; extra == "all"
Requires-Dist: osqp<1.0,>=0.6; extra == "all"
Requires-Dist: sphinx<9,>=8; extra == "all"
Requires-Dist: furo>=2024.8.6; extra == "all"
Requires-Dist: myst-parser<5,>=4; extra == "all"
Requires-Dist: jupyter>=1.0; extra == "all"
Requires-Dist: jupytext<2.0,>=1.16; extra == "all"
Requires-Dist: pandas<3.0,>=2.0; extra == "all"
Requires-Dist: yfinance<0.3.0,>=0.2.40; extra == "all"
Requires-Dist: scikit-learn<2.0,>=1.4; extra == "all"
Dynamic: license-file

# Portfolio Optimization via VQE

<p align="center">

<a href="https://pypi.org/project/vqe-portfolio/">
<img src="https://img.shields.io/pypi/v/vqe-portfolio?style=flat-square" alt="PyPI Version">
</a>

<a href="https://pypi.org/project/vqe-portfolio/">
<img src="https://img.shields.io/pypi/pyversions/vqe-portfolio?style=flat-square" alt="Python Versions">
</a>

<a href="https://github.com/SidRichardsQuantum/VQE_Portfolio_Optimization/actions/workflows/ci.yml">
<img src="https://img.shields.io/github/actions/workflow/status/SidRichardsQuantum/VQE_Portfolio_Optimization/ci.yml?label=tests&style=flat-square" alt="Tests">
</a>

<a href="https://github.com/SidRichardsQuantum/VQE_Portfolio_Optimization/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/SidRichardsQuantum/VQE_Portfolio_Optimization?style=flat-square" alt="License">
</a>

<a href="https://github.com/sponsors/SidRichardsQuantum">
<img src="https://img.shields.io/badge/sponsor-GitHub-ea4aaa?style=flat-square&logo=githubsponsors" alt="Sponsor">
</a>

</p>

PyPI: [https://pypi.org/project/vqe-portfolio/](https://pypi.org/project/vqe-portfolio/)

Website: [https://sidrichardsquantum.github.io/VQE_Portfolio_Optimization/](https://sidrichardsquantum.github.io/VQE_Portfolio_Optimization/)

A Python library for portfolio optimization with PennyLane. It provides Binary VQE and QAOA for selecting a fixed number of assets, and Fractional VQE for long-only allocation. Classical baselines and independent candidate evaluation support reproducible comparisons.

The experiments use quantum simulation and do not establish quantum advantage or production readiness.

## Installation

```bash
pip install vqe-portfolio
```

Optional dependencies:

```bash
pip install "vqe-portfolio[data]"       # Market data utilities
pip install "vqe-portfolio[classical]"  # SciPy/HiGHS and CVXPY/OSQP baselines
pip install -e ".[dev,docs]"           # Development and documentation
```

## Quickstart

Run a small synthetic asset-selection problem:

```python
import numpy as np
from vqe_portfolio import BinaryVQEConfig, run_binary_vqe

mu = np.array([0.10, 0.12, 0.07, 0.09])
sigma = np.eye(4) * 0.02
config = BinaryVQEConfig(k=2, lam=4.0, alpha=2.0, steps=25, seed=0)
result = run_binary_vqe(mu, sigma, config)
print(result.x_topk)
```

The command-line interface supports the same solvers:

```bash
vqe-portfolio --help
python -m vqe_portfolio --help
```

See the [usage guide](USAGE.md) for complete API and CLI examples, ansatz options, real-data workflows, and efficient frontiers.

## Repository structure

```text
src/vqe_portfolio/
├── binary.py, qaoa.py, fractional.py   # Quantum solvers
├── problem.py, types.py               # Problem evaluation and solver types
├── ansatz.py, optimize.py             # Shared circuit and optimizer code
├── baselines/                        # Classical references and optional solvers
├── benchmark.py                      # Independent candidate evaluation/reporting
├── research/                         # Study logic and shared runner infrastructure
└── ...                               # CLI, data, plotting, frontier utilities
scripts/                              # Experiment entry points and report generation
experiments/                          # Study configuration and reproduction guide
results/                              # Saved research evidence
notebooks/                            # Tutorial and comparison clients
tests/                               # Solver, research, CLI, compatibility tests
docs/                                 # Sphinx documentation
```

See [architecture and development](docs/architecture.md) for module boundaries and the v0.3.0 migration notes. Existing public imports remain supported. Version 0.3.1 adds opt-in solver reliability controls and end-to-end execution budgets; see the [usage guide](USAGE.md#solver-reliability-controls-v031) and [changelog](CHANGELOG.md).

## Documentation and research

| Guide | Contents |
| --- | --- |
| [Usage](USAGE.md) | Installation, API, CLI, benchmarks, and reproduction commands |
| [Theory](THEORY.md) | Portfolio formulations, circuit mappings, and derivations |
| [Results](RESULTS.md) | Committed benchmark and diagnostic findings |
| [Research protocol](QUANTUM_ADVANTAGE.md) | Evaluation design and limits on advantage claims |
| [Experiments](experiments/README.md) | Validation, training, sampling, and failure diagnostics |

Start with `notebooks/Binary.ipynb`, `notebooks/QAOA.ipynb`, or `notebooks/Fractional.ipynb`. Real-data examples are in `notebooks/examples/`.

Saved study reports:

- [Small-instance validation](results/small_instance_validation/report.md)
- [Before/after training](results/training_diagnostic/report.md)
- [Sampling allowances](results/sampling_allowance/report.md)
- [Training effort](results/training_effort/report.md)
- [Failure diagnostics](results/failure_diagnostics/report.md)
- [Solver reliability controls](results/solver_reliability/report.md)
- [Fixed-deadline simulator pilot](results/budget_benchmark/report.md)

## Author and support

[Sid Richards](https://github.com/SidRichardsQuantum) · [LinkedIn](https://www.linkedin.com/in/sid-richards-21374b30b/) · [Sponsor development](https://github.com/sponsors/SidRichardsQuantum)

MIT License — see [LICENSE](https://github.com/SidRichardsQuantum/VQE_Portfolio_Optimization/blob/main/LICENSE).
