Introduction

XQuad is a hardware-agnostic toolchain for expressing and running quadratic optimisation problems – QUBO, Ising, and integer formulations – on quantum annealers and classical solvers. A problem is written once against the XQVM instruction set and runs unchanged on any backend the toolchain supports.

Think of it as LLVM for quantum computing: write a problem once, compile it to XQVM bytecode, and run it on any supported backend.

What XQuad solves

Combinatorial optimisation problems – travelling salesman, graph colouring, knapsack, set cover, and their relatives – can be expressed as quadratic binary models and handed to a quantum annealer or a classical sampler. XQuad gives that pipeline a single intermediate representation, XQVM bytecode, and a reference virtual machine, so the same compiled program runs on a D-Wave QPU, a local simulated-annealing sampler, or the Quip network without a rewrite. See Quadratic Models for what a QUBO/Ising model actually is, and Backends for the solvers XQuad targets.

The real components

The toolchain is dual-language: a Rust core (VM, assembler, bytecode) with Python interfaces (constraint-programming DSL, solver adapters, FFI bindings, and the xquad CLI).

Two Rust crates, published to crates.io:

A third crate, xqffi, is a PyO3 bridge that exposes xqvm and xqasm to Python. It ships as a Python wheel rather than a crates.io library.

Four Python distributions, published to PyPI:

spec/xqvm/ defines the VM, and the committed conformance vectors hold xqvm to it: each vector runs in CI against the outcome the spec prescribes, and a mismatch fails the build. See Conformance for what a vector does and does not cover.

Architecture at a glance

XQVM is a stack-based interpreter with a 256-slot register file. The value stack holds i64 integers; registers hold typed values (RegVal): integers, integer vectors, QUBO/Ising/integer models (XqmxModel), model vectors, and candidate solutions (XqmxSample). A dedicated loop stack drives RANGE and ITER iteration.

The instruction set comprises 93 instructions, declared once in the opcodes! table at xqvm/src/bytecode/types/table.rs. The Opcode enum, the Instruction enum, mnemonic strings, and operand arity are all derived from that single table.

Every .xqb file opens with a fixed 15-byte XQBC header – magic bytes, format version, calldata/output-slot counts, instruction-stream length, and a CRC-32 checksum – followed by the raw instruction stream: an opcode byte followed by its operands in big-endian byte order. See Bytecode Format for the full field layout.

Where to go next

• Getting Started – install the toolchain and run your first program.
• Concepts – what a QUBO/Ising model is, the ways to use XQuad, and the backends it targets.
• Modelling with XQCP – write a problem with the constraint-programming DSL.
• Running Programs and Solving – execute a compiled program and hand it to a solver.
• XQVM Reference – the machine model, assembly language, instruction set, and bytecode format.
• Embedding – using the Rust crates directly, no_std support, and conformance to the specification.
• Examples – worked problems including a Travelling Salesman Problem.

License

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

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.

First Problem

This page runs one problem from nothing to a real answer. It does not explain how the pieces work – What Happened does that once you have seen a result to explain.

Max-Cut

Max-Cut splits a graph’s nodes into two groups to maximise the total weight of edges crossing between them. Quadratic Models derives its formulation by hand on a three-node graph; examples/maxcut/ is the same problem, runnable, on a graph you pick the size of.

Run It

With XQuad installed and the examples checked out, per Install XQuad:

$ uv run python examples/maxcut/runner.py --seed 42
{
  "_note": "canonical CI golden",
  "_seed": 42,
  "cut_weight": 354,
  "energy": -354,
  "n": 5,
  "partition": [
    0,
    1,
    0,
    0,
    1
  ],
  "valid": 1
}

No flags beyond --seed are required: --n defaults to 5, and --solver defaults to cpu, the baseline that needs no hardware or credentials.

Reading the Result

partition is the answer: one 0 or 1 per node, five nodes here, naming which side of the cut each node is on. cut_weight is the total weight of edges connecting a 0-side node to a 1-side node – the quantity Max-Cut maximises. energy is -354, the negative of cut_weight, because the model minimises -1 times the cut weight to turn maximising into the minimising every XQuad model does; see Quadratic Models for why that sign flip is exact. valid: 1 confirms every value in partition is 0 or 1 – the only thing this problem’s verifier checks, since Max-Cut declares no constraint beyond that.

Next: What Happened names each step this run took, in order, and links to where each one is covered in full.

What Happened

First Problem ran examples/maxcut/runner.py and printed a partition, a cut weight, and an energy. This page is an index: it names the five moves that run made, in order, and points at the page that covers each one in full, rather than explaining them again here. Toolchain Map has its own diagram of the same pipeline, if a picture is what you want first.

Five Moves, One Command

1. A problem became three programs. build_problem in examples/maxcut/runner.py describes Max-Cut once, in Python, with the xqcp DSL; problem.compile() turned it into an encoder, a verifier, and a decoder, sharing no state. Three Programs covers why there are three and not one, and walks this exact run step by step.
2. The encoder ran and built a model. Quadratic Models covers the Hamiltonian it built, specialised to this graph’s weights.
3. A solver minimised it. cpu, the default backend, ran simulated annealing over the model and returned a sample. Backends covers the other four solvers this same model could have gone to instead, unchanged.
4. The verifier checked the sample and computed its energy independently. energy: -354 was not relayed from the solver; see Quadratic Models: Energy for that computation.
5. The decoder turned the sample into partition. See Outputs and Decoding for what a decoder can read and what it hands back.

Where to Go From Here

• Toolchain Map – every piece named above, in one table, with what each hands to the next.
• Modelling – write your own Problem instead of reading someone else’s; builds on a second running example, Knapsack, from the first input declaration onward.
• Running Programs – drive an already-compiled program from Python yourself, the way runner.py does internally.
• Solving Overview – the five solvers behind step 3, and what each needs installed before you can reach it.
• Using the Examples – turn Max-Cut, or any of the other thirteen examples, into a problem of your own.

Toolchain Map

XQuad turns one problem description into bytecode that runs unchanged on any backend it supports. This page names the pieces that make that true, and what each one consumes and produces.

flowchart LR
    P["DSL (xqcp) or hand-written .xqasm"] --> ASM[Assembler]
    ASM --> B[XQVM bytecode]
    B --> V["VM: xqvm"]
    H[Host program] -->|calldata| V
    V -->|model-building program| M[XQMX model]
    M --> H
    H --> SLV[xqsa solver]
    SLV -->|sample| H
    H -->|sample as calldata| V
    V -->|verifier / decoder programs| H

Following the Pipeline

A hand-written program can skip most of this. Save the following as add.xqasm:

; push two integers and add them
PUSH 10
PUSH 32
ADD
HALT

$ xquad vm asm add.xqasm -o add.xqb
assembled 4 instructions (21 bytes) -> add.xqb
$ xquad vm run add.xqb
stack (bottom to top):
  42

Here the pipeline is just two rows: the assembler and the VM. The xquad CLI plays the host program’s role, reading add.xqb from disk and printing the result, and that already runs the real toolchain end to end. XQVM Reference walks through this same add.xqasm again, from the machine’s side: what each instruction does to the stack as it runs.

A problem worth handing to a solver uses every row in the table above. xqcp compiles a Problem into three separate .xqasm programs, not one – see Three Programs for what those three are and why. The first one builds a model; xqsa solves it; the other two check and decode the answer. A Python host program – xquad.program, xqffi.vm, or a full xqcp pipeline – drives it, injecting calldata before each VM run and reading outputs back after. See Ways to Use XQuad for which surface plays that host-program role in each of the six ways to work with XQuad.

Where to Go From Here

• Ways to Use XQuad – the six surfaces that build a model and drive execution, and how to pick one.
• Quadratic Models – what the model in the middle of this pipeline actually is, and why constraints become part of it.
• Three Programs – why xqcp compiles a problem into three separate programs instead of one.
• Backends – the solvers that sit in the gap between encoder and verifier.

Past this chapter: Modelling builds a model with the DSL, Running Programs and Solving Overview execute it and hand it to a solver, and XQVM Reference is the machine this whole pipeline compiles down to.

Ways to Use XQuad

Six separate surfaces get a problem into XQuad and a result back out. Pick the wrong one and you find out several pages later. This page is the map.

xqcp – The DSL

You write a Problem in Python: declare inputs, define the model, add objective terms and constraints, declare outputs. problem.compile() returns CompiledPrograms(encoder, verifier, decoder) – three .xqasm programs, ready to run. See Three Programs for what those three are and why there are three. Every example under examples/ is built this way; examples/maxcut/runner.py is a complete pipeline you can read start to finish.

Stop here if you have a combinatorial problem to model and no existing .xqasm source. Keep reading if you already have compiled bytecode and need to run or inspect it. Full coverage: Modelling.

xquad.program – Program and Session

Program.from_source(src) or Program.load(bytecode) loads a program once; program.session(output_slots=n) gives you a Session you call .run() on repeatedly, each time with fresh calldata via session.set_calldata(...). Each run returns a RunResult with dict-keyed outputs (an unset slot reads as None), the residual stack, and the step count. Program.from_source plus Session.run() round-trips 40 + 2 through calldata and an output slot to {0: 42}, and running the same session again returns {0: 42} again: each run() starts clean.

Stop here if you are driving an already-compiled program from Python and want calldata handling and output decoding done for you. Keep reading if you are choosing between this and the raw FFI below. Full coverage: Running Programs.

xqffi.vm – The Raw FFI

xqffi.vm.Vm is a thin wrapper over the Rust interpreter: construct a Vm, call set_calldata/set_output_slots, call .run(bytecode), read .outputs(). No Program/Session layer on top, and unlike Session, a Vm holds its stack and registers across runs: call .run() twice on the same Vm without an intervening .reset() and the second run’s results sit on top of the first’s. reset() clears the stack, registers, and loop state; calldata and outputs both survive a reset() untouched, and only a fresh set_output_slots(n) call replaces the output slots. Session sidesteps the question entirely: Session.run() builds a fresh Vm per call, so no state survives between runs. That is the real reason to prefer it for anything but a single one-off program.

Reach for Vm directly only if you are building your own convenience layer on top, or the Program/Session assumptions do not fit – most Python users want xquad.program or xquad.vm instead. Full coverage: Running Programs.

xquad.vm – The Source-Level VM

xquad.vm.VM wraps xqffi.vm.Vm. run(source) assembles .xqasm text and runs it; run_bytecode(bytecode) runs pre-assembled bytes. Calldata, output slots, and the step and memory limits persist across runs until reset(), while every run starts from a fresh stack and register file. Outputs come back as the xqffi types unchanged: int, list[int], XqmxModel, XqmxSample, or None. Every example runner under examples/ imports VM from here, not xqffi.vm directly.

Stop here if you run .xqasm source from a script and want the settings to carry from one run to the next. Keep reading if you need the raw FFI underneath instead. Full coverage: Running Programs.

xquad CLI

xquad vm asm, xquad vm run, xquad vm dis, xquad vm check – four subcommands, entirely in the shell. Assemble a .xqasm file to bytecode, run a .xqb file (or a .xqasm file with --text) against calldata, disassemble bytecode back to a readable listing, or verify a compiled program before running it. xquad vm asm add.xqasm -o add.xqb followed by xquad vm run add.xqb, xquad vm dis add.xqb, and xquad vm check add.xqb assembles, runs, disassembles, and verifies the four-instruction add.xqasm from Toolchain Map.

Stop here if you are working from a shell or from CI. Keep reading if you need to drive many runs programmatically rather than one at a time. Full coverage: CLI.

Rust Embedding

xqvm::InstructionBuilder builds a Program directly from Rust, with no .xqasm text step at all:

#![allow(unused)]
fn main() {
use xqvm::{InstructionBuilder, Vm};

let mut builder = InstructionBuilder::new();
builder.emit_push(10).emit_push(32).emit_add().emit_halt();
let program = builder.build().unwrap();

let mut vm = Vm::new();
vm.run(&program).unwrap();
assert_eq!(vm.stack(), &[42]);
}

The xqvm crate is no_std + alloc-compatible, so this is the surface for embedding XQVM where Python, or even a filesystem, is not available.

Stop here if you are embedding the VM inside another Rust program. Everyone else wants one of the five surfaces above. Full coverage: Builder API.

The Orthogonal Choice: Where It Solves

Whichever surface builds your model, you still choose separately where that model gets solved: local CPU or GPU simulated annealing, a D-Wave QPU, or the Quip network. xqsa.build_solver(name, seed=...) selects a backend by name regardless of which surface above produced the model, and every example runner exposes this as a --solver flag. See Backends.

Quadratic Models

Every backend XQuad targets agrees on one thing: a single number, computed from a candidate assignment, that the solver tries to make as small as possible. That number is the model’s energy, and a quadratic model is the recipe for computing it:

$$H(x) = \sum_i \text{linear}[i] \cdot x_i + \sum_{i \le j} \text{quadratic}[i,j] \cdot x_i \cdot x_j$$

x is a vector of variables. linear[i] scales with variable i’s own value, and quadratic[i,j] scales with the product of i and j’s values – a cost, or a saving if negative. Read those as “the cost of turning i on” and “the extra cost of turning i and j on together” when x is binary; Three Domains below covers two domains where nothing is “on.” No term touches three variables at once – that is what “quadratic” means here. The sum runs over \(i \le j\), not \(i < j\): the diagonal is legal, and quadratic[i,i] scales with \(x_i^2\). What that means depends on the domain – on binary variables \(x^2 = x\), so it acts as a linear bias written through the quadratic table; on spin variables \(x^2 = 1\), so it is a constant offset. The VM stores and evaluates such a term without interpreting it. H is called the model’s Hamiltonian, borrowing the term physicists use for a system’s total energy, because the annealing hardware XQuad can target literally is a physical system settling toward a low-energy state.

XQVM builds this structure directly: BQMX/SQMX/XQMX allocate a model register, and SETLINE/SETQUAD/ADDLINE/ADDQUAD write the two coefficient maps one term at a time. See Allocators and Coefficient Access for the instructions.

Why Optimisation Problems Become One of These

A combinatorial problem – which cities to visit in what order, or which items fit in the knapsack – usually starts life as a set of decisions plus rules those decisions must obey. A quadratic model has no separate mechanism for rules: it is one function, and a solver’s only operation is minimising it. Every constraint has to become part of the same H, or the solver never sees it. The Penalties section below is that mechanism, and the concept this page most wants you to leave with.

A Worked Example: Max-Cut

Take Max-Cut: split a graph’s nodes into two groups to maximise the total weight of edges that cross between them. \(x_i \in \{0, 1\}\) marks which group node \(i\) is in. For each weighted edge \((i, j, w)\):

$$\text{linear}[i] \mathrel{+}= -w, \qquad \text{linear}[j] \mathrel{+}= -w, \qquad \text{quadratic}[i,j] \mathrel{+}= 2w$$

That edge’s contribution to \(H\) is \(-w(x_i + x_j - 2x_ix_j)\), and \(x_i + x_j - 2x_ix_j\) is the binary XOR of \(x_i\) and \(x_j\): it is \(1\) when \(x_i \neq x_j\) and \(0\) when they match. That edge contributes \(-w\) exactly when it crosses the partition, and \(0\) otherwise. Summed over every edge, \(H\) is the negative of the cut weight, so minimising \(H\) maximises the cut. examples/maxcut/runner.py builds exactly this model.

For three nodes and edges \((0,1,3)\), \((1,2,5)\), \((0,2,1)\), the rule above gives:

$$\text{linear} = \{0: -4,\ 1: -8,\ 2: -6\}, \qquad \text{quadratic} = \{(0,1): 6,\ (1,2): 10,\ (0,2): 2\}$$

Two assignments, worked by hand:

• \(x = (1, 1, 0)\): \(H = (-4)(1) + (-8)(1) + (-6)(0) + 6(1)(1) + 10(1)(0) + 2(1)(0) = -12 + 6 = -6\). Nodes 0 and 1 share a group, so only the two edges crossing to node 2 count: \(5 + 1 = 6\), and \(-6\) is the negative of that, matching.
• \(x = (1, 0, 1)\): \(H = (-4)(1) + (-8)(0) + (-6)(1) + 6(1)(0) + 10(0)(1) + 2(1)(1) = -10 + 2 = -8\). Every edge except \((0,2)\) crosses: \(3 + 5 = 8\), matching. This is the lowest of the four distinct cuts – a partition and its complement always have the same energy, so the eight assignments give four cuts – so it is the Max-Cut optimum for this graph.

Three Domains

x_i is not always a 0/1 bit. XQVM supports three domains, and the choice affects one thing above all: whether a backend can solve the result.

Binary is QUBO – Quadratic Unconstrained Binary Optimisation – the domain most combinatorial formulations target directly: a variable is either selected or not. The Max-Cut model above is binary.

Spin is the Ising model: each variable is a magnetic moment pointing up or down, \(-1\) or \(+1\), which is the domain quantum annealing hardware minimises natively. A spin variable’s linear coefficient rewards one orientation and penalises the other by the same amount, rather than switching a cost on or off. Binary and spin describe the same choices: substituting \(x_i = (s_i + 1)/2\) (or \(s_i = 2x_i - 1\)) turns any binary Hamiltonian into a spin Hamiltonian over the same variables, with rescaled coefficients and one additive constant that does not change which assignment is optimal. Build a model in one domain and you can rebuild it in the other; between these two the choice is free, since every current xqsa solver accepts both, so pick whichever domain the problem is natural in.

Integer generalises past two states to give a variable \(k\) integer values directly, suited to a quantity with a natural ordering or magnitude – a position in a short list – without one-hot encoding it into several binary variables first. Unlike binary and spin, it is not a relabelling of the other two: it cannot encode an unordered categorical choice, because a quadratic form over integer variables cannot express that two values merely differ without also expressing by how much.

Integer is the domain with a real consequence: every current xqsa solver rejects it. An integer XqmxModel is a real thing you can build in XQVM bytecode today, but there is no backend yet that can solve one. See Backends.

A model and a sample share a domain and a variable count, but not a shape: a model is two sparse coefficient maps, linear and quadratic, while a sample is one value per variable and nothing else. Allocators covers both families and their default values in full.

Energy

Given a model and a candidate assignment (a sample), ENERGY computes \(H(x)\) for that specific x and pushes the result – the same formula as the model’s Hamiltonian above, evaluated at one point. “Energy” and “Hamiltonian value at x” mean the same thing throughout XQuad’s documentation. A solver’s job is to search for the x that minimises this value; XQVM’s job is only to compute it, which is what lets a program check a solver’s answer independently rather than trust it. See Energy Evaluation.

Penalties: Folding a Constraint into the Objective

The constraint instructions below expand assuming binary variables, where \(x^2 = x\). That identity does not hold for spin variables, where \(x^2 = 1\) always: apply these instructions to a BQMX model, and convert a spin model to binary first if you need one of them (see Three Domains).

Take the simplest useful constraint: exactly one of a set of variables should be 1 (a one-hot choice – pick exactly one city to visit first, one colour for this node). Written as a penalty term:

$$H \mathrel{+}= P \cdot \left(\sum_i x_i - 1\right)^2$$

The squared term is zero exactly when the constraint holds (the sum is 1) and strictly positive for every assignment that violates it – pick zero variables and the sum is 0, pick two and the sum is 2, either way \((\sum x_i - 1)^2 \ge 1\). Adding this to \(H\) means violating the constraint always costs at least \(P\) units of energy on top of whatever the rest of the objective says. A solver minimising the combined \(H\) has a direct incentive to satisfy the constraint, without any code path in the solver that knows constraints exist – it is minimising one number, the same way it always does.

This is the general shape behind most of XQVM’s high-level constraint instructions: ONEHOTR/ONEHOTC are exactly the sum above over a grid row or column, and EXCLUDE, IMPLIES, EQUALITY, ATLEAST, and ATLEASTW are the same idea applied to different rules: mutual exclusion, implication, weighted equality, at-least-k with unit weights, and at-least-k with arbitrary weights. The instruction reference also documents REDUCE, which uses the same technique – a term that is zero exactly when a condition holds – but to enforce an algebraic identity between variables rather than a rule from the problem; that is a different enough job to read about on its own. The full expansion for each instruction – which linear and quadratic coefficients change by how much – is reference material, not a concept, and lives on High-Level Constraints and in the normative HLF specification. This page is not repeating that table; the mechanism above is what to carry forward from it.

Choosing a Penalty Weight

\(P\) is not a detail to default and forget – it is the real engineering decision in penalty-based modelling, and it fails in both directions.

Too low, and the solver buys its way out of the constraint: \(P\) must exceed the largest objective improvement any violating assignment can buy over the best feasible one, or the minimiser takes that trade, because nothing in \(H\) told it not to. Suppose the Max-Cut model above also carried a one-hot constraint over nodes 0 and 2 only, with weight \(P\). The unconstrained optimum \(x = (1, 0, 1)\) worked out above violates it; the best assignments that satisfy it are \(x = (1, 1, 0)\), worked out above, and \(x = (0, 0, 1)\), both at \(H = -6\). Violating the constraint lowers the energy from \(-6\) to \(-8\), an improvement of \(2\), so penalty = 1 costs less than it saves and the minimiser still prefers the infeasible optimum. penalty = 2 ties the two, and \(P\) must exceed \(2\) before satisfying the constraint wins outright.

Too high does not corrupt the model itself. For any two assignments that both satisfy the constraint, the penalty term is 0 on both, so their energy difference is exactly the objective’s difference, independent of \(P\); ENERGY computes that difference with exact i64 arithmetic, so nothing in \(H\) degrades. What a large \(P\) costs happens outside the model. On a fixed-precision device, an objective difference much smaller than \(P\) can fall below the device’s resolution once the combined \(H\) is scaled to fit it, so the device stops representing that difference at all. And a large \(P\) raises the energy barrier between feasible regions, so a heuristic such as simulated annealing gets trapped in whichever feasible region it reaches first and stops exploring for a better one elsewhere.

Getting this right in practice – how to size \(P\) relative to your objective, and how to tell from a solver’s output which failure mode you hit – belongs to Constraints. What to take from this page is that the weight is a parameter you choose, not one XQVM chooses for you: every constraint instruction pops penalty off the stack as an ordinary operand.

Three Programs

An optimisation problem in XQuad is three independent programs sharing one instruction set: an encoder, a verifier, and a decoder. They communicate only through calldata in and outputs out. xqvm’s Three-Program Architecture defines this shape, so it is not something xqcp adds on top. Nothing in the instruction set enforces it – see Beyond xqcp – but every tool in the toolchain assumes it.

xqcp generates all three for you from one Problem definition: problem.compile() returns CompiledPrograms(encoder, verifier, decoder), three independent .xqasm sources, each its own complete program with its own fixed inputs and outputs. A hand-written program can follow the same shape with no DSL involved: xqvm/examples/tsp/main.rs builds and runs a three-program TSP pipeline directly against the Rust xqvm crate.

Why Three, Not One

XQVM has no instruction that calls a solver. Its 93 instructions cover control flow, stack and register I/O, arithmetic, comparison, vectors, grid operations, the constraint and energy family – nothing that reaches outside the VM to an annealer or a sampler. Solving happens in host code, between two runs of the VM, using whichever backend Backends describes. A model-building program cannot also be the program that checks and decodes the answer, because the answer does not exist yet when that program halts.

flowchart LR
    Q[Problem definition] -->|compile| ENC[Encoder]
    Q -->|compile| VER[Verifier]
    Q -->|compile| DEC[Decoder]
    ENC -->|XQMX model| H[Host program]
    H -->|model| SLV[xqsa solver]
    SLV -->|XQMX sample| H
    H -->|model, sample| VER
    H -->|sample| DEC
    VER -->|energy, valid| H
    DEC -->|decoded result| H

What Each Program Does

Encoder. Reads the problem’s runtime inputs from calldata, allocates the XQMX model, and emits every objective term and constraint penalty the DSL recorded. Its one output is the model, on slot 0. This is “a program whose job is to construct a model” – running it does not solve anything, it only builds the thing a solver will minimise.

Verifier. Takes the encoder’s own inputs, then the model and the sample, and checks whether the sample satisfies every constraint the encoder applied, then computes the sample’s energy with the ENERGY opcode. It outputs (energy, valid). It needs the encoder’s inputs because it replays the encoder to rebuild the constraint data, which lives in registers at VM runtime rather than in the model. This is how a sample’s feasibility gets checked independently of whatever backend produced it.

Decoder. Takes a sample and N, and extracts the answer in the problem’s own terms – a tour, a partition, a set of selected items – into one or more output vectors. It does not know or care whether the sample it was given is valid; that is the verifier’s job, not the decoder’s.

Independent, Not Sequential

The three programs share no state. Communication between them happens only through calldata in and outputs out – there is no hidden channel, and no program reads another program’s internals. The verifier and the decoder are not a pipeline: both read the same sample straight from the solver, at the same point, side by side. A host program can decode a sample the verifier just rejected, which is useful for inspecting what a bad solution actually looks like.

A Concrete Run

examples/maxcut/runner.py is exactly this shape. Max-Cut declares no constraints, so its verifier has none to check: the loop under ; === Validity checks === in the compiled verifier only confirms each sample value is 0 or 1. The ENERGY recomputation still runs and is real independent verification – the energy the verifier reports is computed fresh from the model and the sample, not relayed from the solver.

Its run() function makes four calls in sequence, three of them through the VM:

1. vm.run(programs.encoder) with calldata [n, flat_edges] and one output slot, producing an XQMX model.
2. solver.solve(model), entirely outside the VM, producing a sample.
3. vm.run(programs.verifier) with calldata [n, flat_edges, model, sample] and two output slots, producing (energy, valid).
4. vm.run(programs.decoder) with calldata [sample, n] and one output slot, producing the decoded partition.

Running uv run python examples/maxcut/runner.py --n 5 --seed 42 prints:

$ uv run python examples/maxcut/runner.py --n 5 --seed 42
{
  "_note": "canonical CI golden",
  "_seed": 42,
  "cut_weight": 354,
  "energy": -354,
  "n": 5,
  "partition": [
    0,
    1,
    0,
    0,
    1
  ],
  "valid": 1
}

The encoder, verifier, and decoder are deterministic – same bytecode and calldata in, same output out. The solve sitting between them is only pinned to the seed and the dwave-samplers version, since SA is sensitive to BQM construction order, so a different version of that library can return a different valid sample for the same seed. See below for what make example-smoke checks instead of the exact output.

_note and _seed are the runner’s own bookkeeping, not part of the result: _note’s value, "canonical CI golden", describes what the runner calls this invocation, not a guarantee that a test pins against it. energy is the negative of cut_weight because the encoder minimises -weight per crossing edge to make the objective function, matching the derivation in Quadratic Models. valid: 1 here only confirms every sample value is in {0, 1}, which is all this problem’s verifier checks. make example-smoke is what actually guards this example: it runs it once and checks valid == 1, and does not compare cut_weight, energy, or partition against a stored answer. These numbers depend on the dwave-samplers version behind cpu; a different version can return a different valid sample with a different cut weight.

The three VM calls above, and the solve between them, are the host program driving all three compiled programs and the solver together – see Ways to Use XQuad for the surfaces that can play that role.

Beyond xqcp

A hand-assembled .xqasm program is free to read inputs, build a model, and produce output in one file, the way Toolchain Map’s minimal add.xqasm example does – the interpreter does not enforce the three-program split. The split earns its cost once an external solver sits in the loop and a sample needs independent checking, which is exactly when reaching for xqcp, or hand-writing the same three-program shape, starts to pay off. See Modelling: Compiling for how the compiler produces the three programs, and Running Programs and Solving Overview for executing each stage.

Backends

“Hardware-agnostic” means one concrete thing: build a model once, then choose where it solves, from five backends behind a single interface. Nothing about the model, the encoder, or the verifier changes with that choice.

The Solver Set

build_solver(name, seed=...) constructs any of the five from this name, so a caller can stay backend-agnostic. seed reaches the three classical simulated-annealing backends and is ignored by dwave (physical hardware has no seed) and quip (env-configured, no local randomness).

What Actually Distinguishes Them

Where the computation happens. cpu, cuda, and metal all run the identical algorithm family – simulated annealing – just on different local processors; picking between them is a performance question, not a correctness one. dwave hands the problem to real annealing hardware over the network. quip does not solve anything itself: it posts the model as a job to the network’s mempool, a miner solves it on hardware of its own choosing, and the adapter decodes whatever comes back.

Domain support. Every backend above accepts a binary or spin model and rejects anything else: Solver._validate_model() raises ValueError for any domain other than BINARY or SPIN. XQVM’s third domain, integer (XQMX), has no backend yet. See Quadratic Models for what the three domains are.

The result contract is identical regardless of backend. Every solve() call returns a SolverResult(sample, energy, timing, metadata). energy is not simply relayed from the device: XQuad’s own verifier program recomputes it independently with the ENERGY opcode, so you never have to take a backend’s word for its own energy – run the verifier and recompute it. See Three Programs.

Before You Choose

cpu needs no hardware and no credentials, so it is the default: the reproducible baseline every other backend is compared against. The other four need something this book cannot check for you – a GPU for cuda or metal, D-Wave Leap credentials for dwave, network configuration for quip – and setting each of those up belongs to the pages below.

Depth Lives in Solving

This page is orientation, not a manual. Backend-specific setup, parameter tuning, and result interpretation belong to Solving Overview, Local Solvers, D-Wave QPU, Quip Network, and Energy and Precision.

Modelling Lifecycle

XQCP is a Python-embedded DSL that turns a problem description into three XQVM assembly programs. You declare a Problem’s runtime inputs, allocate the quadratic model those inputs fill, add objective terms and constraints, declare what you want back, then call compile(). XQCP records every call you make against Problem as you make it and only turns that recording into .xqasm when compile() runs – see Compiling for how the recording becomes three programs.

A problem definition follows one call sequence, in order:

Problem(name) -> input()* -> define_model() -> body* -> output()* -> compile()

input() calls come first: Inputs and Model Shape covers why, and what a declared input becomes at run time. define_model() runs exactly once and makes problem.model available for the rest of the body: objective terms, constraints, and loops, in any order, covered across Expressions, Objectives, Constraints, and Control Flow. Your first output() call marks the start of the decoder section, covered in Outputs and Decoding.

Why XQCP, Not Assembly

Ways to Use XQuad names six surfaces for getting a problem into XQuad; XQCP is one of them. Reach for it when you are modelling a combinatorial problem from scratch and would otherwise hand-write the same loop-over-variables, add-a-coefficient pattern in .xqasm three times over, once per program – Problem records that pattern once, and the compiler emits all three. Write .xqasm directly instead when a program is small enough that the three-program duplication costs nothing to write by hand. Reach for xqvm::InstructionBuilder instead when a Rust host is generating programs and adding a Python step to emit them buys nothing.

One Problem, Once

Every page in this chapter builds on the same running example: examples/knapsack/runner.py. It takes item weights, item values, and a capacity, and chooses the subset of items maximising total value without exceeding the capacity. build_problem is the whole of it:

def build_problem(n: int, weights: list[int], values: list[int], capacity: int) -> Problem:
    problem = Problem("Knapsack")

    num_items = problem.input("num_items", type=Types.Int)
    weights_in = problem.input("weights", type=Types.Vec)
    values_in = problem.input("values", type=Types.Vec)
    capacity_in = problem.input("capacity", type=Types.Int)

    problem.define_model(size=num_items, domain=Domain.BINARY)

    # Objective: minimise -sum(v_i * x_i)
    with problem.range(0, num_items) as i:
        vi = problem.stow("vi", values_in.get(i))
        problem.model.linear[i].add(-vi)

    # Constraint: sum(w_i * x_i) <= W
    indices = problem.vec()
    coeffs = problem.vec()
    with problem.range(0, num_items) as i:
        indices.push(i)
        coeffs.push(weights_in.get(i))

    problem.slack(indices, coeffs, num_items, capacity_in)
    problem.model.apply_equality(indices, coeffs, capacity_in, 100)

    selected = problem.output("selected", type=Types.Vec)
    with problem.range(0, num_items) as i:
        selected.append(problem.sample.getline(i))

    return problem

One binary variable per item: x_i = 1 means item i is selected. Four inputs, one 1D binary model sized to num_items, a range loop building the objective, a second range loop paired with slack and apply_equality encoding the capacity constraint, and a decoder loop reading the solved sample back into a selected vector. Running it end to end:

$ uv run python examples/knapsack/runner.py --seed 42
{
  "_note": "canonical CI golden",
  "_seed": 42,
  "capacity": 18,
  "energy": -32446,
  "n": 5,
  "selection": [
    1,
    1,
    1,
    0,
    1
  ],
  "total_value": 46,
  "total_weight": 12,
  "valid": 1,
  "values": [
    5,
    4,
    18,
    3,
    19
  ],
  "weights": [
    2,
    1,
    5,
    4,
    4
  ]
}

_note and _seed are the runner’s own bookkeeping, the same as in Three Programs. energy is the full model’s Hamiltonian, capacity constraint included, so it is not simply -total_value here the way Max-Cut’s energy is -cut_weight – Objectives isolates just the objective term’s contribution, and Constraints covers what the rest of energy is paying for.

This run is not the optimum: the five weights sum to 16, under the capacity of 18, so every item fits and the true best value is 49, not the 46 printed above. A heuristic solver returns a good sample, not a proven best one. valid: 1 reports only the verifier’s binary-domain check here, not the capacity constraint; see Compiling for what a verifier actually checks.

Inputs and Model Shape starts with the four problem.input() calls and the define_model() line above; the rest of the chapter works through the remaining lines in the order they appear.

Where to Go From Here

• Inputs and Model Shape – runtime inputs and the 1D/2D model they fill.
• Expressions – the operators and functions that build a coefficient or a loop bound.
• Objectives – turning “minimise this” into linear/quadratic coefficients, sign included.
• Constraints – folding a rule into the objective as a penalty.
• Control Flow – range, iter, and branch.
• Outputs and Decoding – reading a solved sample back into your problem’s own terms.
• Compiling – what problem.compile() actually produces.

Inputs and Model Shape

A Problem definition starts with two declarations: the runtime inputs it reads, and the model those inputs fill. Both happen before anything else – spec/xqcp/SPEC.md fixes the order as Problem(name) -> input()* -> define_model() -> body* -> output()* -> compile(), and input() calls after define_model() raise RuntimeError.

Every code sample in this chapter, and the rest of Modelling and Solving, assumes the same import:

from xquad import cp

It is shown once, here, and omitted everywhere after.

Inputs

problem.input(name, type=cp.Types.Int) or type=cp.Types.Vec declares one runtime value and returns an InputRef you use for the rest of the problem body. examples/knapsack/runner.py declares four:

num_items = problem.input("num_items", type=cp.Types.Int)
weights_in = problem.input("weights", type=cp.Types.Vec)
values_in = problem.input("values", type=cp.Types.Vec)
capacity_in = problem.input("capacity", type=cp.Types.Int)

Types.Int is a scalar integer, and Types.Vec is a vector of integers. Every runtime input is one of these two types.

Declaration Order Is Calldata Order

Compiling the fragment above emits this for each input:

PUSH 0
INPUT r0
PUSH 1
INPUT r1

INPUT pops a calldata slot index and clones calldata[slot] into the target register. It does not check the calldata value’s type against anything (Register I/O covers INPUT in full). XQCP’s register allocator hands out registers in call order starting at r0, and because input() must run before define_model(), the first input() call is allocated r0, the second r1, each next call the next register, with nothing else allocated between them. That is why the slot index XQCP pushes before each INPUT matches the input’s position in your problem.input() call sequence: your Nth input() call reads calldata[N-1].

The host has to supply calldata in that same order. examples/knapsack/runner.py calls vm.set_calldata([n, weights, values, capacity]), matching num_items, weights_in, values_in, capacity_in above one for one. Nothing checks this correspondence: INPUT clones whatever sits at that slot, regardless of the input’s declared type. Swap the position of weights and values on either side and both are Types.Vec, so no RegisterType fault stops you – the encoder runs to completion and reads weights where it wanted values. See Calldata and Outputs for how a host supplies calldata to any XQVM program, XQCP-generated or hand-written.

Reading a Vec Input

A Types.Vec input supports two operations no Types.Int input has:

values_in.get(i)      # VECGET: element at index i
values_in.veclen()    # VECLEN: the vector's length

Both return an expression, not a value – see Expressions for what you can build with the result. Calling either on a Types.Int input raises TypeError immediately, at problem-definition time, not at compile time:

>>> num_items.get(0)
TypeError: Cannot index into int input 'num_items'

The Model

problem.define_model(size, domain, rows=None, cols=None) allocates the quadratic model the encoder builds and runs exactly once per problem. Before it runs, problem.model and problem.sample raise RuntimeError; after, both are available for the rest of the chapter. size is the total variable count, as an int or an expression built from your inputs – knapsack sizes its model directly off an input:

problem.define_model(size=num_items, domain=cp.Domain.BINARY)

domain is a Domain member; see Quadratic Models for what each domain means and how to choose between them, since that choice does not belong to this page. Binary is the domain the running examples in this book use. It must be xqcp.Domain, which xquad.cp re-exports: xquad.types.Domain is the VM’s own domain type under the same name, and define_model() raises TypeError if handed it.

Integer Variables

An integer variable takes one of k values rather than two. Give the width directly:

problem.define_model(size=num_assets, domain=cp.Domain.INTEGER, k=4)

That allocates num_assets variables over {0, 1, 2, 3}. k is an expression like size, so it may come from calldata.

Where the values you are modelling are not zero-based, give bounds instead:

problem.define_model(size=num_assets, domain=cp.Domain.INTEGER, lo=-5, hi=5)

You then write coefficients over x in [-5, 5] while the model holds y = x - lo in {0, ..., 10}, and sample.value(i) shifts back on the way out. XQCP rewrites each quadratic write for you: w * x_i * x_j expands to w*y_i*y_j + w*lo*y_i + w*lo*y_j + w*lo^2 once x = y + lo is substituted, so the write records w*lo against the linear coefficient of both indices as well. The w*lo^2 constant is dropped, because XQMX has no offset field. Energies shift by the same amount for every assignment, so the minimum is still in the same place; the number is not the objective’s true value. Linear writes need no correction.

Two consequences worth knowing before you reach for the ranged form. Setting a coefficient is refused on it, on quadratic[i, j] = w and linear[i] = w alike, because setting replaces a coefficient while the corrections can only accumulate: two writes to the same pair would disagree, and a linear set would drop whatever corrections earlier quadratic writes had left on that index. Use .add(), which loses nothing, since a coefficient starts at zero. And a runtime lo competes with an output loop bound for the decoder’s single calldata scalar, so compile() raises naming both. Literal bounds sidestep it.

Constraints are binary-only. On a spin or integer model every apply_* method is refused and only coefficient writes are supported, because each expansion in the VM is derived under x^2 = x. Write the penalty out by hand, as Portfolio Rebalance does for its budget.

Categorical Variables

A categorical variable takes one of k unordered cases. There is no VM domain for that, so XQCP records the standard encoding:

problem.define_model(size=num_nodes, domain=cp.Domain.CATEGORICAL, k=num_colors, penalty=200)

That is a num_nodes x num_colors binary grid with one ONEHOTR per row, built through the same calls you would have written yourself. The model is binary afterwards, so constraints work on it as usual and coefficient access is (variable, case). Read the answer back with sample.case(v), which gives the case a variable took or -1 if its row came back empty.

1D and 2D Models

A model is either flat (1D, indexed 0..size) or a grid (2D, indexed by (row, col)). Every model in this chapter is 1D: knapsack’s x_i is one binary decision per item, with no row/column structure to it. Pass rows and cols to get a grid instead:

problem.define_model(size=rows * cols, domain=cp.Domain.BINARY, rows=rows, cols=cols)

rows and cols are both-or-neither: define_model() raises ValueError when given exactly one, rather than building a 1D model that fails later.

Once a model has a shape, coefficient access accepts a (row, col) tuple in place of a flat index, and XQCP flattens it for you. Compiling

n = problem.input("n", type=cp.Types.Int)
problem.define_model(size=n * n, domain=cp.Domain.BINARY, rows=n, cols=n)
problem.model.linear[(1, 2)] = 99

emits the block below, once n has claimed r0 and define_model() has claimed r1 for cols and r2 for the model:

PUSH 1
PUSH 2
LOAD r1
IDXGRID
PUSH 99
SETLINE r2

r1 is the cols register define_model() allocated; this block does not depend on n’s runtime value at all, only on how many calls came before it. IDXGRID computes row * cols + col, so at run time, with n = 3, the coordinate (1, 2) flattens to 1 * 3 + 2 = 5, and every coordinate-accepting call on a 2D model (coefficient access, apply_exclude, apply_implies) goes through the same flattening. size still has to equal rows * cols yourself; XQCP does not derive one from the other. It does optimise the size expression itself: size=n*n emits a single SQR instead of LOAD, LOAD, MUL whenever both multiplicands are the same register, 2D model or not. Grid allocation itself – RESIZE and the rest of what BQMX r2 plus a shape actually builds – is Allocators and Grid Operations territory, not this page’s.

Symbolic Reference Types Introduced Here

spec/xqcp/TYPES.md is the normative reference for every symbolic type XQCP hands back. The two this page introduces:

SampleRef – problem.sample, the model’s read-only counterpart used in the decoder – is created together with ModelRef but belongs to Outputs and Decoding, where it is actually used. Expressions covers LoopVar and RegLoad, the two symbolic types this page’s fragments do not need yet; the full type table, including register-allocation and error-condition details past what this page restates, is in spec/xqcp/TYPES.md.

With inputs declared and a model allocated, the next thing every problem body needs is a way to compute with them – see Expressions.

Expressions

Every symbolic value XQCP hands you – an InputRef from problem.input(), a LoopVar from problem.range()/problem.iter(), a RegLoad from problem.stow(), a coefficient read back from model.linear[i] – builds the same kind of expression tree when you combine it with an operator or an xq_* function. A plain Python int used anywhere one of these is expected gets coerced to a literal automatically; anything else raises TypeError. This page groups the resulting vocabulary by what you are trying to compute, not by class hierarchy.

Every xq_* function below lives in the same namespace as Problem and Types:

from xquad import cp

Arithmetic: Computing a Value

+ - * // % and unary - work exactly as Python’s operators do on integers, and compile to ADD SUB MUL DIV MOD NEG. Knapsack’s objective loop uses three of them in three lines:

with problem.range(0, num_items) as i:
    vi = problem.stow("vi", values_in.get(i))
    problem.model.linear[i].add(-vi)

-vi is unary negation on a RegLoad; problem.range and problem.iter yield LoopVars (i here) with the same arithmetic, used as loop-bound math in Max-Cut’s offset = e * 3. // is integer division, matching XQVM’s DIV, not Python’s floating-point / – XQCP has no /, since every value in this system is an i64.

Adding or subtracting exactly the literal 1 is special-cased: a + 1 compiles to LOAD, INC and a - 1 to LOAD, DEC, skipping the PUSH 1 a general add or subtract would need. Nothing about how you write it changes – a + 1 and a - 1 are the natural way to write these, and the compiler does the substitution for you.

Comparisons: Producing 0 or 1

== < > <= >= compile to EQ LT GT LTE GTE, each pushing 1 for true and 0 for false rather than a Python bool. That makes a comparison’s result usable anywhere an integer is: as a coefficient directly, as the condition argument to problem.branch() (see Control Flow), or combined further with arithmetic.

Python has no != here. There is no XQVM opcode for it, so != on an XQCP expression raises immediately, at problem-definition time:

TypeError: '!=' is not supported on XQCP expressions; use xq_not(a == b) instead

_ExprOps overloads __ne__ purely to raise that. Left to Python’s default, __ne__ would call __eq__ and invert the result, and inverting a CompareOp object with not only asks whether the object itself is falsy – which it never is – so a != b would evaluate to the constant False regardless of a and b. Write xq_not(a == b) instead:

model.linear[0] = cp.xq_not(a == b)

compiles to LOAD, LOAD, EQ, NOT, and gives 1 when a and b differ, 0 when they match.

Bitwise: Bit-Level Values

& | ^ ~ << >> compile to BAND BOR BXOR BNOT SHL SHR, useful wherever a problem packs several small values into one integer, or – as in knapsack’s slack step – builds a binary-weighted sum out of individual bits. These are ordinary Python operators, not xq_* functions, because Python lets you overload them.

Index Math: One Number From Several

Two functions turn a pair (or triple) of coordinates into a single flat index:

cp.xq_triu(i, j)            # IDXTRIU: upper-triangular packed index for (i, j)
cp.xq_grid(row, col, cols)  # IDXGRID: row * cols + col, grid flat index

xq_grid is what a 2D model’s tuple-coordinate coefficient access uses internally – see Inputs and Model Shape for that path; call it directly when you need the flat index as a value in its own right rather than as a coordinate to model.linear[...]. xq_triu(i, j) swaps i and j when i > j, then computes j * (j - 1) // 2 + i on the swapped pair, so the packed index does not depend on argument order, per the swap rule spec/xqvm/ISA.md gives for IDXTRIU. xq_triu(2, 5) returns 12 (5 * 4 // 2 + 2; no swap needed, since 2 <= 5).

Logical and Other Free Functions

Python’s and, or, and not keywords cannot be overloaded. XQCP gives you functions in their place. The first four work on the 0/1 convention comparisons use, not on Python truthiness:

cp.xq_not(x)                # NOT:  0 -> 1, non-zero -> 0
cp.xq_and(a, b)             # AND
cp.xq_or(a, b)              # OR
cp.xq_xor(a, b)             # XOR
cp.xq_bnot(x)               # BNOT: bitwise complement, the same opcode as ~ above,
                            # kept as a function for symmetry -- not the same as xq_not

Writing a and b, a or b, not a, or using an expression as an if condition instead of calling one of these functions raises immediately, the same way != does above:

TypeError: XQCP expressions cannot be used in a boolean context ('and', 'or', 'not', 'if'); use xq_and(a, b), xq_or(a, b) or xq_not(a) instead

Python’s and/or/not/if all decide on the truthiness of the object, not on the value it represents, so XQCP has no way to give them the right answer – only to refuse before a Python habit produces the wrong operand or the constant False in place of a real expression.

Five more free functions round out the arithmetic vocabulary that has no Python operator:

cp.xq_sqr(x)                # SQR:  x * x
cp.xq_abs(x)                # ABS:  absolute value
cp.xq_min(a, b)             # MIN
cp.xq_max(a, b)             # MAX
cp.xq_bitlen(x)             # BITLEN: floor(log2(x)) + 1, and 0 for x <= 0

Naming an Expression: stow

problem.stow(name, expr) evaluates an expression once and stores it in a register, returning a RegLoad you can reuse without re-emitting the computation. Knapsack’s vi = problem.stow("vi", values_in.get(i)) is this: values_in.get(i) is a VECGET, emitted once per loop iteration and bound to vi, and every later use of vi in that iteration is a cheap LOAD instead of repeating the VECGET. Passing an existing RegLoad back into stow overwrites that register instead of allocating a new one – useful for an accumulator threaded through a loop.

The operators and free functions above are the DSL’s whole vocabulary; spec/xqcp/TYPES.md lists nothing this page omits. With that in hand, the next question is what you do with a value once you have one: Objectives covers turning an expression into a term the solver minimises.

Objectives

An objective is the part of a model’s Hamiltonian you write directly, as opposed to the part a constraint instruction adds on your behalf – see Quadratic Models for what the Hamiltonian \(H\) is and why a solver minimising it is the whole mechanism. In XQCP terms, an objective is whatever you assign or add to model.linear[i] and model.quadratic[i, j] before any constraint method runs.

Solvers Minimise. Say So.

Every backend XQuad targets minimises. If your problem is a maximisation, you have to negate it, and getting this backwards produces a model that runs, verifies, and confidently returns the worst answer instead of the best one – nothing checks that you meant to maximise.

Knapsack maximises total value. examples/knapsack/runner.py writes the objective as:

# Objective: minimise -sum(v_i * x_i)
with problem.range(0, num_items) as i:
    vi = problem.stow("vi", values_in.get(i))
    problem.model.linear[i].add(-vi)

x_i = 1 means item i is selected, and -vi is the sign flip: instead of rewarding selection with +v_i, the objective penalises it with -v_i, so minimising H picks large values, not small ones. Isolating just this loop – no capacity constraint – and running the encoder with num_items=5, values=[5, 4, 18, 3, 19], then computing ENERGY against the sample [1, 1, 1, 0, 1] (items 0, 1, 2, 4 selected, values 5 + 4 + 18 + 19 = 46) gives:

objective-only energy: -46
expected: -(sum of selected values) = -46

Energy is exactly the negative of total value, for any selection, because that is what linear[i] = -v_i means: drop the - and the same solver would minimise total value instead, selecting nothing.

Assign or Accumulate

model.linear[i] and model.quadratic[i, j] are CoefficientRef proxies, not values. Three things you can do with one:

The same three exist for model.quadratic[i, j], via SETQUAD/ADDQUAD/ GETQUAD. The distinction matters the moment more than one term touches the same coefficient – knapsack’s .add(-vi) runs once per item, each touching a different linear[i], so assign and accumulate would agree there. They stop agreeing as soon as two terms share a coefficient: two .add() calls against the same linear[0] with weights 5 and 7 leave it at 12; two = assignments with the same weights leave it at 7, the second overwriting the first outright. Reach for .add() any time a coefficient might accumulate contributions from more than one place, which for an objective built inside a loop – the usual shape – is the common case; reach for = when you know this is the coefficient’s only source.

Quadratic Terms

A quadratic coefficient couples two variables, and the same accumulate pattern applies. Max-Cut’s objective is the DSL rendition of the Max-Cut coefficient rule Quadratic Models derives by hand – for each weighted edge (i, j, w):

problem.model.linear[i].add(-w)
problem.model.linear[j].add(-w)
problem.model.quadratic[i, j].add(w * 2)

three .add() calls, one per term of \(\text{linear}[i] \mathrel{+}= -w,\ \text{linear}[j] \mathrel{+}= -w,\ \text{quadratic}[i,j] \mathrel{+}= 2w\). .add() is what makes this loop correct: a node touched by several edges accumulates a -w contribution from each one, and = would let the last edge silently overwrite every edge before it. Running examples/maxcut/runner.py --n 5 --seed 42 confirms the sign on the result – energy: -354 against cut_weight: 354 – matching the same “minimise the negative” pattern knapsack uses, for the same reason.

Coefficient access on a 2D model accepts (row, col) tuples in place of flat indices, for both linear and quadratic coordinates independently – see Inputs and Model Shape for the flattening XQCP applies; nothing about objective assignment changes once a coordinate is a tuple instead of an int.

Beyond Quadratic: model.reduce()

Everything above stops at degree two: one or two variables per term. model.reduce(var_a, var_b, p_aux) -> RegLoad is the only way past that. It performs a Rosenberg degree reduction: allocate one fresh auxiliary variable w at model.size, grow model.size by one, and add enforcement terms so w behaves as var_a AND var_b: p_aux * (x_a*x_b - 2*x_a*w - 2*x_b*w + 3*w), which is 0 when w == x_a AND x_b and strictly positive otherwise. It returns w as a RegLoad, an ordinary variable index you can use in a further quadratic term, or feed into a second reduce() call to reach one degree higher still:

w = problem.model.reduce(ti, tj, p_aux)
problem.model.quadratic[w, tk].add(coeff)   # coeff * x_i * x_j * x_k

examples/cubic_opt/runner.py builds a cubic term this way, one reduce() call per term inside a problem.range() loop; max3sat and portfolio_opt use the same one-call pattern for their own cubic terms. examples/quartic_opt/runner.py chains two reduce() calls to reach a quartic term – the reason reduce() returns a RegLoad rather than nothing.

p_aux is a penalty in its own right, separate from any constraint penalty in the same model: it has to be large enough that violating the w == x_a AND x_b relationship is never worth it, the same reasoning Constraints applies to constraint penalties. Each reduce() call that actually executes grows model.size by one, so the final variable count is size plus the number of reduce() calls executed – loops included. cubic_opt allocates one auxiliary variable per cubic term inside its loop, not one for the whole model.

reduce() hangs off model, like every constraint form, but it is not one: XQCP keeps it out of the DSL’s constraint bookkeeping deliberately, since it is a structural transformation of the model, not a domain rule about a solution. That is also why it lives on this page and not Constraints.

How Large an Objective Gets

An objective’s magnitude is bounded by what its coefficients can sum to. Knapsack’s linear coefficients are -values, so its objective ranges from 0 (nothing selected) down to -49 for values = [5, 4, 18, 3, 19] (everything selected, which for this instance fits the capacity: the weights [2, 1, 5, 4, 4] sum to 16, under the capacity of 18) – a range fixed entirely by the problem’s own numbers, before any constraint enters the picture. Constraints picks a penalty weight relative to a range like this one; this page stops at producing the range, not sizing anything against it.

With an objective in place, the next step most problems need is a rule the objective alone cannot express – see Constraints for folding one into the same Hamiltonian.

Constraints

A constraint is a rule a solution must obey. XQCP has no separate mechanism for rules – every constraint call turns into a penalty term added to the model’s Hamiltonian, the same H Quadratic Models describes. This page covers the constraint forms the DSL exposes, when to reach for each, and how to size the penalty weight in practice. For the linear/quadratic coefficient deltas each opcode produces, see High-Level Constraints; this page does not repeat that table.

Every constraint method hangs off problem.model, the ModelRef that define_model() makes available, and every one takes a penalty argument.

The Constraint Forms

onehot_row/onehot_col, exclude and implies take coordinates directly; on a 2D model those coordinates can be (row, col) tuples, flattened automatically. equality, atleast, atleastw and inequality instead take two vector registers built with problem.vec() and .push(): indices names which variables participate, coeffs (where present) weights them.

A minimal \(2 \times 2\) grid problem exercises the row/column/pairwise forms together:

problem.define_model(size=n * n, domain=Domain.BINARY, rows=n, cols=n)
with problem.range(0, n) as r:
    problem.model.apply_onehot_row(r, penalty=50)
with problem.range(0, n) as c:
    problem.model.apply_onehot_col(c, penalty=50)
problem.model.apply_exclude((0, 0), (1, 1), penalty=50)
problem.model.apply_implies((0, 1), (1, 0), penalty=50)

rows and cols on define_model are what make the two one-hot forms legal. Omit them and every apply_onehot_row/apply_onehot_col call raises InvalidGridDimensions at run time – xquad vm check cannot catch it, because grid extents are runtime values. The product rows * cols must also fit inside size; a grid cannot describe cells the model never declared. atleast, atleastw and inequality append slack variables past the grid and only ever grow size, so they never invalidate a grid that was legal when it was set.

Compiling and running this for n = 2 produces a model whose linear and quadratic maps match the row/column penalties plus the two pairwise terms:

linear:    {0: -100, 1: -50, 2: -100, 3: -100}
quadratic: {(0, 1): 100, (0, 2): 100, (0, 3): 50, (1, 2): -50, (1, 3): 100, (2, 3): 100}

atleast and atleastw allocate slack variables and grow model.size directly, as part of their own expansion – ATLEAST’s own expansion in HLF.md builds the slack terms itself rather than composing with the SLACK instruction below. That is a real difference, not an implementation detail: SLACK takes no model operand and only appends to the indices/coeffs vectors it is given, so it never touches model.size by itself. A problem.slack() call grows the model only later and indirectly, when a subsequent apply_equality() widens it to max(indices) + 1 – a problem.slack() result that apply_equality() never consumes leaves the model unchanged. Each atleast/atleastw call, by contrast, allocates floor(log2(max_excess)) + 1 slack variables, where max_excess is N - k for atleast and sum(coeffs) - k for atleastw, and zero slack variables when max_excess is zero or less. A 3-item apply_atleast(idx, 2, penalty=30) allocates one slack variable, since max_excess = 3 - 2 = 1. apply_atleastw(idx, coeffs, 3, penalty=30) on the same three indices then allocates zero more for coeffs = [1, 1, 1], one more for coeffs = [1, 1, 2], or two more for coeffs = [1, 2, 3].

Turning an Inequality into an Equality

None of the forms above is <= or >= on a plain sum – atleast/atleastw cover >=, but a capacity constraint like knapsack’s (“total weight at most W”) needs the other direction. problem.slack() bridges the gap: it appends binary-weighted slack variables to an indices/coeffs pair so that an EQUALITY constraint over the combined vector is satisfiable exactly when the original inequality holds. See SLACK for the bit-width formula.

examples/knapsack/runner.py builds its capacity constraint this way:

indices = problem.vec()
coeffs = problem.vec()
with problem.range(0, num_items) as i:
    indices.push(i)
    coeffs.push(weights_in.get(i))

problem.slack(indices, coeffs, num_items, capacity_in)
problem.model.apply_equality(indices, coeffs, capacity_in, 100)

indices/coeffs start as the item weights, one entry per item. slack appends slack variables starting at index num_items (the model’s current size) sized to absorb up to capacity_in of unused capacity. apply_equality then constrains sum(weight_i * x_i) + sum(slack bits) == capacity. If the items sum to less than capacity, some slack combination fills the gap exactly. If they sum to more, no slack combination can, because slack only adds. The compiled encoder shows the two instructions back to back:

LOAD r0
LOAD r3
SLACK r7 r8

LOAD r3
PUSH 0x64
EQUALITY r4 r7 r8

model.apply_inequality(indices, coeffs, num_items, capacity_in, 100) composes exactly these two calls into one and produces the same model. Reach for the two-call form when you need indices/coeffs for something else afterward, or want the two steps visible; reach for apply_inequality otherwise.

Why the Reported Energy Is Not Just -total_value

EQUALITY’s expansion adds penalty * a_k * (a_k - 2b) and 2 * penalty * a_k * a_m terms but drops the constant penalty * b^2, since it shifts every assignment’s energy equally and does not change which one is optimal – see HLF.md. Dropping a constant from the model does not drop it from ENERGY’s result: a feasible sample still carries -penalty * b^2 as a fixed offset, because the terms that remain evaluate to exactly that once the constraint holds.

Running examples/knapsack/runner.py --seed 42 selects items worth 46 in total against a capacity of 18, at penalty = 100, and reports energy = -32446. That is -46 - 100 * 18^2 = -46 - 32400 = -32446: the objective contribution and the constant the equality constraint leaves behind, added together. Objectives isolates the -46 on its own; this is where the other -32400 comes from.

Choosing a Penalty Weight

Quadratic Models gives a safe upper bound: penalty must exceed the largest objective improvement any violating assignment can buy over the best feasible one. It is not the tightest bound – an equality-shaped violation (equality, one-hot, atleast, atleastw) with integer excess d actually pays penalty * d^2, and exclude/implies pay penalty outright, the d = 1 case. The rest of this section finds that tighter threshold by accounting for d directly.

Enumerate the Failure, Not the Intuition

Take a 4-item knapsack: weights [3, 4, 5, 2], values [4, 5, 6, 3], capacity 7. The best feasible selection is items {0, 1} or {2, 3}, tied at value 9 and weight 7. Every selection that exceeds capacity is a candidate the solver might prefer instead, if the penalty is too cheap. Seven of the sixteen selections exceed it:

The last column is value gap / excess^2, because EQUALITY’s penalty term is penalty * (sum - target)^2: a selection exceeding capacity by d pays penalty * d^2, not penalty. The largest entry in that column, not the largest value gap, sets the threshold: {0, 2} needs penalty > 1, the largest threshold in the table, while {0, 1, 2, 3} – the biggest value gain – needs only penalty > 0.18, because its excess of 7 is squared away. Reasoning from the value gap alone (9, from the worst offender by value) is safe, but it oversizes the weight here: the raw gap suggests penalty > 9, nine times the penalty > 1 this problem actually needs.

Compiling this exact problem and brute-forcing every assignment of the real QUBO – 4 item variables plus the 3 slack bits SLACK allocates for a capacity of 7 – confirms the table: at penalty = 1, the true optimum is a three-way tie at H = -58 between the two feasible sets and the infeasible {0, 2}; at penalty = 2, only the two feasible sets remain, both at H = -107. penalty = 1 is the exact boundary the table predicts, not an approximation of it.

A tie at the boundary is not a tie a sampler breaks the same way every seed. Sampling this exact model at penalty = 1 with SolverCPU (200 reads) across eight seeds returns the infeasible {0, 2} on two of the eight, at the identical energy, -58, as every feasible seed; the other six split across the two feasible ties. A single feasible sample at a borderline weight is not evidence the weight is safe – the tie means either outcome is a true optimum, and only the rate across repeated solves, each with a different solver seed, separates a weight sitting on the boundary from one below it. A penalty that is actually below its threshold, rather than sitting on it, behaves differently: building a second 4-item instance (weights [5, 4, 2, 5], values [7, 4, 3, 9], capacity 6) whose tightest threshold works out to penalty > 3, the identical penalty = 1 is now strictly below it, and all eight seeds return the infeasible pick, every time, because there the infeasible assignment is the unique optimum rather than one member of a tie.

When You Cannot Enumerate

Most problems are too large to brute-force. Enumerate a small instance of the same shape if you can, the way the table above does, since the qualitative lesson – the tightest violator, not the most valuable one, sets the threshold – carries over. When even that is impractical, a safe but loose fallback exists for a purely linear objective: since each variable contributes to it at most once, no two full assignments can differ by more than the sum of the absolute values of every linear coefficient, and any nonzero integer excess is at least 1, so penalty greater than that sum always rejects every violation. A quadratic objective needs the same sum extended to include the absolute value of every quadratic coefficient too, since a quadratic[i,j] term can also flip between two assignments. For the table above that sum is 4 + 5 + 6 + 3 = 18, eighteen times the actual boundary of 1 – a real bound, not the largest single coefficient, and worth using only until you can afford to enumerate a representative case.

The seed-42 knapsack run printed in One Problem, Once has values [5, 4, 18, 3, 19], and knapsack’s objective is -values (see Objectives), so the same fallback sum is 5 + 4 + 18 + 3 + 19 = 49. The runner’s own penalty = 100 clears that sum outright, so it is safe by this loose bound alone, without needing the per-instance enumeration this page otherwise recommends.

Too High Does Not Corrupt the Model

Raising penalty from 2 to 1000 on the same problem leaves the gap between the best and second-best true optimum at exactly 1 in both cases, for the reason Quadratic Models gives: the penalty term is zero on every feasible assignment, so it cannot change their relative order.

What a large penalty costs instead happens outside the model, on the hardware that has to represent it – see Energy and Precision for that trade-off, and Selection Under Budget for a worked recipe built on this page.

Control Flow

XQCP gives you four constructs for anything beyond a flat sequence of calls: problem.range(), problem.iter(), problem.branch(), and problem.stow(). Each is a Python API you call while building a Problem, and each records something into the action list that compile() later turns into real XQVM instructions. That gap between the two is the first thing to get straight, because it decides what each construct actually buys you.

A Python Loop and a Compiled Loop Are Different Things

xqcp is a Python program that runs once, when you call problem.compile(), to produce an .xqasm string. An ordinary Python for loop inside your problem definition runs during that one recording pass – it does not exist in the output at all. Three plain calls to add(1) inside for i in range(3) record three separate add_linear actions, one per concrete index, and the compiled encoder shows exactly that: no loop instruction, three ADDLINE blocks back to back.

for i in range(3):
    problem.model.linear[i].add(1)

PUSH 0
PUSH 1
ADDLINE r1
PUSH 1
PUSH 1
ADDLINE r1
PUSH 2
PUSH 1
ADDLINE r1

problem.range() is different: it records one RANGE loop that the VM executes at run time, over a count that need not be known until calldata arrives. with problem.range(0, num_items) as i compiles to a single RANGE/NEXT pair regardless of how large num_items turns out to be, because num_items is a runtime input, not a Python integer the recorder can unroll:

with problem.range(0, num_items) as i:
    vi = problem.stow("vi", values_in.get(i))
    problem.model.linear[i].add(-vi)

PUSH 0
LOAD r0
RANGE
  LVAL r5
  LOAD r5
  VECGET r2
  STOW r6
  LOAD r5
  LOAD r6
  NEG
  ADDLINE r4
NEXT

This is examples/knapsack/runner.py’s objective loop, unaltered. Use a plain Python loop only when the count is fixed at problem-definition time and small; use problem.range() whenever the count depends on an input, which is the common case, since num_items in this example is not known until calldata is set.

range – Counted Loops

problem.range(start, end) is a context manager yielding a LoopVar. It records a range_start action on entry and a range_end action on exit, and compiles to RANGE/NEXT around whatever the body records. The bounds can be any expression, not just literals or inputs – problem.range(i + 1, n) inside another range(0, n) builds the upper-triangular pattern a pairwise comparison needs, one RANGE nested inside another:

with problem.range(0, n) as i:
    with problem.range(i + 1, n) as j:
        problem.model.quadratic[i, j].add(1)

For n = 3 this adds quadratic[i, j] += 1 for every pair with i < j: (0, 1), (0, 2), (1, 2), each exactly once, matching what running the compiled encoder against n = 3 produces. RANGE is documented at the instruction level in Loops, where it pops count and start, not start and an exclusive end. problem.range(start, end) takes the exclusive end a Python range would; the compiler emits the subtraction that turns it into a count, so a non-zero start shows a SUB before RANGE – compiling problem.range(2, 5) emits PUSH 2 / PUSH 5 / PUSH 2 / SUB / RANGE. A start of 0 hides this, because end and count coincide there, so every RANGE listing so far in this chapter shows no SUB.

iter – Looping Over a Vector’s Elements

problem.iter(vec, start, end) loops over a slice of a vector’s actual elements rather than a count, compiling to ITER/NEXT. It always yields a pair, (idx, val): the element’s absolute position in the vector and its value. Unpack whichever you need and discard the other with _:

with problem.iter(weights, 0, n) as (idx, val):
    problem.model.linear[idx].add(val)

Running this against weights = [7, 8, 9] produces linear = {0: 7, 1: 8, 2: 9} – idx supplies the coordinate, val the weight added there. The compiled form pairs LIDX/LVAL inside the loop body with exactly this reading:

PUSH 0
LOAD r0
ITER r1
  LIDX r3
  LVAL r4
  LOAD r3
  LOAD r4
  ADDLINE r2
NEXT

Reach for iter when the loop body needs the element’s value directly and would otherwise call vec.get(idx) on every iteration; reach for range when the body needs an index into something other than the vector being walked, the way knapsack’s objective loop above indexes values_in by position rather than walking it as a slice.

stow – Carrying State Across Iterations

Expressions covers what problem.stow(name, expr) does and why knapsack’s objective loop uses it once per iteration. Inside range and iter, stow has a second job: passing an existing RegLoad back into it, instead of a name, reuses that RegLoad’s register rather than allocating a new one, which is how a loop carries an accumulator from one iteration to the next:

acc = problem.stow("acc", 0)
with problem.range(0, n) as i:
    problem.stow(acc, acc + i)
problem.model.linear[0].add(acc)

The compiled loop body reads and writes the same register, r2, on every iteration, and running it for n = 4 leaves linear[0] = 6 – 0 + 1 + 2 + 3:

PUSH 0
STOW r2
PUSH 0
LOAD r0
RANGE
  LVAL r3
  LOAD r2
  LOAD r3
  ADD
  STOW r2
NEXT

branch – Conditional Terms

problem.branch(cond1, body1, cond2, body2, ..., default) compiles to a chain of JUMPI/JUMP/TARGET with first-match semantics. branch tests conditions in order and runs the first true arm’s body; no later arm runs, even one whose condition is also true. The final argument is mandatory and has no condition – pass a callable for a default action, or None to do nothing when no arm matches.

with problem.range(0, n) as i:
    w = problem.stow("w", weights.get(i))
    problem.branch(
        w > 5, lambda: problem.model.linear[i].add(w * 10),
        w > 0, lambda: problem.model.linear[i].add(w),
        None,
    )

LOAD r4
PUSH 5
GT
NOT
JUMPI .1
  LOAD r3
  LOAD r4
  PUSH 10
  MUL
  ADDLINE r2
  JUMP .0
TARGET .1
LOAD r4
PUSH 0
GT
NOT
JUMPI .2
  LOAD r3
  LOAD r4
  ADDLINE r2
  JUMP .0
TARGET .2
TARGET .0

Each condition compiles to itself negated, then a JUMPI past its arm: w > 5 becomes NOT then JUMPI .1, so the arm runs when the condition is true and is skipped straight to TARGET .1 when it is false. An arm that runs ends with JUMP .0, past every remaining arm, which is what makes the semantics first-match rather than last-match. The default arm has no condition and no skip logic – it just falls through to TARGET .0 if reached.

Each body is a zero-argument callable, called once while recording, under the same recording pass a range body runs under, so it can reference i and w from the enclosing scope. Running this for weights = [7, 3, 0] adds 70 at index 0 (7 > 5), 3 at index 1 (3 > 5 is false, 3 > 0 is true), and nothing at index 2 (neither condition holds, and the default is None): linear = {0: 70, 1: 3}, with index 2 absent rather than zero.

Nesting and Ordering

range and iter nest to arbitrary depth, matching the nesting Loops documents at the instruction level: LVAL, LIDX and NEXT always act on the innermost active loop. branch arms can themselves contain range, iter, or further branch calls, since a body callable can record anything a top-level problem definition can.

The encoder splits body actions into an objective block and a constraint block by scanning for constraint calls – see Compiling for that partition. A range or iter body is recorded flatly, so a nested constraint call is still visible to the scan. A branch arm is captured separately: a constraint call made only inside one still constrains the model, but prints under ; === Objective === instead of ; === Constraints ===. Call constraint methods directly inside the enclosing range instead, the way examples/set_cover/runner.py does, if you want the section comment to match.

Outputs and Decoding

A solver hands back a sample: one raw value per variable. Decoding turns that assignment into the answer your problem is actually about – a chosen item set, for knapsack. This page covers a decoder program’s outputs, its read access to the sample, and when decoding outside the VM makes more sense.

Declaring an Output

problem.output(name, type=Types.Vec, length=None) declares one decoder output and returns an OutputRef. type must be Types.Vec – every pipeline output is a vector, and problem.output() raises TypeError for anything else. An output is filled one of two ways, chosen by length=.

Appending

Without length=, an output starts empty and .append(value) grows it by one element:

selected = problem.output("selected", type=Types.Vec)
with problem.range(0, num_items) as i:
    selected.append(problem.sample.getline(i))

This is examples/knapsack/runner.py’s decoder in full: one output, selected, filled by reading the sample’s per-item assignment directly. problem.sample.getline(i) reads sample[i]: 1 if the solver selected item i, 0 otherwise. selected ends up the same shape as the input item list, a 0/1 flag per item rather than a list of chosen indices. Compiled, this is the decoder assembly Compiling shows in full: VECI r2 ; selected, a RANGE loop reading GETLINE r0 and pushing with VECPUSH r2, then PUSH 0 / OUTPUT r2.

Writing and Reading by Index

With length=, the decoder starts the output as length zeros, and you write and read it by index: out[i] = value compiles to VECSET, and out[i] to VECGET. Use it when a value’s position is computed rather than reached in order. On the grid examples/tsp/runner.py builds, one row per city and one column per position, rowfind gives the position a city was placed at, so the tour can be written city by city:

tour = problem.output("tour", type=Types.Vec, length=n)
with problem.range(0, n) as city:
    tour[problem.sample.rowfind(row=city, value=1)] = city

length is anything the decoder can evaluate before its first loop: a literal, the scalar on calldata slot 1, arithmetic over those, or a sample read. Slots you never write stay 0. An out[i] read returns an expression, so one output can feed another:

flags = problem.output("flags", type=Types.Vec, length=n)
scores = problem.output("scores", type=Types.Vec)
with problem.range(0, n) as i:
    flags[i] = problem.sample.getline(i)
with problem.range(0, n) as i:
    scores.append(flags[i] * 10 + i)

Record-Time Checks

The two modes do not mix, and both are checked when you write the problem, not when the decoder runs. out[i] = value or out[i] on an output without length= raises

TypeError: Writing to output 'selected' by index needs a declared length; declare it with problem.output('selected', length=n), or fill it with selected.append(value)

(Reading from for a read), and .append() on an output with length= raises

TypeError: Output 'tour' was declared with length= and is filled by index; write tour[i] = value instead of tour.append(value)

A literal length= below 1 raises ValueError, and so does a literal index outside [0, length) when length= is a literal too. A length= that reads another output, such as length=counts[0], raises ValueError as well: every length is evaluated before any output is filled, so it would read 0. Any other index is bounds-checked by the VM when the decoder runs, which faults with IndexOutOfBounds. A length that evaluates to 0 or less at decode time leaves the output empty, so the first index write faults the same way.

problem.output() must be called at the top level. Inside a problem.range() or problem.iter() block, or inside a branch() arm, it raises RuntimeError at once:

RuntimeError: problem.output('o') is called inside a range() or iter() block; declare every output at the top level, outside every loop and branch() arm

Reading a Sample

problem.sample is available once define_model() has run, and exposes seven read methods built on the Grid Operations and Coefficient Access instructions a Sample register supports:

getline and value differ only on a model declared with lo=/hi=, where the stored variable is y = x - lo and value(i) adds lo back to give the x you wrote coefficients over. Everywhere else they are the same call. getline is the only raw reader and value the only shifted one, so nothing shifts unless you ask.

case(v) is rowfind(v, 1) under a name that says what it means on a categorical model: the case variable v took, or -1 where the solver left that row empty. It reads the same on any 2D binary grid, whether or not Domain.CATEGORICAL built it.

Knapsack’s flat model only needs getline. A 2D grid model – one variable per (row, col) pair, the way a one-hot assignment problem is usually shaped – more often needs colfind: “which row has a 1 in this column” reads directly as “which choice was made for this slot.” On a \(2 \times 2\) grid sample with rows [0, 1] and [1, 0], sample.colfind(col=0, value=1) returns 1 (row 1 has the 1 in column 0) and sample.colfind(col=1, value=1) returns 0, each call compiling to the column pushed, then the value to match, then COLFIND r{sample}.

What a Decoder Block May Reference

Everything recorded after the first problem.output() call goes to the decoder and to nothing else, and the decoder is a separate program with a separate register file. It runs on two pieces of calldata: the sample on slot 0, and one scalar on slot 1. Anything a decoder block names that is not reachable from those two is refused at compile() rather than compiled into a read of whatever register happens to hold something.

A block may reference the sample through the read methods above, its own loop variables, one scalar, and out[i] on an output declared with length=. That scalar does not have to be N: examples/graph_coloring/runner.py stows a total variable count before declaring its output and passes that on slot 1. The emitted decoder names which one it resolved, so INPUT r1 ; total_vars tells you what the caller has to supply. Naming a second one raises, because the decoder is handed exactly one and cannot say which of the two you meant:

RuntimeError: xqcp: a decoder block references two scalars, 'n' and 'acc', but the decoder is handed exactly one on calldata slot 1

What a block may not reference is anything the decoder was never given: a vector input or a problem.vec() allocation, a model coefficient (problem.model.linear[i] – the decoder holds the sample, not the model), or a loop variable from a loop that has closed. problem.iter() is refused for the same reason: ITER walks a vector register, and no input vector reaches the decoder. Walk the indices with problem.range() and read each one from problem.sample.

Filling Outputs in Any Order

The decoder allocates every output before it runs anything else and ships every output to its slot after everything else has run. Between those, it walks every action recorded after the first problem.output() once, in the order you recorded them. An output can therefore be filled from any point after its declaration: two outputs from one loop, or an earlier output after a later one has been declared.

chosen = problem.output("chosen", type=Types.Vec)
weights = problem.output("weights", type=Types.Vec)
with problem.range(0, num_items) as i:
    chosen.append(problem.sample.getline(i))
    weights.append(problem.sample.getline(i) * 2)

Conditional Outputs

problem.branch() works after the first problem.output(), with the same first-match arms it has in the encoder. Conditions read the sample, loop variables and the scalar, like any other decoder expression. This keeps only the indices of the selected items instead of a flag per item:

picked = problem.output("picked", type=Types.Vec)
with problem.range(0, num_items) as i:
    problem.branch(
        problem.sample.getline(i) == 1, lambda: picked.append(i),
        None,
    )

With items 0, 3 and 4 selected out of five, picked decodes to [0, 3, 4]. An arm takes everything else a decoder block takes: .append(), out[i] = value, a problem.range() loop, and a nested problem.branch().

The Decoder Program vs. Decoding in the Host

Once a solver returns a sample, two different things can decode it, and they are not the same operation.

The decoder program is XQVM bytecode: vm.run(programs.decoder) with the sample and N on calldata, exactly like running the encoder or the verifier. It only ever sees the sample through the instructions above, so it runs on any surface that can execute XQVM bytecode – Ways to Use XQuad lists six – with no Python or Rust object model required at the call site.

Decoding in the host means reading the sample object directly in whatever language is driving the pipeline, without running the decoder program at all. In Python, a solved sample is an XqmxSample, so sample.get_linear(i) for each item index reads the same assignments sample.getline(i) does inside the decoder, just from host code instead of from bytecode:

vm.set_calldata([sample, n])
vm.set_output_slots(1)
vm.run(programs.decoder)
result = vm.outputs()[0]

decoder_selection = list(result)                            # via programs.decoder
host_selection = [sample.get_linear(i) for i in range(n)]   # direct read

VM imports from xquad.vm, alongside the xquad.cp/xquad.types imports Inputs and Model Shape opens this chapter with. set_output_slots has to run before vm.run, since the slot count defaults to 0. OUTPUT against a slot that was never allocated raises OutputIndex while the decoder runs.

vm.outputs()[0] comes back as a plain list of int. Both reads of the seed-42 knapsack sample (weights = [2, 1, 5, 4, 4], values = [5, 4, 18, 3, 19], capacity = 18) produce the same list: [1, 1, 1, 0, 1]. Host decoding is less code for a one-off script already holding the sample in memory. The decoder program is the version worth keeping once decoding needs to happen the same way regardless of which language or environment is driving the run, or needs to be inspected and verified as an artifact in its own right the way the encoder and verifier already are.

Where This Page Stops

Decoding turns a sample into an answer; it says nothing about whether that answer is any good. valid and energy come from the verifier, not the decoder – see Compiling for what a verifier’s validity check does and does not cover. Choosing a solver and judging solution quality belong to Solving Overview and Running Programs, not here.

Compiling

problem.compile() walks the action list problem.define_model(), your objective terms, your constraints and problem.output() recorded, and returns CompiledPrograms(encoder, verifier, decoder) – three .xqasm strings. Three Programs covers why the split exists and what each program is for; this page covers what compile() actually emits and how to read it when something is wrong.

Three Independent Passes

compile() runs three separate compiler functions over the same action list, each keeping a different subset. Nothing computed for one program carries into another; there is no shared intermediate representation.

Compiling examples/knapsack/runner.py’s build_problem() – the exact code from Constraints, unaltered – produces this encoder:

; === Inputs ===
PUSH 0
INPUT r0
PUSH 1
INPUT r1
PUSH 2
INPUT r2
PUSH 3
INPUT r3

; === Allocations ===
LOAD r0
BQMX r4

; === Objective ===
PUSH 0
LOAD r0
RANGE
  LVAL r5
  LOAD r5
  VECGET r2
  STOW r6
  LOAD r5
  LOAD r6
  NEG
  ADDLINE r4
NEXT
VEC r7
VEC r8
PUSH 0
LOAD r0
RANGE
  LVAL r9
  LOAD r9
  VECPUSH r7
  LOAD r9
  VECGET r1
  VECPUSH r8
NEXT
LOAD r0
LOAD r3
SLACK r7 r8

; === Constraints ===
LOAD r3
PUSH 0x64
EQUALITY r4 r7 r8

; === Output ===
PUSH 0
OUTPUT r4
HALT

PUSH 0x64 is 100, the penalty passed to apply_equality – the compiler renders a handful of common penalty values in hex for readability; every other constant here prints in decimal.

This is the encoder for the exact problem shape examples/knapsack/runner.py builds, independent of the item count: register numbers and instruction count come from how many input(), stow(), vec() and define_model() calls the Python code makes, not from --n at the command line.

What compile_encoder Does

Per spec/xqcp/COMPILER.md, the encoder partitions the action list into inputs, the model allocation, and a body that splits again into objective and constraint blocks: a top-level block is a constraint block if it contains any of onehot_row/onehot_col/exclude/implies/equality/atleast/atleastw/inequality, otherwise it is objective. ; === Objective === and ; === Constraints === are these two blocks, in that order, regardless of the order you wrote them in Python. Knapsack’s objective loop and the SLACK call both come from code written before apply_equality, and neither one is itself a constraint action, so the encoder above places both in the objective section (see Control Flow for the one case, a constraint call inside a branch arm, where this partition surprises). The output section is fixed: PUSH 0 / OUTPUT r{model} / HALT, since an encoder’s only output, always on slot 0, is the model it built.

Register allocation is one incrementing counter shared across the whole program. spec/xqcp/COMPILER.md fixes the order. Inputs go first. A 2D model’s cols register comes ahead of the model register; a 1D model has no cols register, so its model register follows the inputs directly. Loop variables, stowed values, vec() registers and output registers fill in afterward, each claiming a register in the order it is called. Knapsack’s model is 1D: its four inputs claim r0-r3, the model claims r4, and everything after follows call order – r5/r6 for the objective loop’s LoopVar and stow, r7/r8 for the two vec() calls. Inputs and Model Shape shows the 2D case, where the cols register lands before the model register: one input at r0, cols at r1, model at r2. Going past r255 raises RuntimeError at compile time, before any assembly is generated.

What compile_verifier and compile_decoder Do

The verifier replays the encoder. A constraint’s operands – the index and coefficient vectors an apply_equality was handed – are register handles, not data: those vectors are built by VECPUSH instructions that run inside the encoder at VM runtime, often nested in loops. A separate program with its own register file cannot inherit them. So the verifier re-executes the encoder’s inputs, loops, stows, branches and vector construction, drops every model mutation, and emits a check of the sample in place of each constraint, at the same point in the stream. Its register and vector state at each constraint site is then identical to the encoder’s.

That is why the verifier keeps the encoder’s register numbers instead of starting a fixed layout of its own, and why it takes the encoder’s calldata. It claims eight registers above the encoder’s high-water mark: the sample, the valid flag, energy, the model’s declared size, a weighted-sum accumulator, an ITER position, an element, and a counter tracking the index each REDUCE would have allocated. Going past r255 raises RuntimeError at compile time.

Knapsack’s encoder stops at r11, so its verifier’s sample lands on r12 and its valid flag on r13:

; === Inputs ===
PUSH 0
INPUT r0
PUSH 1
INPUT r1
PUSH 2
INPUT r2
PUSH 3
INPUT r3
PUSH 4
INPUT r4
PUSH 5
INPUT r12

; === Model shape ===
LOAD r0
STOW r15

; === Validity checks ===
PUSH 1
STOW r13

; Check every declared variable is in the model's domain
PUSH 0
LOAD r15
RANGE
  LVAL r17
  LOAD r17
  GETLINE r12
  COPY
  PUSH 0
  EQ
  SWAP
  PUSH 1
  EQ
  OR
  LOAD r13
  AND
  STOW r13
NEXT

; === Objective (replayed for state, not for energy) ===
PUSH 0
LOAD r0
RANGE
  LVAL r5
  LOAD r5
  VECGET r2
  STOW r6
NEXT
VEC r7
VEC r8
PUSH 0
LOAD r0
RANGE
  LVAL r9
  LOAD r9
  VECPUSH r7
  LOAD r9
  VECGET r1
  VECPUSH r8
NEXT

; === Constraints ===
PUSH 0
STOW r16
PUSH 0
VECLEN r7
ITER r7
  LIDX r17
  LVAL r18
  LOAD r17
  VECGET r8
  LOAD r18
  GETLINE r12
  MUL
  LOAD r16
  ADD
  STOW r16
NEXT
LOAD r16
LOAD r3
LTE
LOAD r13
AND
STOW r13

; === Energy ===
ENERGY r4 r12
STOW r14

; === Output ===
PUSH 0
OUTPUT r14
PUSH 1
OUTPUT r13
HALT

Three things in that listing are worth reading closely. The model is INPUT into r4, the register the encoder allocated it to, so replayed references resolve without a renumbering pass; BQMX is skipped, but the size expression is replayed and stowed because the domain check needs the bound. The objective loop stowing r6 has no effect on the outcome and runs anyway – a later constraint could read that register, and the replay does not try to work out which stows matter. And the capacity check reads LTE, not EQ: knapsack builds its constraint with slack() followed by apply_equality, and a slack-extended equality is an inequality over the real variables. The SLACK instruction is not replayed, so r7 and r8 hold the four item entries and no slack entries.

The domain check runs to the model’s declared size, r15, replayed from define_model. Slack and REDUCE auxiliary variables live past that size and are not domain-checked. A SPIN model is checked against -1 and +1 instead of 0 and 1; the binary-only constraint kinds – onehot_row, onehot_col, exclude, implies – raise at compile time on a spin model rather than emit a check that does not mean anything there.

The decoder puts the sample on r0 and N on r1, allocates every output vector with VECI under one ; === Decode === header, walks everything recorded after the first problem.output() call, then ships every output with PUSH {slot} / OUTPUT r{out} under one ; === Output === header. Inside the decoder, every scalar reference – an input the encoder read, or a value problem.stow() put in a register – resolves to LOAD r1, because one scalar is all the decoder is handed:

; === Inputs ===
PUSH 0
INPUT r0
PUSH 1
INPUT r1  ; num_items

; === Decode ===
VECI r2  ; selected
PUSH 0
LOAD r1
RANGE
  LVAL r10
  LOAD r10
  GETLINE r0
  VECPUSH r2
NEXT

; === Output ===
PUSH 0
OUTPUT r2
HALT

num_items in with problem.range(0, num_items) as i is an InputRef in the encoder, so in the decoder it becomes LOAD r1, the same register slot 1 was read into two lines above – the decoder has no independent notion of num_items, only of the one scalar it is passed. Which scalar that is, is the program’s choice rather than a fixed N, and the header comment names it. Referencing a second, distinct scalar is rejected at compile(); see Outputs and Decoding for the full list of what a decoder block may and may not name.

The Calldata and Output Contract

Each program’s calldata order and output slots are fixed by what it was compiled from, and a host has to match them exactly:

examples/knapsack/runner.py’s run() function drives exactly this contract: vm.set_calldata([n, weights, values, capacity]) and vm.set_output_slots(1) before the encoder, matching the four problem.input() calls in build_problem() in order and the encoder’s one output slot; vm.set_calldata([n, weights, values, capacity, model, sample]) and vm.set_output_slots(2) before the verifier; vm.set_calldata([sample, n]) and vm.set_output_slots(1) before the decoder. The output slot count defaults to 0; running a program that executes OUTPUT against a slot that was never allocated raises OutputIndex (see Limits and Errors).

Problem.verifier_calldata() returns that order as a list of names – ["num_items", "weights", "values", "capacity", "model", "sample"] for knapsack – so a host can zip its own values against it rather than rebuilding the order from the problem definition.

Inspecting the Emitted Assembly

programs.encoder, programs.verifier and programs.decoder are plain Python strings – printing one is the fastest way to see what a problem definition actually compiled to, which is how every listing on this page was produced. From there, the xquad CLI static-inspects a single program without needing a Python host at all: xquad vm asm and xquad vm dis round-trip a .xqasm file to bytecode and back to a readable listing, and xquad vm check runs the same structural, jump-target, loop-nesting, register type-state and stack-depth checks problem.compile() already runs automatically through xqffi when that package is installed. See CLI for the full command reference; nothing about compiling changes it.

xquad vm check and xquad vm dis work on any of the three programs as they stand, but xquad vm run does not, because none of the three programs’ inputs are all plain integers – the encoder above needs two vectors on calldata positions 1 and 2, and the CLI’s --calldata flag only accepts a comma-separated list of i64s. Handing it integers where a program expects a vector does not fail to parse; it fails at run time, once the program tries to use the value:

$ xquad vm run --text knapsack.encoder.xqasm --calldata 2,10,20,5
Error: run failed: RegisterType { reg: 2, expected: "vec<int>", got: "int" }

Running any of these three programs against real calldata needs a host that can construct vectors, models and samples – the Python VM/Program surfaces Ways to Use XQuad describes, covered in full in Running Programs. The CLI’s role here is static: assemble, disassemble, and verify a program’s structure before handing it to a host that can supply calldata rich enough to run it.

Running Programs

This page covers driving an already-compiled .xqasm or .xqb program from Python: loading it, supplying calldata, running it, and reading outputs back. Ways to Use XQuad names the surfaces; this page is the full coverage for three of them: xquad.program, and the two VM wrappers underneath and alongside it. For writing a problem with the xqcp DSL, see Modelling. For what xquad vm check checks and how to fix a rejected program, see Verification.

All three surfaces run the same Rust xqvm interpreter, and every example on this page runs as shown.

Program and Session

xquad.program.Program loads a program once; Program.session() gives you a Session you call .run() on repeatedly, each time with fresh calldata. Each run returns a RunResult with dict-keyed outputs, the residual stack, and the step count:

from xquad.program import Program

src = """
PUSH 0
INPUT r0
PUSH 1
INPUT r1
LOAD r0
LOAD r1
ADD
STOW r2
PUSH 0
OUTPUT r2
HALT
"""

program = Program.from_source(src)
assert program.instruction_count == 11
assert program.source is not None   # retained for debugging

session = program.session(output_slots=4)
session.set_calldata([40, 2])
result = session.run()

assert dict(result.outputs) == {0: 42, 1: None, 2: None, 3: None}
assert result.stack == []
assert result.steps == 11

# Re-run with different calldata -- sessions carry no hidden state.
session.set_calldata([100, 200])
assert dict(session.run().outputs) == {0: 300, 1: None, 2: None, 3: None}

RunResult.outputs is a dict keyed by slot index; a slot the program never wrote reads as None rather than raising. Program is immutable and reusable; Session carries the mutable calldata and output-slot count. Deriving a second Session from the same Program gives you two runners that share no state.

Step limits

Session.set_step_limit(n) caps how many instructions a run may execute before run() raises. The limit is exact: 0 permits no instructions at all. A fresh Session starts at xquad.vm.DEFAULT_STEP_LIMIT, which is 10,000,000. None is the only unbounded spelling, and a caller has to write it – unbounded execution is asked for, never inherited.

A run that faults raises the xqffi.vm.XqvmError subclass named for the fault – here StepLimitExceeded – with the fault’s description as its message. XqvmError is a RuntimeError.

from xqffi.vm import StepLimitExceeded

session = program.session(output_slots=1)
session.set_calldata([1, 2])
assert "step_limit=10000000" in repr(session)

session.set_step_limit(3)
try:
    session.run()
except StepLimitExceeded as e:
    print(e)
# step charge of 1 exceeds the step limit of 3 (3 steps already charged)

# 0 is not a sentinel for "unlimited" -- it executes nothing, so this
# 11-step program fails at its first instruction.
session.set_step_limit(0)
try:
    session.run()
except StepLimitExceeded:
    pass

# None removes the bound. A program that never halts will not return,
# and it does not take SIGALRM: the GIL is held inside the Rust run.
session.set_step_limit(None)
assert "step_limit=unlimited" in repr(session)
assert dict(session.run().outputs) == {0: 3}

A budget that exactly covers the program succeeds. This one needs 11 steps, so set_step_limit(11) runs it and set_step_limit(10) does not.

Loading bytecode directly

Program.load(bytes) parses raw wire-format bytes – a .xqb blob produced by xquad vm asm or by program.bytecode(). No source is retained:

blob = program.bytecode()
reloaded = Program.load(blob)
assert reloaded.source is None
assert reloaded.instruction_count == program.instruction_count

Program.load never validates its input; a malformed blob decodes successfully as a Program object and only fails once a Session tries to run it. A one-byte blob is too short even for the wire-format header:

p = Program.load(b"\x43")
s = p.session()
try:
    s.run()
except RuntimeError as e:
    print(e)
# decode error: XQBC header is truncated

Program.from_source validates at load time instead: an unassemblable string raises ValueError immediately, before a Session exists.

Calldata types

A calldata list may mix any of int, list[int], xqffi.vm.XqmxModel, xqffi.vm.XqmxSample, and None (unset). Session.set_calldata checks every element’s type as soon as you call it, not at run time:

from xqffi.vm import (
    Domain,
    IndexOutOfBounds,
    InvalidGridDimensions,
    XqmxModel,
    XqmxSample,
)

model = XqmxModel.binary(size=4)   # or XqmxModel(Domain.BINARY, size=4)
model.set_linear(0, -1)
model.set_quad(0, 1, 2)

sample = XqmxSample.spin(values=[-1, 1, -1, 1])

session.set_calldata([model, sample, [1, 2, 3], 42])
# session.run() now sees four typed input slots.

try:
    XqmxModel.binary(size=4, rows=2, cols=3)
except InvalidGridDimensions as e:
    print(e)
# a 2 x 3 grid does not fit 4 variables; rows and cols must both be 0,
# or both positive with rows * cols <= size

try:
    session.set_calldata([object()])
except TypeError as e:
    print(e)
# unsupported calldata element type: object; expected int, list[int],
# XqmxModel, XqmxSample, or None

The constructors also refuse a size over xqffi.vm.MAX_ALLOCATION_SIZE, the largest allocation bytecode can make, with InvalidAllocation, and XqmxSample refuses a value outside its domain with ValueError. The coefficient accessors (set_linear, get_linear, set_quad, get_quad) raise IndexOutOfBounds for a variable index outside 0..size, a negative index included. InvalidAllocation, InvalidGridDimensions and IndexOutOfBounds are XqvmError faults, so RuntimeError subclasses:

try:
    model.set_linear(4, 1)
except IndexOutOfBounds as e:
    print(e)
# index 4 out of bounds (len 4)

Inspecting a model or sample

XqmxModel and XqmxSample are pyo3 objects; there is no dict-conversion helper in this package today. Read a model’s coefficients through its own accessors:

model = XqmxModel.binary(size=4)
model.set_linear(0, -1)
model.set_linear(2, 3)
model.add_quad(0, 1, 2)

model.domain          # Domain.BINARY
model.domain.name     # "binary"
model.size            # 4
list(model.linear_items())     # [(0, -1), (2, 3)]
list(model.quadratic_items())  # [((0, 1), 2)]
model.get_linear(0)   # -1
model.get_quad(0, 1)  # 2
repr(model)            # 'XqmxModel(domain=binary, size=4)'

model.energy(XqmxSample.binary([1, 1, 0, 0]))  # 1, as ENERGY computes it

add_linear and add_quad accumulate into a coefficient and raise xqffi.vm.ArithmeticOverflow, leaving the model unchanged, if the result leaves the signed 64-bit range. A sample’s values are checked against its domain when it is constructed; XqmxSample.binary([2]) raises ValueError.

__repr__ is intentionally minimal. To inspect every coefficient or serialise a model, iterate linear_items() and quadratic_items().

The other two VM surfaces

Two lower-level wrappers sit underneath and alongside xquad.program, both worth knowing about directly.

xqffi.vm.Vm is the thinnest possible wrapper over the Rust interpreter: construct it, call set_calldata / set_output_slots, call .run(bytecode), read .outputs() as a positional list. .reset() clears the stack, registers, loop stack, and step counter, but calldata and output slots are untouched by it – both persist across runs until you call set_calldata() or set_output_slots() again. It is what Session.run() builds internally:

from xqffi.vm import Vm

vm_src = "PUSH 7\nPUSH 5\nADD\nSTOW r0\nPUSH 0\nOUTPUT r0\nHALT\n"
bytecode = Program.from_source(vm_src).bytecode()

vm = Vm()
vm.set_output_slots(1)
vm.run(bytecode)
assert vm.outputs() == [12]

Ways to Use XQuad covers when to reach for it directly instead of Session.

xquad.vm.VM is a separate wrapper that every example runner under examples/ actually uses (examples/maxcut/runner.py, examples/knapsack/runner.py). It wraps xqffi.vm.Vm and runs .xqasm source text directly, assembling it on each run(); run_bytecode() takes pre-assembled bytes instead:

from xquad.vm import VM

src = "PUSH 7\nPUSH 5\nADD\nSTOW r0\nPUSH 0\nOUTPUT r0\nHALT\n"
v = VM()
v.set_output_slots(1)
v.run(src)
assert v.outputs() == [12]
assert v.stack() == []

VM keeps calldata, output slots, and the step and memory limits across runs until reset(), but resets the machine before every run, so no stack or register state leaks from one run into the next. VM.outputs() returns the same XqmxModel / XqmxSample objects as xqffi.vm.Vm.outputs() and Session.run().outputs. Pick VM when you run .xqasm source from a script and want the settings to carry across runs; pick Session for the dict-keyed, slot-sparse ergonomics shown above; pick xqffi.vm.Vm only if you are building your own layer on top of the raw Rust FFI.

VM.set_calldata() stores a copy of the list it is given, holding the same objects, and checks nothing itself, because the values check themselves. An XqmxSample raises ValueError when it is built with a value outside its domain, and again when such a value is written to it, so no out-of-domain sample can reach run(). The element types are checked at run(): anything other than an int, a list[int], an XqmxModel, an XqmxSample or None raises TypeError there. A program that writes an out-of-domain value with SETLINE or ADDLINE faults with SampleOutOfDomain, an XqvmError.

A complete run across three programs

A compiled problem is three independent programs – see Three Programs for why. Driving all three from xquad.program looks like this, using the exact build_problem function examples/knapsack/runner.py defines (see Compiling for what compile() emits):

from examples.knapsack.runner import build_problem
from xquad.program import Program
from xqffi.vm import XqmxSample

n = 4
weights = [2, 3, 4, 5]
values = [3, 4, 5, 8]
capacity = 8

problem = build_problem(n, weights, values, capacity)
programs = problem.compile()

# Encoder: inputs in, model out.
encoder = Program.from_source(programs.encoder)
enc_session = encoder.session(output_slots=1)
enc_session.set_calldata([n, weights, values, capacity])
model = enc_session.run().outputs[0]

# A hand-picked sample -- items 1, 2, 3 selected, no solver involved.
sample = XqmxSample.binary(values=[0, 1, 1, 1, 0, 0, 0, 0])

# Verifier: the encoder's own inputs, then model and sample; (energy, valid) out.
verifier = Program.from_source(programs.verifier)
ver_session = verifier.session(output_slots=2)
ver_session.set_calldata([n, weights, values, capacity, model, sample])
ver_result = ver_session.run()
energy, valid = ver_result.outputs[0], ver_result.outputs[1]

# Decoder: sample + N in, decoded selection out.
decoder = Program.from_source(programs.decoder)
dec_session = decoder.session(output_slots=1)
dec_session.set_calldata([sample, n])
selected = dec_session.run().outputs[0]

assert (energy, valid, selected) == (-4817, 0, [0, 1, 1, 1])

Items 1, 2 and 3 weigh 3 + 4 + 5 = 12 against a capacity of 8, so the sample violates the capacity constraint and valid comes back 0. energy is still computed: ENERGY recomputes the objective whatever the sample’s feasibility, so the two outputs answer different questions. Swap in [1, 1, 0, 0, 0, 0, 0, 0] – items 0 and 1, weighing 5 – and the same run gives (-5507, 1). Verification says what valid covers.

The verifier takes the encoder’s calldata because it replays the encoder to rebuild the constraint data, then appends the model and the sample. Each program’s own .set_calldata order and .set_output_slots count are fixed by what it was compiled from – Compiling has the full table. A real pipeline replaces the hand-picked sample above with xqsa.build_solver(...).solve(model).sample; see Solving Overview.

What this page does not cover

• Tracing. Step-by-step execution inspection is not part of Session today.
• Keyword calldata (session.set_calldata(n=4, ...)). Session takes a positional list only; there is no input-slot labelling to key against.
• A _repr_html_ for notebooks. __repr__ is the only representation Program, Session, RunResult, XqmxModel and XqmxSample provide.
• A to_numpy() helper. Convert via linear_items() / quadratic_items() and numpy.asarray(...) on your own side; this package does not carry a numpy dependency.

Verification

xquad vm check rejects a program before it runs, printing the first structural or semantic problem the bytecode verifier finds. This page takes you from that message to a working program. Verifier is the reference half, covering what each phase checks and what every error means. This page does not repeat that; it shows each error actually firing and what to change.

xquad vm check --text file.xqasm assembles the source in memory and verifies the result; xquad vm check file.xqb verifies pre-assembled bytecode. Both forms and their exit codes are covered in CLI: check; this page assumes you already know how to invoke it.

Reading an error

Every example below is the smallest program that reproduces its error, followed by the exact xquad vm check output it produces.

Structural errors

BadOpcode – a byte in the instruction stream does not map to any of the 93 known instructions. This cannot come from a .xqasm file the assembler accepted; it means a .xqb file was hand-edited or corrupted:

Error: check failed: BadOpcode: unknown opcode 0x0d at byte 0x0000

Fix: reassemble from source rather than editing bytecode by hand, and check the .xqb file was not truncated or modified in transit.

TruncatedInstruction – the byte stream ends partway through an instruction’s operand bytes. A PUSH1 opcode byte with no value byte after it triggers it:

Error: check failed: TruncatedInstruction: truncated instruction at byte 0x0000

Fix: same as BadOpcode – the .xqb file is not a complete, valid encoding. Reassemble it.

Jump-target and loop-nesting errors

UndefinedJumpTarget – a jump instruction’s label id is at or past the program’s target count. Text assembly cannot produce this: the assembler resolves every .N label reference against the labels actually defined in the source and refuses to emit a jump to one that does not exist – xqasm::undefined_label, at assemble time, before the verifier ever runs. UndefinedJumpTarget is a defense for bytecode assembled some other way, or corrupted after assembly: a jump instruction’s label-id byte, changed to a value the program’s target count does not cover, produces:

Error: check failed: UndefinedJumpTarget: jump at byte 0x0003 references undefined target label 5 (program has 1 targets)

Fix: this is not something valid .xqasm can trigger, so seeing it means the .xqb file in hand is not what the assembler produced. Reassemble from source.

NoActiveLoop – NEXT, LVAL, or LIDX appears with no RANGE or ITER open at that point:

NEXT
HALT

Error: check failed: NoActiveLoop: loop instruction at byte 0x0000 executed outside any active loop

Fix: every NEXT, LVAL, and LIDX needs an enclosing RANGE/ITER on every path that reaches it – check you have not placed one outside the loop body, or past a jump that skips the loop opener.

UnmatchedLoop – a RANGE or ITER opens with no matching NEXT before the program ends:

PUSH 0
PUSH 3
RANGE
HALT

Error: check failed: UnmatchedLoop: unmatched loop: RANGE/ITER at byte 0x0004 has no corresponding NEXT (1 loop(s) still open at end of program)

Fix: add the missing NEXT. If this program came from xqcp, it usually means a with problem.range(...) block (see Control Flow) whose body raised or returned before the DSL closed it correctly – check the generated .xqasm for the loop in question.

Register errors

ReadUnsetRegister – a register is read before anything writes it, or before every incoming control-flow path writes it (must-init analysis, phase 3, catches the second case even when phase 2’s type check alone would not):

LOAD r0
HALT

Error: check failed: ReadUnsetRegister: register r0 read at byte 0x0000 before being written

Fix: write the register before reading it. If the read follows a branch, confirm both arms write it – a register set on only one side of a conditional is ReadUnsetRegister at the first read after the join, even though nothing about the type looked wrong on either arm individually. DROP also resets a register to unset; a LOAD right after DROP on the same register fails the same way.

RegisterTypeMismatch – a register holds a RegVal variant other than the one the instruction needs. Here BQMX writes a Model, and LOAD only handles Int:

PUSH 4
BQMX r0
LOAD r0
HALT

Error: check failed: RegisterTypeMismatch: register r0 at byte 0x0004: expected int, got model

Fix: LOAD is for scalar integers. To move a Model out of a register for inspection or as another instruction’s operand, pass the register directly to an instruction that accepts Model (GETLINE, ENERGY, and others); do not route it through LOAD.

Stack-depth errors

StackUnderflow – a reachable instruction would pop more items than the analysis can prove are on the stack:

ADD
HALT

Error: check failed: StackUnderflow: stack underflow at byte 0x0000

Fix: push the operands an instruction needs before it runs. This same check also catches loop-related shortfalls; see the “does not guarantee” section below for its blind spot.

StackOverflowRisk – the analysis converges on a depth past the 8,192-item limit for some reachable block. A straight-line run of 8,200 PUSH instructions with no loop involved:

Error: check failed: StackOverflowRisk: potential stack overflow at byte 0x0000 (depth 8200)

Fix: this fires on a single basic block’s static depth, so the usual cause is building up a large flat structure with individual PUSH/VECPUSH calls rather than a loop. Reducing the item count, or restructuring the build as a loop the analysis can bound per iteration, both work; see the next section for why a loop is not automatically safe either.

LoopStackImbalance – a loop body’s net stack effect is non-zero: the depth the analysis computes at NEXT differs from the depth at the matching RANGE/ITER. An unmatched PUSH inside the loop body:

PUSH 0
PUSH 3
RANGE
PUSH 99
NEXT
HALT

Error: check failed: LoopStackImbalance: loop starting at byte 0x0004 has non-zero stack effect (entry depth 0, exit depth 1)

Fix: every value a loop body pushes needs a matching pop (directly, or via STOW into a register) before NEXT, so each iteration leaves the stack exactly as it found it. SCLR inside a loop body is a special case: it resets the tracked depth to zero unconditionally, so this error fires when the loop’s entry depth was already non-zero, not when the body’s depth before the reset was non-zero. If the entry depth was zero, the same reset can instead mask a real imbalance earlier in the body, and the mismatch surfaces later, at the next downstream join point, rather than here.

StackDepthMismatch – two control-flow paths reach the same join point with different stack depths, so the depth at that point is not well-defined. A conditional that pushes on only one arm:

PUSH 1
JUMPI .0
PUSH 2
.0: HALT

Error: check failed: StackDepthMismatch: stack depth mismatch at join point byte 0x0006: one path has depth 0, another has depth 1

Fix: make every arm of a branch leave the same stack depth before it rejoins. If only one arm pushes a value, move that push above the branch so both arms inherit it.

What passing verification does not guarantee

A pass means every phase’s static checks succeeded. It does not mean the program runs to completion. Verifier: what passing verification guarantees states the precise scope. Treat a pass as “structurally sound,” not as “will run to completion.”

A whole class of faults is outside the verifier’s reach: they depend on values, and the verifier tracks types and depths rather than values. An allocator size, a grid extent, a loop bound, a calldata index and every arithmetic operand are ordinary popped stack values, so InvalidAllocation, InvalidGridDimensions, InvalidIntegerK, ArithmeticOverflow, IndexOutOfBounds, SampleOutOfDomain, LoopStackOverflow, StepLimitExceeded and MemoryLimitExceeded are all runtime faults with no static counterpart. SampleOutOfDomain is the clearest case of why: the value written into a sample can arrive from calldata, so no amount of static analysis can know it. A verified program can still raise any of them, and for an embedder that is the point: the budgets and the range checks are what bound a program the verifier has already passed. See Limits and Errors.

The generated verifier program is not the bytecode verifier

xquad vm check and the verifier program are two different things that share a name by coincidence of vocabulary.

xquad vm check runs the bytecode verifier described above and in Verifier: a static analysis over any .xqasm or .xqb file, checking that the program is well-formed before anything executes. It has no idea what problem, if any, the program encodes.

A compiled problem’s verifier program is one of the three .xqasm outputs problem.compile() returns – see Three Programs and Compiling. It is an ordinary program like any other: xquad vm check can check it is well-formed, the same as it checks the encoder or the decoder. What the verifier program itself does at runtime – taking a model and a candidate sample as calldata and producing (energy, valid) – is domain logic the DSL emitted, unrelated to the bytecode verifier’s job. Running the verifier program does not verify a program in the bytecode-verifier sense, and running xquad vm check against the verifier program’s .xqasm text does not check whether a sample is a good answer.

What the generated verifier’s valid flag covers

valid is the conjunction of one check per constraint the problem declared, plus a domain check over every declared variable. A sample that violates an onehot_row, onehot_col, equality, inequality, atleast, atleastw, exclude, implies, or the Rosenberg auxiliary a reduce() allocated, comes back valid = 0. Compiling shows how each check is emitted.

The checks are over the variables the problem declared, not over the encoding. slack() extends an equality’s index vector with the encoder’s own variables; the verifier checks that constraint as sum <= bound over the real variables and leaves the slack bits unconstrained. Checking the expanded form instead would report valid = 0 for a feasible sample whose slack bits a solver happened to leave inconsistent, which on a settlement path means refusing to pay for a correct answer.

Two things valid = 1 does not claim. The domain check runs to the model’s declared size, so slack and REDUCE auxiliaries allocated past that size are not domain-checked. And valid says nothing about optimality: ENERGY recomputes the objective independently of where the sample came from, and a feasible sample can still be a poor one.

Solving Overview

Backends names the five solvers and what distinguishes them. This chapter covers each one in enough depth to run it: installation, parameters, and what its result actually contains.

xqsa is the package that does this. It defines one base class, Solver, and four classes built on it – SolverCPU, SolverGPU, SolverDWave, and SolverQuip – which cover the five backends: SolverGPU runs on either a CUDA or a Metal GPU, picked by its engine. A model built from xqcp or by hand in XQVM bytecode does not know or care which one samples it.

The Solver Interface

Every backend is called through the same single method:

class Solver:
    def solve(self, model: XqmxModel, **kwargs: Any) -> SolverResult: ...

model is an XqmxModel over the binary or spin domain. **kwargs override that solver’s constructor defaults for this call only – solver = SolverCPU(num_reads=100) then solver.solve(model, num_reads=500) runs 500 reads without building a new solver. On every backend except quip, a keyword the solver does not take raises TypeError instead of being ignored, so a typo such as num_raeds=500 fails loudly. solve() raises on failure (hardware unreachable, no embedding found, connection lost); it never returns a partial or empty result.

solve() is the same code for every backend except quip: it validates the model, runs the backend, recomputes the energy and assembles the result. A backend only supplies the part that turns a model into a sample, so the result has the same shape whichever one ran.

The return value is a frozen dataclass:

@dataclass(frozen=True)
class SolverResult:
    sample: XqmxSample
    energy: int
    timing: float
    metadata: dict[str, Any] = field(default_factory=dict)

sample is the solution, an XqmxSample with one value per variable. energy is the authoritative Hamiltonian energy. timing is wall-clock seconds spent solving. metadata holds what the run used, covered below.

energy is never the backend’s own reported value taken on faith. Every solve() recomputes it with the same integer formula the XQVM ENERGY opcode uses, over the model and the returned sample. See Energy and Precision for what that buys you and what it costs on hardware with limited precision.

metadata has exactly three keys on cpu, cuda, metal, and dwave:

result = SolverCPU(seed=42).solve(model)
result.metadata["params"]["algorithm"]
# 'sa'

Backend-specific detail lives under params, so code that reads seed and reads works on any of the four; see D-Wave QPU for what dwave puts there. quip is the exception: it returns a different set of keys entirely, with no seed, reads, or params; see Quip Network.

Picking a Backend by Name

build_solver constructs any of the five from a short string, so a caller – an example runner, a CLI flag, a script – can stay backend-agnostic:

from xqsa import SOLVERS, DEFAULT_SOLVER, build_solver

print(sorted(SOLVERS))
# ['cpu', 'cuda', 'dwave', 'metal', 'quip']
print(DEFAULT_SOLVER)
# cpu

solver = build_solver("cpu", seed=42)
result = solver.solve(model)

seed reaches the three classical simulated-annealing backends (cpu, cuda, metal) and is ignored for dwave (physical hardware has no seed) and quip (configured from the environment; the miner’s own randomness is out of the caller’s control).

The registry otherwise uses each backend’s own constructor defaults, with one exception: its cuda and metal entries raise num_reads to 200 and num_sweeps to 2000, rather than the 100 and 1000 the bare constructor defaults to. They build SolverGPU(engine="cuda", num_reads=200, num_sweeps=2000) and the same with engine="metal". Local Solvers has the constructor defaults for every backend.

Swapping Backends Without Changing the Model

This is the claim the whole toolchain rests on, so here it is checked rather than asserted. examples/maxcut/runner.py builds one Max-Cut model with xqcp, runs the encoder on the Rust XQVM, and samples the result with whichever solver --solver names, built through build_solver. Run it against two different backends – cpu (CPU simulated annealing, 100 reads and 1000 sweeps) and metal (an Apple Silicon GPU kernel, a different process on different hardware, and – per the registry’s override above – 200 reads and 2000 sweeps) – and nothing about the model or the encoder changes:

uv run python examples/maxcut/runner.py --n 6 --seed 42 --solver cpu
uv run python examples/maxcut/runner.py --n 6 --seed 42 --solver metal

Both print the same result: "energy": -571, "cut_weight": 571, "valid": 1, the identical partition. The encoder produced one QUBO; two unrelated solvers minimised it and agreed. That agreement is not guaranteed in general – a harder model can leave different backends in different local optima – but the model they were handed, and the verifier that checked what came back, never changed.

The Domain Every Backend Rejects

XQVM has three domains: binary, spin, and integer. Every current xqsa solver’s _validate_model() accepts binary and spin and raises ValueError on integer:

from xqsa import SolverCPU
from xquad.types import XqmxModel

model = XqmxModel.integer(size=3, k=4)
SolverCPU().solve(model)
# ValueError: Unsupported domain for solving: integer

An integer XqmxModel is a real thing you can build in XQVM bytecode today – see Three Domains – but nothing in this chapter can solve one. spec/xqsa/DOMAINS.md calls this “reserved”: a future solver may relax the check, but none of the current five does. Re-encoding the problem in binary or spin is the only route around it today.

Choosing Among the Rest

That baseline requirement – runs anywhere, needs nothing – is exactly DEFAULT_SOLVER: every other backend is worth comparing against cpu before you trust its answer.

Local Solvers

Three of the five backends run entirely on the machine calling them, using only local hardware and no account. cpu runs on the CPU; cuda and metal run custom simulated-annealing kernels on an NVIDIA or Apple Silicon GPU. The metal examples below ran for real, on an Apple Silicon Mac; no NVIDIA GPU was available while writing this chapter, so the cuda material comes from reading xqsa/inprocess/cuda.py rather than from execution.

SolverCPU: The Baseline

SolverCPU wraps dwave-samplers’ SimulatedAnnealingSampler. It needs only a CPU and no credentials, and that is exactly what makes cpu the xqsa.DEFAULT_SOLVER: every other backend in this chapter is worth comparing against it before you trust a faster or more exotic answer. It ships in the base package – pip install xqsa is enough.

from xqsa import SolverCPU
from xquad.types import XqmxModel

model = XqmxModel.binary(size=4)
model.set_linear(0, -1)
model.set_quad(0, 1, 2)

solver = SolverCPU(seed=42)
result = solver.solve(model)
print(result.energy, result.metadata)

Constructor parameters, all overridable per call via solve(**kwargs):

SolverCPU also takes algorithm, which is "sa" and has no other value yet. A misspelled parameter raises TypeError, whether you pass it to the constructor or to solve().

GPU Backends: SolverGPU

SolverGPU bypasses the D-Wave SDK entirely. It converts the model to a dense array and runs parallel-replica simulated annealing directly on the GPU, in custom CUDA or Metal kernels. engine picks which, and it is required: SolverGPU(engine="cuda") or SolverGPU(engine="metal"), which are what the cuda and metal names build. Picking between the CPU backend and either GPU engine is a performance question, not a correctness one – see Backends; all three run the identical annealing algorithm family, just on different processors.

Install the extra that matches your hardware:

pip install xqsa[cuda]     # NVIDIA GPU, CUDA 12.x driver
pip install xqsa[metal]    # Apple Silicon Mac with a Metal device

from xqsa import SolverGPU
from xquad.types import XqmxModel

model = XqmxModel.binary(size=4)
model.set_linear(0, -1)
model.set_quad(0, 1, 2)

solver = SolverGPU(engine="metal", algorithm="sa", num_reads=200, num_sweeps=2000, seed=42)
result = solver.solve(model)
print(result.energy)
# -1

Wall-clock result.timing is not shown here: it varies by roughly 2x between runs on identical hardware, so a single pasted number would read as a performance claim it cannot support. The Metal engine also supports algorithm="gibbs" (block Gibbs sampling over a greedy graph coloring of the coupling graph). Both algorithms produce correct output on real Metal hardware: xqsa/tests/test_gpu_validation.py checks each against models with a known exact ground state, plus a spin-glass model matched within 2% of the CPU reference energy, all six of which pass.

The CUDA engine supports only algorithm="sa" – CUDA has no Gibbs kernel. Any other algorithm raises ValueError saying it is not available in-process; further algorithms arrive with the solver binaries. See xqsa/inprocess/cuda.py for the implementation the rest of this section describes.

Every parameter except algorithm is overridable per call via solve(**kwargs). These are the constructor’s own defaults. xqsa.build_solver, the backend-agnostic constructor covered in Solving Overview, raises num_reads to 200 and num_sweeps to 2000 for both GPU engines instead of using these defaults.

The Metal engine computes coefficients in float32; the CUDA engine computes them in float64, end to end in its kernels. result.energy is always recomputed afterward in exact integer arithmetic on both, so either GPU run and a CPU run report the same authoritative energy regardless of which precision the search itself used. See Energy and Precision for what the float32 downcast costs the Metal engine and when it matters.

Driver Prerequisites

After installing, confirm the solver class constructs before building a model around it:

python -c "from xqsa import SolverGPU; SolverGPU(engine='cuda'); print('ok')"
python -c "from xqsa import SolverGPU; SolverGPU(engine='metal'); print('ok')"

Both raise ImportError with a pip install xqsa[...] hint if the extra is missing, and RuntimeError if the extra is installed but no matching GPU is detected – import xqsa itself never fails on a missing extra, only constructing the solver that needs it does.

D-Wave QPU

SolverDWave submits the model to a physical D-Wave Advantage quantum annealer over the D-Wave Leap cloud API. This page is derived from xqsa/inprocess/dwave.py and spec/xqsa/*; no D-Wave Leap account was available while writing it, so nothing on this page was run.

Credentials

Requires the [dwave] extra:

pip install xqsa[dwave]

SolverDWave() resolves an API token from the token= constructor argument first, then the DWAVE_API_TOKEN environment variable; with neither set, construction raises ValueError. An optional endpoint= or DWAVE_API_ENDPOINT overrides the default Leap API URL.

import os
os.environ["DWAVE_API_TOKEN"] = "your-leap-token"

from xqsa import SolverDWave
from xquad.types import XqmxModel

model = XqmxModel.binary(4)
model.set_linear(0, -1)
model.set_quad(0, 1, 2)

solver = SolverDWave()                           # auto-selects a Pegasus-topology Advantage system
result = solver.solve(model)
print(result.metadata["params"]["solver"])       # e.g. "Advantage_system5.4"
print(result.metadata["params"]["qpu_timing"])   # QPU timing breakdown from Leap

Pass solver="Advantage_system5.4" to target a specific system instead of the default Pegasus-topology filter. SolverDWave also takes mode, which is "qpu" and has no other value yet; hybrid modes are not available.

What Embedding Means

A D-Wave Advantage chip is not fully connected: each physical qubit couples only to a fixed, small set of neighbours defined by its Pegasus topology. Your model’s coupling graph is almost never a subgraph of that hardware graph directly. SolverDWave wraps the sampler in dwave.system.EmbeddingComposite, which finds a minor embedding: each logical variable maps to a chain of one or more physical qubits, wired together so the chain acts as a single variable by strongly coupling its members (chain_strength).

Problem size on real hardware is not simply “how many variables.” A densely coupled model needs longer chains to embed, chains compete for the chip’s limited qubits, and a model that does not embed at all raises rather than silently degrading. EmbeddingComposite handles the search automatically; there is no separate embedding step to call in xqsa. Contrast this with Quip Network, where SolverQuip requires an exact subgraph match onto a fixed topology and refuses to do this chain-based embedding at all.

Parameters

Everything except token, endpoint, and solver is overridable per call: solver.solve(model, annealing_time=100, chain_strength=2.0). chain_strength and auto_scale are the only Ocean sampling parameters xqsa forwards to the sampler, and only when set. Any other keyword raises TypeError instead of reaching the sampler unchecked.

How a QPU Result Differs

The result shape is the same SolverResult every backend returns, but two things are specific to this backend. result.energy is still recomputed by xqsa in exact integer arithmetic from the returned sample – the chip’s own reported energy is never trusted directly – but the sample search itself ran on physical hardware subject to analog noise and the embedding above, not an exact digital simulation. And result.metadata["params"] carries QPU-specific detail that the local backends do not report at all.

metadata has the same three keys as every backend except quip:

params["solver"] names the physical Advantage system that ran the job. params["qpu_timing"] is the timing breakdown Leap returns – a dict when present, with keys that come from Leap and are not fixed by xqsa, or None when the sampler response carries no timing info at all. params["raw_energy"] is the chip’s own reported energy, informational only.

result.timing covers the whole call, including converting the model to a BQM and the sample back, not only the round trip to Leap. See Solving Overview for the shape every backend shares.

Quip Network

SolverQuip is the one backend in this chapter that does not solve anything itself. It proposes the model as a job to the Quip Network’s QuantumComputeMempool pallet, waits for a miner – hardware it does not control, running an algorithm it does not choose – to solve it, and decodes whatever comes back as an XQMX sample.

This page is derived from xqsa/quip/, spec/xqsa/SOLVERS.md, and an internal contributor testing guide. The mechanism it describes has been exercised end to end against aglais, the public Quip test network. Your First Quip Job walks one job through it; Gaps lists what the figures there cannot promise.

Installation and Configuration

Requires the [quip] extra:

pip install "xquad[quip]"

The umbrella xquad package forwards [quip] to the matching xqsa extra, as it does [cuda], [dwave], and [metal]; with xqsa alone, pip install "xqsa[quip]" is the same install. The extra brings in substrate-interface (the chain RPC client), certifi (the CA bundle wss:// falls back to on a macOS Python with none), and quip-signer, a native extension providing the chain’s hybrid signature scheme (sr25519 plus FN-DSA-512), which substrate-interface alone cannot produce. quip-signer resolves a prebuilt wheel on Linux and builds from source with a local Rust toolchain on macOS and Windows. Both guards are lazy: import xqsa and every other solver in this chapter work without the extra installed; only constructing SolverQuip needs it.

Both the chain RPC connection over wss:// and the faucet request verify the certificate chain, host name and validity dates, and by default neither checks revocation (no CRL, no OCSP). To check revocation lists, pass an ssl.SSLContext as ssl_context to SolverQuip, SolverQuip.for_network or fund_from_faucet. Both clients then use it in place of the default CA-bundle context, reconnects and autofund included; it is ignored for ws:// and http:// URLs, and SolverQuip refuses it with an https:// RPC URL, whose transport cannot use it. The context replaces the default entirely, so it must carry its own trusted roots: on a macOS Python whose trust store is empty, load certifi’s bundle as below. A standard-library context checks only revocation lists you fetch and load yourself. With VERIFY_CRL_CHECK_LEAF, as below, it needs the list from each server certificate’s issuer; with VERIFY_CRL_CHECK_CHAIN, one for every certificate in each chain. One context serves both servers, so with autofund on, load the lists for the faucet’s issuer as well as the RPC node’s. A handshake missing a list it needs fails.

import ssl
import certifi
from xqsa.quip import SolverQuip

ctx = ssl.create_default_context(cafile=certifi.where())
ctx.load_verify_locations(cafile="issuer-crl.pem")  # a PEM CRL you fetched
ctx.verify_flags |= ssl.VERIFY_CRL_CHECK_LEAF
solver = SolverQuip.for_network("aglais", ssl_context=ctx)

A standard-library context cannot check OCSP, which needs a different TLS stack that fails closed when the check does not finish. Code that opens its own chain connection with connect in xqsa.quip.metadata passes a context through ws_options["sslopt"]["context"] instead.

Configuration resolves from constructor arguments first, then environment variables:

The signer comes from the first of these that is set: seed, keystore, QUIP_SIGNER_SEED, QUIP_KEYSTORE, the project account preference, the user account preference, then ~/.quip/keystore.json, created on first use. An explicit argument wins over the environment, so a keystore argument wins over an exported QUIP_SIGNER_SEED. spec_id and topology both default to chain state (DefaultIsingSpecId and DefaultTopology). spec_id is a constructor-only override with no environment variable. topology also reads QUIP_TOPOLOGY, accepts "native", and can be overridden per order; see The Topology Constraint.

The order options among these (reward, access, resolution, deadline_blocks, block_wait and topology) are client defaults. Every order create_order() builds inherits them, and create_order() or JobOrder.set() override them for that order. The quality floors (max_energy, min_solutions and min_diversity) exist per order only, never as client defaults. Job Orders covers each option, including the payout rules and access rules. delivery accepts only "OnChainOnly": the client has no subscriber for the ResultReady event the pallet’s Callback delivery emits when the order expires.

Before connecting, the constructor raises ValueError for a delivery other than "OnChainOnly", and for an access or resolution that is not one of the rules above. After connecting, it checks the default access against the chain’s allowlist limits. The remaining options are checked against the chain’s limits when an order is created.

Accounts

A keystore is an account: the file holds its 32-byte master seed in plain text, so treat it as the account itself and keep it out of version control. Each account level holds keystore files and an account preference:

The project level is the nearest .quip/ directory found walking up from the working directory, stopping below the home directory, so ~/.quip/ is never a project. A .quip/ owned by another user or writable by everyone is skipped, so a shared directory such as /tmp cannot choose the signer. A preference is the single line account = "<name>". A project preference may name a project or a user keystore, and a name present at both levels resolves to the project one; a user preference applies in every directory, so it names a user keystore. Account names are lowercase letters, digits, _ and -, at most 64 characters, starting with a letter or digit.

xqsa.quip.accounts manages them. Each call takes the level explicitly:

from xqsa.quip import create_account, resolve_accounts, use_account

create_account("work", level="user")
use_account("work", level="project")
print(resolve_accounts().in_effect)

create_account writes a keystore from a fresh seed, or from seed=, and refuses to replace one unless overwrite=True; with no name it writes default. At project level with no .quip/ found, it makes one in the working directory, and anything created under a project .quip/ also writes a .quip/.gitignore of * when there is none. use_account and clear_account set and remove a preference. resolve_accounts lists every keystore with its account and walks the signer order above, reporting the step in effect. Each step is a SignerSource, whose account_id is the 32-byte account of the keystore it points at, read from the account the keystore caches, so no seed is loaded; it is None for the seed steps and for a missing or unusable keystore. resolve_accounts never writes a file or reads a seed, so an unusable keystore or a broken preference is listed with the problem rather than raised. SolverQuip raises QuipSigningError only when such a step is the one it would sign with.

For reads that need no signer, pass read_only=True:

solver = SolverQuip.for_network("aglais", read_only=True)
print(solver.balance(account=address))  # SS58 text, 0x hex or bytes

A read-only client resolves no signer, so it never creates a keystore, and refuses seed and keystore. get_receipt, and list_orders, balance, reserved and order_slots given account=, work on it. Everything that signs, account, and those four without an account raise QuipSigningError.

A signing client reads its own account the same way:

solver = SolverQuip.for_network("aglais")
print(solver.account)
print(solver.balance(), solver.reserved(), solver.order_slots())

5FXRydTJYE4cPGBH9CSf3dyGvaJNnYATEZJMyFqMiLPHv9oc
0 0 (0, 32)

account is the signer’s account in SS58. balance() is the free balance in planck, which an order’s reward and fee are paid from. reserved() is the reserved balance: the chain reserves an order’s reward when it is proposed and releases it when a claim or a reclaim closes the order, and it includes anything else the runtime reserves. order_slots() returns (used, limit): the orders not yet closed, each holding a slot until a claim or a reclaim closes it, and the runtime’s MaxOrdersPerProposer, None when the runtime sets no cap. Each takes account= to read another account. xquad quip account show prints all four; see Accounts. (Captured on 2026-10-26 with a fresh, unfunded account.)

Named networks

SolverQuip.for_network(name, **kwargs) builds a solver from a named preset in xqsa.quip.networks instead of an explicit url:

SolverQuip.for_network("aglais")

Two presets are registered: aglais, the public test network, and devnet, the local Docker stack contributors run for offline testing. The RPC and faucet coordinates behind each preset live in xqsa.quip.networks, move with the deployment, and are corrected in patch releases. The test network’s own page, aglais.quip.network, publishes the current endpoints and the faucet; check the preset against it if a connection fails. The preset also names its network’s faucet, if it has one, which the solver uses unless faucet= names another; QUIP_FAUCET_URL does not override a preset.

A preset may also pin its network’s genesis hash and may have no faucet. With a pinned genesis, for_network() refuses a node that serves another chain with a QuipConnectionError naming both hashes. With no faucet, an account that cannot cover a quote is refused with a QuipSubmissionError that says <network> has no faucet; fund the account another way. Neither current preset does either: both name a faucet, and both leave the genesis open, because a test network relaunches with a new genesis. The Quip MainNet preset will pin its genesis and have no faucet.

Runtime compatibility

SolverQuip reads the runtime’s specVersion once, when it connects; a client that stays connected across an upgrade keeps the version it read until it reconnects. Runtime 119 renamed the order’s energy-ceiling field from min_energy_milli to max_energy_milli. xquad 0.4.5 and later send the ceiling as max_energy_milli only, so they need runtime 119 or later: on an older runtime the proposal fails to encode. xquad 0.4.2 and earlier cannot propose on 119.

ResolutionTopNWeighted needs runtime 119 or later. On an older runtime every order that uses it is refused before signing, because older runtimes weight the split by absolute energy, so a worse answer can take the larger share.

Moving a network to runtime 119 starts it afresh instead of upgrading it in place. Orders placed before the move do not carry over, so an order id recorded before it does not name the same order after it. aglais has run runtime 119 since its relaunch on 2026-10-15.

The signed-extension order comes from the chain’s metadata, not from a list in the client. At its first connect, SolverQuip checks that it can encode the extrinsic envelope and every signed extension the runtime declares, and every signature is checked against the runtime the same way. A runtime it cannot read or sign for raises QuipMetadataError: at connect, or at signing when the runtime changed under a live client, before anything is sent. The remedy is upgrading xquad; retrying the same node gives the same answer.

Every reconnect must reach the chain the first connection reached: a node that serves another genesis is refused with a QuipConnectionError naming both hashes. A reconnect checks the genesis only, and fails with QuipMetadataError only for a node whose metadata this client cannot read. A submit() that is settling a send stops at once on either fault and leaves the order sending (see Settling a send).

Each connection logs the network, runtime and genesis at INFO on the xqsa.quip logger, with reconnected to in place of connected to on a reconnect (captured on 2026-10-26):

connected to Quip aglais at wss://bootnode-1.aglais.quip.network:20049/rpc: specVersion 119, transactionVersion 7, genesis 0x542a9915acf840b8940d35ca6de242f669a0c6e3b40f9a8d8c14b9bf7b8ebecb

Job Lifecycle

Submitting an order calls propose_job, which reserves the full reward and emits a JobProposed event. Miners discover work only from that live event stream – there is no storage backfill, so a job proposed before a miner subscribed stays invisible to it. A miner that accepts solves it on its own hardware with its own algorithm and submits a solution.

The chain marks an order Expired at its effective expiry, or a few blocks later when many orders expire at once, and only a claim or a reclaim closes it. SolverQuip computes finality itself from block height instead of waiting for an OrderClosed event:

effective_expiry = min(created_at + deadline_blocks, first_solution_at + block_wait)

JobOrder.wait() and solve() poll until the chain head reaches that height. solve(model, **options) is create_order(model, **options).submit().wait() followed by decoding the answer into a SolverResult (see Metadata); unlike create_order(), it warns about an unknown option and drops it instead of raising. The order surface – drafts, quotes, receipts, reclaiming, and reading answers – is on Job Orders.

Only solve(), and the deprecated query(), reclaim on their own. When an order finalizes with zero solutions, they reclaim the reserved reward through reclaim_order and raise QuipJobFailedError, whose message says whether the reward was reclaimed or why it was not. JobOrder.wait(), JobOrder.best() and a receipt’s wait() never reclaim; call reclaim() on the order or its receipt.

The Topology Constraint

Real annealing hardware – and the miner fleet behind this network – has a fixed set of physical couplings. SolverQuip skips the chains and minor embedding that D-Wave QPU’s EmbeddingComposite builds, and instead requires subgraph placement: an injective variable-to-node mapping where every one of the model’s couplings maps onto a real hardware edge. A model whose coupling graph is not a subgraph of the target topology raises PlacementError, carrying the couplings that could not be placed. Placement is deterministic, computed from the model alone, so nothing about it needs to be persisted or looked up later.

The target topology is resolved once, at construction, from three sources in order: the topology= argument, the QUIP_TOPOLOGY environment variable, then the chain’s QuantumPow.DefaultTopology. Because the same topology shape hashes differently per deployment – each network’s allowed-value specifications fold into the hash – a hash from one Quip deployment is not portable to another. That is why nothing is pinned in the codebase: every source is deployment-local, and a topology that resolves from none of them raises rather than selecting a hash no chain would accept. QUIP_TOPOLOGY is the operator’s override for whichever chain they are pointed at, and targets a registered non-default topology without threading a constructor argument through. solve() does not check the resolved hash against QuantumPow.MineableTopologies. That set is the chain’s active mining set: it gates submit_proof, and so block production, not the compute mempool. An order carries its nodes, edges and coefficients inline and no topology hash at all, so the chain cannot perceive which topology an order was built against, and the solver fleet has no topology field to filter on. A topology that is registered but not mineable is proposed, matched and solved like any other.

Native topology mode

Passing topology="native" builds the topology from the model’s own variables and couplings instead of reading one from the chain. It is accepted on the constructor, as an order option on create_order() and JobOrder.set(), per call on solve() and the deprecated quote() and query(), and through QUIP_TOPOLOGY=native, matched without regard to case or surrounding whitespace:

result = solver.solve(model, topology="native")

The variables, after any BINARY-to-SPIN fold, are relabelled densely to 0..n-1, so placement is the identity and cannot raise PlacementError. No chain topology is read, and the native topology carries no allowed-value sets, so the allowed-value warning stays silent; the mempool never enforces those sets. mapping= has no hardware graph to target in this mode and raises ValueError. A per-call value overrides the constructor’s in either direction. A native order is as large as the model, so one over the mempool’s MaxNodes (5,000) or MaxEdges (50,000) raises EncodingError before it is quoted. The solver reads both bounds from the chain for each native order; a failed read raises QuipConnectionError.

Native mode narrows who can answer. A miner that cannot embed an arbitrary graph, such as a QPU-backed one, cannot solve these orders; the simulated-annealing miner fleet can. Native mode is never chosen automatically on PlacementError: a call that raises today would otherwise start proposing jobs and spending funds.

Coefficient Encoding

The normative rules for this section are Coefficient encoding and allowed values – the same URL EncodingError, the rounding warning, and the allowed-value warning below all carry.

XQMX coefficients are natural-scale integers. The pallet stores couplings and fields as milli-scale i32 values, read back on-chain as value / 1000. Confirmed directly from xqsa/quip/codec.py:

from xqsa.quip.codec import MILLI_SCALE, MAX_NATURAL_COEFFICIENT
print(MILLI_SCALE, MAX_NATURAL_COEFFICIENT)
# 1000 2147483

SolverQuip computes spin coefficients from the model, multiplies each by MILLI_SCALE, and rounds to the nearest integer milli value, ties to even. A coefficient finer than 1/1000 is therefore rounded, not refused. Each rounding moves a coefficient by at most 0.0005. SolverQuip reports the largest such error once per solver instance as a warnings.warn when the model is placed (by create_order(), a set() that places it again, or solve()), and on every result as metadata["quantization_error"]. A coefficient whose rounded milli value would overflow i32 still raises EncodingError. An energy ceiling (max_energy) on a rounded model warns as well, because the chain applies the ceiling to the rounded model; Energy and Precision explains the ceiling’s units.

Rounding changes only the model the miners search. result.energy is recomputed on your original model, so a returned sample is never scored against the rounded coefficients. The winning submission is still chosen by the chain’s energy on the rounded model; only the vectors inside it are re-scored on yours. quantization_error bounds each coefficient, not the energy: a sample’s energy can move by up to quantization_error times the number of nonzero terms. A model whose coefficients all round to zero raises EncodingError rather than proposing an empty order. A BINARY model with ordinary three-decimal weights is the common case: the basis change below divides each quadratic weight by 4, so 1.5 on x_0 and 0.001 on x_0 x_1 give a spin field of 0.75025, which encodes as 750.

MAX_NATURAL_COEFFICIENT is the exact ceiling only for a SPIN model, whose h/j coefficients pass through to the pallet unchanged. A BINARY model goes through a basis change first (s = 2x - 1, via dimod), which folds every quadratic coefficient into the linear field of both variables it touches: j_ij = b_ij / 4, and h_i = a_i / 2 + 1/4 * (sum of every quadratic coefficient incident on i). _to_milli() only ever sees these post-conversion values, so for a BINARY model the natural-scale ceiling moves in both directions from what the constant alone suggests:

• An isolated coefficient survives past MAX_NATURAL_COEFFICIENT: an isolated quadratic term up to about 8_589_934 (roughly 4x), an isolated linear term up to about 4_294_967 (roughly 2x).
• A high-degree variable can overflow well below it, because h_i aggregates a quarter of every incident quadratic term. Ten quadratic terms of 1_000_000 all touching variable 0 give h_0 = 2_500_000 – nowhere near MAX_NATURAL_COEFFICIENT – but its milli value, 2_500_000_000, exceeds i32 and raises EncodingError.

The error in that case reads h[0] = 2500000.0 overflows the encodable range, naming a linear field the caller never set directly; the actual cause is the aggregate of ten quadratic terms landing on variable 0 during the basis change. This is a range shift, not a precision loss – quarters and halves of integers are exact in floating point, and exact at 1/1000 milli scale too (0.25 becomes 250) – the stored value is correct, only the range it has to fit in moved.

Rescaling a model does not change its optimum (see Choosing a Penalty Weight), so an oversized coefficient is fixable by scaling the whole model down, not a hard ceiling on what you can express.

Each topology also declares an allowed-value set for its coefficients (the default plain-Ising spec allows {-1, 0, +1} for fields and {-1, +1} for couplings), but the pallet does not enforce it, so SolverQuip submits coefficients as-is. A miner matches jobs by an exact hash over the topology’s structure, not over the coefficient values, and real hardware rescales monotonically in any case. An out-of-spec coefficient produces a one-time warnings.warn, not a rejection.

Cost Model

A job costs two amounts, both in planck, the chain’s smallest denomination:

• The reward: the order’s reward, else the client’s reward, else QUIP_REWARD, else the chain’s MinReward. A reward below MinReward raises QuipOrderOptionError before anything is signed. propose_job reserves the reward from the caller’s account. A solved order’s reward is allocated to its winning solvers on chain and paid when one of them claims it; a receipt’s settlement() shows the split. An order that finalizes with no solutions can have its reward reclaimed, and solve() reclaims it itself, so a failed job costs the fee, not the reward.
• The transaction fee for propose_job, burned either way.

create_order(model).quote() prices an order without proposing it. It signs the propose_job extrinsic the order would submit, asks the chain for its fee through payment_queryInfo, and reads the account balance. Nothing is submitted and no nonce is consumed. submit() later sends the same signed extrinsic, re-signing only if the account’s nonce moved in between or half its inclusion window has passed (see Settling a send). quote() returns a JobQuote:

str(quote) renders a 72-column box: the network, account and block; the problem and where it was placed; the reward, fee and total in token units; then the balance, the shortfall and whether the account can afford the job. submit() and solve() build the same quote before proposing, log it at INFO on the xqsa.quip logger (also printing it to stderr when stderr is a terminal), and pass it to the autoconfirm and autofund gates. A field the solver could not read is left out of the box.

What each part of the price measures:

• The fee is metered. It comes from benchmarked weights plus the encoded length, so it grows with the model’s nodes and edges. It is small next to the reward. Fees are burned, not paid to the block author, and do not respond to congestion: the runtime’s fee multiplier is constant.
• The reward is arbitrary. MinReward is a round runtime constant that gates submissions. Nothing derives it from the cost of solving, yet it is nearly all of what a job costs.
• Solver compute is not metered. The runtime declares type VM = NoOpVm, so nothing on-chain executes or measures the miner’s work, and that work never enters the price.
• The token is subsidised. On aglais, AGLS comes free from the faucet and has no external price. autofund draws from the faucet for a short account, and fund_from_faucet(dest, url=...) requests one drip directly.

This page does not print a current figure, because every one of these amounts is live chain state; JobOrder.quote() reads it. For a dated figure from an observed job, see Your First Quip Job.

Metadata

SolverResult.metadata for quip carries nine keys, eight read from the order and one from the encoding:

best_energy_milli is milli-scale (see Coefficient Encoding) and is not directly comparable to result.energy, the authoritative natural-scale energy recomputed on your model; diffing the two without converting scale first will make a correct result look wrong.

metadata["solver"] here names the solver account that answered, not a piece of hardware – D-Wave QPU records the physical Advantage system that ran the job under metadata["params"]["solver"], so the same name refers to a different kind of thing depending on the backend.

solve() returns the leader’s best vector, the answer the chain pays for, rather than the best vector any solver stored. leader, leader_read and energy_matches_chain say whether that rule held or a fallback chose another vector; Reading the answer describes the rule and both fallbacks.

Failure Taxonomy

Sixteen exception classes cover this backend – one base class and fifteen concrete failures, spanning local encoding checks, order checks, the consent and funding gates, and network-dependent lifecycle failures. Fifteen are exported from xqsa.quip and xquad.sa.quip; the deprecated QuipUnconfirmedError still imports from both, with a warning, but import * does not bring it in:

The EncodingError emptiness check tests whether linear_items() and quadratic_items() are both empty. Both list nonzero terms only – an XqmxModel drops a term the moment its coefficient returns to 0 – so “has no terms” and “carries only zero terms” are the same condition, and an all-zero model never reaches the chain.

EncodingError and PlacementError can be raised entirely locally, before anything touches the network – they come from xqsa.quip.codec, the same module the coefficient encoding above uses. The one exception is the native size check, which reads MaxNodes and MaxEdges from the chain first; a failed read raises QuipConnectionError. QuipOrderOptionError and QuipCancelledError are also raised before anything is signed or proposed. The rest depend on chain state or the round trip completing.

Deprecated APIs

Each of these warns with a DeprecationWarning and is removed in v0.6.0:

solve() is not deprecated, and neither is a typed resolution= on solve(). The strict paths refuse what the deprecated ones accept: create_order() and JobOrder.set() raise TypeError for mode=, a raw chain dict, or an unknown option.

query() has no full replacement yet. A receipt follows an order on chain but cannot decode its answers onto your model, so from a session other than the one that submitted the order, query(order_id, model, ...) is still the only way to get a decoded SolverResult.

Python shows a DeprecationWarning by default only when the deprecated call is made from __main__: a script sees it, but a library calling the same API does not. Run with -W default::DeprecationWarning to see every one; each points at the calling line.

Gaps

Your First Quip Job now walks a funded job end to end with the numbers one run produced. What stays open is that those numbers move:

• MinReward is a runtime constant, not storage governance can set. It changes only with a runtime upgrade, with no extrinsic and no event. SolverQuip reads it live, so the toolchain follows a change; prose does not.
• The fee weights are benchmark output. Re-running the runtime’s benchmarks moves the fee for the same model.
• Congestion is not a cause. The fee multiplier is constant, so for a given model and the default reward, only an upgrade moves either figure. JobOrder.quote() is the only reading to trust at submission time.
• Timing and fleet behaviour are unmeasured. How long a job takes and how many miners answer it depend on the fleet at that moment; the tutorial reports one run, not a distribution.

Your First Quip Job

This page submits one job to aglais, the public Quip test network, from an empty account: define a four-city Travelling Salesman Problem in XQCP, run its encoder on the XQVM locally, and hand the resulting model to SolverQuip as a job order. Every output block below was captured from the code on this page, run against aglais on 2026-10-15 at runtime specVersion 119. Quip Network is the reference for the mechanism and Job Orders for the order surface; this page is the walkthrough.

Install

pip install "xquad[quip]"

The extra pulls in the chain client and quip-signer, the native extension that signs extrinsics. quip-signer ships a prebuilt wheel on Linux and builds from source with a local Rust toolchain on macOS and Windows.

Set Up an Account

xquad quip account show is the setup check: it prints the account in effect, where it comes from, and its balance. On a first run there is none. At a terminal it prints the guidance, then offers to create an account; the answer defaults to skip, and nothing is written until the last answer:

xquad quip --network aglais account show

No Quip account is set up.

No keystores found. Create one with `xquad quip account new`, or bring a seed with `xquad quip account import`.

Resolution order (the first match signs):

  1  QUIP_SIGNER_SEED     unset
  2  QUIP_KEYSTORE        unset
  3  project preference   unset
  4  user preference      unset
* 5  default              ~/.quip/keystore.json

Setting the account:

  xquad quip account use <name>             prefer <name> in this project, else for your user
  xquad quip account use <name> --global    prefer <name> for your user
  xquad quip account use --unset [--global] clear the preference at that level
  --keystore PATH, QUIP_KEYSTORE, QUIP_SIGNER_SEED override the preferences
Create one now? (new, import, skip) [skip]: skip

Answering new creates the account there and then. Off a terminal, or with --json, the command prints the same guidance as an error and exits 1 without asking or creating anything.

Create the account, then check it again:

xquad quip account new
xquad quip --network aglais account show

created default at the user level: ~/.quip/keystore.json
  5GGt9yK5EbpdQNv3fCnpZLo93DgL663VsT7VeS5ueJqNoaBD
it is the user default, which signs when nothing else is set
Account   5GGt9yK5EbpdQNv3fCnpZLo93DgL663VsT7VeS5ueJqNoaBD
Source    default keystore ~/.quip/keystore.json
Balance   0.000000000000 AGLS
Reserved  0.000000000000 AGLS
Orders    0 of 32 slots used

The keystore holds the account’s signing key. Keep the file: it is the account. It starts empty; Submit funds it from the faucet. These two blocks were captured on 2026-10-24, with a fresh account. The receipts further down came from a different, funded account, so their Account line is not the one shown here.

Build the Model

The model is the TSP example at n = 4, with a fixed distance matrix instead of a random one so the numbers below are reproducible. The encoder runs on your machine; nothing touches the network yet.

from xquad import cp
from xquad.vm import VM

n = 4
distances = [12, 30, 25, 18, 40, 22]  # xq_triu order: 0-1, 0-2, 1-2, 0-3, 1-3, 2-3

problem = cp.Problem("TSP")
num_cities = problem.input("num_cities", type=cp.Types.Int)
distance_matrix = problem.input("distance_matrix", type=cp.Types.Vec)
problem.define_model(size=num_cities * num_cities, domain=cp.Domain.BINARY, rows=num_cities, cols=num_cities)

with problem.range(0, num_cities - 1) as city_i:
    with problem.range(city_i + 1, num_cities) as city_j:
        dist = problem.stow("dist", distance_matrix.get(cp.xq_triu(city_i, city_j)))
        with problem.range(0, num_cities) as position:
            next_position = (position + 1) % num_cities
            problem.model.quadratic[(city_i, position), (city_j, next_position)].add(dist)
            problem.model.quadratic[(city_j, position), (city_i, next_position)].add(dist)

with problem.range(0, num_cities) as city:
    problem.model.apply_onehot_row(city, penalty=100)
with problem.range(0, num_cities) as position:
    problem.model.apply_onehot_col(position, penalty=100)

tour = problem.output("tour", type=cp.Types.Vec)
with problem.range(0, num_cities) as position:
    tour.append(problem.sample.colfind(col=position, value=1))

programs = problem.compile()

vm = VM()
vm.set_calldata([n, distances])
vm.set_output_slots(1)
vm.run(programs.encoder)
model = vm.outputs()[0]

model is a 16-variable BINARY XQMX: one variable per city and tour position.

Connect and Quote

from xquad import sa

solver = sa.quip.SolverQuip.for_network("aglais", topology="native")
order = solver.create_order(model)
print(order)
print(order.quote())

╭─ Job order (draft) ──────────────────────────────────────────────────╮
│ Network     aglais                                                   │
├──────────────────────────────────────────────────────────────────────┤
│ Model       16 variables, 96 couplings, binary                       │
│ Placed      native, 16 spins                                         │
├──────────────────────────────────────────────────────────────────────┤
│ Payout      single best                                              │
│ Access      open                                                     │
│ Floors      none                                                     │
│ Deadline    100 blocks                                               │
│ Block wait  10 blocks                                                │
│ Reward      1.000000000000 AGLS                                      │
├──────────────────────────────────────────────────────────────────────┤
│ Quote       not quoted                                               │
│ Receipt     not submitted                                            │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Job quote ──────────────────────────────────────────────────────────╮
│ Network     aglais                                                   │
│ Account     5DL9B7rhMw1cg7kXzqmdj5QZ1V67vBvfYPq2bTEgZfSXiBSJ         │
│ Quoted at   block 1896                                               │
├──────────────────────────────────────────────────────────────────────┤
│ Problem     16 variables -> 16 spins, 96 couplings                   │
│ Placed on   native                                                   │
├──────────────────────────────────────────────────────────────────────┤
│ Reward      1.000000000000 AGLS  refunded if unanswered              │
│ Fee         0.002011933394 AGLS  exact                               │
│ Total       1.002011933394 AGLS                                      │
╞══════════════════════════════════════════════════════════════════════╡
│ Balance     0.000000000000 AGLS                                      │
│ Shortfall   1.002011933394 AGLS                                      │
│ Affordable  no                                                       │
╰──────────────────────────────────────────────────────────────────────╯

Two arguments do the work:

• "aglais" selects the preset carrying the network’s RPC endpoint and faucet; see Named networks.
• topology="native" submits the order over the model’s own coupling graph. In the default mode, the placement search finds no embedding of this model in the network’s topology within its step budget and raises PlacementError; native mode skips placement. See Native topology mode.

create_order() places the model and returns a draft JobOrder with the client’s defaults: winner takes all, any solver may answer, no quality floors, a 100-block deadline and a 10-block wait after the first answer. Nothing has been signed or sent. Job Orders covers every option a draft takes.

No signer is passed, so SolverQuip signs with the account xquad quip account show reported. To use a different keystore, pass it:

solver = sa.quip.SolverQuip.for_network("aglais", keystore="~/.quip/work.json", topology="native")

quote() signs the order’s propose_job extrinsic and asks the chain what it would cost, without submitting anything. The returned JobQuote carries each amount in planck, the chain’s smallest unit, as reward_planck, fee_planck, total_planck, balance_planck and shortfall_planck; fee_exact says the fee came from the chain rather than a fallback estimate. The signature is kept, and submit() sends those same bytes.

What the figure means

As of 2026-10-15, at specVersion 119, a job costs 1 AGLS in reward plus about 0.0020 AGLS in fee: about 1.0020 AGLS in total. The reward is the chain’s MinReward, a runtime constant. It is charged to gate submissions and maps to no measured compute: the runtime declares type VM = NoOpVm, so the chain meters none of the solver’s work. The fee is metered, burned, and does not rise with congestion. AGLS on aglais comes free from the faucet. Both figures move when the runtime is upgraded, so read them from quote() rather than from this page.

Submit

order.submit()

╭─ Job quote ──────────────────────────────────────────────────────────╮
│ Network     aglais                                                   │
│ Account     5DL9B7rhMw1cg7kXzqmdj5QZ1V67vBvfYPq2bTEgZfSXiBSJ         │
│ Quoted at   block 1896                                               │
├──────────────────────────────────────────────────────────────────────┤
│ Problem     16 variables -> 16 spins, 96 couplings                   │
│ Placed on   native                                                   │
├──────────────────────────────────────────────────────────────────────┤
│ Reward      1.000000000000 AGLS  refunded if unanswered              │
│ Fee         0.002011933394 AGLS  exact                               │
│ Total       1.002011933394 AGLS                                      │
╞══════════════════════════════════════════════════════════════════════╡
│ Balance     0.000000000000 AGLS                                      │
│ Shortfall   1.002011933394 AGLS                                      │
│ Affordable  no                                                       │
╰──────────────────────────────────────────────────────────────────────╯

submit() quotes once more and shows that quote: it always goes to the xqsa.quip logger at INFO, and it is also printed when stderr is a terminal, as here. It then runs two gates with their defaults. autoconfirm=True accepts the price. The account is short, so autofund=True draws one drip of 10 AGLS from the faucet. Finally it sends the signed propose_job, which reserves the reward, and returns the order, now submitted, once the block holding it is finalized, a few blocks after it is included. The order is read-only from here: set(), quote() and submit() refuse it.

Read the Result

order.wait()
solution = order.best()
print(solution.energy)
print(solution.solver, solution.leader, solution.energy_milli)

vm = VM()
vm.set_calldata([solution.sample, n])
vm.set_output_slots(1)
vm.run(programs.decoder)
print(list(vm.outputs()[0]))

-696
5GqG8c8zWHX33ruGJX4FDokxCTFrASVi268einKJY1XnHNYn True -1790000
[0, 1, 3, 2]

wait() blocks until the order is final by block height. Here the first answer arrived six blocks after the order was included, and the order was final ten blocks later, at the end of its 10-block wait; the script returned about 122 seconds after it started.

• The decoded tour visits cities 0, 1, 3, 2 and returns to 0. Its length is 12 + 40 + 22 + 30 = 104. It is a valid tour but not the shortest: of the three distinct tours on four cities, 0, 1, 2, 3 is shortest, at 77, with energy -723. The network pays for the best answer it receives, not for the optimum, and here the two answers that arrived missed it. The one-call form below came back with the shortest tour.
• solution.energy is that length plus -800, the constant the eight one-hot penalties contribute at any valid assignment. It is recomputed on your model.
• best() returns the leader’s best vector: the answer from the solver the chain ranks first, and pays. solution.leader is True when that rule held; Reading the answer covers the cases where it falls back to another solver’s vector.
• energy_milli is the vector’s energy on the chain’s milli scale, in the SPIN basis, and is not comparable to solution.energy directly.

The order’s receipt shows what the chain recorded, including the fee and the payout:

print(order.receipt())

╭─ Job order 20 receipt ───────────────────────────────────────────────╮
│ Network     aglais                                                   │
│ Proposer    5DL9B7rhMw1cg7kXzqmdj5QZ1V67vBvfYPq2bTEgZfSXiBSJ         │
│ Submitted   block 1898, 2026-10-15 04:22:24 UTC                      │
├──────────────────────────────────────────────────────────────────────┤
│ Problem     16 spins, 96 couplings                                   │
│ Spec        0x8f46f3a31321d1d093314fc769c42cbe7a83d71a0b69e6571a0f68 │
│             e2a04067f0                                               │
├──────────────────────────────────────────────────────────────────────┤
│ Payout      single best                                              │
│ Access      open                                                     │
│ Floors      none                                                     │
│ Deadline    100 blocks                                               │
│ Block wait  10 blocks                                                │
│ Reward      1.000000000000 AGLS                                      │
├──────────────────────────────────────────────────────────────────────┤
│ Status      final                                                    │
│ Answers     2                                                        │
│ Leader      5GqG8c8zWHX33ruGJX4FDokxCTFrASVi268einKJY1XnHNYn         │
│ Energy      -1790                                                    │
╞══════════════════════════════════════════════════════════════════════╡
│ Fee         0.002011933394 AGLS                                      │
│ Winner      1.000000000000 AGLS, awaiting claim                      │
╰──────────────────────────────────────────────────────────────────────╯

Two solvers answered; the leader wins the whole reward, which it receives once a claim is made. The account now holds the drip less one job’s total.

The one-call form

solve() does all of the above in one call: it creates the order, submits it, waits, and returns the leader’s answer as a SolverResult, whose metadata names the order:

result = solver.solve(model)
print(result.energy)
print(result.metadata)

-723
{'order_id': 23, 'solver': '5GqG8c8zWHX33ruGJX4FDokxCTFrASVi268einKJY1XnHNYn', 'best_energy_milli': -1817000, 'energy_matches_chain': True, 'leader_read': True, 'leader': True, 'num_submissions': 1, 'num_solutions': 1, 'quantization_error': 0.0}

solve() prints the quote box the same way submit() does. Metadata explains each key.

Confirm Before Paying

autoconfirm=False asks on the terminal before anything is proposed. Answering anything but y raises QuipCancelledError, which carries the quote:

from xquad import sa

solver = sa.quip.SolverQuip.for_network("aglais", topology="native", autoconfirm=False)
try:
    result = solver.solve(model)
except sa.quip.QuipCancelledError as exc:
    print("cancelled:", exc)
    print(exc.quote.total_planck)

╭─ Job quote ──────────────────────────────────────────────────────────╮
│ Network     aglais                                                   │
│ Account     5DL9B7rhMw1cg7kXzqmdj5QZ1V67vBvfYPq2bTEgZfSXiBSJ         │
│ Quoted at   block 1952                                               │
├──────────────────────────────────────────────────────────────────────┤
│ Problem     16 variables -> 16 spins, 96 couplings                   │
│ Placed on   native                                                   │
├──────────────────────────────────────────────────────────────────────┤
│ Reward      1.000000000000 AGLS  refunded if unanswered              │
│ Fee         0.002011933394 AGLS  exact                               │
│ Total       1.002011933394 AGLS                                      │
╞══════════════════════════════════════════════════════════════════════╡
│ Balance     4.989940332991 AGLS                                      │
│ Shortfall   0.000000000000 AGLS                                      │
│ Affordable  yes                                                      │
╰──────────────────────────────────────────────────────────────────────╯
[quip] Submit this job for 1.002011933394 AGLS? [y/N] n
cancelled: autoconfirm declined: answered 'n' at the prompt
1002011933394

The same gate runs in order.submit(). With no terminal to ask on, a notebook included, autoconfirm=False raises QuipCancelledError without prompting. A declined job costs nothing: the gate runs before funding, so it draws no drip, and nothing reaches the chain.

To decide in code instead, pass a callable that receives the JobQuote and returns whether to submit. This one accepts any job up to 2 AGLS (a token here has 12 decimals):

solver = sa.quip.SolverQuip.for_network(
    "aglais",
    topology="native",
    autoconfirm=lambda quote: quote.total_planck <= 2 * 10**12,
)
result = solver.solve(model)
print(result.metadata["order_id"], result.energy)

╭─ Job quote ──────────────────────────────────────────────────────────╮
│ Network     aglais                                                   │
│ Account     5DL9B7rhMw1cg7kXzqmdj5QZ1V67vBvfYPq2bTEgZfSXiBSJ         │
│ Quoted at   block 1936                                               │
├──────────────────────────────────────────────────────────────────────┤
│ Problem     16 variables -> 16 spins, 96 couplings                   │
│ Placed on   native                                                   │
├──────────────────────────────────────────────────────────────────────┤
│ Reward      1.000000000000 AGLS  refunded if unanswered              │
│ Fee         0.002011933394 AGLS  exact                               │
│ Total       1.002011933394 AGLS                                      │
╞══════════════════════════════════════════════════════════════════════╡
│ Balance     5.991952266385 AGLS                                      │
│ Shortfall   0.000000000000 AGLS                                      │
│ Affordable  yes                                                      │
╰──────────────────────────────────────────────────────────────────────╯
24 -723

What a Failed Job Costs

An order that becomes final with no answers costs its transaction fee, which is burned either way. Its reward stays reserved until the order is reclaimed. solve() reclaims it for you and raises QuipJobFailedError, carrying the order_id, with a message that says whether the reclaim succeeded:

QuipJobFailedError: order 25 finalized with no solutions; only allowlisted solvers could answer (accounts 5DL9..iBSJ) and none did; the reserved reward was reclaimed

That order was restricted to an account that is not a registered solver, so nobody could answer it. Its total cost was the proposal fee plus the reclaim fee, about 0.004 AGLS. A faucet drip drawn for a job stays in the account either way.

On an order you submitted yourself, wait() and best() never reclaim. best() raises QuipJobFailedError and tells you to reclaim; do it once the order is final:

refunded = order.reclaim()

A job that outlasts the solver’s timeout raises QuipTimeoutError instead, carrying order_id and the order’s receipt. The job is still live on chain, so wait on the receipt again:

from xquad import sa

try:
    order.wait()
except sa.quip.QuipTimeoutError as exc:
    exc.receipt.wait()

Coming Back Later

The order lives on chain, not in your session. A new process lists the account’s orders and rebuilds any one’s receipt from its id:

solver = sa.quip.SolverQuip.for_network("aglais")
print(solver.list_orders())
receipt = solver.get_receipt(20)
print(receipt.status())

[24, 23, 21, 20]
{'state': 'finalized', 'order_id': 20, 'chain_status': 'Expired', 'created_at': 1898, 'first_solution_at': 1904, 'effective_expiry': 1914, 'current_block': 2219, 'solution_count': 2}

chain_status is Expired: the chain marked the order expired at its effective expiry. It turns Closed once someone claims it, and print(receipt) then shows the Winner row as claimed. A closed order drops out of list_orders(), which lists only orders not yet closed, but its receipt still rebuilds from the id. Orders 21 and 22 were placed for the examples on Job Orders. Orders 22 and 25 are already missing: they went unanswered and were reclaimed. A receipt also lists the solvers that answered and their raw spin vectors, shows the settlement, and reclaims an unanswered order with receipt.reclaim().

From a shell, xquad quip --network aglais orders lists the same orders, one line each, and xquad quip --network aglais status 20 prints the receipt box; see Orders.

A receipt does not hold your model, so it cannot decode an answer into a tour. Decoding needs the JobOrder from the session that submitted it. From a new session, the deprecated solver.query(order_id, model, topology="native") still returns a decoded SolverResult, with the same topology the order was proposed with; it warns and is removed in v0.6.0 (see Deprecated APIs).

What Native Mode Gives Up

A miner that cannot embed an arbitrary graph, such as a QPU-backed one, cannot answer a native order. The simulated-annealing miners on aglais answered every open job on this page.

Job Orders

SolverQuip.solve() proposes a job, waits for it and decodes the answer in one call. create_order() splits that call into steps: it returns a draft JobOrder that you can inspect, change, price and submit, and a submitted order leaves a receipt that follows it on chain from any session. Every option is checked against the chain’s limits before anything is signed, so a refused option costs nothing.

This page covers the order surface. Quip Network covers installation, configuration, encoding, cost and the error classes, and Your First Quip Job walks one order through end to end. The examples import from xquad.sa.quip; xqsa.quip exports the same names. Every output on this page was captured on aglais at specVersion 119 on 2026-10-15, from the 16-variable TSP model the tutorial builds, unless it says otherwise.

Orders

from xquad import sa

solver = sa.quip.SolverQuip.for_network("aglais", topology="native")
order = solver.create_order(model, deadline_blocks=200)
print(order)
print(order.quote())
order.submit().wait()
print(order.receipt())

create_order(model, **options) places the model and returns a draft. It takes ten options. The first six default to the client’s values (see Installation and Configuration); mapping and the three quality floors exist per order only:

Any other keyword raises TypeError, including mode= (deprecated) and delivery= (client-only):

TypeError: unknown order option 'mode'; expected one of access, block_wait, deadline_blocks, mapping, max_energy, min_diversity, min_solutions, resolution, reward, topology

reward, deadline_blocks and block_wait must be integers (TypeError: reward must be an int, not str). A raw chain dict for access or resolution raises TypeError: access: raw chain values are not accepted.

States

An order is in one of five states, or the deprecated unconfirmed. status()["state"] reports it, and the order box shows it in its title.

Calling set(), quote() or submit() on any order other than a draft or a sending one raises QuipSubmissionError:

QuipSubmissionError: order 20 is finalized; set() works only on a draft order

Changing a draft

set(**options) takes the same options as create_order(). It re-runs every check over the whole configuration and leaves the order unchanged if any check refuses, so it also repeats the warnings for options you did not touch. It places the model again only when topology or mapping changes. Any change drops the cached signature, so the next quote() or submit() signs afresh. options() returns all ten options as a dict, and each is also a read-only property (order.reward, order.access, order.max_energy and so on).

Quote and submit

quote() signs the order’s propose_job extrinsic once and caches it, then prices it: the fee from the chain’s payment_queryInfo, the account balance and the head block, all re-read on every call. Nothing is sent and no nonce is consumed. It returns a JobQuote; Cost Model lists its fields.

submit() sends the cached extrinsic, signing first if the order was never quoted. Before sending, it quotes again and runs the autoconfirm and autofund gates, as solve() does. Once the proposal is sent, it ends in one of three states:

• submitted: the order is in a finalized block, and submit() returns the order.
• failed: the dispatch failed, and submit() raises QuipSubmissionError("propose_job 0x... failed on chain in block 0x...: <error>. The fee was paid and no order was placed.").
• sending: the send could not be settled, and submit() raises QuipSubmitIncompleteError; see Settling a send.

A proposal the node refuses, or one proven never to have reached the chain, leaves the order a draft, and submit() raises QuipSubmissionError; submitting it again signs afresh.

A signature carries the account’s nonce. When another order from the same account is sent between quote() and submit(), the nonce has moved, so submit() signs again. Two drafts quoted together and then submitted show it:

a = solver.create_order(model, resolution=sa.quip.ResolutionTopNEqual(2))
b = solver.create_order(model, access=sa.quip.AccessAllow(accounts=[me]), deadline_blocks=10, block_wait=0)
a.quote(), b.quote()
a.submit()
b.submit()

proposed Quip job: order_id=21 spec_id=0x8f46...67f0 reward=1000000000000 planck (block 0x2114...c0fa)
account nonce moved from 1 to 2 since signing; signing again
proposed Quip job: order_id=22 spec_id=0x8f46...67f0 reward=1000000000000 planck (block 0x2a8b...1752)

(Log lines from the xqsa.quip logger at INFO, hashes shortened.) If the nonce moves again while submit() signs, it refuses rather than race the other client: QuipSubmissionError: account nonce moved twice while submitting; another client is sending from this account. Nothing was sent.

submit() logs the quote box at INFO on the xqsa.quip logger, and also prints it to stderr when stderr is a terminal.

Settling a send

Every proposal is signed mortal: the chain accepts it only within inclusion_window_blocks of the finalized block it was signed at, and never after. The window is a client setting, not an order option. SolverQuip and for_network() take 64 to 2048 blocks, rounded up to the next power of two, so inclusion_window_blocks=100 gives 128; a value outside that range raises QuipOrderOptionError (inclusion_window_blocks=4096 must be from 64 to 2048), and one that is not an integer raises TypeError, both before connecting. The default, DEFAULT_INCLUSION_WINDOW_BLOCKS, is 64 blocks, about 6.4 minutes. A longer window rides out more congestion or a longer outage, but a send that never lands takes longer to be proven dead. The quote box shows the window in its Window row (included within 64 blocks), and a draft’s status()["inclusion_window_blocks"] reports it.

quote() signs once, but submit() signs again when the account nonce has moved or half of the cached bytes’ window has passed, so a quote left sitting never sends bytes that could expire before they land. It refuses to sign at all while finality lags the best block by half the window or more: QuipSubmissionError: finality lags 40 blocks behind the best block, at least half the 64-block inclusion window; nothing was sent, try again once it catches up.

submit() reads the outcome from finalized state alone. The order becomes submitted, with its order id, or failed once the block holding the proposal is finalized, so submit() returns a few blocks after the proposal is included, not at inclusion. A failed dispatch is read from that block’s events, as System.ExtrinsicFailed: <error>. While the proposal may still land, submit() sends the same bytes again, so a node that lost them learns them again; the bytes carry one hash and one nonce, so they land once at most. A lost connection is reopened with backoff. Settling reads past blocks’ state, so the node must keep full state history (--state-pruning=archive); the named network presets do.

When submit() cannot settle the send by the end of its window, because no node could be reached or finality stalled, it raises QuipSubmitIncompleteError and leaves the order sending. It stops at once, with the same error, when the block that spent the nonce or its events cannot be decoded, when a reconnect reaches another chain or a node whose runtime metadata this client cannot read, or when the node has discarded the state it needs. The error is a QuipSubmissionError, so existing handlers still catch it. It carries order (None after pickling, since the order holds a live connection), extrinsic_hash, nonce and window_end, the last block that can include the proposal; the specific cause is its __cause__. The message ends with what to do. This example is illustrative, built from the message in xqsa/quip/client.py, not captured:

QuipSubmitIncompleteError: propose_job 0x5e0c...81d4 (nonce 3) was sent but is not settled (<the last error>). Its window ends at block 4160. The order is sending: calling submit() again resumes it; it never places a second order.

Calling submit() on a sending order resumes it. It settles the bytes already sent, up to the end of their window, and signs nothing. If they landed, the order is submitted (or failed, raised as above). If they are proven never on chain, the order is a draft again and is quoted, gated, signed and sent as a new one. Either way it never places a second order:

from xquad import sa

try:
    order.submit()
except sa.quip.QuipSubmitIncompleteError as exc:
    print(exc.extrinsic_hash, exc.nonce, exc.window_end)
    exc.order.submit()  # resumes; never places a second order

A KeyboardInterrupt, or any other exception, after the bytes may have reached the node also leaves the order sending. submit() prints the hash, nonce and window end to stderr and re-raises the exception unchanged:

[quip] submit() stopped after propose_job 0x5e0c...81d4 (nonce 3) may have reached the node; its window ends at block 4160. The order is sending: calling submit() again resumes it; it never places a second order.

Before that point the order stays a draft. While an order is sending, every other method settles it first: status() makes one read without waiting and reports the state it settles to, or, while it cannot, state, extrinsic_hash, nonce and window_end. The order box shows the hash, nonce and window end in its Receipt row. A sending order pickles with its signed bytes, but copy() and deepcopy() refuse it, since two live orders must not share one nonce.

Each send spends one account nonce, and the chain includes an account’s transactions in nonce order. A send signed while an earlier one from the same account is still waiting in the node’s pool takes the next nonce, so it cannot land before the earlier one. If the earlier send’s window ends with it never on chain, its nonce stays unspent: the order settles back to a draft, and its submit() raises QuipSubmissionError: propose_job 0x... never reached the chain. The later send cannot land while that nonce is unspent. Submitting the earlier draft again signs with that nonce, and once it lands, the later send can still land within its own window. If nothing spends the nonce before the later window ends, the later order settles back to a draft the same way.

Checks before signing

create_order() and set() check each option against the chain’s limits, which the client reads once when it connects. A refusal raises QuipOrderOptionError, a QuipSubmissionError whose option attribute names the option. A warning is a UserWarning; the order is still built. The limits on aglais are MinReward 1 AGLS, MaxDeadlineBlocks 1000 and MaxBlockWait 100.

The chain itself accepts a deadline of 0, which expires on arrival. The short-deadline warning reflects how often aglais answered: an order with a 1-block deadline was answered 0 times out of 11, 30 blocks 28 times out of 38, and 100 blocks 108 times out of 108. The other options’ checks are in their sections below.

The order box

print(order) renders a 72-column box. Its sections are the network; the model and where it was placed; the terms (payout, access, floors, deadline, block wait and reward); and a summary of the latest quote and the receipt:

╭─ Job order (draft) ──────────────────────────────────────────────────╮
│ Network     aglais                                                   │
├──────────────────────────────────────────────────────────────────────┤
│ Model       16 variables, 96 couplings, binary                       │
│ Placed      native, 16 spins                                         │
├──────────────────────────────────────────────────────────────────────┤
│ Payout      single best                                              │
│ Access      open                                                     │
│ Floors      none                                                     │
│ Deadline    100 blocks                                               │
│ Block wait  10 blocks                                                │
│ Reward      1.000000000000 AGLS                                      │
├──────────────────────────────────────────────────────────────────────┤
│ Quote       not quoted                                               │
│ Receipt     not submitted                                            │
╰──────────────────────────────────────────────────────────────────────╯

On a draft, the Quote row shows the last quote taken and whether the account can afford it. Once the order has an id, a Paid row replaces it: the fee the chain charged, read from the order’s TransactionFeePaid event, the reward, and the quote’s total beside them for comparison. The quoted fee is an estimate at the head block, so the two can differ. When the fee cannot be read, the row says fee unknown. A failed order paid the fee but placed nothing, so its Paid row shows the fee and the quote with no reward. A sending order’s outcome is unknown, so a Quoted row shows the quote alone.

Payout rules

The resolution option decides how the reward is split:

• "SingleBest" or ResolutionSingleBest(), the default: the leader, the solver the chain ranks first, takes the whole reward.
• ResolutionTopNEqual(n): the best n ranked solvers split it evenly.
• ResolutionTopNWeighted(n): the best n split it by rank. With k ranked solvers, rank r (0 is best) gets weight k - r; energies decide only the order.

from xquad import sa

order = solver.create_order(model, resolution=sa.quip.ResolutionTopNEqual(2))

n runs from 1 to 32. The rule’s own constructor checks it, so a bad n raises ValueError (ResolutionTopNEqual: n must be from 1 to 32, got 33) or TypeError before any order exists. n=1 warns ResolutionTopNEqual(1) pays exactly like ResolutionSingleBest(). Any other value for resolution is refused: with ValueError on the constructor, and with QuipOrderOptionError on an order:

resolution='TopNEqual' is not a payout rule; pass 'SingleBest' or one of ResolutionSingleBest(), ResolutionTopNEqual(n), ResolutionTopNWeighted(n)

ResolutionTopNWeighted needs runtime 119 or later (see Runtime compatibility). On a network below runtime 119, create_order(), set(), solve() and quote() refuse it before signing (captured on runtime 118):

QuipOrderOptionError: ResolutionTopNWeighted needs runtime 119 or later, and the chain runs runtime 118; older runtimes weight by absolute energy, so a worse answer can take the larger share

A top-N rule with n above 1 and block_wait=0 warns, because the order closes on its first answer: resolution=top 3, equal split: with block_wait=0 only the first answer is accepted, so there can be only one winner.

Settlement

The chain ranks solvers by energy, lowest first, with the earlier submitter first on a tie. Winners are the first n ranked solvers, so an order with fewer answers than n has fewer winners. A receipt’s settlement() computes each winner’s share:

• TopNEqual: each winner gets reward // k, and rank 0 also gets the remainder. A reward of 10 over 3 winners splits [4, 3, 3].
• TopNWeighted: with total = k * (k + 1) / 2, rank r gets (reward // total) * w + (reward % total) * w // total for its weight w, and rank 0 also gets the remainder. A reward of 10 over 3 winners splits [6, 3, 1].

A top-2 order answered by three solvers, two of them tied at the best energy:

print(order.settlement())

{'claimed': False, 'winners': [{'solver': '5Gn1BACWJGtxCnkHpbonhLZJw3ZYF3LzwXEoWjub74E9RPv9', 'energy_milli': -1790000, 'allocation_planck': 500000000000}, {'solver': '5FNGHjGLzoo8CXv4iiX7z71xJycYpTGZUaA37281kZhWoWun', 'energy_milli': -1790000, 'allocation_planck': 500000000000}]}

An allocation is not a payment. One claim_reward extrinsic pays every winner; until then the receipt shows each as awaiting claim, and claimed turns True once the chain closes the order. Below runtime 119, settlement() of a TopNWeighted order raises NotImplementedError, and the receipt prints that message as its Reward row. The order box and the receipt show the rule as single best, top 2, equal split or top 2, weighted by rank.

Access

The access option decides who may answer. "Open" or AccessOpen(), the default, admits every registered solver. AccessAllow(accounts=[...], types=[...]) admits a solver whose account is listed or whose declared type is listed:

from xquad import sa

order = solver.create_order(model, access=sa.quip.AccessAllow(types=["QpuDwave"]))

Solver types are self-declared when a solver registers, and the protocol does not verify them, so a type entry admits any solver that claims it. On aglais, an order allowlisted to Cpu was answered by our own solver and three others.

The allowlist is bounded:

• It must name at least one account or type: AccessAllow: name at least one account or solver type; the chain refuses an empty list (ValueError, from the constructor). An empty list would fail on chain after the fee was paid.
• At most 8 types (ValueError).
• At most MaxBidMiners accounts, 16 on aglais: AccessAllow lists 17 accounts; the chain's MaxBidMiners is 16 (QuipOrderOptionError).
• Type names come from the runtime’s MinerType, on aglais Cpu, Gpu, QpuDwave, QpuIbm, QpuIonq, QpuPasqal and Asic: AccessAllow: unknown solver type 'Fpga'; the chain has Cpu, Gpu, QpuDwave, QpuIbm, QpuIonq, QpuPasqal, Asic (QuipOrderOptionError).

Over either cap the runtime fails with no readable error, which is why the client refuses first. Duplicate entries are dropped, and accounts, given as SS58, 0x hex or bytes, are normalised to 0x hex. A bad value for access raises ValueError on the constructor and QuipOrderOptionError on an order: access='Bid' is not an access rule; pass 'Open' or one of AccessOpen(), AccessAllow(accounts=[...], types=[...]).

An allowlisted account that is not a registered solver is never refused, but it warns, naming the account in SS58:

UserWarning: access: 5DL9B7rhMw1cg7kXzqmdj5QZ1V67vBvfYPq2bTEgZfSXiBSJ is not a registered solver, so it cannot answer until it registers

The constructor warns for its default access, and create_order() and set() warn when they change it. When nobody on the allowlist answers, the no-answer error says so: order 22 has no answers; only allowlisted solvers could answer (accounts 5DL9..iBSJ) and none did; once it is final, reclaim its reward with order.reclaim().

A solver that is not on the list and answers anyway is refused on chain with System.ExtrinsicFailed: QuantumComputeMempool.NotEligibleSolver, followed by the error’s description when the metadata carries one. Network coordinators submit to allowlisted orders regardless and pay for each refused submission, so a block explorer can show many refused submissions against one allowlisted order: 4 to 142 per order on aglais.

Quality floors

Three per-order options set a minimum quality an answer must reach. None of them is a client default.

• max_energy: an energy ceiling. The chain drops each submitted vector above it.
• min_solutions: how many vectors each answer must carry. The chain stores exactly that many from each submission.
• min_diversity: how different those vectors must be, as a fraction of the placed spins. 0 means no floor.

max_energy is in model units, the same units as result.energy. For a BINARY model the chain’s energy differs from the model’s by a constant offset, which the client subtracts before it sends the ceiling; An Energy Ceiling on the Quip Network works through the conversion. A ceiling that moves shows both values in the order box’s Floors row, here for max_energy=-2 on the model -2*x0 + x0*x1:

│ Floors      energy <= -2 (chain -1.25)                               │

Refusals (QuipOrderOptionError unless marked) and warnings:

What the chain does with each floor:

• The ceiling drops each submitted vector above it. A submission is refused (InsufficientEnergy) only when none of its vectors is left.
• With min_solutions=k, the chain stores exactly the k most diverse vectors of each submission. That subset can leave out a solver’s best vector, which is one reason best() can fall back (see Reading the answer).
• Diversity is the average pairwise Hamming distance over the placed spins, in thousandths, with a vector and its full flip counted as the same vector. That is why n spins cap it at floor(n/2)/n: a 3-spin model caps at 0.333.

Floors narrow the answers a solver can give, and a small model may have too few distinct vectors to meet min_solutions or min_diversity at all, so an order with floors can go unanswered. The no-answer error then names them: best() in model units, solve() in chain units. The order box shows floors in model units; the receipt shows them in chain units; both show none when no floor is set.

Receipts

A submitted order has a receipt, a JobOrderReceipt. It holds only the order id and the network’s genesis hash, needs no model, and reads the chain on every call. order.receipt() returns it; on a draft it raises QuipSubmissionError: this order is a draft; submit() it first. Any session rebuilds a receipt from the order id:

solver = sa.quip.SolverQuip.for_network("aglais")
print(solver.list_orders())
receipt = solver.get_receipt(20)
print(receipt.status())

[24, 23, 21, 20]
{'state': 'finalized', 'order_id': 20, 'chain_status': 'Expired', 'created_at': 1898, 'first_solution_at': 1904, 'effective_expiry': 1914, 'current_block': 2219, 'solution_count': 2}

get_receipt() raises QuipConnectionError for an id that names no order (order 1000000000 not found on-chain (QuantumComputeMempool.JobOrders)).

list_orders(state=None, account=None) returns the ids of an account’s orders that are not yet closed, newest first: the chain drops an order from the account’s list once a claim or a reclaim closes it. state is "submitted", "finalized", "unanswered" (final with no answers, so reclaim() refunds it) or None, and any other value raises ValueError; account is SS58, 0x hex or bytes, and defaults to the signer. It returns at most the newest 32 ids, after the state filter, and warns when there are more: showing 32 of N orders on this account. This 32-order page limit was imposed for the old protocol cap of 32 orders per account; please flag it to the xquad team so it can be lifted.

receipt.summary() returns the order’s outcome as one flat dict, the fields the receipt box shows under its status rows; xquad quip orders and status --short print its order id, state and leader as one line (see Orders):

print(solver.get_receipt(20).summary())

{'order_id': 20, 'state': 'final', 'open_until': None, 'answers': 2, 'leader': '5GqG8c8zWHX33ruGJX4FDokxCTFrASVi268einKJY1XnHNYn'}

Its state is open, final (answered, the reward awaiting a claim), reclaimable (final with no answers, so reclaim() refunds it) or closed (claimed or reclaimed). open_until is the block an open order closes at, None otherwise; leader is None with no answers. Captured on 2026-10-26.

The receipt and the in-session JobOrder share these methods:

chain_status and state answer different questions. state is finalized once the chain head passes the order’s effective expiry, while chain_status is the chain’s own record: Opened until the effective expiry, Expired from then, and Closed once a claim or a reclaim closes the order. The chain expires a bounded number of orders per block, so when many expire at once an order can read Opened for a few blocks past its expiry. The deprecated SolverQuip.status() returns the old keys, status and is_final, in place of state and chain_status.

wait() raises QuipTimeoutError with the receipt attached, so the caller can wait again instead of rebuilding it:

from xquad import sa

try:
    order.wait()
except sa.quip.QuipTimeoutError as exc:
    receipt = exc.receipt
    receipt.wait()

QuipTimeoutError drops the receipt when it is pickled, since the receipt holds a live connection; another process rebuilds it with get_receipt(exc.order_id).

The receipt box

print(receipt) renders a box with five sections: the network, proposer and submission block and time; the problem; the terms, with floors in chain units; the outcome (status, answer count, leader and its energy); and, under a double rule, the money. The fee is what the chain charged the proposing extrinsic, tip included, read from the block that placed the order; when it cannot be read the row says unknown. The Reward row is reserved, leader so far, reserved, no answers yet, reclaimed, or unanswered: reclaim with get_receipt(N).reclaim(); an answered, final order shows one Winner row per winner, awaiting claim or claimed:

╭─ Job order 20 receipt ───────────────────────────────────────────────╮
│ Network     aglais                                                   │
│ Proposer    5DL9B7rhMw1cg7kXzqmdj5QZ1V67vBvfYPq2bTEgZfSXiBSJ         │
│ Submitted   block 1898, 2026-10-15 04:22:24 UTC                      │
├──────────────────────────────────────────────────────────────────────┤
│ Problem     16 spins, 96 couplings                                   │
│ Spec        0x8f46f3a31321d1d093314fc769c42cbe7a83d71a0b69e6571a0f68 │
│             e2a04067f0                                               │
├──────────────────────────────────────────────────────────────────────┤
│ Payout      single best                                              │
│ Access      open                                                     │
│ Floors      none                                                     │
│ Deadline    100 blocks                                               │
│ Block wait  10 blocks                                                │
│ Reward      1.000000000000 AGLS                                      │
├──────────────────────────────────────────────────────────────────────┤
│ Status      final                                                    │
│ Answers     2                                                        │
│ Leader      5GqG8c8zWHX33ruGJX4FDokxCTFrASVi268einKJY1XnHNYn         │
│ Energy      -1790                                                    │
╞══════════════════════════════════════════════════════════════════════╡
│ Fee         0.002011933394 AGLS                                      │
│ Winner      1.000000000000 AGLS, awaiting claim                      │
╰──────────────────────────────────────────────────────────────────────╯

Reclaiming

reclaim() returns an unanswered order’s reserved reward and returns the planck refunded. It reads the head block, then refuses before signing, with QuipReclaimRefusedError, in this order:

1. order N was proposed by <account>, not by this account
2. order N is already closed (reclaimed or settled)
3. order N is open until block B (about M min); reclaim after it closes
4. order N was answered by K solvers; its reward awaits a claim and cannot be reclaimed

If the chain refuses the reclaim, it raises QuipReclaimRefusedError naming the block and the chain’s error, and the fee is charged. If the outcome is unknown, it raises QuipSubmissionError("the reclaim of order N (<extrinsic>) was sent but its outcome is unknown"); a retry is safe, since a reclaim that landed makes the next one refuse as already closed. A reclaim costs its own transaction fee, about 0.0019 AGLS on aglais.

Only solve(), and the deprecated query(), reclaim on their own: when an order finalizes with no answers, they reclaim it and raise QuipJobFailedError, saying whether the reclaim succeeded:

QuipJobFailedError: order 25 finalized with no solutions; only allowlisted solvers could answer (accounts 5DL9..iBSJ) and none did; the reserved reward was reclaimed

JobOrder.wait(), JobOrder.best() and a receipt’s wait() never reclaim.

Reading the answer

An in-session JobOrder holds the model it was built from, so it decodes answers onto it:

solution = order.best()
print(solution.energy)
print(solution.solver, solution.leader, solution.energy_milli)

-696
5GqG8c8zWHX33ruGJX4FDokxCTFrASVi268einKJY1XnHNYn True -1790000

best() returns a Solution (importable from xquad.sa.quip, or xqsa.quip, only) with five fields:

solutions(solver=None) returns every stored answer as a Solution, best first by recomputed energy with the leader’s vectors first on a tie. With solver, it returns that solver’s vectors alone, and raises KeyError for a solver that did not answer. An unanswered order returns an empty list.

best() returns the leader’s best vector, the answer the chain pays for, not necessarily the best vector any solver stored. It falls back to the best stored vector overall, the leader first on a tie, in two cases:

• The ranking cannot be read, or names a solver with no stored answer. metadata["leader_read"] is then False on a solve() result.
• None of the leader’s stored vectors recomputes to the energy the chain ranked it at. energy_matches_chain is then False, and the client logs both energies at WARNING. A worse resubmission can overwrite a solver’s stored answer, and min_solutions can store a subset without the best vector, so this is not necessarily an encoding fault.

Under a fallback, leader stays True only when the leader’s own vector is also the best overall. best() reads the chain each time, so on an open order a later call can return a different answer. It never reclaims: with no answers, it raises QuipJobFailedError and tells you to call order.reclaim() once the order is final.

Decoding needs the in-session JobOrder, because a receipt does not hold the model. From another session, get_receipt(order_id) gives you the order’s status, solvers, raw vectors, settlement and reclaim, but not a decoded sample; the deprecated query(order_id, model, ...) is the only way to decode one there (see Deprecated APIs).

Energy and Precision

Every backend in this chapter returns the same kind of number, computed the same way, no matter what found the sample: an integer. This page covers how that number is computed and compared, and where precision is lost or preserved as a model moves from an exact integer formula onto real hardware.

The Formula

A sample’s energy with respect to a model is:

$$E = \sum_i \text{linear}[i] \cdot x_i ;+; \sum_{i \le j} \text{quadratic}[i,j] \cdot x_i \cdot x_j$$

identical to the model’s Hamiltonian from Quadratic Models, evaluated at one concrete assignment x, and identical to the XQVM ENERGY opcode (see Energy Evaluation). A verifier program run through XQVM and xqsa’s own recomputation compute the same formula two independent ways.

The Precision Contract

SolverResult.energy must equal model.energy(sample) exactly, an integer-to-integer comparison with zero tolerance for drift. Every XQMX coefficient and every variable assignment is an integer, so the energy formula is a sum of integer products, not a float that merely rounds to the right answer. It is an exact integer whenever it is representable at all, and representable is a real condition: XqmxModel.energy checks every term product and every partial sum against the i64 range and raises ArithmeticOverflow rather than returning a wrapped number, so a model whose energy leaves that range has no energy this contract can report. Solver._recompute_energy() returns model.energy(sample); every backend in this chapter uses it instead of trusting whatever float its underlying library reports. That raw float, where one exists, survives only as metadata["params"]["raw_energy"], for diagnostics – never as the authoritative value.

A verifier program never has to take a solver’s word for its own answer. It recomputes the same integer independently with ENERGY. There are three outcomes, not two: the comparison holds, the comparison fails, or ENERGY raises ArithmeticOverflow and the verifier produces no verdict at all. The third is not a solver disagreement and must not be read as one – it says the model’s energy left the i64 range on the way to being computed. XqmxModel.energy is the function ENERGY itself calls, so the two accumulate in the same sorted key order, check the same intermediates, and agree on which models fall into it.

A Large Penalty Does Not Corrupt the Model

Choosing a Penalty Weight argues that a large \(P\) cannot corrupt a model, because energy differences between feasible assignments survive exactly however large \(P\) gets. Take that page’s three-node Max-Cut model with a one-hot penalty \(P \cdot (x_0 + x_2 - 1)^2\) added on top, and score two feasible assignments and one infeasible one through XqmxModel.energy() at three wildly different weights:

P=           2 | E(feasible_a)=           -8 E(feasible_b)=           -6 E(infeasible)=  -8 diff= 2
P=        1000 | E(feasible_a)=        -1006 E(feasible_b)=        -1004 E(infeasible)=  -8 diff= 2
P=  2000000000 | E(feasible_a)=  -2000000006 E(feasible_b)=  -2000000004 E(infeasible)=  -8 diff= 2

The difference between the two feasible assignments stays exactly 2 at every weight. The penalty term is 0 on both, so what separates them is the underlying objective alone, and integer arithmetic never lets it drift.

The infeasible assignment’s own energy does not move either – it sits at -8 at every \(P\) above. What moves is the two feasible energies, and they fall without bound as \(P\) grows. That is the missing +P constant, not the penalty term itself: the true, unstorable Hamiltonian adds +P to every assignment that violates the constraint and +0 to every assignment that satisfies it, so dropping that constant subtracts a uniform P from every stored energy. On the infeasible sample the missing +P exactly cancels the penalty’s own +P, leaving it unchanged; on a feasible sample there is nothing to cancel, so the stored energy falls by P.

What a Large Penalty Costs Instead

Nothing in the model degrades, but two things outside it do, and both matter to backends in this chapter.

Fixed-precision hardware loses resolution. The Metal engine (SolverGPU(engine="metal")) computes coefficients in float32 on the GPU, not the integer arithmetic ENERGY uses – result.energy is still recomputed in exact integers afterward, but the search that finds the sample runs at float32 precision. The CUDA engine does not share this: its kernels take const double* throughout, its acceptance draws stay float64, and result.energy is recomputed the same way as every other backend. See Local Solvers for the per-backend split. The rest of this section applies to the Metal engine and to fixed-precision annealing hardware, not to every GPU backend.

A float32 mantissa carries about seven decimal digits. Once a term in the combined Hamiltonian is large enough that a difference of 2 no longer changes the float, the Metal engine’s search cannot distinguish the two assignments that difference separates, even though ENERGY still resolves them exactly afterward:

import numpy as np
np.float32(-2000000006) == np.float32(-2000000004)   # True -- the 2 vanished, at the Metal engine's width
np.float64(-2000000006) == np.float64(-2000000004)   # False -- still resolved, at the CUDA engine's width
np.float32(-1006) == np.float32(-1004)                 # False -- still resolved

At P = 2000000000 the two feasible assignments above are computationally indistinguishable to the Metal engine’s float32 search even though XqmxModel.energy() still tells them apart exactly; at P = 1000 they are not. The CUDA engine’s float64 search keeps this pair distinguishable at this scale, though a large enough \(P\) would eventually exhaust its wider but still finite mantissa too. Neither GPU backend’s correctness ever suffers – the returned energy is always the exact integer – but the Metal engine’s search can lose the signal, at penalty weights where the CUDA engine’s still keeps it visible.

Real annealing hardware rescales, and the Quip network encodes at fixed precision. A physical D-Wave annealer maps coefficients onto its analog range with a monotonic, optimum-preserving rescaling, so an oversized \(P\) is not rejected there – it costs usable range on the device instead. SolverQuip goes further: it scales every coefficient by MILLI_SCALE = 1000 into the chain’s i32 fields, so an oversized coefficient can overflow i32 and raise EncodingError, and one finer than 1/1000 is rounded to the nearest milli, with the largest rounding error reported. MAX_NATURAL_COEFFICIENT = 2_147_483 is the exact bound only for a SPIN model; a BINARY model – the domain every worked example on this page uses – goes through a basis change first that shifts the bound in both directions, and can overflow well before any single coefficient looks anywhere near that large. See Quip Network for the full derivation.

A large penalty also raises the barrier between feasible regions, independent of any hardware precision question: a heuristic search such as simulated annealing has to cross that barrier to leave the first feasible region it reaches, and a larger \(P\) makes crossing less likely within a fixed number of sweeps. Sizing \(P\) in practice, and reading a solver’s output to tell which of these failure modes you hit, belongs to Constraints.

An Energy Ceiling on the Quip Network

SolverQuip’s max_energy order option (see Quality floors) is an energy ceiling, and it is in model units: the same units as XqmxModel.energy and result.energy. The chain never sees your model, only its spin fields and couplings at milli scale, so the client converts the ceiling before sending it.

For a SPIN model the conversion is a change of scale: the ceiling times 1000, rounded down, so the chain admits exactly the energies at or below it. A BINARY model also carries a constant. The basis change s = 2x - 1 (see Quip Network) turns the model into spin fields and couplings plus an offset that no spin multiplies, and the chain, which stores only the fields and couplings, computes energies without it. The client subtracts the offset first:

chain ceiling (milli) = floor((max_energy - offset) * 1000)

A value within a millionth of a milli of the grid snaps to it before the floor, so float noise such as -1.2500000000001 does not lower the ceiling to -1251.

Take E = -2*x0 + x0*x1. Its spin form has fields h0 = -0.75 and h1 = 0.25, a coupling of 0.25, and an offset of -0.75. The assignment x0 = 1, x1 = 0 has model energy -2; on the chain, with spins s0 = +1, s1 = -1, its energy is -0.75 - 0.25 - 0.25 = -1.25. So max_energy=-2 goes on chain as -1250 milli, and the order box shows both values:

│ Floors      energy <= -2 (chain -1.25)                               │

The chain applies the ceiling to the model it holds. When the model’s coefficients were rounded to the milli grid (see What a Large Penalty Costs Instead), the chain’s energies differ slightly from yours, so an answer near the ceiling can land on either side of it, and create_order() warns. A ceiling below the lowest energy the placed model can reach is refused, and one at or above the highest warns that it filters nothing; Quality floors lists every check.

Examples

Graph problems

Examples that encode graph cuts, colouring, covers, independent sets, and tours.

• Max-Cut – Find a 2-colour partition of a weighted graph that maximises the cut weight.
• Graph Coloring – Assign colours to graph nodes so adjacent nodes do not share a colour.
• Maximum Independent Set – Select the largest subset of graph nodes with no selected edge between them.
• Vertex Cover – Select the smallest vertex subset that covers every graph edge.
• Travelling Salesman Problem – Find the shortest Hamiltonian tour through a random symmetric distance matrix.

Selection and packing

Examples that select subsets, cover demands, pack bins, and balance integer weights.

• Knapsack – Select items that maximise value while respecting a capacity constraint.
• Bin Packing – Pack items into the minimum number of fixed-capacity bins.
• Set Cover – Select the minimum set collection whose union covers the universe.
• Weighted Set Cover – Select sets with capacities to cover element demands at minimum cost.
• Number Partition – Split positive integers into two subsets with nearly equal sums.
• Portfolio Optimization – Select a fixed-size portfolio while penalising higher-order risk interactions.
• Portfolio Rebalance – Choose signed integer asset weights against a risk matrix and a budget.

Satisfiability and higher-order

Examples that reduce clauses and higher-order pseudo-Boolean objectives to quadratic models.

• Max-3-SAT – Find the assignment that satisfies the maximum number of 3-literal clauses.
• Cubic Optimization – Minimise a cubic pseudo-Boolean objective through HOBO degree reduction.
• Quartic Optimization – Minimise a degree-4 pseudo-Boolean objective through two-stage REDUCE chaining.

Using the Examples

examples/ holds fourteen self-contained problems, one directory each, listed on the gallery page. This page covers what every directory has in common, how to run one, and how to turn one into a problem of your own – the task the rest of this chapter does not cover, because it is not specific to any single example.

What Every Example Shares

Each examples/<name>/ holds a README.md, which this chapter’s other pages are generated from, and a runner.py. Nothing else – no .xqasm files. problem.compile() builds the three programs in memory at runtime as plain strings; see Three Programs for what those three programs are and Compiling for what compile() emits. Every runner.py follows the same shape:

• build_problem(...) – an xqcp Problem definition: inputs, a model, an objective, constraints, and outputs. This is the part that changes from problem to problem, and the part Modelling covers in full.
• run(programs, ...) – three VM.run() calls against the compiled encoder, verifier, and decoder, with one xqsa solver call between the first two. Every example wires calldata and output slots the same way: encoder in, model out; model plus sample plus N in, energy and valid out; sample plus N in, decoded result out.
• main(...) – an argparse CLI, and a JSON result printed to stdout or written with -o.

examples/manifest.yaml lists every directory once, under a group (dir, title, blurb), and drives both the gallery grouping and scripts/gen-example-docs.py’s validation that every listed directory has a runner.py and a README.md. This page itself is exempt: it is named in the manifest’s preserved_pages, so make regen-docs leaves it alone instead of overwriting it from a source README.md that does not exist.

Running One

uv run python examples/<name>/runner.py --seed 42

Every runner accepts --seed, --solver, and -o/--output. Most also take --n for problem size; a few split size across two flags instead (--n plus --bins, --colors, --budget, or --m), or use --num-elements and --num-sets in place of --n. Check the individual page’s Usage table for the exact flags.

The compiled programs run on the Rust XQVM through xqffi. Backends covers what differs by solver backend. Where a model has several optima of equal energy, the solver returns one of them, and a different optimum decodes to a different answer even though both are equally correct: a different solver or seed can change the decoded result without changing valid or energy.

Adapting an Example

Copying and editing an existing runner.py is the fastest way to model a new problem, and it is what this section walks through concretely: turning examples/maxcut/runner.py’s Max-Cut into a minimum s-t cut with two fixed terminals.

Max-Cut splits a graph’s nodes into two groups to maximise the crossing edge weight, with no constraint on which node ends up where. Quadratic Models derives its formulation; build_problem’s inner loop is the part that matters here:

with problem.range(0, edge_count) as e:
    offset = e * 3
    i = problem.stow("i", edges_in.get(offset))
    j = problem.stow("j", edges_in.get(offset + 1))
    w = problem.stow("w", edges_in.get(offset + 2))
    problem.model.linear[i].add(-w)
    problem.model.linear[j].add(-w)
    problem.model.quadratic[i, j].add(w * 2)

Suppose two specific nodes must end up on opposite sides – node 0 and node n - 1, say, standing in for two machines a network partition must separate. That is a different problem, minimum s-t cut with fixed terminals, and it is two small edits away:

with problem.range(0, edge_count) as e:
    offset = e * 3
    i = problem.stow("i", edges_in.get(offset))
    j = problem.stow("j", edges_in.get(offset + 1))
    w = problem.stow("w", edges_in.get(offset + 2))
    problem.model.linear[i].add(w)          # sign flipped: minimise, not maximise
    problem.model.linear[j].add(w)
    problem.model.quadratic[i, j].add(w * -2)

# Fix node 0 to side 0 and node n-1 to side 1. 10_000 comfortably
# exceeds the total weight of every edge (at most C(n,2) * 100 for
# this graph), so neither fixed node is ever worth flipping to save
# weight elsewhere.
problem.model.linear[0].add(10_000)
problem.model.linear[num_nodes - 1].add(-10_000)

Everything else stays: the random weighted graph, problem.define_model, the partition output loop, and run(). The DSL calls used – model.linear[i].add() and model.quadratic[i, j].add() – are the same two maxcut/README.md already lists. main() needs one further edit, covered in the next section: drop the canonicalize_partition(partition) call, because this variant’s two sides stop being interchangeable.

Running the original and the variant on the same seed and graph (--n 5 --seed 42 on both):

Unmodified examples/maxcut/runner.py:

{"cut_weight": 354, "energy": -354, "partition": [0, 1, 0, 0, 1], "valid": 1}

The variant:

{"cut_weight": 196, "energy": -9804, "partition": [0, 1, 1, 1, 1], "valid": 1}

The cut drops from 354 to 196, confirming the variant found a smaller crossing weight rather than reusing the maximiser’s answer, and partition[0] == 0 with partition[-1] == 1 confirms the two terminals landed where they were pinned.

Telling a Variant Wrong from a Variant Different

valid alone does not catch a modelling mistake here: Max-Cut and this variant both declare no constraints, so valid reports only that every sample value is 0 or 1 – see Constraints for what a verifier’s built-in check does and does not cover. energy is not a safe single number either. Get the terminal bias backwards – problem.model.linear[0].add(-10_000) and problem.model.linear[num_nodes - 1].add(10_000), the two signs swapped – and the run reports the same cut_weight (196) and the same energy (-9804) as the correct version. A cut and its complement (every node’s side flipped) always cost the same, so reversing which two nodes get pinned just picks the other member of that pair; nothing about the aggregate numbers changes.

partition is where the mistake shows, but only once canonicalize_partition(partition) is gone from main(). Max-Cut calls it because a cut and its complement are the same cut, so normalising node 0 to side 0 throws nothing away. This variant cannot afford that: the two terminals make the two sides distinguishable, and canonicalising erases the one fact the pinning added. Building both versions with that call removed and running each on the same seed and graph (--n 5 --seed 42):

Correct:

{"cut_weight": 196, "energy": -9804, "partition": [0, 1, 1, 1, 1], "valid": 1}

Swapped:

{"cut_weight": 196, "energy": -9804, "partition": [1, 0, 0, 0, 0], "valid": 1}

cut_weight and energy still agree, for the reason above. partition[0] and partition[-1] no longer do: 0 and 1 on the correct run, 1 and 0 on the swapped one. Catching this mistake means checking the property the edit was supposed to guarantee – that the two terminals sit on the sides they were pinned to – against a sample nothing downstream has normalised. The same habit generalises past this one example: name the specific property an edit is supposed to produce, and check that property against output no later step has adjusted, not just valid and a plausible-looking energy.

Max-Cut

Source: examples/maxcut/README.md

Find a 2-colour partition of a weighted graph that maximises the total weight of edges crossing the partition.

QUBO formulation

• Input: num_nodes (int), edges (list of flat (i, j, w) triples, 3*|E| entries)
• Model: n binary variables, one per node. x[v] in {0, 1} selects the side of the cut.
• Objective: for each edge (i, j, w), add -w*(x_i + x_j) and +2w*x_i*x_j. Minimising this minimises -sum w*[x_i != x_j], i.e. maximises the cut.

DSL methods used

• problem.input() – declare typed calldata inputs
• problem.define_model() – allocate binary XQMX model
• problem.stow() – bind intermediate computations to named registers
• problem.range() – emit RANGE loops
• model.linear[i].add() – accumulate linear bias on variable i
• model.quadratic[i, j].add() – accumulate quadratic coupling between variables i and j
• problem.output() – declare typed output slots
• problem.sample.getline() – read a row from the sample bitstring

Pipeline overview

1. CP (xqcp) – build a random weighted complete graph, declare binary variables (one per node), and add linear/quadratic QUBO terms per edge.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary, then computes energy; this problem declares no constraints for it to check
6. Decode – decoder extracts the 2-colour partition

Usage

uv run python examples/maxcut/runner.py --seed 42
uv run python examples/maxcut/runner.py --n 6 --seed 7 -o /tmp/mc.json

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Graph Coloring

Source: examples/graph_coloring/README.md

Assign one of C colors to each node of an undirected graph such that no two adjacent nodes share the same color (proper C-coloring).

QUBO formulation

• Input: number of nodes N, number of colors C, edge list
• Model: N categorical variables over C cases. Domain.CATEGORICAL records that as an N x C binary grid, x[v,c] = 1 if node v gets color c, with a one-hot row per node.
• Objective: none. The problem is pure constraint satisfaction: a colouring is scored only by its constraint violations. A valid C-colouring scores -penalty * N, not 0, because XQMX has no constant-term field and each satisfied ONEHOTR stores -penalty rather than 0. That is -1000 at the --n 5, penalty 200 defaults. The colour count defaults to 4 because a G(5, 0.5) graph routinely contains a 4-clique – the default seed’s does – and a 4-clique has no 3-colouring, so --colors 3 would make the canonical instance unsatisfiable. See Constraints.
• Constraints:
  • One-hot per node: sum_c x[v,c] = 1 (ONEHOTR, penalty 200) – implied by the domain, not written
  • Exclusion per (edge, color): x[u,c] + x[v,c] <= 1 (EXCLUDE, penalty 200)

Encoding strategy

The one-hot row per node is what makes a categorical variable categorical, so define_model(domain=Domain.CATEGORICAL, k=C, penalty=200) emits it: the grid and one ONEHOTR per row, through the same record paths a hand-written loop would use. The compiled program is what this example emitted before the domain existed.

EXCLUDE is applied per (edge (u,v), color c) pair via a nested range loop. The 2D coordinates (u, c) and (v, c) are resolved to flat indices using IDXGRID: u * num_colors + c and v * num_colors + c.

Reading the answer back is sample.case(v), a ROWFIND for the 1 in node v’s row. ROWFIND returns -1 where a row holds no 1, which is the uncoloured sentinel this example used to produce in host code.

DSL methods used

• problem.define_model(size=N, domain=Domain.CATEGORICAL, k=C, penalty=200) – the grid and its one-hot rows
• model.apply_exclude((u, c), (v, c), penalty) – EXCLUDE per edge per color
• sample.case(node) – the case a node took, or -1

Pipeline overview

1. CP (xqcp) – generate a random graph, declare N categorical variables over C cases, and add EXCLUDE constraints per (edge, color) pair.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary, the one-hot row sums, and the per-edge exclusions, then computes energy
6. Decode – decoder reads each node’s case with ROWFIND, giving one color index per node

Usage

uv run python examples/graph_coloring/runner.py --seed 42
uv run python examples/graph_coloring/runner.py --n 6 --colors 4

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Maximum Independent Set

Source: examples/max_independent_set/README.md

Find the largest subset of nodes in an undirected graph such that no two selected nodes share an edge.

QUBO formulation

• Input: number of nodes N, edge list
• Model: N binary variables. x_i = 1 if node i is in the independent set.
• Objective: minimise -sum(x_i) (maximise set size)
• Constraints: per edge (i,j): x_i + x_j <= 1 (SLACK + EQUALITY)

Each edge inequality is encoded via SLACK + EQUALITY. A single binary slack variable s (capacity = 1) converts x_i + x_j <= 1 into the equality x_i + x_j + s = 1, and EQUALITY adds the penalty P*(x_i + x_j + s - 1)^2.

Slack variable indices start at num_nodes and are allocated one per edge.

DSL methods used

• problem.vec() – allocate untyped vector registers for indices and coefficients
• problem.slack(indices, coeffs, start_index, capacity) – append one slack entry per edge
• model.apply_equality(indices, coeffs, target, penalty) – EQUALITY constraint

Pipeline overview

1. CP (xqcp) – generate a random graph, declare binary variables (one per node), and encode each edge independence constraint via SLACK + EQUALITY.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that the independence constraints hold, then computes energy
6. Decode – decoder extracts the selected nodes

Usage

uv run python examples/max_independent_set/runner.py --seed 42
uv run python examples/max_independent_set/runner.py --n 7

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Vertex Cover

Source: examples/vertex_cover/README.md

Find the minimum subset of vertices such that every edge in an undirected graph has at least one endpoint in the subset.

QUBO formulation

• Input: number of nodes N, edge list
• Model: N binary variables. x_v = 1 if vertex v is in the cover.
• Objective: minimise sum(x_v)
• Constraints: per edge (i,j): x_i + x_j >= 1 (ATLEAST with k=1)

The at-least-1 constraint is encoded directly with ATLEAST. For each edge, ATLEAST allocates one slack variable at model.size and adds the penalty P*(x_i + x_j - 1 - s)^2, where s in {0,1} accounts for the case when both endpoints are selected (sum = 2).

DSL methods used

• problem.vec() – allocate a vector register for the two endpoint indices per edge
• model.apply_atleast(indices, k, penalty) – ATLEAST constraint with k=1

Pipeline overview

1. CP (xqcp) – generate a random graph, declare binary variables (one per vertex), and encode per-edge coverage constraints via ATLEAST.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that every edge is covered, then computes energy
6. Decode – decoder extracts the selected vertices

Usage

uv run python examples/vertex_cover/runner.py --seed 42
uv run python examples/vertex_cover/runner.py --n 7

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Travelling Salesman Problem

Source: examples/tsp/README.md

Find the shortest Hamiltonian tour through N cities given a random symmetric distance matrix.

QUBO formulation

• Input: num_cities (int), distance_matrix (list, flat upper triangle, n*(n-1)/2 entries)
• Model: an n x n binary grid. x[i, p] = 1 means city i is at tour position p.
• Objective: sum of distances between consecutive positions in the tour.
• Constraints: one-hot row (each city at exactly one position) and one-hot column (each position holds exactly one city), both with penalty 100.

Hamiltonian

The Hamiltonian is the sum of three terms:

$$H = H_{\text{dist}} + H_{\text{row}} + H_{\text{col}}$$

\(H_{\text{dist}}\) is the tour length. For every pair of cities \(i < j\) and every position \(p\), a term fires whichever direction the tour visits them in – city i at p and city j at the next position, or the reverse:

$$H_{\text{dist}} = \sum_{i<j} \sum_{p=0}^{n-1} d_{ij} \left( x_{i,p}, x_{j,(p+1) \bmod n} + x_{j,p}, x_{i,(p+1) \bmod n} \right)$$

\(H_{\text{row}}\) and \(H_{\text{col}}\) are the one-hot constraints apply_onehot_row and apply_onehot_col add, at penalty \(P = 100\):

$$H_{\text{row}} = P \sum_{i=0}^{n-1} \left( \sum_{p=0}^{n-1} x_{i,p} - 1 \right)^2, \qquad H_{\text{col}} = P \sum_{p=0}^{n-1} \left( \sum_{i=0}^{n-1} x_{i,p} - 1 \right)^2$$

XQMX has no field for a constant term. Each satisfied one-hot constraint drops its +P and leaves -P in the stored model instead of 0 – see Constraints.

\(H_{\text{row}}\) forces each city onto exactly one position; \(H_{\text{col}}\) forces each position to hold exactly one city. Both terms are zero as written on a valid tour, so they never change which valid tour is shortest – but because of the dropped constant above, what a satisfied constraint actually contributes is -P, not 0. That is the -2 * P * n = -800 term in the worked example below. A violation (a city visiting two positions, or a position holding two cities) still costs more than a satisfied constraint.

Whether that makes every invalid grid’s energy exceed every valid tour’s depends on \(P\) relative to the tour-length difference a violation can buy back. Constraints gives the general criterion. At \(P = 100\) it holds for this seed-42, 4-city instance. The best invalid grid scores -581, 6 above the worst valid tour’s -587. It does not hold at every instance where \(P = 100\) is used. At --n 5 --seed 7, the second command under Usage below, an invalid grid scores -770, below 40 of the 120 valid tours.

DSL methods used

• problem.input() – declare typed calldata inputs
• problem.define_model() – allocate binary 2D grid XQMX model
• problem.stow() – bind intermediate computations to named registers
• problem.range() – emit RANGE loops
• model.quadratic[(city_i, pos), (city_j, pos)].add() – accumulate quadratic coupling using 2D grid coordinates
• model.apply_onehot_row() – ONEHOTR constraint per city
• model.apply_onehot_col() – ONEHOTC constraint per position
• problem.output() – declare typed output slots
• problem.sample.colfind() – find the row index with value 1 in a given column

Pipeline overview

1. CP (xqcp) – build a random symmetric distance matrix, declare an n x n binary grid, and add quadratic distance terms plus one-hot row/column constraints.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and the one-hot row and column constraints, then computes energy
6. Decode – decoder extracts the tour as a sequence of city indices

Steps 3-6 are three independent XQVM programs plus a solver call in between, sharing data only through calldata and outputs:

flowchart LR
    ENC[Encoder] -->|model| SLV[xqsa solver]
    ENC -->|model| VER[Verifier]
    SLV -->|sample| VER
    SLV -->|sample| DEC[Decoder]
    VER -->|energy, valid| OUT[Host program]
    DEC -->|tour| OUT

The encoder’s calldata is num_cities, distance_matrix; the verifier’s is model, sample, num_cities; the decoder’s is sample, num_cities. See Three Programs for why the split exists.

Worked example

uv run python examples/tsp/runner.py --n 4 --seed 42 builds this 4-city instance (edge labels are distance_matrix, indexed by the upper-triangle position of each city pair):

graph LR
    0 ---|82| 1
    0 ---|15| 2
    0 ---|95| 3
    1 ---|4| 2
    1 ---|36| 3
    2 ---|32| 3

The runner returns this tour:

{
  "_note": "canonical CI golden",
  "_seed": 42,
  "energy": -650,
  "n": 4,
  "tour": [0, 2, 1, 3],
  "tour_distance": 150,
  "valid": 1
}

tour_distance is d(0,2) + d(2,1) + d(1,3) + d(3,0) = 15 + 4 + 36 + 95 = 150, matching \(H_{\text{dist}}\) for a valid tour. energy is H_{\text{dist}} + H_{\text{row}} + H_{\text{col}}: on a valid tour, each of the 4 rows and 4 columns contributes its one active variable’s -P linear term and nothing from the quadratic term (no two variables in the same row or column are both 1), for -P * n per constraint family, so energy = tour_distance - 2 * P * n = 150 - 2 * 100 * 4 = -650, matching the run.

Usage

uv run python examples/tsp/runner.py --seed 42
uv run python examples/tsp/runner.py --n 5 --seed 7 -o /tmp/tsp.json

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Knapsack

Source: examples/knapsack/README.md

The 0/1 Knapsack problem: given N items with integer weights and values, select a subset maximising total value subject to a weight capacity constraint.

QUBO formulation

• Input: N item weights and values, capacity W
• Model: N binary variables. x_i = 1 means item i is selected.
• Objective: minimise -sum(v_i * x_i)
• Constraints: capacity sum(w_i * x_i) <= W (SLACK + EQUALITY)

The inequality is encoded via SLACK + EQUALITY. SLACK appends binary slack variable entries (s_j with coefficients 2^j) to the index and coefficient vectors, converting the inequality to the equality sum(w_i*x_i) + sum(s_j*2^j) = W. EQUALITY then adds the penalty term P*(sum(a_k*x_k) - W)^2 to the QUBO.

DSL methods used

• problem.vec() – allocate untyped vector registers for indices and coefficients
• problem.slack(indices, coeffs, start_index, capacity) – append slack entries
• model.apply_equality(indices, coeffs, target, penalty) – EQUALITY constraint

Pipeline overview

1. CP (xqcp) – generate random item weights and values, declare binary variables, and encode the capacity inequality via SLACK + EQUALITY.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that the capacity constraint holds, then computes energy
6. Decode – decoder extracts the item selection

Usage

uv run python examples/knapsack/runner.py --seed 42
uv run python examples/knapsack/runner.py --n 6

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Bin Packing

Source: examples/bin_packing/README.md

Pack N items with given integer sizes into the minimum number of bins, each with a fixed capacity C.

QUBO formulation

• Input: N item sizes (list), number of bins B, bin capacity C
• Model: (N + 1) * B binary variables in an (N + 1) x B grid. Rows 0..N-1 are the assignment cells: x[i,b] = 1 if item i is placed in bin b. Row N holds one indicator per bin: y[b] = 1 if bin b is open.
• Objective: +BIN_COST on each indicator y[b], so the energy counts the bins the packing opens. A bias spread over the assignment cells instead would be identically N on every feasible packing, because each item lands in exactly one bin, and could not tell a one-bin packing from a three-bin one.
• Constraints:
  • Assignment per item i: sum_b x[i,b] = 1 (ONEHOTR, penalty 200)
  • Linking per (i, b): x[i,b] -> y[b] (IMPLIES, penalty 200)
  • Capacity per bin b: sum_i s_i * x[i,b] <= C (SLACK + EQUALITY, penalty 100)

The capacity inequality is encoded by appending binary slack variable entries to the column index/coefficient vectors, converting it to a weighted equality. Each bin gets its own slack block: bin b’s entries start at (N + 1) * B + b * bitlen(C), past every model variable and past every earlier bin’s block. Sharing one start index across bins would let one bin’s slack absorb another’s overflow, leaving the capacity constraint under-constrained.

DSL methods used

• model.apply_onehot_row(row, penalty) – ONEHOTR assignment constraint
• model.apply_implies(coord_a, coord_b, penalty) – IMPLIES linking constraint
• problem.vec() – allocate untyped vector registers for indices and coefficients
• problem.slack(indices, coeffs, start_index, capacity) – append slack entries
• model.apply_equality(indices, coeffs, target, penalty) – EQUALITY constraint
• xq_bitlen(value) – BITLEN, used to size each bin’s slack block

Pipeline overview

1. CP (xqcp) – generate random item sizes, declare an (N + 1) x B binary grid, and add ONEHOTR assignment constraints per item, IMPLIES links per cell, and SLACK + EQUALITY capacity constraints per bin.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary, the per-item assignment, the bin-usage links and the per-bin capacity, then computes energy
6. Decode – decoder extracts the bin assignments

Usage

uv run python examples/bin_packing/runner.py --seed 42
uv run python examples/bin_packing/runner.py --n 5 --bins 4

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Set Cover

Source: examples/set_cover/README.md

Given a universe of E elements and a collection of S sets, find the minimum sub-collection whose union equals the universe.

QUBO formulation

• Input: number of elements E, number of sets S, coverage membership matrix (flat list of E*S entries, covers[e][s] = 1 if set s covers element e)
• Model: S binary variables. x_s = 1 if set s is selected.
• Objective: minimise sum(x_s)
• Constraints: per element e: sum_{s: covers[e][s]=1} x_s >= 1 (ATLEAST with k=1)

For each element, the encoder iterates over all sets and uses a branch to conditionally push only covering set indices into the element’s index vector. ATLEAST then enforces that at least one covering set is selected.

DSL methods used

• problem.vec() – allocate a vector register for each element’s covering set indices
• problem.branch(cond, arm, default) – conditional VECPUSH based on coverage membership
• model.apply_atleast(indices, k, penalty) – ATLEAST constraint with k=1

Pipeline overview

1. CP (xqcp) – generate a random coverage matrix, declare binary variables (one per set), and encode per-element coverage constraints via conditional branching and ATLEAST.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that every element is covered, then computes energy
6. Decode – decoder extracts the selected sets

Usage

uv run python examples/set_cover/runner.py --seed 42
uv run python examples/set_cover/runner.py --num-sets 6

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Weighted Set Cover

Source: examples/weighted_set_cover/README.md

A generalisation of Set Cover where each set s has a coverage capacity cap[s] and each element e has a demand demand[e]. The goal is to select sets of minimum total cost such that the total capacity of covering selected sets meets each element’s demand.

QUBO formulation

• Input: number of elements E, number of sets S, set costs, set capacities, element demands, coverage membership matrix
• Model: S binary variables. x_s = 1 if set s is selected.
• Objective: minimise sum(cost[s] * x_s)
• Constraints: per element e: sum_{s: covers[e][s]=1} cap[s] * x_s >= demand[e] (ATLEASTW)

For each element, a branch conditionally pushes (set index, capacity) pairs into per-element index/coefficient vectors, then ATLEASTW enforces the weighted threshold.

DSL methods used

• problem.vec() – allocate vector registers for covering set indices and capacities
• problem.branch(cond, arm, default) – conditional VECPUSH based on coverage membership
• model.apply_atleastw(indices, coeffs, k, penalty) – ATLEASTW constraint

Pipeline overview

1. CP (xqcp) – generate a random weighted coverage instance, declare binary variables (one per set), and encode per-element weighted demand constraints via conditional branching and ATLEASTW.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that every demand is met, then computes energy
6. Decode – decoder extracts the selected sets

Usage

uv run python examples/weighted_set_cover/runner.py --seed 42
uv run python examples/weighted_set_cover/runner.py --num-sets 6

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Number Partition

Source: examples/number_partition/README.md

Given N positive integers, find a way to split them into two subsets of equal sum (or as close as possible if an exact split does not exist).

QUBO formulation

• Input: N positive integers a_i
• Model: N binary variables. x_i = 1 puts number a_i in subset A.
• Objective: minimise P * (sum(a_i * x_i) - S/2)^2 where S = sum(a_i)

An exact partition exists when S is even and the penalty evaluates to zero. The QUBO minimiser finds the balanced partition when one exists, or the most balanced split when the total is odd.

DSL methods used

• problem.vec() – allocate untyped vector registers for indices and coefficients
• model.apply_equality(indices, coeffs, target, penalty) – EQUALITY constraint

Pipeline overview

1. CP (xqcp) – generate random positive integers, declare binary variables (one per number), and encode the half-sum equality constraint via EQUALITY.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that the partition constraint holds, then computes energy
6. Decode – decoder extracts the subset assignment

Usage

uv run python examples/number_partition/runner.py --seed 42
uv run python examples/number_partition/runner.py --n 8

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Portfolio Optimization

Source: examples/portfolio_opt/README.md

Select a portfolio of exactly B assets from N candidates to maximise expected return while penalising higher-order risk cross-interactions.

QUBO formulation

• Input: N asset returns, cubic risk interactions (i, j, k, sigma), budget B
• Model: N binary variables. x_i = 1 if asset i is selected.
• Objective: -sum(r_i * x_i) + sum(sigma_ijk * x_i * x_j * x_k) – first term maximises return (minimising its negation), second penalises correlated three-asset risk interactions.
• Constraints: budget sum(x_i) = B (EQUALITY with unit coefficients, penalty 200)

Encoding strategy

Return terms are linear: ADDLINE(i, -r_i) per asset.

Cubic risk terms (i, j, k, sigma) are degree-reduced:

1. REDUCE(i, j, P_AUX) -> w (Rosenberg enforcement for w = x_i * x_j)
2. ADDQUAD(w, k, sigma) (sigma * w * x_k = sigma * x_i * x_j * x_k)

Budget constraint builds uniform-coefficient index/coeff vecs then calls EQUALITY with target = B and penalty = 200. EQUALITY is emitted after all objective (body) actions because it lands in the constraint section.

DSL methods used

• model.reduce(var_a, var_b, p_aux) – HOBO degree reduction for cubic risk terms
• problem.vec() – allocate index/coefficient vecs for the budget constraint
• model.apply_equality(indices, coeffs, target, penalty) – budget EQUALITY

Pipeline overview

1. CP (xqcp) – generate random returns and cubic risk interactions, declare binary variables, degree-reduce risk terms via REDUCE, and add a budget EQUALITY constraint.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary, that the budget constraint holds, and that each REDUCE auxiliary equals the product it stands for, then computes energy
6. Decode – decoder extracts the selected assets

Usage

uv run python examples/portfolio_opt/runner.py --seed 42
uv run python examples/portfolio_opt/runner.py --n 6 --budget 3

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Portfolio Rebalance

Source: examples/portfolio_rebalance/README.md

Choose a signed integer weight for each asset, trading expected return off against a risk matrix, subject to the weights summing to a budget. Negative weights are short positions, which is the whole reason this example is not a binary select-or-not model.

QUBO formulation

• Input: number of assets N, a return per asset, a symmetric N x N risk matrix flattened row-major
• Model: N integer variables x_i in [-5, 5], declared with lo=/hi=. The model holds y_i = x_i - lo in {0, ..., 10}; coefficients are written over x and sample.value() shifts back on the way out.
• Objective: -sum(r_i * x_i) + sum_{i <= j} C_ij * x_i * x_j
• Constraint: sum(x_i) = B, as the penalty P * (sum_i x_i - B)^2
• Energy: shifted twice over, and not comparable with any other example’s. The ranged domain drops the constant that substituting x = y + lo produces, because XQMX carries no offset field, and the budget square drops its own P*B^2 the way EQUALITY does. Both shifts are uniform across assignments, so argmin is exact even though the number is not the objective’s true value.

Encoding strategy

The budget constraint is written out by hand rather than handed to apply_equality. Every high-level constraint in the VM expands under x^2 = x, which holds for binary variables only, so xqcp refuses all of them off a binary model. Expanded, P * (sum_i x_i - B)^2 is P on each diagonal, 2P on each off-diagonal pair, and -2PB on each linear coefficient. Writing that square is the same work the HLF would have done, and it is what the open question about per-domain expansions is about.

The ranged domain then does its own rewriting underneath. Each quadratic write records w*lo against the linear coefficient of both named indices, because w * x_i * x_j expands to w*y_i*y_j + w*lo*y_i + w*lo*y_j + w*lo^2 once x = y + lo is substituted. A write to the diagonal lands both corrections on the one index, giving the 2*w*lo that squaring asks for. None of that is visible in the model-building code above.

lo and hi are literals. A runtime lo would want the decoder’s single calldata scalar, which the output loop bound already spends, and xqcp raises naming both rather than picking one.

DSL methods used

• problem.define_model(size=N, domain=Domain.INTEGER, lo=-5, hi=5) – ranged integer weights
• model.linear[i].add(w) and model.quadratic[i, j].add(w) – the only operations a non-binary model supports
• sample.value(i) – the weight in the domain it was declared over, rather than the stored y

What this example proves

valid == 1 proves that the domain check, the record-layer shift and the decode compose on a chosen assignment. It proves nothing about optimisation: no solver samples an integer model yet, so --solver is accepted, ignored, and the pipeline runs against a hand-picked weight vector that sits inside the domain and sums to the budget.

Pipeline overview

1. CP (xqcp) – generate returns and a symmetric risk matrix, declare N ranged integer weights, and write the objective and the budget square as coefficients
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – skipped; the runner supplies the assignment itself
5. Verify – verifier checks every weight is inside {0, ..., 10} against the k replayed from define_model, then computes energy
6. Decode – decoder reads each weight and adds lo, giving the signed weights back

Usage

uv run python examples/portfolio_rebalance/runner.py --seed 42
uv run python examples/portfolio_rebalance/runner.py --n 6

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Max-3-SAT

Source: examples/max3sat/README.md

Given M clauses of 3 positive literals over N binary variables, find the assignment that satisfies the maximum number of clauses.

QUBO formulation

• Input: N binary variables, M clauses of 3 positive literals
• Model: N binary variables. x_v in {0, 1}.
• Objective: minimise sum over clauses of P*(1-x_i)(1-x_j)(1-x_k)

A clause (i,j,k) is violated when all three variables are 0. Expanding the product (dropping the constant term):

P*(-x_i - x_j - x_k + x_i*x_j + x_i*x_k + x_j*x_k - x_i*x_j*x_k)

The cubic term -P*x_i*x_j*x_k is degree-reduced via REDUCE(i, j) -> w, introducing one auxiliary variable w per clause with Rosenberg enforcement P_AUX*(x_i*x_j - 2*x_i*w - 2*x_j*w + 3*w). The cubic term becomes the quadratic term -P*w*x_k.

DSL methods used

• model.reduce(var_a, var_b, p_aux) – HOBO degree reduction; returns a RegLoad holding the auxiliary variable index for chaining into quadratic terms

Pipeline overview

1. CP (xqcp) – generate random 3-literal clauses, declare binary variables, and degree-reduce the cubic violation terms via REDUCE.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that each Rosenberg REDUCE auxiliary equals the product it stands for, then computes energy
6. Decode – decoder extracts the variable assignment

Usage

uv run python examples/max3sat/runner.py --seed 42
uv run python examples/max3sat/runner.py --n 8 --m 10

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Cubic Optimization

Source: examples/cubic_opt/README.md

Minimise a cubic pseudo-Boolean objective over binary variables via single-stage HOBO degree reduction.

QUBO formulation

• Input: N binary variables, M cubic interaction terms (i, j, k, c)
• Model: N binary variables. Linear bias -1 per variable rewards selection, creating tension with the positive cubic terms.
• Objective: sum(c_t * x_i * x_j * x_k) - sum(x_v)

Each cubic term (i, j, k, c) is degree-reduced to quadratic via:

1. REDUCE(i, j, P_AUX) -> w – allocates auxiliary variable w with Rosenberg enforcement P_AUX*(x_i*x_j - 2*x_i*w - 2*x_j*w + 3*w)
2. ADDQUAD(w, k, c) – adds c*w*x_k = c*x_i*x_j*x_k to the QUBO

DSL methods used

• model.reduce(var_a, var_b, p_aux) – single-stage HOBO degree reduction

Pipeline overview

1. CP (xqcp) – generate random cubic interaction terms, declare binary variables with linear bias, and degree-reduce each cubic term via REDUCE.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that each Rosenberg REDUCE auxiliary equals the product it stands for, then computes energy
6. Decode – decoder extracts the variable assignment

Usage

uv run python examples/cubic_opt/runner.py --seed 42
uv run python examples/cubic_opt/runner.py --n 5 --m 4

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Quartic Optimization

Source: examples/quartic_opt/README.md

Minimise a degree-4 pseudo-Boolean objective via two-stage REDUCE chaining.

QUBO formulation

• Input: N binary variables, M quartic interaction terms (i, j, k, l, c)
• Model: N binary variables. Linear bias -1 per variable rewards selection, creating tension with the positive quartic terms.
• Objective: sum(c_t * x_i * x_j * x_k * x_l) - sum(x_v)

Each quartic term (i, j, k, l, c) is encoded via two-stage REDUCE:

1. w = REDUCE(i, j, P_AUX) – introduces auxiliary w; w approximates x_i*x_j.
2. v = REDUCE(w, k, P_AUX) – introduces auxiliary v; v approximates w*x_k = x_i*x_j*x_k. Here w is the variable index returned from the first REDUCE.
3. ADDQUAD(v, l, c) – adds c*v*x_l = c*x_i*x_j*x_k*x_l to the QUBO.

Each quartic term allocates 2 auxiliary variables. With M terms, the model grows by 2*M variables beyond the original N.

DSL methods used

• model.reduce(var_a, var_b, p_aux) – two chained HOBO degree reductions; the RegLoad returned by the first REDUCE is passed as var_a to the second

Pipeline overview

1. CP (xqcp) – generate random quartic interaction terms, declare binary variables with linear bias, and two-stage degree-reduce each quartic term via chained REDUCE.
2. Assemble – .xqasm text to bytecode via xquad.asm
3. Encode – run encoder on chosen XQVM to produce the XQMX model
4. Sample – solver runs SA/QPU/GPU over the model
5. Verify – verifier checks the sample is binary and that each Rosenberg REDUCE auxiliary equals the product it stands for, then computes energy
6. Decode – decoder extracts the variable assignment

Usage

uv run python examples/quartic_opt/runner.py --seed 42
uv run python examples/quartic_opt/runner.py --n 6 --m 3

Choosing a solver

Solver selection and install extras are the same for every example: see Using the Examples and Solving Overview. The default is cpu, and a non-default solver will not reproduce the canonical result.

Canonical output

example-smoke validates that the runner produces valid == 1 with --seed 42 --solver cpu. The smoke test is invariant-based – it checks validity, not exact output.

Cookbook

The fourteen examples under examples/ each solve one problem – Knapsack, TSP, Graph Coloring – and each already contains a working encoding. Nothing in the repository names those encodings as patterns you can reuse on a problem that is not itself Knapsack or TSP. This chapter names five recurring shapes instead, each grounded in the example or examples that embody it and shown as code that actually ran. One further page covers getting the arithmetic right once a shape is chosen.

This chapter assumes Modelling – it builds problems with the same xqcp calls that chapter introduces and does not re-explain them. It also assumes Quadratic Models for what a penalty term is and why one exists at all.

The Five Shapes

Permutations and Assignment are the same grid with one constraint family removed – see Assignment for the direction that mistake most often runs. Selection Under Budget and Mutual Exclusion overlap at one boundary: a capacity of exactly 1 on a pair is the same instruction family EXCLUDE gives you directly, covered in Mutual Exclusion. examples/bin_packing/ and examples/graph_coloring/ each compose two of these shapes in one problem (assignment plus a capacity, and assignment plus exclusion, respectively) – reading a problem as “which of these shapes does each part look like” scales to a combined problem the same way it does to a single-pattern one.

The Arithmetic Page

Integer Scaling is not a shape – every pattern above needs it, sooner or later, while turning real-valued problem data into the integer coefficients every pattern above is written in terms of. Sizing the penalty weight itself, and reading a solver’s output to tell whether a cheap constraint violation bought a good-looking energy, is Constraints’s territory, not a cookbook page of its own.

Where This Chapter Stops

None of these pages re-derives what a one-hot, EXCLUDE, or EQUALITY constraint expands to in linear and quadratic coefficients – that table is High-Level Constraints, already written, and this chapter links to it rather than repeating it. This chapter is about recognising which instruction family a new problem needs and what it costs once chosen, not about the instructions themselves.

Permutations

Assign N things to N positions so that each thing gets exactly one position and each position gets exactly one thing. Recognise it whenever “order” or “visit each once” appears in a problem statement: a tour, or a seating arrangement of N guests into N chairs.

The encoding is an \(N \times N\) binary grid, x[thing, position] = 1 meaning that thing sits at that position, with a one-hot constraint on every row and every column: ONEHOTR for “this thing takes exactly one position,” ONEHOTC for “this position holds exactly one thing.” A feasible assignment is a permutation matrix – exactly one 1 per row and per column – and the two constraint families together are what force that shape.

The Shape, Isolated

examples/tsp/ is the one example in this repository that embodies this pattern: x[city, position] = 1 means a city sits at a tour position, and the objective adds the distance between consecutive positions’ cities on top of the same row/column one-hot pair (TSP, examples/tsp/runner.py). Stripping the distance objective out leaves the pattern on its own – allocate the grid, apply both one-hot families, decode with colfind:

from xquad import cp

def build_problem(n: int) -> cp.Problem:
    problem = cp.Problem("PurePermutation")
    num_items = problem.input("num_items", type=cp.Types.Int)
    problem.define_model(size=num_items * num_items, domain=cp.Domain.BINARY,
                          rows=num_items, cols=num_items)

    with problem.range(0, num_items) as row:
        problem.model.apply_onehot_row(row, penalty=10)
    with problem.range(0, num_items) as col:
        problem.model.apply_onehot_col(col, penalty=10)

    perm = problem.output("perm", type=cp.Types.Vec)
    with problem.range(0, num_items) as position:
        perm.append(problem.sample.colfind(col=position, value=1))
    return problem

Compiling for n = 3 and running the encoder on the Rust VM, then solving the result with SolverCPU at seed=42. All six permutations of three things are tied at -60, so a different seed decodes to a different one and both lines below still hold:

decoded permutation (thing at each position): [0, 1, 2]
is a permutation of range(N): True
energy: -60

xquad vm check --text accepts the compiled encoder:

ok: permutation_encoder.xqasm (29 instructions)

and xquad vm run --text ... --calldata 3 reproduces the same model deterministically from the assembled bytecode, independent of the Python solve above:

outputs:
  [0] = Model(XqmxModel { domain: Binary, size: 9,
    linear: {0: -20, ..., 8: -20},
    quadratic: {(0, 1): 20, (0, 2): 20, ..., (7, 8): 20}, rows: 3, cols: 3 })

Nine linear terms at -20 (one per cell: each cell belongs to one row and one column, so it picks up -penalty twice) and eighteen quadratic terms at +20 (every same-row and every same-column pair) – exactly ONEHOTR’s and ONEHOTC’s expansions from High-Level Constraints superimposed on the same grid. examples/tsp/ builds the identical row/column structure and adds distance coefficients on top; nothing about the permutation half changes when an objective joins it.

Cost in Variables

The grid is \(N^2\) variables – no slack, no auxiliary variables, since both ONEHOTR and ONEHOTC only rewrite coefficients on cells that already exist. That quadratic growth is the real cost of this pattern: doubling the number of things to order quadruples the variable count, before an objective term is added.

Failure Mode

Applying only one axis – ONEHOTR without ONEHOTC, or the reverse – does not raise an error; it produces a model where each thing still picks exactly one position, but nothing stops two things from picking the same one. That looser rule is Assignment. The other failure is structural rather than semantic: ONEHOTR/ONEHOTC read grid dimensions from RESIZE, so a model with no grid set has no row or column for them to constrain. Both raise InvalidGridDimensions at the instruction that needed the grid – see High-Level Constraints. xquad vm check does not catch it, since grid dimensions are runtime values, so the failure surfaces when the encoder runs rather than when it compiles.

Assignment

Match each of N things to exactly one of B slots, with no requirement that every slot receives a thing and no requirement that B equals N. Recognise it whenever one set is matched into another with no requirement that the match run both ways: items into bins, nodes onto colours.

This is Permutations with the column half removed. Encode it as an \(N \times B\) grid, x[thing, slot] = 1 meaning that thing occupies that slot, with a one-hot family on every row only: each thing picks exactly one slot, but a slot may hold zero, one, or many things. Dropping the column constraint gives a different rule, not a weaker form of the same one, and Permutations names the mistake in the other direction: applying only one axis where both are wanted.

Recognising the Row-Only Shape

examples/bin_packing/ assigns each item to exactly one bin – one ONEHOTR per item row of its grid (Bin Packing, examples/bin_packing/runner.py):

# Assignment constraint: each item i must go in exactly one bin
with problem.range(0, num_items) as i:
    problem.model.apply_onehot_row(i, 200)

ONEHOTR is the special case of EQUALITY with \(a_k = 1\) and \(b = 1\), which High-Level Constraints states directly. Writing it by hand – a vec() pair per row, an index and a 1 pushed per column, then apply_equality(indices, coeffs, 1, 200) – expresses the same constraint and costs a loop and two vectors per row. The model here is defined with both rows and cols set, so apply_onehot_row applies and the hand-rolled form buys nothing.

Bin packing’s grid has one row more than it has items. Rows 0..N-1 are the assignment cells; the extra row N holds one indicator variable per bin, and apply_implies((i, b), (num_items, b), 200) opens bin b as soon as any item lands in it. That indicator row is what lets the objective count bins: a bias spread over the assignment cells would sum to N on every feasible packing, because each item lands in exactly one bin, so it could not tell a one-bin packing from a three-bin one.

Running examples/bin_packing/runner.py --seed 42 (4 items, 3 bins, capacity 5, sizes [1, 2, 1, 1]) decodes to assignment: [0, 0, 0, 0] – all four items in bin 0, total size 5 against a capacity of 5. Which single bin gets used is a tie: packing everything into bin 1 or bin 2 has the same energy, and the solver’s seed decides which one comes back. Every item appears in exactly one bin, which is what the row constraint guarantees; nothing requires a bin to be used, and the bin-count objective pushes the other way.

Bin packing composes this row-assignment pattern with a second, unrelated one – each bin’s contents must not exceed its capacity, encoded with SLACK plus EQUALITY exactly like the capacity constraint in Selection Under Budget. That capacity half is not this page’s concern; see Selection Under Budget for the pattern on its own.

Cost in Variables

The grid costs \(N \times B\) variables against Permutations’ \(N^2\), and the saving is entirely the grid: it is cheaper exactly when there are fewer slots than things (\(B < N\)). Dropping the column constraint costs nothing and saves nothing in variables, since neither one-hot family allocates any – EQUALITY with in-range indices does not grow model.size on its own (High-Level Constraints).

Failure Mode

The one this page warns about runs the other direction from Permutations: adding a column one-hot to an assignment problem that does not want one silently turns “N things into B slots” into “a bijection between things and slots,” which only has a feasible solution at all when \(N = B\). If a Permutations-shaped model with RESIZEd grid dimensions comes back consistently infeasible, check whether the problem actually needs both axes constrained or only one.

Selection Under Budget

Choose a subset of N things, each with a cost, so the total cost does not exceed a fixed capacity, while maximising (or minimising) something else about the chosen subset. Recognise it whenever a problem says “at most,” “no more than,” or “fits within” about a sum of per-item weights: a knapsack, a budget of assets, a shipment under a weight limit.

An inequality (<=) combined with a per-item weight that is not always 1 is what distinguishes this shape from Mutual Exclusion’s <= on a pair, or a plain one-hot’s = 1 – here the bound is a general capacity and the items carry arbitrary integer weights. None of ONEHOTR, ONEHOTC, EXCLUDE, or IMPLIES express an inequality; ATLEAST and ATLEASTW cover the mirrored >= direction directly (Vertex Cover, Weighted Set Cover), but XQVM has no <= counterpart over an arbitrary weighted sum. SLACK bridges the gap, turning the inequality into an equality that EQUALITY can enforce – see Constraints for why that substitution is exact, and SLACK for the instruction itself. model.apply_inequality(indices, coeffs, target, capacity, penalty) composes both calls into one – see Constraints, including the caveat there that the target parameter is not a target value: it is where slack variables begin, normally the count of real variables, and capacity is the actual bound. This page assumes both and covers only the recognition and the cost.

The Canonical Instance

examples/knapsack/ is this pattern with nothing else mixed in – Knapsack, examples/knapsack/runner.py. Calling its own build_problem with a fresh instance (six items, capacity 12) rather than the seed-42 instance the Modelling chapter already worked through:

from examples.knapsack.runner import build_problem
from xquad.vm import VM

n = 6
weights = [2, 3, 4, 5, 6, 7]
values = [3, 4, 5, 8, 9, 10]
capacity = 12

problem = build_problem(n, weights, values, capacity)
programs = problem.compile()

vm = VM()
vm.set_calldata([n, weights, values, capacity])
vm.set_output_slots(1)
vm.run(programs.encoder)
model = vm.outputs()[0]

model.size comes back 10: six item variables plus four slack bits, S = floor(log2(12)) + 1 = 4. Solving with SolverCPU and decoding:

selection [0, 0, 0, 1, 0, 1] weight 12 capacity 12 feasible True value 18 energy -14418
verifier energy -14418 valid 1

Items 3 and 5 (weights 5 and 7, values 8 and 10), weight exactly at capacity, value 18. Brute-forcing all 64 subsets confirms 18 is the true optimum, not just a feasible value: 28 of the 64 fit within capacity, and no other reaches value 18. xquad vm check on the compiled encoder (43 instructions) passes.

Cost in Variables

\(N\) item variables plus \(S = \lfloor \log_2(\text{capacity}) \rfloor + 1\) slack bits – logarithmic in the capacity, not the capacity itself, which is what makes representing “at most a million units” cost twenty extra variables rather than a million. Integer Scaling covers a consequence of this formula worth knowing before choosing how finely to scale a fractional capacity: the slack count grows with the scaled capacity, so a needlessly large scale factor costs real variables, not just larger coefficients.

examples/bin_packing/ repeats this exact SLACK + EQUALITY shape once per bin, for a per-bin capacity rather than a single global one – see Assignment, which covers the rest of that problem’s structure. Its start_index argument to SLACK advances per bin – model_vars + b * xq_bitlen(capacity) – so each bin’s capacity constraint reaches for its own slack block. Passing the same fixed start index on every iteration is the trap when copying this block as a per-bin template: the bins then share slack variables, and one bin’s overflow can be absorbed by another’s slack. The capacity-constraint shape itself, in isolation, is the same one this page covers.

Failure Mode

A SLACK/EQUALITY pair that looks right can still be infeasible for a reason that has nothing to do with the penalty weight: if every item’s weight already exceeds capacity, or the cheapest single item does, no slack combination rescues it, since slack only adds toward the target, never subtracts from the real items’ contribution (SLACK). Check the raw numbers – smallest item weight against capacity – before reaching for penalty-weight guidance to explain a solver that keeps returning something that looks wrong.

Mutual Exclusion

Two choices conflict, and a solution may take at most one of them. Recognise it in “not both,” “at most one,” or an adjacency rule that forbids a shared property between connected things: two colours on adjacent nodes, two overlapping bookings.

EXCLUDE is the direct opcode: pop penalty, then two variable indices, and add quad[i, j] += penalty – a pure coupling term, no linear part, that costs penalty exactly when both variables are 1 and nothing otherwise (High-Level Constraints). This page also covers IMPLIES, the directional relative: “picking i requires j” rather than “picking both is forbidden.”

EXCLUDE, Direct

examples/graph_coloring/ applies EXCLUDE once per edge per colour: two adjacent nodes may not both hold the same colour (Graph Coloring, examples/graph_coloring/runner.py):

with problem.range(0, num_edges) as e:
    offset = problem.stow("offset", e * 2)
    u = problem.stow("u", edges_in.get(offset))
    v = problem.stow("v", edges_in.get(offset + 1))
    with problem.range(0, num_colors_in) as c:
        problem.model.apply_exclude((u, c), (v, c), 200)

Running examples/graph_coloring/runner.py --seed 1 (5 nodes, 4 colours, 6 edges) returns colors: [0, 1, 0, 0, 2], is_valid: true, energy: -1000 – every one of the six edges checked by hand connects two nodes with different colours.

Forcing the default --seed 42 instance down to --colors 3 shows what EXCLUDE can and cannot do. That seed’s random edges form a 4-clique among nodes {0, 2, 3, 4}, every pair among them an edge, and a 4-clique has no 3-colouring at all. The run reports is_valid: false, energy: -800, and valid: 0; no adjustment to EXCLUDE’s penalty weight changes that. EXCLUDE enforces a rule, and it can only enforce a colouring that exists. The colour count defaults to 4 for exactly this reason. Note that the generated verifier’s valid agrees with the runner’s own is_valid here: it checks each EXCLUDE against the sample directly.

The Same Rule, Encoded Without EXCLUDE

examples/max_independent_set/ needs the identical x_i + x_j <= 1 rule per edge – two adjacent nodes cannot both be in the set – but builds it with SLACK plus EQUALITY instead of EXCLUDE (Max Independent Set):

edge_indices = problem.vec()
edge_coeffs = problem.vec()
edge_indices.push(ni)
edge_indices.push(nj)
edge_coeffs.push(1)
edge_coeffs.push(1)
problem.slack(edge_indices, edge_coeffs, num_nodes + e, 1)
problem.model.apply_equality(edge_indices, edge_coeffs, 1, 200)

Both encode the same inequality; EXCLUDE is a one-instruction convenience for exactly the pairwise case, while SLACK + EQUALITY costs one extra slack variable per edge to reach the identical rule (Selection Under Budget’s pattern, applied here to a capacity of 1). Reach for EXCLUDE whenever the conflict is pairwise, which it almost always is; reach for the manual form only when the exclusion needs to compose with other terms already riding the same index/coefficient vectors.

Running examples/max_independent_set/runner.py --seed 42 (same 5-node, 6-edge graph as the graph-coloring default above, node set {0, 2, 3, 4} forming the clique) returns in_set: [0, 1, 0, 0, 1] – nodes {1, 4}, is_independent: true. Running examples/vertex_cover/runner.py --seed 42 against the identical graph returns cover: [1, 0, 1, 1, 0] – nodes {0, 2, 3}, the exact complement of {1, 4} in {0, 1, 2, 3, 4}. That is not a coincidence of this one instance: a set of nodes covers every edge exactly when the nodes left out share no edge, so a minimum vertex cover and a maximum independent set on the same graph are always complements of each other. But vertex_cover’s own constraint, x_i + x_j >= 1 via ATLEAST, is not this page’s pattern – it requires at least one endpoint, the opposite direction from forbidding both. Do not reach for EXCLUDE when a problem says “at least one of,” even on the same graph shape that motivates exclusion elsewhere.

IMPLIES

No example in this repository calls apply_implies. A minimal demonstration, run rather than assumed, checks the sign directly:

from xquad import cp
from xquad.vm import VM

problem = cp.Problem("ImpliesDemo")
n = problem.input("n", type=cp.Types.Int)
problem.define_model(size=n, domain=cp.Domain.BINARY)
problem.model.apply_implies(0, 1, 50)   # picking 0 requires picking 1
problem.model.linear[0].add(-30)        # a reason to pick 0 at all

programs = problem.compile()
vm = VM()
vm.set_calldata([2])
vm.set_output_slots(1)
vm.run(programs.encoder)
model = vm.outputs()[0]

Reading the resulting coefficients back and evaluating all four assignments by hand:

linear: {0: 20}, quadratic[0,1]: -50
x0=0 x1=0 -> H=0
x0=0 x1=1 -> H=0
x0=1 x1=0 -> H=20
x0=1 x1=1 -> H=-30

x0=1, x1=0 – picking 0 without 1, the forbidden combination – costs 20 more than leaving both off, and exactly 50 more than the legal x0=1, x1=1, matching the penalty=50 passed in. The -30 reward on x0 alone is what gives the solver a reason to pick it in the first place; without it, x0=0 would dominate trivially and the implication would never be tested. IMPLIES’ own expansion, linear[i] += penalty, quad[i, j] += -penalty (High-Level Constraints), is exactly what produced 20 and -50 here: linear[0] = -30 + 50 = 20, no change to linear[1], quadratic[0,1] = 0 - 50 = -50.