XQuad: A Hardware-Agnostic Toolchain for Quadratic Optimization

Quadratic Optimization Problems and Where XQuad Fits

A quadratic unconstrained binary optimization (QUBO) problem takes a set of binary variables and a matrix of coefficients, then finds the assignment that minimizes the quadratic objective. Ising models are structurally equivalent, using spin variables of plus one or minus one instead of zero and one. These formulations appear in combinatorial problems including travelling salesman, graph coloring, knapsack, bin packing, and portfolio optimization. The examples/ directory in the XQuad repository has runnable driver scripts for all of these.

The difficulty is that solvers for QUBO and Ising models do not share a common input format. CPU simulated annealing, GPU-accelerated parallel annealing, D-Wave quantum annealers, and network solvers each require their own problem representation and API. Writing a separate adapter for each backend means maintaining parallel implementations of the same model and rebuilding each one when the problem formulation changes.

XQuad addresses this by acting as a hardware-neutral intermediate layer. You write the problem once in the .xqasm text format or via the xqcp constraint-programming DSL, compile to XQuad bytecode (.xqb), and then dispatch to any supported backend through the xqsa solver adapter layer. The README describes this as "LLVM for quadratic models." Like LLVM, XQuad does not solve the optimization problem itself; it provides a format and a runtime that retargets to hardware. The specification is in spec/xqvm/SPEC.md, and the conformance test vectors live in conformance/.

The Stack VM: Architecture, Register File, and Binary Format

The XQuad Virtual Machine (xqvm) is stack-based with a 256-slot register file. Registers hold typed values: plain integers, integer vectors, QUBO or Ising models stored as the XqmxModel type, and candidate solutions stored as XqmxSample. A separate loop stack drives the RANGE and ITER iteration opcodes, keeping iteration state out of the main register file.

The compiled binary format is .xqb. Each file opens with a 15-byte XQBC header containing magic bytes, a version field, calldata and output-slot counts, code length, and a CRC-32 checksum of the payload. Instructions follow as an opcode byte plus big-endian operands.

The opcode table is declared once in xqvm/src/bytecode/types/table.rs using the opcodes! macro. The machine-readable mirror, conformance/opcodes.yaml, is what the Python reference VM and the CI conformance tests verify against. Any time the Rust macro and the YAML disagree, the build fails. Full instruction semantics are in conformance/opcodes.md; the normative spec is in spec/xqvm/SPEC.md.

The Rust crates that make up the VM layer are xqvm (the interpreter and bytecode codec, no_std plus alloc), xqasm (the .xqasm text-format assembler), and xqcli (the unified CLI binary named xquad). These three crates are published to crates.io. A fourth Rust crate, xqffi, ships as the xqffi PyPI wheel via PyO3 bindings rather than as a reusable Rust library.

Installing XQuad and Running a First Program

The Rust CLI installs via Cargo:

cargo install xqcli

This gives you the xquad binary with subcommands: asm (assemble .xqasm to .xqb), dism (disassemble), run, and verify. For the Python umbrella:

pip install xquad

Prebuilt wheels cover Linux x86_64 and aarch64 with CPython 3.13 or later. On macOS and Windows, pip builds the xqffi Rust extension from source, requiring a Rust toolchain at version 1.85 or newer.

A minimal CLI example assembles and runs a two-integer addition:

; add.xqasm -- push two integers and add them
PUSH 10
PUSH 32
ADD
HALT

xquad asm add.xqasm -o add.xqb && xquad run add.xqb

The assembler writes the XQBC header plus the encoded instruction stream to add.xqb. The run subcommand loads the bytecode, initializes the VM, and prints the outputs. The verify subcommand checks that a bytecode file conforms to the XQBC format and the opcode table without executing it.

For full end-to-end examples that go from the xqcp DSL through the VM to a solver, the examples/ directory contains drivers for TSP, max-cut, and other problems:

uv run --no-sync python examples/tsp/runner.py --seed 42
uv run --no-sync python examples/maxcut/runner.py --seed 42 --interpreter rust

The make example-smoke target runs every example on both the Rust and Python interpreters and verifies that each finds a valid solution.

The Python Session API: Program, Session, and RunResult

The recommended user-facing surface in Python is the xquad.program module. A Program object wraps bytecode and exposes a session factory. The same compiled program can execute many times with different calldata, which is useful when running the same model against multiple parameter sets:

from xquad.program import Program

program = Program.from_source("""
PUSH 0
INPUT r0
PUSH 1
INPUT r1
LOAD r0
LOAD r1
ADD
STOW r2
PUSH 0
OUTPUT r2
HALT
""")

session = program.session(output_slots=1)
session.set_calldata([40, 2])
result = session.run()
assert dict(result.outputs) == {0: 42}

RunResult carries dict-keyed outputs (unset slots appear as None), the residual stack after execution, and a step count. Program.load(bytes) accepts precompiled wire-format bytecode directly, which is useful when the .xqb file was produced by xquad asm.

For conformance testing or one-shot execution, the lower-level xqffi.vm.Vm is also available. It accepts bytecode directly and returns outputs as a list. A middle tier, xquad.vm.VM, wraps both the Rust and Python backends and normalizes types across them, controlled by the VMBackend enum (VMBackend.RUST or VMBackend.PYTHON).

The five Python packages form a layered stack. xqffi provides the raw PyO3 bindings. xqvm_py is the pure-Python reference VM used for conformance. xqcp is the constraint-programming DSL that compiles problem definitions to .xqasm source. xqsa provides the solver adapters. xquad is the umbrella package that exposes the Program and Session API. All five live as members of the uv workspace declared in the root pyproject.toml.

GPU and QPU Solver Backends

The base pip install xquad includes only CPU simulated annealing. For hardware-accelerated or quantum backends, install the matching extra:

pip install xquad[cuda]
pip install xquad[metal]
pip install xquad[dwave]
pip install xquad[quip]

The cuda extra requires a CUDA 12.x driver and an NVIDIA GPU. The metal extra requires an Apple Silicon Mac with a Metal device. The dwave extra requires a D-Wave Leap account and an API token. The quip extra requires a QUIP_RPC_URL and a configured signer. Each set of prerequisites is documented in xqsa/README.md.

Extras are composable:

pip install xquad[cuda,dwave]

This installs both the CUDA and D-Wave adapters in one step. The Rust core (xqvm) supports no_std plus alloc, so the same VM bytecode runs inside WASM runtimes and Substrate pallets as well as native binaries. The fixtures/xqvm-wasm directory contains a WASM build fixture; the fixtures/pallet-xqvm directory is a standalone Substrate pallet workspace excluded from the main Cargo build to avoid inflating compile times.

Conformance Parity Between Rust and Python VMs

XQuad ships two independent VM implementations: the Rust production VM (xqvm) and the Python reference VM (xqvm_py). Both execute the same conformance vectors on every commit in CI. Any behavioral disagreement between the two interpreters fails the build immediately.

This design carries a real cost: every opcode must be implemented twice and kept in sync across three representations, the Rust macro, the YAML file, and the Python module. The benefit is that xqvm_py acts as a readable specification that can be checked against SPEC.md without a Rust compiler. Engineers writing conformance test cases can use the Python reference VM alone without installing any Rust tooling.

The scripts/check-opcode-parity.py script verifies that the opcodes declared in the Rust macro, conformance/opcodes.yaml, and the Python VM all agree. This catches the class of bugs where an opcode is added in one representation but not the others. The metering-parity Makefile target checks that the Rust and Python VMs agree on step counts as well as outputs, which matters for programs that need to reason about computational cost.

Limitations, AGPL-3.0 License, and Pre-Production Status

The README opens with an explicit early-release warning: the instruction set, binary format, and public API may still change before v1.0, and production use is not recommended. There are no GitHub releases and no stable version tag to pin against. The Python packages require CPython 3.13 or later. On macOS and Windows the Rust 1.85 toolchain requirement adds a build step that is non-trivial for teams that do not normally work in Rust.

The project is licensed under AGPL-3.0-or-later. For a library used inside a networked service, AGPL means any modifications you distribute over a network must also be released under AGPL. Teams that need to embed or modify XQuad without open-sourcing their modifications must obtain a separate license. The NOTICE and LICENSE files are at the repository root.

The natural alternative for teams that need a stable SDK today is D-Wave's Ocean SDK. Ocean is a Python library designed specifically for D-Wave hardware and its hybrid solver stack, and it is a mature and stable choice for workloads that run exclusively on D-Wave QPUs. XQuad's difference is hardware neutrality: one problem expressed in .xqasm or xqcp runs on CPU, GPU, D-Wave, or the Quip Network without changing the model definition. That neutrality is only useful if you need to target more than one backend, or if you want to retarget problems between solver technologies over time without rewriting them.

Editorial conclusion

XQuad fits researchers and engineers who need to express a quadratic optimization problem once and run it on multiple hardware backends without rewriting the model for each solver. Teams that need a stable, production-ready library should wait for v1.0; the README is explicit that the instruction set, binary format, and public API may still change before that point. Before adopting, read spec/xqvm/SPEC.md for the current opcode table and check xqsa/README.md for the specific driver prerequisites of each GPU and QPU backend.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. QuipNetwork/xquad on GitHub
4. README