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
Что это такое?XQuad — это набор инструментов, не привязанный к конкретному железу, для записи и запуска задач квадратичной оптимизации (QUBO / Ising / дискретных) на квантовых отжигателях и классических решателях. Это общее промежуточное представление: вы пишете задачу один раз и можете направить её на любой поддерживаемый бэкенд.
Это библиотека Rust, пакет Python или утилита командной строки?Это всё сразу: три крейта Rust (xqvm, xqasm, xqcli) и пять пакетов Python (xqffi, xqvmpy, xqcp, xqsa, xquad), построенных на одной спецификации виртуальной машины. Поэтому его можно использовать как крейт Rust, как библиотеку Python или через утилиту командной строки xquad.
Как запустить задачу в XQuad?Установите общий пакет Python командой pip install xquad (или крейты Rust с crates.io), затем напишите или скомпилируйте программу .xqasm и запустите её через утилиту командной строки xquad (asm/dism/run/verify) или через программный интерфейс Python: Program / Session / RunResult.
Нужен ли инструментарий Rust, чтобы установить пакет Python?Только на macOS и Windows: для Linux x86_64/aarch64 есть готовые сборки (wheel) для CPython >=3.13, а в остальных случаях pip собирает расширение xqffi из исходников, и для этого нужен инструментарий Rust версии >=1.85.
Можно ли уже использовать это в продакшене?Нет — это ранний публичный релиз, и набор инструкций, двоичный формат и публичный API могут ещё измениться до v1.0.
Для чего нужен дополнительный решатель Quip Network?pip install xquad[quip] добавляет бэкенд, который отправляет задачи напрямую в Quip Network. Для аутентификации ему нужны QUIP_RPC_URL и настроенный подписант.
Как XQuad следит за тем, чтобы виртуальные машины Rust и Python работали одинаково?Каждый тестовый вектор соответствия из спецификации запускается и на основной виртуальной машине Rust (xqvm), и на эталонной виртуальной машине Python (xqvmpy) в CI; любое расхождение проваливает сборку.
Как устроена виртуальная машина внутри?Это стековый интерпретатор с типизированным регистровым файлом на 256 слотов (целые числа, векторы целых чисел, модели QUBO/Ising, кандидаты решений) и отдельным стеком циклов для итераций RANGE/ITER.
Есть ли полный разобранный пример, на котором можно учиться?examples/tsp/ разбирает задачу коммивояжера (Travelling Salesman Problem), описанную на DSL xqcp, скомпилированную в .xqasm и запущенную от начала до конца через виртуальную машину Python или Rust с решателем xqsa.
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