From aradotso-trending-skills-37
Assists developers using Aglais XQVM, a Rust quantum virtual machine for QUBO/Ising binary optimization on quantum annealers. Covers XQASM assembly, disassembly, bytecode execution, and no_std/WASM deployment.
npx claudepluginhub joshuarweaver/cascade-ai-ml-agents-misc-1 --plugin aradotso-trending-skills-37This skill uses the workspace's default tool permissions.
> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
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.
# Install Rust stable
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Install dev tools (cargo-nextest, clippy, etc.)
make deps
git clone https://github.com/QuipNetwork/xq-rs
cd xq-rs
cargo build --release
# Binaries: target/release/xqasm, target/release/xqdism, target/release/xqvm
# 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"] }
| 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 |
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
xqasm problem.xqasm -o problem.xqbc && xqdism problem.xqbc && xqvm problem.xqbc
The assembler accepts .xqasm text files. The VM is stack-based; most instructions pop operands from the stack and push results.
; push two integers and add them
PUSH 10
PUSH 32
ADD
HALT
PUSH 42
STORE 0 ; pop stack → register 0
LOAD 0 ; push register 0 → stack
PUSH 10
PUSH 3
ADD ; stack: [13]
PUSH 7
SUB ; stack: [6]
PUSH 2
MUL ; stack: [12]
PUSH 4
DIV ; stack: [3]
; 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
; 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
; 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
PUSH 0
loop:
PUSH 1
ADD
DUP
PUSH 10
LT
JMP_TRUE loop
HALT
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()
}
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);
}
}
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);
}
}
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))
}
The crates/vm/examples/tsp/ directory contains a complete Travelling Salesman Problem encoded as a QUBO driven by a Rust harness. The pattern is:
.xqasm files parameterised by those coefficients.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");
}
; 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
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
#![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
}
# 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
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.
xqasm: command not foundEnsure target/release is on $PATH or use the full path:
export PATH="$PWD/target/release:$PATH"
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 terminatesRANGE 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).
no_std environmentDisable 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.
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
AGPL-3.0-or-later. Embedding in proprietary network services requires source disclosure under the AGPL.