VQE Portfolio Optimization¶
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, Filtering VQE (F-VQE), and QAOA for selecting a fixed number of assets, and a variational quantum allocator for long-only allocation. Classical baselines and independent candidate evaluation support reproducible comparisons.
The allocator was historically called “Fractional VQE”. It parameterises weights
with a quantum circuit and evaluates the portfolio cost classically; it is not
Hamiltonian-expectation VQE. Use run_variational_allocator and
VariationalAllocatorConfig; the old Python and CLI names remain aliases.
The experiments use quantum simulation and do not establish quantum advantage or production readiness.
Binary VQE and QAOA support optional CVaR training
with training_objective="cvar", cvar_alpha=0.25. This emphasizes the lowest-cost
portion of circuit outcomes; mean-cost training remains the default.
Filtering VQE implements normalized
parameter-shift updates toward freshly filtered states. It supports inverse and
exponential filters, adaptive or fixed strength, and analytic or finite-shot
training through run_fvqe and FVQEConfig, or the f-vqe CLI command.
Installation¶
pip install vqe-portfolio
Requires Python 3.10+ and PennyLane 0.42.3+. CI tests the minimum core dependencies and current compatible dependencies on Python 3.10–3.12.
Optional dependencies:
pip install "vqe-portfolio[data]" # Market data utilities
pip install "vqe-portfolio[classical]" # HiGHS, OSQP, and SCIP baselines
pip install "vqe-portfolio[scip]" # SCIP only
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.
Classical exact-K comparators include NumPy-only multistart swap search, simulated annealing, parallel tempering, tabu search, memetic genetic search, iterated local search (ILS), GRASP, and variable neighbourhood search (VNS), plus optional QP relaxation with rounding and swap refinement, HiGHS linearised integer and SCIP quadratic integer optimisation. All support end-to-end execution budgets; see classical baselines.
NumPy projected gradient descent and Frank–Wolfe with away steps supply iterative classical comparators for the separate long-only fractional allocation track, alongside optional OSQP.
Repository structure¶
src/vqe_portfolio/
├── binary.py, fvqe.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.
Version 0.3.3 adds simulated annealing, tabu search, and SCIP to the classical comparisons, small-instance validation, and budget CLI. Version 0.3.4 adds memetic genetic search, ILS, GRASP, QP rounding, VNS, and projected gradient descent; fixes selection and allocator boundaries; and introduces the canonical allocator names and individual algorithm guides. Archived research results retain their original methods and provenance.
Version 0.3.5 adds optional CVaR training for Binary VQE and QAOA, with analytic Adam or finite-shot SPSA optimization and objective metadata in solver results.
Version 0.3.6 adds Filtering VQE and NumPy-only Frank–Wolfe with away steps, including comparison, validation, and execution-budget integration. The roadmap lists further algorithms and implementation requirements.
Version 0.3.7 adds NumPy-only parallel tempering for exact-K binary selection, with comparison, validation, execution budgets, and acceptance/work diagnostics.
Documentation and research¶
Guide |
Contents |
|---|---|
Installation, API, CLI, benchmarks, and reproduction commands |
|
Portfolio formulations, circuit mappings, and derivations |
|
Concise descriptions of quantum and classical methods |
|
Committed benchmark and diagnostic findings |
|
Evaluation design and limits on advantage claims |
|
Validation, training, sampling, and failure diagnostics |
Start with notebooks/Binary.ipynb, notebooks/QAOA.ipynb, or notebooks/Fractional.ipynb. Real-data examples are in notebooks/examples/.
Saved study reports: