Portfolio Optimization via VQE

PyPI: https://pypi.org/project/vqe-portfolio/

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

pip install vqe-portfolio

Optional dependencies:

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:

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:

vqe-portfolio --help
python -m vqe_portfolio --help

See the usage guide for complete API and CLI examples, ansatz options, real-data workflows, and efficient frontiers.

Repository structure

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 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 and changelog.

Documentation and research

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
• Before/after training
• Sampling allowances
• Training effort
• Failure diagnostics
• Solver reliability controls
• Fixed-deadline simulator pilot

Author and support

Sid Richards · LinkedIn · Sponsor development

MIT License — see LICENSE.