xqsa -- Solver adapters for XQMX models

Pluggable solvers for quadratic optimisation models produced by the XQuad toolchain. One interface, five backends:

Install

pip install xqsa               # CPU simulated annealing only
pip install xqsa[dwave]        # add D-Wave QPU support
pip install xqsa[cuda]         # add CUDA GPU support
pip install xqsa[metal]        # add Metal GPU support
pip install xqsa[quip]         # add Quip network support

Extras are composable: pip install "xqsa[cuda,dwave]".

A complete example

build_solver picks a backend by name, so a caller can stay backend-agnostic across all five:

from xqsa import SOLVERS, build_solver
from xqvm_py import XQMX

model = XQMX.binary_model(size=4)
model.set_linear(0, -1)
model.set_quadratic(0, 1, 2)

print(sorted(SOLVERS))
# ['cuda-gpu', 'dwave-cpu', 'dwave-qpu', 'metal-gpu', 'quip']

solver = build_solver("dwave-cpu", seed=42)
result = solver.solve(model)
print(result.sample)
print(result.energy)
# XQMX(mode=SAMPLE, domain=BINARY, size=4, linear_terms=1, quadratic_terms=0)
# -1

Every backend's solve() returns the same SolverResult(sample, energy, timing, metadata): sample is the best assignment found, energy is the Hamiltonian recomputed independently in exact integer arithmetic (never taken on faith from the backend), and metadata's shape is per-backend. build_solver("dwave-cpu", ...) is equivalent to constructing SolverDWaveCPU(...) directly; reach for the class constructor instead of build_solver when the backend is fixed at write time rather than chosen by name at run time.

SolverQuip also splits a job into steps: create_order(model) returns a draft JobOrder whose options (payout rule, allowlist, quality floors) are checked before anything is signed, quote() prices it and submit() sends it. A submitted order leaves a JobOrderReceipt, which any session rebuilds from the order id with get_receipt(). Import them from xqsa.quip.

Reference

Driver prerequisites, per-backend parameters, embedding on a D-Wave QPU, the Quip network job lifecycle and its job orders, and what the reported energy means on fixed-precision hardware are covered in Solving Overview and its chapters. The normative reference is spec/xqsa/SPEC.md; this package follows it, and any divergence here is a bug.

Also see

• xqvm_py -- pure-Python reference VM.
• xqffi -- pyo3 FFI bindings to the Rust runtime.
• xqcp -- constraint-programming DSL that compiles to models this package can sample.
• xquad -- umbrella meta-package.
• Running Programs -- end-to-end tour.

License

AGPL-3.0-or-later.