Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Install XQuad

This page installs XQuad, confirms the install works, and gets the runnable examples this book uses. It also covers what a GPU or QPU solver needs beyond the base install. First Problem picks up from here with a real run.

Install

The root README’s Install section is the canonical install reference for both ecosystems this project ships into – prebuilt wheel platforms, the Rust toolchain required to build the xqffi extension from source, and installing individual Python packages instead of the umbrella.

Install XQuad into a project environment first: a virtual environment, or a uv project.

python -m venv .venv && source .venv/bin/activate
pip install xquad
# or, in a uv project:
uv add xquad

For the xquad command alone, outside any project, install it as a uv tool, with the quip extra for the xquad quip commands:

uv tool install xquad            # the xquad command
uv tool install 'xquad[quip]'    # with the xquad quip commands

On macOS, a user install (pip install --user, or pip falling back to one) puts the xquad command in ~/Library/Python/3.x/bin, which is not on PATH; python -m xquad runs the same command without it.

Verify the Install

xquad --version prints the installed version, confirming the command is on PATH and runs. If your shell reports xquad: command not found, that Python environment’s script directory is not on PATH; python -m xquad --version runs the same command without it. Importing the umbrella package confirms the Python API:

$ python -c "import xquad; print('ok')"
ok

Get the Examples

Every uv run python examples/... command in this book, including on the next page, runs against a checkout of this repository – the examples are not part of any published package, so pip install above does not put them on disk. Get one and set up the Python workspace once:

git clone https://gitlab.com/quip.network/xquad.git
cd xquad
make deps-py

make deps-py needs uv and a Rust toolchain, which builds the xqffi extension from source. It syncs the Python workspace and wires up cross-package imports, so uv run python examples/<name>/runner.py then works from the repository root – the same command every example and cookbook page in this book uses.

GPU and QPU Install Prerequisites

The base install runs CPU simulated annealing only, through xqsa’s cpu backend. Every other solver – a local GPU or a real D-Wave QPU – needs an extra on top, and the extra needs hardware or credentials this page cannot install for you. xqsa/pyproject.toml defines the extras, and xquad/pyproject.toml forwards to the ones it re-exports:

  • cuda – cupy-cuda12x>=13.0, nvidia-cuda-nvrtc-cu12, and nvidia-cuda-runtime-cu12, for a local NVIDIA GPU.
  • dwave – dwave-system>=1.0, for the real D-Wave QPU.
  • metal – pyobjc-framework-Metal>=11.0, marked sys_platform == 'darwin', for a local Apple GPU. The marker means pip install xquad[metal] succeeds on Linux and installs nothing.
  • quip – substrate-interface>=1.7.4,<2 plus quip-signer>=0.3.0,<0.4, for the Quip network solver, which needs a QUIP_RPC_URL and a configured signer; see Quip Network for what that solver does.

xqcp and xqffi define no optional dependencies at all.

The only extra this page can fully specify is [dwave]: it needs a D-Wave Leap account and a DWAVE_API_TOKEN, and dwave ping confirms both. A local GPU ([cuda] or [metal]) is another option; see Local Solvers for those two extras and their driver checks.

pip install "xquad[cuda]", xquad[metal], xquad[dwave], and xquad[quip] each forward to the matching xqsa extra, and extras are composable: pip install "xquad[cuda,dwave]".

A missing extra does not break the base install: import xqsa never fails just because an optional extra is absent. Only constructing the solver class that needs it does, raising ImportError with a pip install xqsa[...] hint naming the extra to add.

Per-solver parameters, driver-level troubleshooting, and what a QPU result contains that a CPU one does not are covered in Solving Overview, Local Solvers, and D-Wave QPU. This section only covers what to install before you get there.

Where to Go From Here

  • First Problem – run a complete problem end to end and get a real answer back.
  • What Happened – the explanation of what that run just did.
  • XQVM Reference – a minimal hand-written .xqasm program, if you want to see the machine underneath before running anything larger.
  • Toolchain Map – the pieces XQuad is built from, and how they hand off to each other.