【免费下载链接】xquadA rust implementation of the Quip Networks quantum virtual machine.项目地址https://gitcode.com/gh_mirrors/xq/xquad点击查看免费下载xqffi是 XQuad 工具链的 Python 扩展层它通过 PyO3和.xqasm汇编器xqasm以原生扩展的形式暴露给 CPython。本文以 xqffi/README.md 为主线结合 xqffi/src/lib.rs、xqffi/src/vm.rs、xqffi/src/asm.rs、xqffi/src/verifier.rs 等源码讲解安装方式、asm/vm/verifier三个子模块的完整 API、底层实现原理以及与上层xquad伞形包的配合方式。读完本文你将能够直接通过 Python 完成.xqasm源码 → 字节码 → 静态验证 → VM 执行 → 读取输出/剩余栈 的完整链路并理解每一步背后的 Rust 实现与预算保护机制。xqffi 是什么纯 FFI 桥接层而非重实现xqffi 在架构上刻意保持薄——它是一个纯 FFI shim只把 Rust 侧的类型与入口点重新暴露出来不包含任何解释器逻辑或汇编逻辑的重新实现。这一点在 xqffi/src/lib.rs 的模块文档中写得很明确它只是xqasm与xqvm两个 crate 的 PyO3 绑定。与之相对面向终端用户的各种便利设施——Program/Session/RunResult、关键字形式的 calldata、trace 检查——都放在纯 Python 的xquad伞形包中由 xqffi 提供底层引擎。也就是说两层职责划分是层载体职责FFI 桥接层xqffiRust cdylib暴露xqvm::Vm、xqasm::assemble_source、xqvm::verifier等 Rust 入口便利层xquad纯 PythonProgram/Session/RunResult、calldata 校验、双后端切换等从 Cargo.toml 可以看到xqffi 的依赖只有xqvm、xqasm与pyo3三项lib目标同时启用cdylib供 Python 加载与rlib供工作区内 Rust 测试与消费方直接引用不必经过 Python 层两种 crate 类型。pyo3启用了abi3-py313feature这意味着生成的扩展遵循 CPython 的 stable ABIabi3可以跨多个 Python 3.13 补丁版本复用。发行与构建方式以maturin构建发布为 abi3 的 manylinux wheelsx86_64与aarch64CPython ≥ 3.13外加一个通用的 sdist 供其他平台使用。pyproject.toml 中声明requires-python 3.13、构建后端为maturin1.7,2、module-name xqffi与 Cargo 的[lib] name一致并开启strip减小扩展体积。许可证为 AGPL-3.0-or-later。安装pip install xqffi安装后即可import xqffi。xqffi顶层模块本身只负责注册三个子模块见下文模块注册机制日常使用直接导入子模块from xqffi.asm import assemble_source from xqffi.vm import Vm表面 API 总览xqffi 暴露三个 Python 子模块分别对应 Rust 侧的三个入口子模块绑定对象对应 Rust 代码xqffi.asmparse_xqasm/assemble_source/disassemble/instruction_countxqffi/src/asm.rsxqffi.vmVm/XqmxModel/XqmxSample及常量xqffi/src/vm.rsxqffi.verifierverify/verify_sourcexqffi/src/verifier.rs模块注册机制sys.modules 处理三个子模块是在模块入口函数 xqffi/src/lib.rs 中手工注册的。这里有一个值得注意的细节PyO3 的add_submodule只会在父模块上设置属性不会自动把子模块写进sys.modules——而from xqffi.asm import parse_xqasm这类导入依赖sys.modules解析。因此注册代码同时调用了sys_modules.set_item(xqffi.asm, ...)等把子模块显式登记进sys.modules保证两种导入方式import xqffi.asm与from xqffi.asm import ...都能解析。xqffi.asm汇编与反汇编xqffi.asm是xqasmcrate 的绑定提供四个函数xqffi/src/asm.rsassemble_source(source: str) - bytes把.xqasm源码直接汇编为wire 格式.xqb原始字节。内部调用xqasm::assemble_source后取其program.encode()结果以 Pythonbytes返回。适合需要.xqb字节码输出的外部消费方。任何解析或汇编失败都会抛出ValueError。parse_xqasm(source: str) - dict同样走一次完整汇编但返回的是一个面向xqvm_py.program.Program直接消费的字典结构为{ instructions: [(opcode_u8, operand_bytes, pc), ...], jump_targets: {target_id: pc, ...}, }其中operand_bytes是 Pythonbytes对象PyO3 对Vecu8的默认转换。xqvm_py.core.executor通过instr.operands[i]索引单字节值——tuple[int, ...]与bytes都支持该操作xqvm_py的program_from_xqasm辅助函数会把它包成Instructiondataclass 所需的 tuple 形状。jump_targets则由Program::jump_table()的 id → pc 映射填充。disassemble(bytecode: bytes) - str对原始字节码调用xqvm::Disassembly生成人类可读的反汇编清单每条指令一行带 pc 偏移跳转目标显示为.N标签。注意输出不可往返——标签已被物化成.N标记且清单携带 pc 偏移因此不能用parse_xqasm把它解析回去只用于展示与xquad dism的输出格式一致。如果需要把.xqb字节码程序化地转换回Program应直接使用xqvm::bytecode::codec::decode。instruction_count(bytecode: bytes) - int解码字节码并用xqvm::InstructionStream遍历计数返回指令条数。字节码无法解码时抛出ValueError。一个典型的汇编 → 反汇编 → 计数组合用法from xqffi.asm import assemble_source, disassemble, instruction_count src PUSH 40\nPUSH 2\nADD\nHALT bc assemble_source(src) # wire-format bytes print(instruction_count(bc)) # 4 print(disassemble(bc)) # 每行一条指令带 pc 偏移xqffi.vm底层一次性执行 VMxqffi.vm是一致性测试conformance harness驱动的低层 API是对xqvm::Vm的一个小包装xqffi/src/vm.rs。核心用法from xqffi.vm import Vm from xqffi.asm import assemble_source vm Vm() vm.set_calldata([40, 2]) vm.set_output_slots(1) vm.run(assemble_source(src)) assert vm.outputs() [42]Vm 类的方法面PyVmxqffi/src/vm.rs暴露以下方法方法作用说明set_calldata(list)安装输入槽元素可以是int、list[int]、XqmxModel、XqmxSample或None其他类型抛TypeErrorset_output_slots(n)预留输出槽数量对应Vm::set_output_slotsset_step_limit(limit)设置步数上限精确语义0不允许执行任何指令set_unlimited_steps()解除步数上限用于无界运行set_memory_limit(bytes)设置内存分配预算默认 1 GiBmemory_used()上次运行计费字节数用于观测分配预算消耗run(bytecode)执行 wire 格式字节码解码失败或执行失败抛RuntimeErroroutputs()读取输出槽返回list元素为int/list[int]/XqmxModel/XqmxSample/None未设置槽stack()读取剩余栈list[int]自底向上steps()累计步数自构造或最近一次reset以来的计费成本单位总数instructions()指令分发总数与steps()不同见下文步数与指令数reset()重置 VM 状态清空栈、寄存器、循环栈、步数与内存计数器、输出槽、calldata 与输出两个预算设置step/memory limit作为配置保留异质 calldata 的类型映射calldata 现在支持异质元素set_calldata内部由py_to_regvalxqffi/src/vm.rs做类型分派映射到 Rust 的RegValPython 侧RustRegVal变体intRegVal::Intlist[int]任意整数序列RegVal::VecIntXqmxModelRegVal::ModelXqmxSampleRegVal::SampleNoneRegVal::Unsetoutputs()的逆分派regval_to_py除了映射回上述类型外还会把RegVal::VecXqmx转换成XqmxModel的 Python 列表。关于None槽位有个重要的行为细节Python 的[None, 5]经py_to_regval会变成RegVal::Unset加一个RegVal::Intcalldata 长度保持为 2。这样槽位缺席与槽位值为空在 Rust 与 Python 两个后端之间保持一致详见 xquad/vm.py 中_prepare_calldata_python的注释。步数与指令数metering 的两个计数steps()与instructions()是两个不同的计数xqffi/src/vm.rsstep是计费成本单位每条指令在分派前先收取基础成本而工作量随程序控制数据伸缩的操作码会收取更多参见 spec/xqvm/METERING.md。instruction只是被分派的指令条数。因此一个工作量与数据规模相关的操作码一次分派可能对应多个 step。这也是xqvm中DEFAULT_STEP_LIMIT 10_000_000xqvm/src/vm.rs存在的意义作为针对失控循环的安全上限。XqmxModel / XqmxSample薄 getter/setter 包装XqmxModel与XqmxSample是对 Rust 侧xqvm::XqmxModel/xqvm::XqmxSample的薄包装用于直接操作模型与样本from xqffi.vm import XqmxModel, XqmxSample m XqmxModel(domainbinary, size3, rows0, cols0) m.set_linear(0, 2) # SETLINE 语义越界抛 IndexError m.set_quad(0, 1, -1) # SETQUAD 语义越界抛 IndexError m.linear_items() # 稀疏线性项 list[(index, coefficient)] m.quadratic_items() # 稀疏二次项 list[((i, j), coefficient)]i j构造签名xqffi/src/vm.rsXqmxModel(domain, size, rows0, cols0, kNone)XqmxSample(domain, values, rows0, cols0, kNone)其中domain取binary、spin或integer后者必须提供k 2。domain_from_strxqffi/src/vm.rs会拒绝非法组合integer缺k、k 2、binary/spin带k、未知 domain 名都会抛ValueError。构造期的三重校验这是 FFI 层承担安全边界职责的体现check_sizexqffi/src/vm.rssize不得超过xqvm::MAX_ALLOCATION_SIZE即u32::MAXxqvm/src/vm.rs。六个 XQMX 分配器都拒绝超过该上限的size因此一个更大的模型/样本必然是任何程序都无法构造出来的。check_gridxqffi/src/vm.rs(0, 0)表示无网格的初始状态其他情况必须满足rows * cols size即RESIZE的要求否则抛ValueError——把不合法的网格在宿主构建处就拒绝而不是等到第一个网格操作码读取时才报InvalidGridDimensions。XqmxSample的域校验构造时逐一检查values中每个值都在 domain 内xqffi/src/vm.rs越域抛ValueError。这是必要的安全缺口补丁Vm::set_calldata在 Rust 侧设计为不可失败信任嵌入方的路径宿主提供的样本不会经过 VM 内SETLINE/ADDLINE的域检查又因为该类型只暴露 getter、构造后不可被改出 domain下游也就不必再扫描。XqmxSample还支持len(sample)__len__即变量数与__repr__。模块级常量xqffi.vm还导出三个常量让 Python 宿主从 Rust 侧读取预算值而不必重复抄写字面量xqffi/src/vm.rs常量值含义DEFAULT_STEP_LIMIT10_000_000默认步数上限DEFAULT_MEMORY_LIMIT1 301 GiB默认分配预算MAX_ALLOCATION_SIZEu32::MAX分配器允许的最大sizexqcli run的--step-limit默认值、xquad的 Python VM 包装、conformance harness 的每向量默认值都从同一个常量读取从机制上杜绝四套字面量漂移参见 xqvm/src/vm.rs 的注释。xqffi.verifier执行前静态验证xqffi.verifier是xqvm::verifier的绑定提供两个函数xqffi/src/verifier.rsfrom xqffi.verifier import verify, verify_source verify_source(PUSH 1 HALT) # 返回 None通过 verify_source(NEXT HALT) # 抛 ValueError: NoActiveLoop: ...verify(bytecode: bytes)对已汇编字节码运行默认验证器。verify_source(source: str)先汇编.xqasm源码再验证等价于assemble_sourceverify的一次性组合。两者在首个违规处抛出ValueError。错误消息以稳定的变体名开头如NoActiveLoop: loop instruction at byte 0x0000 ...调用方可以直接用msg.split(: , 1)[0]做程序化分派而无需自定义异常类。验证器检查什么verify解码为Program后运行全部验证阶段xqvm/src/verifier/mod.rs阶段检查内容典型错误StructuralPhase截断的指令字节、未知操作码TruncatedInstruction、BadOpcodeJumpTargetPhase跳转标签 ≥ 目标表长度UndefinedJumpTargetLoopNestingPhase循环开/闭平衡、循环上下文读取NoActiveLoop、UnmatchedLoopRegisterTypePhaseCFG 上的读前写read-before-write与类型态失配ReadUnsetRegister、RegisterTypeMismatchUninitRegisterPhaseCFG AND-meet至少一条路径上未初始化ReadUnsetRegisterStackDepthPhaseCFG 上的栈深下溢/上溢、循环平衡、汇合点失配StackUnderflow、StackOverflowRisk、LoopStackImbalance、StackDepthMismatch前三个阶段structural、jump、loop通过一次合并扫描运行其余阶段各自构建控制流图并执行数据流分析。概括地说每个跳转都落在TARGET上、每个寄存器都在被写入之后才被读取、栈深度保持平衡。完整的验证器说明见 docs/book/src/xqvm/verifier.md。与上层 xquad 伞形包配合交互式 / 多轮执行 API对于 REPL / notebook / 脚本工作流README 推荐使用xquad.program的Program/Session/RunResult交互式多轮 APIfrom xquad.program import Program program Program.from_source(src) session program.session(output_slots1) session.set_calldata([40, 2]) result session.run() assert dict(result.outputs) {0: 42}Program.from_source(source)内部就是调用xqffi.asm.assemble_source生成字节码Program.load(bytes)则直接接受 wire 格式字节码见 xquad/program.py。Session.run()返回RunResult其outputs是以槽位索引为键的字典未设置槽显示为None此外还包含剩余栈stack与步数stepsxquad/program.py。Session还提供set_step_limitNone表示无界需显式写出、set_memory_limit默认 1 GiB等配置xquad/program.py。双后端统一 VMxquad 还通过 xquad/vm.py 的VM类提供统一解释器接口可按VMBackend.RUST/VMBackend.PYTHON选择后端Rust 后端走xqffi.vm.VmPython 后端走纯 Python 参考 VMxqvm_py.Executor。所有 FFI 类型都在边界处转换调用方只接触xquad.types中的规范 Python 类型XQMX、Vec、int、list[int]。两个后端按同一收费表计费因此对任何能双端运行的程序memory_used()结果一致。xquad 包本身是一个薄 meta-package把xqffi、xqcp、xqsa统一到一个命名空间下xquad/init.py使编码 → 采样 → 验证 → 解码全流水线只需一组导入。深入FFI 边界的信任模型与测试印证为什么边界校验放在宿主侧xqffi 中反复出现的一个设计主题是**校验放在宿主边界而不是 VM 内部**xqvm::Vm::set_calldata被设计为 infallible不可失败是受信任嵌入方的路径因此异质 calldata 的类型检查、XqmxSample的域检查都在xqffi的set_calldata/ 构造器中完成xqffi/src/vm.rs。模型/样本构造时的size、grid、索引边界检查同理XqmxModel::set_linear等系数写入底层是稀疏存储、接受任意索引所以越界检查在宿主边界完成与 VM 内部系数操作码的行为保持一致xqffi/src/vm.rs。这一点在 xquad/tests/test_model_boundary.py 中有直接测试验证 Python 侧构建的模型/样本在到达 VM 前就被拒绝QUI-1164 / QUI-1168。一致性测试如何驱动它conformance harness 是 xqffi 的头号用户。在 conformance/src/lib.rs 中run_rust对每个测试向量执行源码汇编 → 执行与字节码 encode/decode 往返 → 执行两条路径并强制结果一致防止汇编器与解码器产生行为漂移。xqffi的xqffi.vm即对应 harness 驱动的 Python 侧等价物xqffi/src/vm.rs。reset 语义的坑Vm.reset()会清空包括calldata 与输出槽在内的全部运行状态只保留两个预算设置。因此一个reset 后再次运行的宿主必须重新调用set_calldata与set_output_slots——跳过它们会让下一个程序在无 calldata、零输出槽的情况下运行结果是错误答案而非报错xqffi/src/vm.rs。xquad.vm.VM每次运行都会重装两者因此该陷阱只在使用xqffi.vm.Vm类直连时可达。更多资料纯 Python 参考 VMconformance oraclexqvm_py编译为.xqasm的约束编程 DSLxqcp求解器适配层CPU/GPU 退火、D-Wave QPU、Quip 网络xqsa带交互式 API 的伞形包xquad程序运行全流程教程docs/book/src/running/README.md计量与计费规范spec/xqvm/METERING.md虚拟机规范与编码格式spec/xqvm/SPEC.md、spec/xqvm/ENCODING.md许可证AGPL-3.0-or-later。赞分享【免费下载链接】xquadA rust implementation of the Quip Networks quantum virtual machine.项目地址https://gitcode.com/gh_mirrors/xq/xquad点击查看免费下载相关推荐xquad 嵌入指南用 InstructionBuilder 以 Rust 流式 API 构建 XQVM 字节码xquad 嵌入指南用 InstructionBuilder 以 Rust 流式 API 构建 XQVM 字节码 InstructionBuilder 是 x在 Rust 中执行现有 Python 代码PyO3 嵌入解释器调用指南在 Rust 中执行现有 Python 代码PyO3 嵌入解释器调用指南 导读 当你的 Rust 程序需要复用已经写好的 Python 代码工具函数、业务脚开发工具PyO3 教程使用 [pyclass] 与 [pymethods] 在 Rust 中定义 Python 类PyO3 教程使用 pyclass 与 pymethods 在 Rust 中定义 Python 类 pyclass 是 PyO3 基于 Rust 过程宏体系提开发工具上一篇章节执行闭环深度解析AI-Novel-Writing-Assistant如何逐章完成生成、审核、修复与状态回灌下一篇rsuite Grid 栅格多行布局实战列自动换行机制与源码级原理解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考