xqsa 0.3.0rc1

Solver adapters for XQMX models (dwave-samplers; pluggable solver interface).

xqsa -- Solver adapters for XQMX models

Pluggable solvers for quadratic optimisation models produced by the XQuad toolchain.

Solver	Class	Transport	Install
DWave CPU simulated annealing	SolverDWaveCPU	local	pip install xqsa
D-Wave Advantage QPU	SolverDWaveQPU	D-Wave Leap cloud	pip install xqsa[dwave]
CUDA GPU simulated annealing	SolverCudaGPU	local (NVIDIA GPU)	pip install xqsa[cuda]
Metal GPU SA / Gibbs	SolverMetalGPU	local (Apple GPU, macOS)	pip install xqsa[metal]

Install

# CPU simulated annealing only
pip install xqsa

# Add D-Wave QPU support
pip install xqsa[dwave]

# Add CUDA GPU support (requires NVIDIA GPU + CUDA driver)
pip install xqsa[cuda]

# Add Metal GPU support (requires macOS + Apple Silicon GPU)
pip install xqsa[metal]

Quick start -- CPU simulated annealing

from xqsa import SolverDWaveCPU
from xqvm_py import XQMX, XQMXDomain

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

solver = SolverDWaveCPU()
result = solver.solve(model)
# result.sample: XQMX   -- the best assignment found
# result.energy: int     -- authoritative Hamiltonian energy
# result.timing: float   -- wall-clock seconds spent solving
# result.metadata: dict  -- seed, reads, solver-specific params

Quick start -- D-Wave Advantage QPU

Requires a D-Wave Leap account and pip install xqsa[dwave].

import os
os.environ["DWAVE_API_TOKEN"] = "your-leap-token"  # or pass token= directly

from xqsa import SolverDWaveQPU
from xqvm_py.xqmx import XQMX

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

solver = SolverDWaveQPU()              # auto-selects best Advantage system
result = solver.solve(model)
print(result.metadata["solver"])       # e.g. "Advantage_system5.4"
print(result.metadata["qpu_timing"])   # QPU timing breakdown from Leap

Credential resolution order: token= constructor argument -> DWAVE_API_TOKEN env var -> ValueError.

For a specific solver: SolverDWaveQPU(solver="Advantage_system5.4"). For custom annealing: solver.solve(model, annealing_time=100, chain_strength=2.0).

Quick start -- CUDA GPU simulated annealing

Requires an NVIDIA GPU with CUDA support and pip install xqsa[cuda].

from xqsa import SolverCudaGPU
from xqvm_py.xqmx import XQMX

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

solver = SolverCudaGPU()                # uses all defaults
result = solver.solve(model)
print(result.energy, result.timing)

# Custom parameters
solver = SolverCudaGPU(num_reads=200, num_sweeps=2000, seed=42)
result = solver.solve(model, beta_range=(0.1, 5.0))

Algorithm selection via the strategy parameter (currently only "sa" is supported; "gibbs" and "metropolis" are planned).

Quick start -- Metal GPU (Apple Silicon)

Requires macOS with an Apple Metal GPU and pip install xqsa[metal].

from xqsa import SolverMetalGPU
from xqvm_py.xqmx import XQMX

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

# Simulated annealing (default), or strategy="gibbs" for block Gibbs sampling.
solver = SolverMetalGPU(strategy="sa", num_reads=200, num_sweeps=2000, seed=42)
result = solver.solve(model)
print(result.energy, result.timing)

The strategy parameter selects "sa" (simulated annealing) or "gibbs" (block Gibbs sampling over a greedy graph colouring). beta_schedule_type selects "geometric" (default) or "linear". Coefficients are computed in float32 on the GPU; result.energy is recomputed authoritatively in integer arithmetic.

Solver protocol

Any class conforming to xqsa.Solver can drop in:

class Solver(ABC):
    @abstractmethod
    def solve(self, model: XQMX, **kwargs: Any) -> SolverResult: ...

SolverResult is a frozen dataclass of (sample: XQMX, energy: int, timing: float, metadata: dict). Solvers return the best solution found for the model.

Specification

Authoritative specification: ../spec/xqsa/SPEC.md. The spec is the source of truth; any divergence in this reference implementation 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.
• docs/python-api-walkthrough.md -- end-to-end tour.

License

AGPL-3.0-or-later.