xquad README

The project's README from github.com/QuipNetwork/xquad. As one markdown file: README.md.

XQuad

Early public release. The instruction set, binary format, and public API may still change before v1.0. Production use is not recommended yet.

XQuad is a hardware-agnostic toolchain for expressing and running quadratic optimization problems (QUBO / Ising / discrete) across quantum annealers and classical solvers. It ships as three Rust crates plus five Python distributions built around a single virtual-machine specification.

Think of it as LLVM for quadratic models -- a common intermediate representation that lets you write a problem once and retarget it to any supported backend.

Install

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.

Package map

Three Rust crates on crates.io:

Crate Binary Description
xqvm none X-Quadratic Virtual Machine interpreter, bytecode codec, opcode table (no_std + alloc)
xqasm none .xqasm text-format assembler
xqcli xquad Unified CLI -- xquad asm / dism / run / verify

Five Python distributions on PyPI:

Package Description
xqffi PyO3 FFI bindings for xqvm + xqasm (xqffi.vm, xqffi.asm, xqffi.verifier)
xqvm_py Pure-Python reference VM (conformance oracle)
xqcp Constraint-programming DSL that compiles to .xqasm
xqsa Solver adapters -- CPU/GPU annealers, D-Wave QPU, Quip network
xquad Umbrella meta-package with interactive Program / Session / RunResult API

The one Rust package without a crates.io artefact is the xqffi pyo3 crate itself -- it ships as the xqffi PyPI wheel rather than a reusable Rust library.

Quick start

A minimal program (CLI)

; 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

End-to-end (Python, via the umbrella)

The recommended user-facing surface is xquad.program.Program + Session + RunResult. Load once, run many times with different calldata, inspect outputs by slot:

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}

Program.load(bytes) takes wire-format bytecode; Session.run() returns a RunResult with dict-keyed outputs (unset slots present as None), residual stack, and step count. See Running Programs for the full tour.

Low-level / conformance surface

For conformance harnesses and one-shot execution, the raw xqffi.vm.Vm is still available directly:

from xqffi.asm import assemble_source
from xqffi.vm import Vm

bytecode = assemble_source(src)
v = Vm()
v.set_calldata([40, 2])
v.set_output_slots(1)
v.run(bytecode)
assert v.outputs() == [42]

The xquad.vm.VM class offers a middle tier -- a unified wrapper with backend dispatch (VMBackend.RUST / VMBackend.PYTHON) that accepts .xqasm source and normalises types across the two interpreters.

End-to-end worked example

examples/tsp/ shows a full Travelling Salesman Problem driven from the xqcp DSL through the VM and xqsa solver, runnable on either the Python reference VM or the Rust VM:

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

# Run every example on both interpreters, check each finds a valid solution:
make example-smoke

Architecture

XQuad is a stack-based interpreter with a 256-slot register file. Registers hold typed values -- integers, integer vectors, QUBO/Ising models (XqmxModel), and candidate solutions (XqmxSample). A dedicated loop stack drives RANGE/ITER iteration.

The opcode table is declared once in xqvm/src/bytecode/types/table.rs via the opcodes! x-macro; conformance/opcodes.yaml is the machine-readable mirror that all three representations (YAML, Rust macro, xqvm_py.opcodes) are checked against at build time and in CI (scripts/check-opcode-parity.py).

The binary format (.xqb) opens with a fixed 15-byte XQBC header -- magic, version, calldata/output-slot counts, code length, and a CRC-32 checksum of the payload -- followed by the instruction stream: an opcode byte followed by its operands in big-endian byte order.

See conformance/opcodes.md for instruction-by-instruction semantics and spec/xqvm/SPEC.md for the normative spec.

Development

Prerequisites

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # stable Rust
make deps                                                          # dev tools

Local setup

make xquad

This syncs the Python workspace (xqvm_py, xqcp, xqsa, xqffi, xquad) into .venv/, builds the xqffi pyo3 extension via maturin, puts the repo root on sys.path so scripts anywhere in the repo can import xqcp / xqsa / xqvm_py / xqffi / xquad naturally, and installs the xquad CLI binary under ~/.cargo/bin/.

Open a REPL with everything ready:

make repl

CI-equivalent locally

make preflight    # what CI enforces, split into preflight-rs / -py / -parity / -docs / -policy
make conformance  # cross-impl parity suite (Rust + Python)

Contributing

See CONTRIBUTING.md for the development workflow, commit conventions, and DCO sign-off requirements. Agent guidelines for AI coding assistants are in AGENTS.md; cutting a release is documented in RELEASING.md.

License

Licensed under the GNU Affero General Public License v3.0 or later.

xquad (QuipNetwork/xquad)

Searching Database…

5.6K ·GitHub
Xquad
What is this?XQuad is a hardware-agnostic toolchain for expressing and running quadratic optimization problems (QUBO / Ising / discrete) across quantum annealers and classical solvers, acting as a common intermediate representation you write once and retarget to any supported backend.
Is this a Rust library, a Python package, or a CLI tool?It is all three: three Rust crates (xqvm, xqasm, xqcli) plus five Python distributions (xqffi, xqvmpy, xqcp, xqsa, xquad) built around one VM specification, so you can use it as a Rust crate, a Python library, or via the xquad CLI.
How do I get a problem running on XQuad?Install the Python umbrella with pip install xquad (or the Rust crates from crates.io), then write or compile a .xqasm program and run it through the xquad CLI (asm/dism/run/verify) or the Python Program / Session / RunResult API.
Do I need a Rust toolchain to install the Python package?Only on macOS and Windows: prebuilt wheels exist for Linux x86_64/aarch64 (CPython >=3.13), but elsewhere pip builds the xqffi extension from source, requiring a Rust toolchain >=1.85.
Is it ready for production use yet?No - this is an early public release and the instruction set, binary format, and public API may still change before v1.0.
What is the Quip Network solver extra for?pip install xquad[quip] adds a backend that submits problems to the Quip Network itself, which needs a QUIP_RPC_URL and a configured signer to authenticate.
How does XQuad keep the Rust and Python VMs in sync?Every conformance vector in the spec is run against both the Rust production VM (xqvm) and the Python reference VM (xqvmpy) in CI, and any disagreement fails the build.
What does the VM architecture look like under the hood?It is a stack-based interpreter with a 256-slot typed register file (integers, integer vectors, QUBO/Ising models, candidate solutions) and a dedicated loop stack for RANGE/ITER iteration.
Is there a full worked example to learn from?examples/tsp/ walks through a Travelling Salesman Problem defined in the xqcp DSL, compiled to .xqasm, and run end-to-end through either the Python or Rust VM with the xqsa solver.
What are similar projects?hexstellar, turboquant_plus, burn, scalene, fframes, jax, koharu, bend
Which topics is it in?quantum-computing, ffi, jupyter, scientific-computing, metal, optimization, agplv3, wasm, apple-silicon, nvidia, cuda, sdk
Creator
QuipNetwork
Size
3.7 MB
Stars
5.6K
Updated
CommitOct 15
Age
6mo
Commits · 90 Days