Skip to content

Quickstart

git clone https://github.com/Yuma-Ichikawa/QQA4CO.git
cd QQA4CO
uv sync --extra plotly --extra gui --extra dev

The first sync takes a couple of minutes (PyTorch wheel). Subsequent runs reuse the resolved lockfile.

With pip

pip install qqa                          # core (CPU torch + numpy/networkx)
pip install "qqa[plotly]"                # + interactive Plotly figures
pip install "qqa[gui]"                   # + Streamlit dashboard
pip install "qqa[all]"                   # everything (docs, dev, notebook, gui, plotly)

Quote the extras list — bare brackets are a glob pattern in zsh and Bash with noglob disabled.

Solve a first problem

import networkx as nx
import qqa

qqa.fix_seed(0)
g = nx.random_regular_graph(d=3, n=100, seed=0)
problem = qqa.MaximumIndependentSet(g, penalty=2)
result = qqa.solve(problem, profile="balanced", device="auto")
print(f"MIS size: {-int(result.best_obj)}  in {result.runtime:.2f}s")

qqa.solve(...) is the stable entry point. qqa.anneal(...) remains available when direct control of the QQA loop is useful.

Inspect the route before spending a budget:

print(qqa.inspect(problem).to_dict())
print(qqa.plan(problem, profile="quality", device="auto").to_dict())

Solve a public MPS/QPLIB file with the same API:

result = qqa.solve("instance.mps", profile="balanced", budget=60)
# Explicit opt-in certification; install the selected backend extra first.
certified = qqa.solve("instance.mps", profile="certify", budget=60)

Run the CLI

qqa version
qqa inspect model.mps
qqa plan model.mps --profile balanced
qqa solve model.mps --profile balanced --budget 60
qqa solve --problem sk --size 100 --sol-size 128 --epochs 1000
qqa benchmark fetch miplib --output data/public-benchmarks/miplib
qqa benchmark fetch qplib --output data/public-benchmarks/qplib

Launch the GUI

qqa gui

Browse example notebooks

  • examples/01_maximum_independent_set.ipynb
  • examples/04_edwards_anderson_3d.ipynb
  • examples/06_binary_perceptron.ipynb
  • examples/13_typed_primal_dual_runtime.ipynb — Model Doctor, goal/budget solve, cockpit, checkpoint/resume, and verified result package
  • examples/14_factor_split_qqa_study.ipynb — factor-split execution, guarantees, QQA Study/Trial campaigns, and Benchmark Hub statistics
  • examples/15_pqqa_sa_pa.ipynb — PQQA, simulated annealing, and population annealing comparison
  • examples/16_cra_pignn.ipynb — CRA-PI-GNN walkthrough across every supported graph problem
  • examples/17_cpra_pignn.ipynb — CPRA penalty / variation diversification
  • examples/18_solver_benchmark.ipynb — matched-instance QQA, SA, CRA-PI-GNN, and CPRA comparison

Run any of them with uv run jupyter lab.

Where to go next