quipnetwork / xq-rs

Rust (from crates.io)

cargo install xqcli           # gives you the `xquad` binary

Python (from PyPI)

pip install xquad             # umbrella -- full pipeline
# or pick individual pieces:
pip install xqffi xqcp xqsa   # FFI bindings + DSL + solvers

Prebuilt wheels are available for Linux x86_64 and aarch64 (CPython >= 3.13). On macOS and Windows, pip builds the xqffi Rust extension from source -- this requires a Rust toolchain (>= 1.85).

GPU/QPU support

The base install includes CPU simulated annealing only. To use GPU or quantum hardware solvers, install the corresponding extra:

| Solver | Install | Prerequisite | |--------|---------|-------------| | NVIDIA CUDA GPU (cuda-gpu) | pip install xquad[cuda] | CUDA 12.x driver + NVIDIA GPU | | Apple Metal GPU (metal-gpu) | pip install xquad[metal] | Apple Silicon Mac with a Metal device | | D-Wave Advantage QPU (dwave-qpu) | pip install xquad[dwave] | D-Wave Leap account + API token | | Quip Network solver (quip) | pip install xquad[quip] | QUIP_RPC_URL + a configured signer |

Extras are composable: pip install xquad[cuda,dwave]. See xqsa/README.md for driver prerequisites and per-solver quick-starts.

For a guided walkthrough that installs XQuad, verifies it, and runs a complete problem end to end, see Install XQuad in the book.

All checks must pass before a merge request is accepted. make preflight runs the full local mirror of what CI enforces, grouped by phase so a single-language MR can run just its half:

make preflight          # everything below, in one shot
make preflight-rs       # fmt, taplo, clippy, rustdoc, deny (root + pallet fixture), unit/integration/doc tests
make preflight-py       # taplo, ruff format + lint, pytest, uv.lock freshness
make preflight-parity   # opcode parity, conformance, example smoke
make preflight-docs     # generated-doc freshness, docs drift, README length, prose (needs vale)
make preflight-policy   # changelog render, release-notes scoping, atomic spec-MR and commit-message guards

make preflight-release (crate packaging dry-run plus the five Python distributions) needs maturin, twine, and uv on PATH, so it is kept out of plain make preflight; see RELEASING.md.

make all (fmt + lint + test) is a convenience for reformatting the tree and running everything locally, but it is not what CI runs -- CI invokes the preflight-* targets above, one per pipeline phase. Match those before pushing.

Miri is not part of preflight-rs; run it separately with make test-miri before submitting changes that touch unsafe code, dependencies, or procedural macros -- see Undefined Behaviour below.

For the individual leaf targets behind each preflight-* aggregate (fmt-rs, lint-clippy, test-unit-rs, and so on), see the Quick-Reference Commands in AGENTS.md rather than a second list here that can drift from it.