Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
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
; 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
use aglais_xqvm_vm::Vm;
fnmain() {
// Load bytecode from a fileletbytecode = std::fs::read("program.xqbc").expect("read bytecode");
letmut vm = Vm::new();
vm.load(&bytecode).expect("load");
vm.run().expect("run");
// Inspect top of stack after executionifletSome(val) = vm.stack_top() {
println!("Result: {:?}", val);
}
}
Accessing registers after execution
use aglais_xqvm_vm::{Vm, Value};
fnrun_and_inspect(bytecode: &[u8]) -> Value {
letmut 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:
Generate coefficients in a Rust harness (problem-specific math).
Emit .xqasm files parameterised by those coefficients.
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]externcrate alloc;
use alloc::vec::Vec;
use aglais_xqvm_bytecode::StreamReader;
pubfndecode_instructions(bytes: &[u8]) ->Vec<alloc::string::String> {
letmut reader = StreamReader::new(bytes);
letmut out = Vec::new();
whileletOk(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:
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:
