aglais-xqvm-quantum-vm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Aglais XQVM Skill

Aglais XQVM技能

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.

由ara.so提供的技能——2026每日技能合集。

Aglais XQVM是一款基于Rust开发的硬件无关量子计算虚拟机。它为面向量子退火器的二进制优化问题（QUBO/Ising公式表示）提供统一的字节码中间表示——相当于量子计算领域的LLVM。该虚拟机基于栈结构，拥有256槽寄存器文件，支持

no_std + alloc

以部署在WASM/裸金属环境中，包含四个crate：bytecode、assembler、disassembler和interpreter。

Installation & Setup

安装与设置

Prerequisites

前置条件

undefined

undefined

Install Rust stable

安装稳定版Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install dev tools (cargo-nextest, clippy, etc.)

安装开发工具（cargo-nextest、clippy等）

make deps

undefined

make deps

undefined

Build from source

从源码构建

git clone https://github.com/QuipNetwork/xq-rs
cd xq-rs
cargo build --release

git clone https://github.com/QuipNetwork/xq-rs
cd xq-rs
cargo build --release

Binaries: target/release/xqasm, target/release/xqdism, target/release/xqvm

二进制文件路径：target/release/xqasm, target/release/xqdism, target/release/xqvm

undefined

undefined

Add as a library dependency

添加为库依赖

toml

undefined

toml

undefined

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"] }

[dependencies] aglais-xqvm-bytecode = { path = "crates/bytecode" } aglais-xqvm-vm = { path = "crates/vm" }


针对`no_std`环境（WASM、裸金属）：

```toml
[dependencies]
aglais-xqvm-bytecode = { path = "crates/bytecode", default-features = false, features = ["alloc"] }

Workspace Crate Overview

工作区Crate概述

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

Crate	二进制文件	作用
`aglais-xqvm-bytecode`	—	操作码表、指令类型、构建器、二进制编解码器、流读取器
`aglais-xqvm-asm`	`xqasm`	文本汇编器：将 `.xqasm` 转换为 `.xqbc` 字节码
`aglais-xqvm-disasm`	`xqdism`	字节码反汇编器：将字节码转换为人类可读的清单
`aglais-xqvm-vm`	`xqvm`	字节码解释器：栈、寄存器、QUBO/Ising执行

CLI Commands

CLI命令

xqasm

— Assembler

xqasm

— 汇编器

undefined

undefined

Assemble a source file to bytecode

将源文件汇编为字节码

xqasm program.xqasm -o program.xqbc

Assemble with verbose output

带详细输出的汇编

xqasm program.xqasm -o program.xqbc --verbose

undefined

xqasm program.xqasm -o program.xqbc --verbose

undefined

xqdism

— Disassembler

xqdism

— 反汇编器

undefined

undefined

Inspect bytecode encoding as human-readable listing

以人类可读清单形式查看字节码编码

xqdism program.xqbc

Pipe to file

输出到文件

xqdism program.xqbc > listing.txt

undefined

xqdism program.xqbc > listing.txt

undefined

xqvm

— Interpreter

xqvm

— 解释器

undefined

undefined

Execute bytecode

执行字节码

xqvm program.xqbc

Run with debug output (if supported)

带调试输出运行（若支持）

xqvm program.xqbc --debug

undefined

xqvm program.xqbc --debug

undefined

Full pipeline

完整流程

xqasm problem.xqasm -o problem.xqbc && xqdism problem.xqbc && xqvm problem.xqbc

xqasm problem.xqasm -o problem.xqbc && xqdism problem.xqbc && xqvm problem.xqbc

XQASM Language Reference

XQASM语言参考

The assembler accepts

.xqasm

text files. The VM is stack-based; most instructions pop operands from the stack and push results.

汇编器接受

.xqasm

文本文件。虚拟机基于栈结构；大多数指令从栈中弹出操作数并将结果压入栈中。

Basic stack operations

基础栈操作

asm

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

asm

; 推入两个整数并相加
PUSH 10
PUSH 32
ADD
HALT

Registers (0–255)

寄存器（0–255）

asm

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

asm

PUSH 42
STORE 0        ; 弹出栈内容 → 寄存器0
LOAD  0        ; 将寄存器0内容推入栈

Arithmetic

算术运算

asm

PUSH 10
PUSH 3
ADD            ; stack: [13]
PUSH 7
SUB            ; stack: [6]
PUSH 2
MUL            ; stack: [12]
PUSH 4
DIV            ; stack: [3]

asm

PUSH 10
PUSH 3
ADD            ; 栈内容: [13]
PUSH 7
SUB            ; 栈内容: [6]
PUSH 2
MUL            ; 栈内容: [12]
PUSH 4
DIV            ; 栈内容: [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

asm

; 创建一个3元素向量 [1, 2, 3]
PUSH 1
PUSH 2
PUSH 3
PUSH 3         ; 长度
VEC            ; 栈内容: [Vec([1,2,3])]
STORE 1

QUBO / Ising model construction

QUBO/Ising模型构建

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

asm

; XQMX_NEW n 创建一个n变量的QUBO模型
PUSH 4
XQMX_NEW       ; 栈内容: [XqmxModel(4个变量)]
STORE 2

; 设置二次耦合项 Q[i][j] = weight
LOAD  2
PUSH  0        ; i
PUSH  1        ; j
PUSH  -1       ; 权重（整数编码）
XQMX_SET_Q    ; 修改寄存器2中的模型

; 设置线性偏置 h[i] = weight
LOAD  2
PUSH  0
PUSH  5
XQMX_SET_H

; 评估候选解的能量
LOAD  2        ; 模型
PUSH  0        ; 样本寄存器（XqmxSample）
XQMX_EVAL     ; 将能量值推入栈

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

asm

; RANGE lo hi → 推入循环栈条目，ITER遍历该范围
PUSH 0
PUSH 5
RANGE          ; 循环i从0到5（不含5）
ITER           ; 推进；完成时跳转到匹配的END_ITER之后
  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

asm

  PUSH 0
loop:
  PUSH 1
  ADD
  DUP
  PUSH 10
  LT
  JMP_TRUE loop
HALT

Rust API: Bytecode Builder

Rust API：字节码构建器

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()
}

使用

aglais-xqvm-bytecode

以编程方式构建程序：

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

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 API：运行虚拟机

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);
    }
}

rust

use aglais_xqvm_vm::Vm;

fn main() {
    // 从文件加载字节码
    let bytecode = std::fs::read("program.xqbc").expect("read bytecode");

    let mut vm = Vm::new();
    vm.load(&bytecode).expect("load");
    vm.run().expect("run");

    // 执行后检查栈顶元素
    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))
}

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

实际应用模式：以QUBO表示旅行商问题（TSP）

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.
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");
}

crates/vm/examples/tsp/

目录包含一个完整的旅行商问题示例，以QUBO形式编码并由Rust驱动。该模式流程如下：

生成系数：在Rust驱动程序中完成（问题特定的数学计算）。
生成
.xqasm
文件：使用上述系数参数化生成。
汇编并运行：使用
```
xqasm
```
/
```
xqvm
```
工具。

rust

// crates/vm/examples/tsp/main.rs模式
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

模式：在汇编中构建QUBO模型

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

asm

; 2变量QUBO：最小化 x0 - x1 + 2*x0*x1
PUSH 2
XQMX_NEW
STORE 0

LOAD 0
PUSH 0
PUSH -1        ; h[0] = -1 （线性项）
XQMX_SET_H

LOAD 0
PUSH 1
PUSH -1        ; h[1] = -1 （线性项）
XQMX_SET_H

LOAD 0
PUSH 0
PUSH 1
PUSH 2         ; Q[0][1] = 2 （二次项）
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

asm

PUSH 4
XQMX_NEW
STORE 0

PUSH 0
PUSH 4
RANGE
ITER
  ; ITER后寄存器1保存当前循环索引
  LOAD  0
  LOAD  1      ; 索引i
  LOAD  1      ; 索引i（对角线→线性项）
  PUSH  -1
  XQMX_SET_Q
END_ITER

HALT

Pattern: no_std bytecode decoding (WASM)

模式：no_std字节码解码（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
}

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

开发流程

undefined

undefined

Run all lints and tests (mirrors CI)

运行所有检查和测试（与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

undefined

cargo run --example tsp --manifest-path crates/vm/Cargo.toml

undefined

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.

crates/bytecode/src/types/table.rs

中的操作码表是所有76条指令的唯一权威来源。主要类别如下：

类别	指令
栈操作	`PUSH` , `POP` , `DUP` , `SWAP`
寄存器操作	`LOAD` , `STORE`
算术运算	`ADD` , `SUB` , `MUL` , `DIV` , `NEG`
比较运算	`EQ` , `LT` , `GT` , `LE` , `GE`
控制流	`JMP` , `JMP_TRUE` , `JMP_FALSE` , `CALL` , `RET` , `HALT`
迭代	`RANGE` , `ITER` , `END_ITER`
向量操作	`VEC` , `VEC_GET` , `VEC_SET` , `VEC_LEN`
QUBO/Ising操作	`XQMX_NEW` , `XQMX_SET_Q` , `XQMX_SET_H` , `XQMX_EVAL` , `XQMX_SAMPLE`

所有操作数均为大端字节序。二进制格式为无文件头的纯指令流。

Troubleshooting

故障排除

xqasm: command not found

xqasm: command not found

Ensure

target/release

is on

$PATH

or use the full path:

export PATH="$PWD/target/release:$PATH"

确保

target/release

已加入

$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.

虚拟机严格基于栈结构。所有弹出值的指令要求栈中存在对应值。检查每个操作前是否有

PUSH

LOAD

指令，且循环不会在未恢复栈平衡的情况下消耗值。

ITER

never terminates

ITER

永不终止

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

RANGE

会将循环边界推入循环栈（与值栈分离）。确保每个

RANGE

都有匹配的

END_ITER

，且范围边界（

lo

hi

）按正确顺序推入（先

lo

后

hi

）。

Build fails in

no_std

environment

no_std

环境下构建失败

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.

禁用

aglais-xqvm-bytecode

的默认特性并启用

alloc

特性：

toml

aglais-xqvm-bytecode = { ..., default-features = false, features = ["alloc"] }

VM crate（

aglais-xqvm-vm

）依赖

std

，不适合裸金属环境。

Inspecting unexpected bytecode

检查异常字节码

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

运行前使用

xqdism

验证汇编器输出：

xqasm suspect.xqasm -o suspect.xqbc
xqdism suspect.xqbc   # 检查指令序列和操作数值
xqvm   suspect.xqbc

License

许可证

AGPL-3.0-or-later. Embedding in proprietary network services requires source disclosure under the AGPL.

AGPL-3.0-or-later。将其嵌入专有网络服务需遵循AGPL协议披露源码。