Choose k assets out of n, and know how far the answer is from the best
QCOS writes mean-variance asset selection as a QUBO, solves it with QAOA and then checks the answer against the exact optimum. You get the portfolio, its risk and return, and its gap to the best feasible portfolio in one response.
- Problem
- Choose exactly k of n assets
- Method
- QUBO, Ising, QAOA
- Check
- Exact optimum by enumeration
The problem
Picking a fixed number of assets is a combinatorial search
Holding exactly k of n assets while trading expected return against risk leaves one candidate portfolio for every way of choosing k. With 20 assets and k = 10 there are 184,756 of them.
A quadratic unconstrained binary optimisation (QUBO) is the form quantum optimisation methods accept. The difficulty is folding the "exactly k" rule into it without letting an invalid portfolio win.
One bit per asset
x_i = 1 when asset i is held, 0 when it is not.
Return and risk in one objective
Expected returns and the covariance matrix enter the same quadratic form.
A budget that holds
The answer always holds exactly k assets; an invalid sample is never returned as the result.
How QCOS solves it
From returns and covariance to a checked answer
- 01
Write the objective
Minimise λ·xᵀΣx − μᵀx, where μ is the vector of expected returns, Σ the covariance matrix and λ your risk aversion.
- 02
Fold in the budget
The rule Σx = k becomes the penalty P(Σx − k)². P is 1.1 times the largest change a single bit flip makes to the objective, so every invalid portfolio scores worse than the best valid one.
- 03
Map to qubits
The QUBO becomes an Ising Hamiltonian of weighted Z and ZZ terms, one qubit per asset.
- 04
Run QAOA
The QAOA angles are optimised on a state vector, then the optimised circuit is sampled with the number of shots you set.
- 05
Keep only valid answers
The result is the best sample that holds exactly k assets, scored by the true objective, not by the penalised energy.
- 06
Check against the optimum
QCOS enumerates every valid portfolio, finds the exact optimum and reports the answer's gap and rank among them.
The API call
One request with your returns and covariance
Send the expected returns, the covariance matrix, how many assets to hold, your risk aversion and the number of shots. Authenticate with your QCOS API key in the X-API-Key header.
curl -X POST https://api.softquantus.com/api/v1/algorithms/hybrid/run \
-H "X-API-Key: $QCOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"preset": "portfolio",
"initial_context": {
"returns": [0.12, 0.10, 0.07, 0.03, 0.09],
"covariance": [
[0.10, 0.02, 0.01, 0.00, 0.02],
[0.02, 0.08, 0.01, 0.00, 0.01],
[0.01, 0.01, 0.05, 0.00, 0.01],
[0.00, 0.00, 0.00, 0.01, 0.00],
[0.02, 0.01, 0.01, 0.00, 0.07]
],
"n_select": 2,
"risk_aversion": 0.5,
"shots": 2048
}
}'Defaults when omitted: n_select is the smaller of 3 and the number of assets, risk_aversion is 1.0 and shots is 2048 (at most 100,000). A malformed instance returns 422.
The answer
What comes back
An abridged response from one run of the QCOS code now in production, on a CPU simulator, on 10 October 2026. Sampled values such as the feasible-shot fraction vary from run to run.
{
"status": "completed",
"final_output": {
"selected_assets": [0, 1],
"expected_return": 0.11,
"risk": 0.2345,
"objective": -0.11,
"algorithm": "QAOA-QUBO",
"is_optimal": true,
"optimality_gap": 1.39e-17,
"rank_among_feasible": 1,
"n_feasible_portfolios": 10,
"feasible_shot_fraction": 0.835,
"repaired": false,
"penalty": { "value": 0.077, "bound_B": 0.07, "margin": 0.007 },
"qaoa": {
"p_layers": 2,
"energy_ratio": 0.752,
"ground_state_probability": 0.092,
"ground_state_uniform_baseline": 0.031
}
}
}Expected return and risk are those of the equal-weight portfolio of the chosen assets. Numbers are rounded here; the API returns full precision.
Reading the result
What each number tells you
- is_optimal and rank_among_feasible
- Rank 1 of 10The chosen pair is the exact optimum among the 10 portfolios that hold two of the five assets.
- optimality_gap
- About 1e-17The difference between the answer's objective and the optimum's, here at floating-point precision.
- feasible_shot_fraction
- 0.835The share of samples that held exactly k assets. It shows how well the penalty kept the search on valid portfolios.
- ground_state_probability
- 0.092 against 0.031How often the QAOA circuit itself sampled the optimum, against the 1-in-32 chance of a uniform guess over five qubits. This isolates what the quantum step contributed.
- repaired
- falseTrue would mean the returned sample was adjusted to meet the budget. The flag is always reported.
Limits
What this does not do
Up to 20 assets
The exact optimum is found by enumeration, which caps an instance at 20 assets. A larger instance is refused with 422, not approximated.
Simulator, not hardware
QAOA runs on a CPU simulator. Access to quantum hardware through Softquantus Cloud is in development.
No claim of advantage
Classical solvers handle instances of this size exactly, and QCOS uses enumeration to check its own answer. The value is a quantum method you can measure honestly.
Equal weights
The model chooses which assets to hold, not how much of each. Return and risk are reported for equal weights.
No silent fallback
If the quantum step fails, the request fails with the reason. No classical rule quietly picks the answer instead.
Values vary
Shots are sampled, so fractions and probabilities change between runs. The optimum and the gap are computed exactly.
Questions
What quants ask about QUBO portfolios
Why write portfolio selection as a QUBO?
A QUBO is the input form of QAOA and quantum annealing. Writing the problem this way lets you test those methods on your own data, with the exact optimum alongside for comparison.
How is the "exactly k assets" rule enforced?
As a quadratic penalty, P(Σx − k)², with P set above the largest change a single bit flip can make. Every invalid portfolio then scores worse than the best valid one, and only valid samples are returned.
Does a quantum computer beat a classical optimiser here?
No such claim is made. QCOS checks every answer against the exact optimum, so you can see what the quantum step found and how often.
Can I call it from Python or an AI agent?
Yes. It is a plain HTTPS call from any language. QCOS is also reached through the softqcos Python SDK and CLI, and through the softqcos-mcp server for AI agents. See MCP integration.
Related
More on QCOS algorithms
Bring your own instance
Send us the returns, covariance and budget of a real selection problem. We will run it and show you the answer, the optimum and the gap.