Skip to content

feat: add QAOA max-cut solver endpoint - #26

Merged
wrigjl merged 2 commits into
mainfrom
feature/maxcut-quantum
Nov 17, 2026
Merged

wrigjl merged 2 commits into
mainfrom
feature/maxcut-quantum

Conversation

@wrigjl

@wrigjl wrigjl commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds POST /maxcut-quantum, which solves weighted Max-Cut with QAOA on the statevector simulator. The code is based on the CS6680 QAOA notebook.

Request

{"nodes": ["1", "2", "3"], "edges": [["1", "2", 4], ["2", "3", 2], ["1", "3", 3]]}

Each edge is [u, v, weight], or [u, v] for weight 1. Parallel edges are summed, self-loops are ignored, and graphs are limited to 16 nodes.

Response: answer is the S side in Redux's MAXCUT certificate format (e.g. "{1,3}"), plus cut_weight, answer_bitstring and qasm. Invalid input returns {"error": ...} with no answer, so Redux's QuantumServerAPI.Ask reports the solver as unavailable instead of passing error text along as a certificate.

Implementation notes

  • Hamiltonian: built directly as Σ (w/2)·ZᵢZⱼ. It matches the qiskit_addon_opt_mapper Maxcut + to_ising output up to the constant offset, so that package and qiskit_ibm_runtime aren't needed. The only new dependency is scipy (already present through qiskit), now pinned explicitly because it's imported directly.
  • Weight scaling: weights are scaled so the largest |w| is 1. This doesn't change the optimal cut, and it keeps γ's useful range near [0, 2π] whatever the weights' magnitude.
  • Transpiling once: the ansatz is transpiled to basis gates once, before COBYLA. Without that, every optimizer step simulates the PauliEvolutionGates with a sparse matrix exponential (5 nodes took minutes; it now takes about 0.1 s).
  • Answer selection: the endpoint returns the sampled bitstring with the best cut, not the most frequent one, and skips splits where S or T would be empty.
  • Ansatz: uses qaoa_ansatz, because the QAOAAnsatz class is deprecated as of Qiskit 2.1.

Testing

  • tests/test_maxcut.py checks answers against brute force (Redux's default instance and the notebook's graph), weight scaling, parallel edges and self-loops, graphs with no edges, and invalid input.
  • An integration test for the endpoint is added to integration/test_api.py.
  • Locally, ruff and black pass, and all 77 tests pass on Python 3.12 and 3.13 with 88% coverage. The integration suite was not run locally.

Timing on random graphs (16 nodes is the limit):

Nodes Time Cut found Best possible
8 0.27 s 43 43
12 0.57 s 98 98
14 0.72 s 208 208
16 2.73 s 208 212

QAOA is approximate, so the 16-node shortfall is expected.

Follow-up

Redux still needs a MAXCUT solver class that posts to this endpoint (same pattern as SATGroverSolver).

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Redux Build System — CI Report

uv · commit 974b2bd

Operation Status Summary Time
audit ✅ no known vulnerabilities 5.7s
format-check ✅ all files formatted 0.4s
lint ✅ 0 issues 0.0s
typecheck ⏭️ not implemented —
unit-test · 3.12 ✅ 84 passed · coverage 87% 57.6s
unit-test · 3.13 ✅ 84 passed · coverage 88% 61.1s
build ✅ built local/quantumsolver:ci · 582MB 13.6s
integration-test ✅ /health ready · 7 passed 9.4s
push ⏭️ only on push to main —

Overall: ✅ 7 passed · 0 failed · 2 skipped

Add POST /maxcut-quantum, which solves weighted Max-Cut with QAOA on
the statevector simulator. Input is {"nodes": [...], "edges": [[u, v,
w], ...]}; the answer is the S side in Redux's MAXCUT certificate
format, alongside cut_weight, answer_bitstring, and the circuit qasm.

The cost Hamiltonian is built directly as sum (w/2) Z_i Z_j with
weights normalized to max |w| = 1, and the ansatz is transpiled to
basis gates once before COBYLA so each step avoids a sparse matrix
exponential. The best-cut sample (excluding empty S or T) is returned.
Invalid input yields {"error": ...} with no answer so Redux reports the
solver as unavailable rather than passing on error text. Graphs are
limited to 16 nodes to stay within the router's timeout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Trosper3
Trosper3 force-pushed the feature/maxcut-quantum branch from 3346a4b to 5091751 Compare November 17, 2026 17:07
@Trosper3

Copy link
Copy Markdown

Rebased onto main now that #27 and #28 are in. Git merged the uv.lock changes without conflicts, and uv lock (uv 0.13.9, the version the image pins) makes no further changes, so the only lock change is still the scipy entry. Locally: 77 unit tests pass, pip-audit reports no known vulnerabilities, ruff and black are clean. Your original commit was 3346a4b if you need it.

@Trosper3

Copy link
Copy Markdown

I am taking care of the Dependabot stuff and I will come review this after.

@Trosper3 Trosper3 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, approving. Bad input always comes back as {"error": ...} with no answer, the cost Hamiltonian and the bit order check out, picking the best sampled cut (not the most frequent) is the right call, and the brute-force comparisons in the tests are a nice touch.

One thing to check after deploying: the 16-node cap is sized to this service's 25 second limit, but Redux stops every compute job at 10 seconds today (ComputeLimits:TimeLimitSeconds). Each request also starts a fresh process that has to import Qiskit and SciPy before solving, and that isn't in the 2.7 s figure. Could you time a 16-node solve end to end through Redux on the server? We're also talking about raising Redux's limit to 30 seconds, which would give this plenty of room.

Optional: seeding the sampler would make the same graph give the same answer every time.

The estimator is exact and COBYLA is deterministic, so the sampler is
the only random step. Seed it with a fixed default (SEED = 6680) so the
same request always gets the same response, accept an optional "seed"
in the request to override it, and echo the seed used back in the
response. Invalid seeds (negative, non-integer, bool) return an error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@wrigjl

wrigjl commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

One thing to check after deploying: the 16-node cap is sized to this service's 25 second limit, but Redux stops every compute job at 10 seconds today.
...
We need to re-examine timeouts in quantum server (e.g. #4), so I'm going to leave this alone for now.

Optional: seeding the sampler would make the same graph give the same answer every time.

I added a fixed seed. Someone calling it directly can change the seed and it gets reported back in the json.

@wrigjl
wrigjl merged commit 8acd9c7 into main Nov 17, 2026
4 checks passed
@wrigjl
wrigjl deleted the feature/maxcut-quantum branch November 17, 2026 19:47
Trosper3 pushed a commit to ReduxISU/Redux that referenced this pull request Nov 17, 2026
MaxCutQAOASolver sends the weighted graph to the quantum service's
/maxcut-quantum endpoint, which runs the Quantum Approximate
Optimization Algorithm, and returns the S side of the cut it finds.
An answer that is not a non-empty proper subset of the nodes is
treated as no answer, so the endpoints report 503 solver_unavailable
rather than passing it on (#625). The timer is checked before the one
blocking call to the service.

Requires ReduxISU/quantumsolver#26 for the /maxcut-quantum endpoint.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants