aradotso/aglais-xqvm-quantum-vm

Aglais XQVM Skill

Skill by ara.so — Daily 2026 Skills collection.

Aglais XQVM is a hardware-agnostic virtual machine for quantum computing written in Rust. It provides a unified bytecode intermediate representation for binary optimization problems (QUBO/Ising formulations) targeting quantum annealers — think LLVM for quantum computing. The VM is stack-based with a 256-slot register file, supports no_std + alloc for WASM/bare-metal deployment, and ships four crates: bytecode, assembler, disassembler, and interpreter.

Installation & Setup

Prerequisites

# Install Rust stable
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install dev tools (cargo-nextest, clippy, etc.)
make deps

Build from source

git clone https://github.com/QuipNetwork/xq-rs
cd xq-rs
cargo build --release
# Binaries: target/release/xqasm, target/release/xqdism, target/release/xqvm

Add as a library dependency

# Cargo.toml
[dependencies]
aglais-xqvm-bytecode = { path = "crates/bytecode" }
aglais-xqvm-vm       = { path = "crates/vm" }

For no_std environments (WASM, bare-metal):

[dependencies]
aglais-xqvm-bytecode = { path = "crates/bytecode", default-features = false, features = ["alloc"] }

Workspace Crate Overview

| Crate | Binary | Role | |---|---|---| | aglais-xqvm-bytecode | — | Opcode table, instruction types, builder, binary codec, stream reader | | aglais-xqvm-asm | xqasm | Text assembler: .xqasm → .xqbc bytecode | | aglais-xqvm-disasm | xqdism | Bytecode → human-readable listing | | aglais-xqvm-vm | xqvm | Bytecode interpreter: stack, registers, QUBO/Ising execution |

CLI Commands

xqasm — Assembler

# Assemble a source file to bytecode
xqasm program.xqasm -o program.xqbc

# Assemble with verbose output
xqasm program.xqasm -o program.xqbc --verbose

xqdism — Disassembler

# Inspect bytecode encoding as human-readable listing
xqdism program.xqbc

# Pipe to file
xqdism program.xqbc > listing.txt

xqvm — Interpreter

# Execute bytecode
xqvm program.xqbc

# Run with debug output (if supported)
xqvm program.xqbc --debug

Full pipeline

xqasm problem.xqasm -o problem.xqbc && xqdism problem.xqbc && xqvm problem.xqbc

XQASM Language Reference

The assembler accepts .xqasm text files. The VM is stack-based; most instructions pop operands from the stack and push results.

Basic stack operations

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

Registers (0–255)

PUSH 42
STORE 0        ; pop stack → register 0
LOAD  0        ; push register 0 → stack

Arithmetic

PUSH 10
PUSH 3
ADD            ; stack: [13]
PUSH 7
SUB            ; stack: [6]
PUSH 2
MUL            ; stack: [12]
PUSH 4
DIV            ; stack: [3]

Vectors / integer arrays

; build a 3-element vector [1, 2, 3]
PUSH 1
PUSH 2
PUSH 3
PUSH 3         ; length
VEC            ; stack: [Vec([1,2,3])]
STORE 1

QUBO / Ising model construction

; XQMX_NEW n creates an n-variable QUBO model
PUSH 4
XQMX_NEW       ; stack: [XqmxModel(4 vars)]
STORE 2

; set quadratic coupling Q[i][j] = weight
LOAD  2
PUSH  0        ; i
PUSH  1        ; j
PUSH  -1       ; weight (integer encoding)
XQMX_SET_Q    ; modifies model in reg 2

; set linear bias h[i] = weight
LOAD  2
PUSH  0
PUSH  5
XQMX_SET_H

; evaluate energy of a candidate solution
LOAD  2        ; model
PUSH  0        ; sample register (XqmxSample)
XQMX_EVAL     ; pushes energy onto stack

Control flow & iteration

; RANGE lo hi → loop stack entry, ITER steps through it
PUSH 0
PUSH 5
RANGE          ; loop i in 0..5
ITER           ; advance; jumps past matching END_ITER when done
  LOAD 0
  PUSH 1
  ADD
  STORE 0
END_ITER

HALT

Labels and jumps

  PUSH 0
loop:
  PUSH 1
  ADD
  DUP
  PUSH 10
  LT
  JMP_TRUE loop
HALT

Rust API: Bytecode Builder

Use aglais-xqvm-bytecode to construct programs programmatically:

use aglais_xqvm_bytecode::{BytecodeBuilder, Instruction, Opcode};

fn build_add_program() -> Vec<u8> {
    let mut builder = BytecodeBuilder::new();

    builder.emit(Instruction::Push(10));
    builder.emit(Instruction::Push(32));
    builder.emit(Instruction::Add);
    builder.emit(Instruction::Halt);

    builder.finish()
}

Decoding bytecode (stream reader)

use aglais_xqvm_bytecode::StreamReader;

fn decode(bytes: &[u8]) {
    let mut reader = StreamReader::new(bytes);
    while let Some(instr) = reader.next_instruction().unwrap() {
        println!("{:?}", instr);
    }
}

Rust API: Running the VM

use aglais_xqvm_vm::Vm;

fn main() {
    // Load bytecode from a file
    let bytecode = std::fs::read("program.xqbc").expect("read bytecode");

    let mut vm = Vm::new();
    vm.load(&bytecode).expect("load");
    vm.run().expect("run");

    // Inspect top of stack after execution
    if let Some(val) = vm.stack_top() {
        println!("Result: {:?}", val);
    }
}

Accessing registers after execution

use aglais_xqvm_vm::{Vm, Value};

fn run_and_inspect(bytecode: &[u8]) -> Value {
    let mut vm = Vm::new();
    vm.load(bytecode).unwrap();
    vm.run().unwrap();
    vm.register(0).cloned().unwrap_or(Value::Int(0))
}

Real-World Pattern: TSP as QUBO

The crates/vm/examples/tsp/ directory contains a complete Travelling Salesman Problem encoded as a QUBO driven by a Rust harness. The pattern is:

1. Generate coefficients in a Rust harness (problem-specific math).
2. Emit .xqasm files parameterised by those coefficients.
3. Assemble + run with xqasm / xqvm.

// crates/vm/examples/tsp/main.rs pattern
use std::process::Command;

fn assemble_and_run(src: &str, out: &str) {
    let asm = Command::new("xqasm")
        .args([src, "-o", out])
        .status()
        .expect("xqasm failed");
    assert!(asm.success());

    let run = Command::new("xqvm")
        .arg(out)
        .status()
        .expect("xqvm failed");
    assert!(run.success());
}

fn main() {
    assemble_and_run("init.xqasm",    "init.xqbc");
    assemble_and_run("problem.xqasm", "problem.xqbc");
    assemble_and_run("eval.xqasm",    "eval.xqbc");
}

Common Patterns

Pattern: build a QUBO model in assembly

; 2-variable QUBO: minimise x0 - x1 + 2*x0*x1
PUSH 2
XQMX_NEW
STORE 0

LOAD 0
PUSH 0
PUSH -1        ; h[0] = -1  (linear)
XQMX_SET_H

LOAD 0
PUSH 1
PUSH -1        ; h[1] = -1  (linear)
XQMX_SET_H

LOAD 0
PUSH 0
PUSH 1
PUSH 2         ; Q[0][1] = 2 (quadratic)
XQMX_SET_Q

HALT

Pattern: iterate over model variables

PUSH 4
XQMX_NEW
STORE 0

PUSH 0
PUSH 4
RANGE
ITER
  ; register 1 holds current loop index after ITER
  LOAD  0
  LOAD  1      ; index i
  LOAD  1      ; index i (diagonal → linear term)
  PUSH  -1
  XQMX_SET_Q
END_ITER

HALT

Pattern: no_std bytecode decoding (WASM)

#![no_std]
extern crate alloc;

use alloc::vec::Vec;
use aglais_xqvm_bytecode::StreamReader;

pub fn decode_instructions(bytes: &[u8]) -> Vec<alloc::string::String> {
    let mut reader = StreamReader::new(bytes);
    let mut out = Vec::new();
    while let Ok(Some(instr)) = reader.next_instruction() {
        out.push(alloc::format!("{:?}", instr));
    }
    out
}

Development Workflow

# Run all lints and tests (mirrors CI)
make all

# Run only tests
cargo test --workspace

# Run lints
cargo clippy --workspace --all-targets -- -D warnings

# Format
cargo fmt --all

# Run a specific example
cargo run --example tsp --manifest-path crates/vm/Cargo.toml

Instruction Set Quick Reference

The opcode table in crates/bytecode/src/types/table.rs is the single source of truth for all 76 instructions. Key categories:

| Category | Instructions | |---|---| | Stack | PUSH, POP, DUP, SWAP | | Registers | LOAD, STORE | | Arithmetic | ADD, SUB, MUL, DIV, NEG | | Comparison | EQ, LT, GT, LE, GE | | Control flow | JMP, JMP_TRUE, JMP_FALSE, CALL, RET, HALT | | Iteration | RANGE, ITER, END_ITER | | Vectors | VEC, VEC_GET, VEC_SET, VEC_LEN | | QUBO/Ising | XQMX_NEW, XQMX_SET_Q, XQMX_SET_H, XQMX_EVAL, XQMX_SAMPLE |

All operands are big-endian. The binary format is a bare instruction stream with no file header.

Troubleshooting

xqasm: command not found

Ensure target/release is on $PATH or use the full path:

export PATH="$PWD/target/release:$PATH"

Stack underflow at runtime

The VM is strictly stack-based. Every instruction that pops values requires them to be present. Check that PUSH / LOAD precedes every operation, and that loops don't consume values without restoring the stack balance.

ITER never terminates

RANGE pushes loop bounds onto the loop stack (separate from the value stack). Ensure every RANGE has a matching END_ITER and that the range bounds (lo, hi) are pushed in the correct order (lo first, hi second).

Build fails in no_std environment

Disable default features and enable the alloc feature on aglais-xqvm-bytecode:

aglais-xqvm-bytecode = { ..., default-features = false, features = ["alloc"] }

The VM crate (aglais-xqvm-vm) requires std and is not suitable for bare-metal.

Inspecting unexpected bytecode

Use xqdism to verify the assembler output before running:

xqasm suspect.xqasm -o suspect.xqbc
xqdism suspect.xqbc   # check instruction sequence and operand values
xqvm   suspect.xqbc

License

AGPL-3.0-or-later. Embedding in proprietary network services requires source disclosure under the AGPL.