Writing a QAOA circuit is a solved problem. Dozens of tutorials, including our own, will get you there in an afternoon. Writing the two-page memo that convinces a risk committee to fund a pilot is a completely different skill, and almost nothing teaches it. Most "quantum computing for finance" content either stays purely technical (build a circuit, print a result) or purely promotional (quantum will transform portfolio optimization). Neither produces the artifact a real business case needs.
PortfolioQ is a small, open-source FastAPI project built specifically to produce that artifact. It's worth walking through, not because it's a production optimizer (its own README says explicitly that it isn't), but because its structure is a genuinely useful template for how to evaluate any quantum optimization claim honestly, portfolio selection or otherwise.
The problem it solves
PortfolioQ targets cardinality-constrained portfolio selection: pick exactly K assets out of N candidates to minimize risk and maximize expected return, using the standard Markowitz mean-variance formulation: minimize risk_factor * wᵀΣw - μᵀw subject to sum(w) == budget, with each w binary. That constraint (exactly K assets, not "up to K") is what makes this a good test case: it's a real, common portfolio-construction requirement, and it's exactly the kind of constraint that's easy to get wrong in a naive QAOA implementation.
Three solvers, run side by side
This is the part most quantum finance demos skip, and it's the part that matters for a business case: PortfolioQ doesn't run one method and report a number. It runs three, on the same data, and compares them.
Classical exact enumeration. Brute-forces every feasible K-of-N combination directly. It's not a strawman. For portfolios in the 10-30 asset range this is fast and exact, which is precisely why it's the right baseline. Any quantum approach has to be measured against this, not against "no answer at all."
Penalty-method QAOA. The standard textbook approach: convert the constrained problem to a QUBO via QuadraticProgramToQubo, encode it as an Ising Hamiltonian, run QAOA. It works, but it spends circuit depth and classical tuning effort enforcing the budget constraint through a penalty term, and some fraction of measured samples violates the constraint outright, silently scored badly rather than rejected. If you're presenting quantum results to people without an SDK background, this is the mode most likely to embarrass you: "why does the quantum solution sometimes pick the wrong number of stocks?"
Dicke-state / XY-mixer QAOA. The constraint-preserving alternative. A Dicke-state initialization (built with a small ancilla "running count" register that provably lands on exactly |budget⟩) combined with an XY-mixer (RXX/RYY gates) keeps every single measurement inside the feasible K-of-N subspace by construction. No penalty tuning, no invalid answers to explain away. It's a heavier circuit, but it's the version you'd want in front of a non-technical audience. Every result respects the constraint they asked for, because the ansatz makes anything else geometrically impossible.
That comparison (one classical baseline, two structurally different quantum approaches) is the shape a credible business case needs. A single quantum result with no classical comparison and no discussion of why the encoding was chosen isn't evidence of anything.
The chart that's the actual deliverable
Here's the part of PortfolioQ's own documentation worth repeating verbatim, because it's the most honest sentence you'll read about applied quantum optimization this year:
Run the same request against a real IBM backend and chart result quality vs. gate count as you increase
reps. This is the "signal vs. noise crossover" chart that's the actual deliverable for a business-case pitch.
That's the whole exercise. Not "we ran QAOA and it worked." Not "quantum is X% faster." A chart with two axes: how close the quantum answer gets to the true optimum (pct_of_optimal: 100% means it matched classical exactly), against how much circuit you had to run to get there (circuit_depth and two_qubit_gates, both reported alongside every result). Run it on the simulator first, then on real hardware, and watch where the lines cross, or don't.
Building the case, step by step
1. Cap your problem size honestly. PortfolioQ's own README recommends 10-30 assets for anything run on real hardware, and explains why: current NISQ devices simply don't have the qubit count or gate fidelity to go further without the noise dominating the signal. A business case that quietly assumes a 500-stock universe on today's hardware isn't a business case, it's fiction. Start with the candidate universe you'd genuinely consider: real tickers, real historical prices (the tool fetches these automatically via yfinance if you don't supply your own).
2. Establish the in-principle baseline on a simulator. Run /optimize/compare-all on aer_simulator before touching real hardware. Check that feasible_fraction on the XY-mixer result is exactly 1.0. That's your sanity check that the constraint-preserving construction works as designed, with no hardware noise yet in the picture.
POST /optimize/compare-all
{
"tickers": ["AAPL", "MSFT", "GOOGL", "AMZN", "NVDA"],
"budget": 2,
"risk_factor": 0.5,
"reps": 2,
"shots": 1024,
"backend": "aer_simulator"
}
3. Move to real hardware and vary reps. This is where the actual data comes from. Point "backend" at a real device ("ibm_torino", for example. See our IBM Quantum free tier guide if you don't have hardware access set up yet) and rerun the same comparison as you increase reps. qaoa_xy_pct_of_optimal and two_qubit_gates climbing together across a handful of reps values is the chart. Because each COBYLA iteration blocks on a real hardware job, use PortfolioQ's async /submit + /jobs/{id} endpoints rather than the blocking ones. A maxiter of 100 means up to 100 hardware round-trips per optimization run, which will outlast most HTTP client timeouts on a queued device.
4. Report the noise honestly, including where it breaks the guarantee. Expect feasible_fraction to drop below 1.0 on real hardware even for the XY-mixer, despite the simulator showing a clean 1.0. That's not a bug and it's not a reason to hide the result. On real hardware, noise, not the algorithm, is what breaks the Hamming-weight preservation the Dicke-state construction guarantees in theory. That gap between simulator and hardware feasibility is itself a meaningful, quotable data point: it's a direct, measured picture of how much today's error rates cost you, expressed in a metric a risk committee reads directly.
5. Write the recommendation the data supports. For 10-30 assets on current hardware, that recommendation is almost never "replace the greedy heuristic in production today". PortfolioQ's own greedy baseline exists precisely as "what we'd run in production today," and it's fast, classical, and usually close to optimal at this scale. The honest, defensible business case is: here is the exact crossover point we measured, here is what has to improve (gate fidelity, qubit count, queue economics) before it moves, and here is the monitoring plan for re-running this comparison as hardware improves. That's a real deliverable. "We're not there yet, and here's precisely how we'll know when we are" is a stronger memo than an inflated claim that won't survive the first follow-up question.
What this template generalizes to
None of the above is specific to portfolios. The same shape (a credible classical baseline, more than one quantum encoding compared honestly, a simulator sanity check before hardware, and a quality-vs-noise chart instead of a single cherry-picked run) is exactly how you'd build a defensible case for QAOA on any other constrained optimization problem: routing, scheduling, or the Max-Cut-style problems in our QAOA tutorial. The specific circuits change. The discipline of comparing against what you already have, and reporting where the noise wins, doesn't.
If you want to see this pattern extended, PortfolioQ's source on GitHub is small enough to read end to end in an afternoon: portfolio.py for the QUBO construction, xy_mixer_solver.py for the constraint-preserving ansatz, and main.py for how the comparison endpoints are wired together. It's explicitly a pilot and capability-building scaffold rather than a production system, which, for the purpose of building a business case rather than shipping a trading system, is exactly the point.