Skip to content

QQA4CO — Parallel Quasi-Quantum Annealing

QQA4CO is a research-grade PyTorch toolkit for combinatorial and spin-glass optimisation. It frames a discrete problem as a continuous, differentiable objective and anneals towards a discrete minimum using gradient-based parallel sampling on the GPU.

  • Unified API — one qqa.anneal() for binary, categorical, permutation, batched-instance, and spin problems.
  • 17-class problem catalogue — MIS, MaxCut, MaxClique, Vertex Cover, Graph Bisection, Coloring, BalancedGraphPartition, Knapsack, NumberPartitioning, MaxSAT3, TSP, QAP, NQueens, Ising 1D, Edwards-Anderson, Sherrington-Kirkpatrick, BinaryPerceptron, HopfieldMemory.
  • Optional GNN backend (qqa[pignn]) — the CRA-PI-GNN baseline (NeurIPS 2024) and the CPRA diverse-solution framework (TMLR 2025), both ported to PyTorch Geometric so they run on Blackwell-class GPUs.
  • Streamlit dashboard — qqa gui opens a polished UI with live progress, per-problem visualisations, and parallel-population view.
  • qqa CLI — reproducible solves and benchmarks from the shell.

Install

pip install qqa                # core
pip install "qqa[plotly]"      # + interactive plots
pip install "qqa[gui]"         # + Streamlit GUI
pip install "qqa[pignn]"       # + CRA-PI-GNN / CPRA backends
pip install "qqa[all]"         # everything

See Quickstart to run your first solve.

Where to go next

If you want to … Go to
Run your first solve Quickstart
Understand which solver to pick Backend reference
Tune hyper-parameters How-to → Tuning
Run on GPU / Blackwell How-to → GPU
Integrate QQA4CO in a pipeline How-to → Integrate
Browse every problem class Problem catalog
Browse every CLI flag CLI reference
Understand the algorithm Algorithm explainer
Add a new problem / relaxation / backend Develop → Extending QQA4CO
Read the source map Develop → Internals
Cut a release Develop → Releasing

Cite

If you use QQA4CO in your research, please cite the paper(s) that match the backend you used. The full BibTeX is in the README; a one-line summary:

  • qqa.anneal (PQQA) — Y. Ichikawa, "Optimization by Parallel Quasi-Quantum Annealing with Gradient-Based Sampling," arXiv:2409.00184, 2024.
  • qqa.pignn.train_cra_pi_gnn — Y. Ichikawa, "Controlling Continuous Relaxation for Combinatorial Optimization," NeurIPS 2024 (OpenReview).
  • qqa.pignn.train_cpra_pi_gnn — Y. Ichikawa & H. Iwashita, "Continuous Parallel Relaxation for Finding Diverse Solutions in Combinatorial Optimization Problems," TMLR 2025 (OpenReview).