aglais-xqvm-quantum-vm

Original：🇺🇸 English
Translated

Expertise in Aglais XQVM, a hardware-agnostic Rust quantum virtual machine for QUBO/Ising binary optimization models targeting quantum annealers.

8installs
Sourcearadotso/trending-skills
Added on

NPX Install

npx skill4agent add aradotso/trending-skills aglais-xqvm-quantum-vm

Tags

Translated version includes tags in frontmatter
quantum-virtual-machinerust-quantumqubo-optimizationaglais-xqvmquantum-annealing

SKILL.md Content

View Translation Comparison →

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

sh
# 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

sh
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

toml
# Cargo.toml
[dependencies]
aglais-xqvm-bytecode = { path = "crates/bytecode" }
aglais-xqvm-vm       = { path = "crates/vm" }
For 
no_std
environments (WASM, bare-metal):
toml
[dependencies]
aglais-xqvm-bytecode = { path = "crates/bytecode", default-features = false, features = ["alloc"] }

Workspace Crate Overview

CrateBinaryRole
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

sh
# 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

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

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

xqvm
— Interpreter

sh
# Execute bytecode
xqvm program.xqbc

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

Full pipeline

sh
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

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

Registers (0–255)

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

Arithmetic

asm
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

asm
; 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

asm
; 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

asm
; 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

asm
  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:
rust
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)

rust
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

rust
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

rust
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
    .
rust
// 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

asm
; 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

asm
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)

rust
#![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

sh
# 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:
CategoryInstructions
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:
sh
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
:
toml
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:
sh
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.