Metadata-Version: 2.4
Name: vqe-portfolio
Version: 0.2.6
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: 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: 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/)

This package implements **portfolio optimization using Variational Quantum Eigensolvers (VQE)** as a clean, testable, and reusable **Python library**, with notebooks acting purely as *clients*.

Three complementary quantum formulations are provided:

- **Binary VQE** — asset *selection* under a cardinality constraint (QUBO → Ising → VQE)
- **QAOA** — gate-based combinatorial optimization using alternating cost and mixer Hamiltonians
- **Fractional VQE** — long-only *allocation* on the simplex using a constraint-preserving quantum parameterization

All core logic lives in `src/vqe_portfolio/`; notebooks and examples simply call the public API.

---

## Implemented Methods

### 1. Binary VQE (Asset Selection)

Select exactly **K assets** by solving a constrained mean–variance problem:

$$
\min_{x \in \{0,1\}^n}
\;\lambda\, x^\top \Sigma x
\;-\;\mu^\top x
\;+\;\alpha(\mathbf{1}^\top x - K)^2
$$

**Highlights**

- QUBO formulation mapped to an **Ising Hamiltonian**
- Configurable ansatz options: **RY + CZ ring**, **RY/RZ + CZ ring**, and PennyLane strongly-entangling layers
- VQE minimizes ⟨H⟩ directly
- Outputs include probabilities, samples, Top‑K projections, λ‑sweeps, and efficient frontiers

Notebook client:

- `notebooks/Binary.ipynb`
- `notebooks/examples/02_Real_Example.ipynb`
- `notebooks/examples/04_Larger_Real_Data_Example.ipynb`

---

### 2. QAOA (Binary Asset Selection)

Solve the same constrained mean–variance problem using the **Quantum Approximate Optimization Algorithm (QAOA)**:

$$
\min_{x \in \{0,1\}^n}
\;\lambda\, x^\top \Sigma x
\;-\;\mu^\top x
\;+\;\alpha(\mathbf{1}^\top x - K)^2
$$

**Highlights**

- Uses the same QUBO → Ising mapping as Binary VQE
- Alternating operator ansatz:
  - cost unitary $e^{-i\gamma H_C}$
  - mixer unitary $e^{-i\beta H_M}$
- Supports:
  - standard **X mixer**
  - **XY mixer** for improved constraint structure
- Produces:
  - bitstring samples
  - marginal selection probabilities
  - Top-K projections
  - feasible candidate solutions
  - λ-sweeps

Notebook client:

- `notebooks/QAOA.ipynb`
- `notebooks/examples/03_Real_Example.ipynb`
- `notebooks/examples/04_Larger_Real_Data_Example.ipynb`

---

### 3. Fractional VQE (Continuous Allocation)

Solve the long-only mean–variance problem on the simplex:

$$
\min_{w \in \Delta}\; -\mu^\top w + \lambda\, w^\top \Sigma w
\quad\text{with}\quad
\Delta={w\ge0,\sum_i w_i=1}
$$

**Highlights**

- Simplex constraint enforced **by construction**
- Configurable ansatz options: **RY**, **RY + CZ ring**, and **RY/RZ + CZ ring**
- No penalty tuning required
- Smooth λ‑sweeps with optional warm starts
- Efficient frontier computed from allocations

Notebook clients:

- `notebooks/Fractional.ipynb`
- `notebooks/examples/01_Real_example.ipynb`
- `notebooks/examples/04_Larger_Real_Data_Example.ipynb`

---

## Why Quantum Here?

Classical mean–variance portfolio optimization is well understood and efficiently solvable *in its simplest form*.
However, many practically relevant extensions introduce **combinatorial structure** that scales poorly with problem size.

This project focuses on those regimes.

### What is classically easy
- Unconstrained or long-only Markowitz optimization
- Convex quadratic objectives on the simplex
- Small-scale cardinality constraints via heuristics

### What becomes hard
- **Exact cardinality constraints** (select exactly *K* assets)
- Discrete–continuous hybrid decision spaces
- Exhaustive exploration of correlated asset subsets
- Non-convex penalty landscapes introduced by constraints

These settings naturally map to **QUBO / Ising formulations**, which are native to near-term quantum algorithms such as **VQE** and **QAOA**.

### Why VQE is a natural research tool
- VQE directly minimizes ⟨H⟩ for problem-encoded Hamiltonians
- Constraints can be enforced **structurally** (fractional case) or via penalties (binary case)
- Hybrid quantum–classical loops align with existing optimization workflows
- The framework cleanly supports:
  - Ansatz experimentation
  - Noise and shot studies
  - Warm-started parameter sweeps

### What this project does *not* claim
- Quantum advantage over classical solvers
- Near-term production readiness
- Superiority to specialized classical optimizers

Instead, this repository provides a **carefully engineered research baseline** for exploring how constrained financial optimization problems behave when expressed in quantum-native representations.

---

## Installation

Base install (quantum algorithms only):

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

With real market data utilities:

```bash
pip install "vqe-portfolio[data]"
```

With classical Markowitz baseline:

```bash
pip install "vqe-portfolio[markowitz]"
```

For development:

```bash
pip install -e ".[dev]"
```

---

## Repository Structure

```
src/
└── vqe_portfolio/
    ├── binary.py        # Binary VQE (QUBO / Ising formulation)
    ├── qaoa.py          # QAOA portfolio optimization
    ├── fractional.py    # Fractional VQE (simplex parameterization)
    ├── frontier.py      # Efficient frontier utilities
    ├── comparison.py    # Exact baselines and comparison helpers
    ├── ansatz.py        # Shared circuit ansätze
    ├── optimize.py      # Optimizer loops
    ├── metrics.py       # Risk / return utilities
    ├── plotting.py      # Centralized plotting helpers
    ├── data.py          # Market data utilities
    └── types.py         # Dataclasses for configs & results

scripts/
├── generate_comparison_results.py  # Synthetic baselines and repeatability CSVs
├── generate_ansatz_comparison.py   # Compact ansatz comparison CSV
└── generate_larger_real_data_example.py  # 12-stock real-data example artifacts

results/
├── synthetic_comparison.csv
├── real_data_comparison.csv
├── generated_comparison_summary.csv
├── generated_repeatability_trials.csv
├── real_data_method_comparison.csv
├── larger_real_data_comparison.csv
└── ansatz_comparison.csv

notebooks/
├── Binary.ipynb
├── QAOA.ipynb
├── Fractional.ipynb
├── Benchmark_Comparison.ipynb
├── Real_Data_Comparison.ipynb
├── Ansatz_Comparison.ipynb
├── examples/
│   ├── 01_Real_example.ipynb
│   ├── 02_Real_Example.ipynb
│   ├── 03_Real_Example.ipynb
│   └── 04_Larger_Real_Data_Example.ipynb
└── images/

tests/
└── test_*.py
```

---

## Usage

This package can be used **both programmatically (Python API)** and **from the command line (CLI)**.

See **[USAGE.md](USAGE.md)** for:

- Command-line interface (CLI) usage
- Minimal API examples
- Synthetic-data quickstart
- Real-data workflows
- Benchmark comparison workflows
- λ-sweeps and efficient frontiers

---

## Additional Documentation

- **Theory & derivations**: [`THEORY.md`](THEORY.md)
- **Usage & reproducibility**: [`USAGE.md`](USAGE.md)
- **Committed benchmark results**: [`RESULTS.md`](RESULTS.md)

---

## Why This Matters

This project demonstrates:

- Mapping **financial optimization problems** to quantum Hamiltonians
- Clean constraint handling (cardinality vs simplex)
- A strict separation between **research code**, notebook clients, and benchmark scripts
- Reproducible hybrid quantum–classical workflows
- Production‑grade packaging and CI for quantum algorithms

---

## References

- QUBO overview: [https://en.wikipedia.org/wiki/Quadratic_unconstrained_binary_optimization](https://en.wikipedia.org/wiki/Quadratic_unconstrained_binary_optimization)
- PennyLane documentation: [https://docs.pennylane.ai](https://docs.pennylane.ai)

---

## Support development

If this repository is useful for research, learning, or experimentation, you can support continued development via GitHub Sponsors:

[https://github.com/sponsors/SidRichardsQuantum](https://github.com/sponsors/SidRichardsQuantum)

Sponsorship supports continued work on open-source implementations of quantum optimization algorithms, including improvements to documentation, reproducible workflows, example notebooks, and benchmarking utilities.

Support helps maintain accessible reference implementations of VQE and QAOA methods for constrained optimization problems and hybrid quantum–classical experimentation.

---

## Author

**Sid Richards**

LinkedIn: [https://www.linkedin.com/in/sid-richards-21374b30b/](https://www.linkedin.com/in/sid-richards-21374b30b/)

GitHub: [https://github.com/SidRichardsQuantum](https://github.com/SidRichardsQuantum)

---

## License

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