vqe-portfolio 0.1.2

VQE-based portfolio optimization with PennyLane

Portfolio Optimization via VQE

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

pip install vqe-portfolio

With real market data utilities:

pip install "vqe-portfolio[data]"

With classical Markowitz baseline:

pip install "vqe-portfolio[markowitz]"

For development:

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 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
• Results & figures: 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
• PennyLane documentation: https://docs.pennylane.ai

---

Author: Sid Richards GitHub: @SidRichardsQuantum MIT License — see LICENSE