Metadata-Version: 2.4
Name: vqe-portfolio
Version: 0.1.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: 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: ruff<1.0,>=0.6; extra == "dev"
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: twine<7,>=6; 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: 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"
Dynamic: license-file

# Portfolio Optimization via VQE

[![PyPI](https://img.shields.io/pypi/v/vqe-portfolio.svg)](https://pypi.org/project/vqe-portfolio/)
[![Python](https://img.shields.io/pypi/pyversions/vqe-portfolio.svg)](https://pypi.org/project/vqe-portfolio/)
[![License](https://img.shields.io/pypi/l/vqe-portfolio.svg)](LICENSE)
[![CI](https://github.com/SidRichardsQuantum/VQE_Portfolio_Optimization/actions/workflows/ci.yml/badge.svg)](https://github.com/SidRichardsQuantum/VQE_Portfolio_Optimization/actions)

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

Two complementary quantum formulations are provided:

* **Binary VQE** — asset *selection* under a cardinality constraint (QUBO → Ising → VQE)
* **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**
* Hardware-efficient **RY + CZ ring** ansatz
* VQE minimizes ⟨H⟩ directly
* Outputs include probabilities, samples, Top‑K projections, λ‑sweeps, and efficient frontiers

Notebook client:

* `notebooks/Binary.ipynb`

---

### 2️⃣ 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**
* No penalty tuning required
* Smooth λ‑sweeps with optional warm starts
* Efficient frontier computed from allocations

Notebook clients:

* `notebooks/Fractional.ipynb`
* `notebooks/examples/Real_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.

### 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

```text
src/
└── vqe_portfolio/
    ├── binary.py        # Binary VQE (QUBO / Ising formulation)
    ├── fractional.py    # Fractional VQE (simplex parameterization)
    ├── frontier.py      # Efficient frontier utilities
    ├── 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

notebooks/
├── Binary.ipynb
├── Fractional.ipynb
├── examples/
│   └── Real_Example.ipynb
└── images/
```

---

## 📖 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
* λ-sweeps and efficient frontiers

---

## 📚 Additional Documentation

* **Theory & derivations**: [`THEORY.md`](THEORY.md)
* **Results & figures**: [`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** and **experiment clients**
* 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)

---

**Author**: Sid Richards
GitHub: [@SidRichardsQuantum](https://github.com/SidRichardsQuantum)
MIT License — see [LICENSE](LICENSE)
