Metadata-Version: 2.4
Name: vqe-portfolio
Version: 0.1.3
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: 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"
Provides-Extra: all
Requires-Dist: cvxpy<2.0,>=1.4; extra == "all"
Requires-Dist: osqp<1.0,>=0.6; 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

[![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

```
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)

---

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

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](LICENSE)
