aglais-xqvm-quantum-vm

What this skill does

# Aglais XQVM Skill

> Skill by [ara.so](https://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

| 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

```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:

| Category | Instructions |
|---|---|
| Stack | `PUSH`, `POP`, `DUP`, `SWAP` |
| Registers | `LOAD`, `STORE` |
| Arithmetic | `ADD`, `SUB`, `MUL`, `DIV`,