qoro / pushquantum-2026-template
PublicStep one: sign up at dash.qoroquantum.net for your API key and hackathon credits. It takes a minute, and section 0.1 shows where the key goes.
| Notebook | What you'll do |
|---|---|
| 00 · Main (this one) | Part 0 · Setup: API key, install, backend. Part 1 · QUBO 101: build a QUBO, characterize and validate it, solve it with QAOA and PCE, partition a bigger one. Part 2: choose your problem |
| 01 · Portfolio optimisation (QOBLIB 06) | Official model → QUBO → classical baseline → PCE and partitioned QAOA → solution file |
| 02 · Network design (QOBLIB 08) | Topology QUBO + exact routing LP → sample, score, write a solution file |
qoblib_tools.py holds Python ports of QOBLIB's solution
checkers for both problems; they reproduce the published numbers exactly (checked against every
published reference solution). Treat it as the referee: change your models and solvers, not the referee..env next to the notebooks containing
QORO_API_KEY="your_api_key_here", and never commit it (add .env to your .gitignore). Divi finds it
on its own, and a key in a .env file wins over the other ways.uvx marimo edit --sandbox 00_main_qubo_101.py
qubo-decompose extra brings D-Wave's hybrid and dwave-samplers packages, used for QUBO
partitioning and simulated annealing. The jupyter extra lets Divi's progress displays render in the
notebook.
Optional: Maestro, Qoro's simulator, also works as a drop-in for code you write directly in Qiskit
(pip install qiskit-maestro) or PennyLane (pip install pennylane-maestro).backend:
MaestroSimulator — Qoro's simulator on your laptop. Great for small circuits and debugging.QoroService — Qoro's cloud (needs your key). Same code; partitioned problems run their sub-circuits in parallel.MonteCarloOptimizer. Each iteration
evaluates a whole population of MC_POPULATION = 50 parameter sets, that is 50 circuits sent to the
backend as one batch, then samples the next population around the best sets so far. Ten
iterations cost 500 circuits but only ten round trips to the cloud. A sequential optimiser such as
COBYLA sends one circuit per step and waits for each result, which is slow on a remote backend.
Raise MC_POPULATION or MC_ITERATIONS for harder problems; credits scale with the circuit count.dimod's add_linear_equality_constraint does the expansion for you.characterize_and_validate compares QAOA against a classical baseline on your problem and returns
a report:
| Part of the report | What it tells you |
|---|---|
summary, recommendations | One sentence on whether and how to run QAOA, and the advice behind it |
structure, fixed_values | Variables that can be fixed exactly, independent parts, how well the QUBO splits into partitions |
classical | The classical baseline's best solution, a lower bound, and the exact optimum when known |
qaoa, recommended_layers, gap_closed | QAOA's quality per layer count, and how many layers to use |
angles, qaoa_initial_params() | Optimised angles: warm-start QAOA and skip most of the optimiser loop |
references | Validation: the energy of each reference state you sent and, when computed, its probability under QAOA |
penalty, recommended_lambda | Penalty-weight guidance, when the problem has a penalty or constraints (notebook 01) |
CharacterizationOptions sets the QAOA ansatz you plan to run (layers, mixer).
Credits scale with the QUBO size, and the call below can take several minutes while the service analyses your QUBO. A finished report can be re-fetched for free with
get_characterization_result(job_id, service=service).characterize_and_validate compares QAOA against a classical baseline on your problem and returns
a report:
| Part of the report | What it tells you |
|---|---|
summary, recommendations | One sentence on whether and how to run QAOA, and the advice behind it |
structure, fixed_values | Variables that can be fixed exactly, independent parts, how well the QUBO splits into partitions |
classical | The classical baseline's best solution, a lower bound, and the exact optimum when known |
qaoa, recommended_layers, gap_closed | QAOA's quality per layer count, and how many layers to use |
angles, qaoa_initial_params() | Optimised angles: warm-start QAOA and skip most of the optimiser loop |
references | Validation: the energy of each reference state you sent and, when computed, its probability under QAOA |
penalty, recommended_lambda | Penalty-weight guidance, when the problem has a penalty or constraints (notebook 01) |
CharacterizationOptions sets the QAOA ansatz you plan to run (layers, mixer).
Credits scale with the QUBO size, and the call below can take several minutes while the service analyses your QUBO. A finished report can be re-fetched for free with
get_characterization_result(job_id, service=service).characterize_and_validate compares QAOA against a classical baseline on your problem and returns
a report:
| Part of the report | What it tells you |
|---|---|
summary, recommendations | One sentence on whether and how to run QAOA, and the advice behind it |
structure, fixed_values | Variables that can be fixed exactly, independent parts, how well the QUBO splits into partitions |
classical | The classical baseline's best solution, a lower bound, and the exact optimum when known |
qaoa, recommended_layers, gap_closed | QAOA's quality per layer count, and how many layers to use |
angles, qaoa_initial_params() | Optimised angles: warm-start QAOA and skip most of the optimiser loop |
references | Validation: the energy of each reference state you sent and, when computed, its probability under QAOA |
penalty, recommended_lambda | Penalty-weight guidance, when the problem has a penalty or constraints (notebook 01) |
CharacterizationOptions sets the QAOA ansatz you plan to run (layers, mixer).
Credits scale with the QUBO size, and the call below can take several minutes while the service analyses your QUBO. A finished report can be re-fetched for free with
get_characterization_result(job_id, service=service).qaoa.solution is only the
single most likely bitstring.
We run QAOA twice:
encoding=) and what the optimiser minimises (objective=):
| Encoding | Qubits for N variables |
|---|---|
DenseEncoding() | |
PolyEncoding() | about (each variable is a 1- or 2-qubit parity) |
MultiBasisEncoding(order=k) | qubits hold variables (X, Y and Z correlators) |
| Objective | What it does |
|---|---|
SoftObjective(alpha=…) | Smooth relaxation; larger alpha pushes variables towards 0/1 |
CVaRObjective(fraction=…) | Mean energy of the best sampled bitstrings; needs make_backend(force_sampling=True) |
ProgressivePCE raises alpha step by step until every variable is binary. Rank PCE's output by
energy (sort_by="energy"), not by probability.PartitioningProgramEnsemble is Divi's divide-and-conquer workflow:
CommunityDecomposer finds communities in the QUBO's
interaction graph, capped at max_n_variables_per_cluster. Any D-Wave hybrid decomposer, such as
hybrid.EnergyImpactDecomposer(size=…), also works.local_search=True runs a greedy single-bit-flip descent on the full QUBO.ensemble.aggregate_results(...) returns (solution, energy), where solution follows
bqm.variables order. ensemble.get_top_solutions(n, strategy=...) returns several stitched
candidates — handy for post-processing.
You now have the full toolchain. Time for real benchmark problems: see the roadmap below.| Notebook | Problem | How far it scales | Where partitioning comes in |
|---|---|---|---|
01_portfolio_optimisation.py | QOBLIB 06: multi-period portfolio optimisation | 3 to 400 assets, 2 to 15 days: 58 to about 36 000 binary variables. No published results above 50 assets | Partitioned QAOA on the full QUBO; PCE for whole QUBOs on few qubits |
02_network_design.py | QOBLIB 08: network design | network05 to network24: 20 to 552 binary variables. Proven optima up to network10 | The topology QUBO is partitioned; an exact LP scores each topology |
qoblib_tools.py, and Divi finds your key in the .env file (section 0.1) by itself.
Instance data is downloaded from QOBLIB's GitHub repository on first use and cached in qoblib_data/,
next to qoblib_tools.py. The .sol files you write land next to the notebook.