XQuad keeps its opcode table in two checked copies and its real home is on GitLab

The canonical repository is a GitLab URL, not this one

The workspace manifest names its own repository as a GitLab address under the project's own namespace, and the tree backs that up: a GitLab CI file and a GitLab directory sit at the root. The repository record here has no homepage at all, and tagged releases do appear on this host, the latest being v0.5.0 on 2026-10-30, alongside a release guide, a changelog configuration and a set of version-check targets in the tree. The two crates that get published carry development versions of 0.5.1-dev, and the manifest explains that the version string is required for publishing while the path keeps the workspace build pointing at live sources, with cargo rewriting the spec on publish.

One opcode table, three representations, checked mechanically

The instruction set is defined once in the Rust crate, inside a file under the bytecode types module, using a declarative macro that expands the table. A machine-readable mirror of the same table lives at xqvm/opcodes.yaml, and it is compared with the Rust macro at compile time (xqvm/src/bytecode/types/parity.rs), so the two cannot drift.

Conformance runs every vector on two VMs and fails the build on disagreement

The parity mechanism is described as the enforcement arm of a spec-first approach, where behaviour is nailed down in a specification file under the spec directory. Every committed conformance vector runs xqvm in continuous integration against the outcome the spec prescribes, and a mismatch fails the build.

Wheels exist for Linux only, and the rest builds Rust at install time

The install section splits by platform and the split is sharp. Prebuilt wheels cover Linux on x86_64 and aarch64, for CPython 3.13 and newer. On macOS and Windows, pip builds the extension module from source, which means a Rust toolchain of 1.85 or newer has to be present before the install can finish.

pip install xquad
pip install xqffi xqcp xqsa

Hardware solvers are all extras rather than part of the base install, which ships CPU simulated annealing only: one extra for NVIDIA CUDA GPUs needing a CUDA 12.x driver and a GPU, one for Apple Metal on an Apple Silicon Mac, one for a D-Wave Advantage QPU needing a Leap account and an API token, and one for the project's own network solver needing a URL setting and a configured signer. The extras compose, so a CUDA and QPU combination is a single install line.

Three API tiers sit over the same VM

There are three ways in, and they are aimed at different users. The lowest is the raw VM object from the FFI package, driven by an assembler function and explicit calls to set calldata, set output slots and run, which is what a conformance harness uses. The middle is a wrapper class around the Rust VM that accepts source text, keeps calldata, output slots and limits across runs, and hands back the FFI types unchanged. The recommended surface for people is a program object with a session and a run result: load a program once, run it many times with different calldata, and read outputs by slot.

from xquad.program import Program
session = program.session(output_slots=1)
session.set_calldata([40, 2])
result = session.run()

The run result is worth reading closely, because it carries dict-keyed outputs where a slot that was never set shows up as None rather than being absent, plus the residual stack and a step count. A program can also be loaded from raw wire-format bytes instead of source, which is the path for anything produced elsewhere.

A fifteen-byte header guards a big-endian instruction stream

The binary format is described precisely enough to write a parser against. It opens with a fixed fifteen-byte header, tagged with its own magic, carrying a version, the calldata and output slot counts, the code length, and a CRC-32 checksum of the payload. After that comes the instruction stream, one opcode byte per instruction followed by its operands. The machine itself is stack-based with a 256-slot register file, and the registers are typed: integers, integer vectors, quadratic and Ising models, and candidate solutions. A dedicated loop stack drives the RANGE and ITER iteration instructions. Bytecode files carry the extension used in the quick start, and the assembler plus runner are both subcommands of one binary.

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

The Makefile's phase targets have no recipes, on purpose

The build file is enormous, with a phony list running to several dozen target names, and its design note explains the shape: the phase aggregates are plain prerequisite lists with no recipes of their own, each one meant to map one to one onto a future continuous integration job, and CI always invokes them with keep-going so that every prerequisite runs. The top-level target is format, lint and test. What the lint configuration denies is more revealing than the targets themselves: unsafe code is denied outright, as are unwrap calls, panics inside functions that return a result, todo and unimplemented markers, and allow attributes without a written reason, while clippy pedantic warnings sit at the base level. A project that describes itself as an early public release has therefore ruled out the two markers most used to mark unfinished work. The tree also carries a prose linter configuration and a formatter configuration for TOML files, so documentation prose is checked like code.

Fifteen example problems, and an interpreter flag on every runner

The examples directory covers fifteen combinatorial families, from the travelling salesman problem and maximum cut through knapsack, graph colouring, set cover, vertex cover, three-satisfiability, independent set, bin packing, number partitioning and two portfolio problems, plus cubic and quartic variants that go beyond quadratic terms. The README runs the tsp and maxcut runners with a --seed argument.

uv run python examples/tsp/runner.py --seed 42
make example-smoke

A smoke target, make example-smoke, runs every example and checks that each finds a valid solution.

Editorial conclusion

XQuad is worth a look if your quadratic problems have to move between solvers, since the value is in the shared bytecode rather than in any one annealer, and the spec-conformance story is a real answer to the usual objection about abstract layers. Set expectations on two points. The README calls it an early public release and says production use is not recommended, with the instruction set, binary format and API all still allowed to change. Tagged releases do exist on this host, the latest being v0.5.0, but the workspace manifest is on development versions and the canonical repository lives elsewhere, so record the exact versions you install if you need reproducibility.

Frequently asked questions

Official sources

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