aglais-xqvm-quantum-vm

# 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`, `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.