xqsa 0.2.0

Solver adapters for XQMX models (dwave-neal today; pluggable backend interface).

xqsa — Solver adapters for XQMX models

Pluggable solver backends for quadratic optimisation models produced by the XQuad toolchain. Today's implementation wraps DWave's simulated annealer (dwave-neal); future backends (D-Wave QPU, other annealers, gradient-based solvers) plug into the same Backend protocol.

Install

pip install xqsa

Quick start

from xqsa import NealBackend
from xqvm_py import XQMX, XQMXDomain

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

backend = NealBackend()
result = backend.solve(model)
# result.sample: XQMX    — the best assignment found
# result.energy: float   — model energy of that sample
# result.timing: float   — wall-clock seconds spent solving
# result.metadata: dict  — backend-specific extras (e.g. run counts)

Backend protocol

Any class conforming to xqsa.Backend can drop in:

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

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

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.