【免费下载链接】xquadA rust implementation of the Quip Networks quantum virtual machine.项目地址https://gitcode.com/gh_mirrors/xq/xquad点击查看免费下载本文以 xqvm_py/README.md 为骨架结合xqvm_py包源码、xqffi绑定、conformance测试与向量数据展开。xqvm_py是 X-Quadratic Virtual MachineXQVM的纯 Python 参考实现其职责是作为 XQuad 工具链的可执行一致性基准conformance oracleconformance/目录下每一个测试向量都必须在这一参考实现与 Rust 生产运行时xqvm上产生完全一致的可观测状态。阅读完本文你将掌握xqvm_py的包结构与各模块职责、如何通过 CLI 与编程接口运行.xqasm/.xqb程序、其执行模型与计量/计费机制以及它如何支撑跨实现的一致性验证。项目定位过渡性的参考实现而非生产运行时xqvm_py是一个 Python reference implementation参考实现对应规范见 spec/xqvm/SPEC.md权威技术规范。它与 Rust 生产运行时 xqvm 构成参考 生产的双实现格局。README 开篇用一个醒目的Status -- transitional过渡性状态框定了它的生命周期定位每一个 conformance 目录下的向量都必须在 Python 参考实现和 Rustxqvm生产运行时上产生完全一致的可观测状态一旦 Rust 运行时经过充分实战检验xqvm_py可能被整体移除届时一致性向量升级为Rust 必须精确产出这些输出的参考数据或降级为原型沙盒——在 Python 中先行试验新 opcode / VM 特性待其获得规范席位后再迁移因此不要在基础设施上硬依赖xqvm_py的存在。从源码结构看包内大量注释都在强调镜像 Rust 实现这一约束例如 xqvm_py/metering.py 开篇即声明常量与公式逐值镜像xqvm/src/metering.rs。Scope纯 Python 执行栈不含汇编器README 明确了xqvm_py的范围边界模块面内容包含纯 Pythonexecutor取指-译码-执行循环、state栈/寄存器/循环控制/跳转表、opcodes、xqmx稀疏二次矩阵model/sample 两种模式、vector类型化vecint/vecxqmx、tracer不包含汇编器与反汇编器。xqasmRust crate 是唯一实现经xqffi.asmpyo3暴露给 Python测试与 CLI shim 都通过xqvm_py.program_from_xqasm把.xqasm文本转换成可执行的Program这意味着文本 → 指令流的解析路径完全委托给 Rustxqvm_py/program.py中的program_from_xqasm调用xqffi.asm.parse_xqasm见 xqffi/src/asm.rs后者在 Rust 侧完成xqasm::assemble_source与codec::decode再把(opcode_byte, operand_bytes, pc)元组列表和跳转表以 Python dict 形式回传由 Python 侧包装成Instructiondataclass。历史上曾有xqvm.assembler树已随 QUI-440 移除。包布局flat layoutxqvm_py/目录本身就是包扁平布局所有核心模块直接位于包根下xqvm_py/ -- 此目录即包本身扁平布局 __init__.py re-export 公共表面Executor、Program、…… __main__.py python -m xqvm_py 入口 executor.py 取指-译码-执行循环 state.py 栈、寄存器、循环控制、跳转表 opcodes.py Opcode 枚举 操作数元数据 program.py Program dataclass program_from_xqasm() xqmx.py 稀疏二次矩阵model sample 模式 vector.py 类型化 vecint / vecxqmx errors.py 类型化运行时错误 tracer.py 逐步执行跟踪器 cli/ python -m xqvm_py run ... tests/ pytest 测试套件构建 wheel 时排除xqvm_py/init.py re-export 了Executor、Program、Opcode、MachineState、Value、Vec、XQMX及大量工具函数兼容旧的from xqvm_py import Executor, Opcode, ...导入习惯当前版本号为0.4.3.dev0。包元数据见 xqvm_py/pyproject.tomlrequires-python 3.13唯一硬依赖为与工作区同版本的xqffi0.4.3.dev0精确锁定五个发行包共享同一工作区版本号。wheel 构建通过 hatchling 排除tests/**、README.md等。快速开始环境准备在 xquad 工作区根目录执行README 原文uv sync # 安装 xqvm_pyeditable xqffi经 maturin 构建 uv run pytest xqvm_py/tests # 运行完整测试套件uv sync会同时把xqffi的 Rust cdylib 经 maturin 构建出来——这是program_from_xqasm能工作的前提。Makefile中test-python目标Makefile同样以uv run --no-sync pytest xqvm_py/tests ...的方式执行并刻意使用--no-sync以避免在测试前重新同步依赖。CLIpython -m xqvm_py runREADME 给出一个最小示例echo PUSH 5 PUSH 3 ADD HALT /tmp/prog.xqasm uv run python -m xqvm_py run /tmp/prog.xqasm # CLI shimrun子命令的完整参数实现在 xqvm_py/cli/run.py参数默认值说明file必填程序文件.xqasm或.xqb均可--text关强制把 FILE 当作汇编文本解释未知扩展名时用--text兜底--calldata 1,2,3[]逗号分隔的 i64 calldata 值按序填入 INPUT 槽--inputs inputs.json无JSON 文件内容形如{calldata: [...]}优先于--calldata--outputs N16保留的输出槽数量OUTPUT 到 N的槽位会以OutputIndex失败--step-limit N10_000_000步数上限精确语义0一条指令都不执行默认值与 Rust VM 一致--memory-limit N1 301 GiB分配预算字节对每个分配指令先计费后分配没有不限哨兵需要传大数--unlimited-steps关无步数上限运行与显式--step-limit冲突两者同时给出会报 parser 错误JSON 输出契约与 Rustxquad run二进制对齐成功{outputs: [...], final_stack: [...], steps: N}。outputs是稀疏映射语义——从未被 OUTPUT 写过的槽位输出nullfinal_stack是 HALT 时的残留栈自底向上程序故障XQVMError子类不是崩溃而是输出{error: {type: 异常类名, message: ...}}并以退出码2返回。这一契约是 conformance harness 能跨实现比较故障身份的关键。.xqb字节码路径会先经xqffi.asm.disassemble反汇编回文本再解析反汇编输出携带 pc 偏移与.N标签目前不可完整往返为可再汇编的源码仅供展示。编程接口README 的程序化示例from xqvm_py import Executor, program_from_xqasm prog program_from_xqasm(PUSH 10\nPUSH 5\nADD\nSTOW r0\nHALT\n) executor Executor() executor.execute(prog) print(executor.state.get_register(0)) # 15Executor.execute的完整签名xqvm_py/executor.pydef execute( self, program: Program, input_data: dict[int, Any] | None None, step_limit: int | None DEFAULT_STEP_LIMIT, # 10_000_000 memory_limit: int DEFAULT_MEMORY_LIMIT, # 1 30 output_slots: int 0, # 与 xqvm::Vm::new() 一致 ) - dict[int, Any]要点input_data按槽号键控list会在边界被转成Vec对齐xqvm::Vm::set_calldata的RegVal::VecInt语义output_slots默认0是对 Rust 的镜像程序写输出槽之前宿主必须声明预留了多少槽返回dict(self.state.output)即输出映射。执行模型Fetch-Decode-Execute 与分派表Executor的核心是取指-译码-执行循环加一张 opcode → handler 方法的分派表xqvm_py/executor.py主循环executewhile not halted and pc len(program)每轮先_charge_steps(BASE_STEPS, step_limit)计步、instructions 1再调step()step()xqvm_py/executor.py从self.program[pc]取指令若注册了tracer先触发on_step_beginhandler 执行后仅当 handler 未修改 PC未跳转、未 halt时advance_pc()异常会先触发tracer.on_error再抛出halt 时触发on_halt分派表覆盖控制流TARGET/JUMP1/JUMPI1/JUMP2/JUMPI2/LIDX/LVAL/NEXT/RANGE/ITER/NOP/HALT、栈与寄存器 I/OPUSH1-8/POP/COPY/SWAP/SCLR/LOAD/STOW/DROP/INPUT/OUTPUT、算术ADD/SUB/MUL/DIV/MOD/SQR/ABS/NEG/MIN/MAX/INC/DEC/BITLEN、比较EQ/LT/GT/LTE/GTE、布尔NOT/AND/OR/XOR、位运算BAND/BOR/BXOR/BNOT/SHL/SHR、分配器VEC/VECI/VECX/BQMX/SQMX/XQMX/BSMX/SSMX/XSMX、Vec 访问VECPUSH/VECGET/VECSET/VECLEN/SLACK、XQMX 访问GETLINE/SETLINE/ADDLINE/GETQUAD/SETQUAD/ADDQUAD、向量数学IDXGRID/IDXTRIU、XQMX 网格RESIZE/ROWFIND/COLFIND/ROWSUM/COLSUM以及高层约束ONEHOTR/ONEHOTC/EXCLUDE/IMPLIES/EQUALITY/ATLEAST/ATLEASTW/REDUCE/ENERGY。状态模型MachineStatexqvm_py/state.py 的MachineState承载全部 VM 状态栈纯整数操作数栈上限MAX_STACK_SIZE 8192 (2^13)每次push都经check_i64校验Python 整数无界必须显式守住有符号 64 位边界寄存器统一寄存器堆dict[int, Value]Value int | Vec | XQMX读取未设置槽抛RegisterNotFoundclear_register幂等清除跳转控制JumpControl目标表targets: dict[int, int] 循环栈loop_stackRANGE 帧用惰性range保存迭代空间永不物化防止四指令程序耗尽宿主内存ITER 帧则真实复制切片元素循环深度上限MAX_LOOP_DEPTH 8192防止跳回循环头而不执行 NEXT造成无界增长输入/输出input_slots/output_slots在运行前由宿主定死读写越界分别抛CallDataIndex/OutputIndex槽位留空未设是合法状态对应 Rust 的RegVal::Unsetreset()将每个字段含两个槽计数恢复初始值保证一次execute()的干净起点。指令与程序Instruction / Programxqvm_py/program.pyInstruction是不可变 dataclassopcode、operands: tuple[int, ...]立即数/寄存器索引/目标 ID、line调试用源行号Program在构造时经_build_jump_targets预扫描 TARGET 并建好跳转表让执行器免去每次运行的预扫jump_targets: dict[int, int]映射顺序目标 ID → 指令下标make_program(instructions)直接由指令列表构建run_program(instructions, input_data, output_slots0)提供构建 执行一站式入口program_from_bytecodexqvm_py/program.py解析.xqb字节码15 字节 XQBC 头bXQBC魔数、version1、input_slots/output_slots、u32 BE 的 code_len、CRC-32/ISO-HDLC 校验和 指令流无 FFI 依赖魔数/版本/长度/CRC 任一不符均抛ValueError。Opcode 表与操作数元数据xqvm_py/opcodes.py 以Opcode(Enum)定义全部指令每个成员携带一个OpcodeMetacode数值 opcode控制流 0x00-0x09寄存器操作 0x0A-0x0F依此类推stack_pop/stack_push栈净效果operand_count/operand_types操作数个数与类型IMMEDIATE/REGISTER/TARGETdescription助记说明stack_reset整栈清空类指令专用标志目前仅SCLR镜像conformance/opcodes.yaml中的stack_reset字段由 scripts/check-opcode-parity.py 逐字段比对。例如TARGET0x00、JUMP10x011 个 TARGET 操作数、JUMPI10x02先弹栈再条件跳转、RANGE0x08弹 2 个值count, start、ITER0x09弹end_idx, start_idx1 个 REGISTER 操作数。值类型Vec 与 XQMXVecxqvm_py/vector.py同质动态数组支持嵌套类型描述VecElemint | xqmx | vec | unsetvec必须带 innerunset仅作最内层。类型在首次 push 时推断或由VECI/VECX显式指定with_capacity支持预分配length/capacity分别追踪当前元素数与已分配容量。XQMXxqvm_py/xqmx.py稀疏二次矩阵是 QUBO/Ising 模型的核心载体模式modeMODEL构建约束/目标函数与SAMPLE解xqvm_py/executor.py 中require_model_mode/require_sample_mode在两个模式间强制切换域domainBINARY {0,1}、SPIN {-1,1}、INTEGER {0,...,k-1}domain_contains采用逐域判定而非闭区间比较因为 SPIN 域在0处有空洞闭区间会错误放行domain_default返回新分配样本变量的默认值SPIN 为-1其余为0维度size变量总数、rows/cols网格索引用非网格为 0、integer_kINTEGER 域的取值个数 2抛InvalidIntegerK稀疏表示linear: dict[int, int]变量索引 → 线性系数、quadratic: dict[tuple[int, int], int]i j的无序对 → 耦合系数工厂方法binary_model/spin_model/integer_model/binary_sample等SAMPLE 模式下linear存放变量赋值0/1 或 -1/1直接构造时会逐项做域校验网格操作row_find/col_find/row_sum/col_sum/triu/compute_energy与高层约束展开expand_onehot/expand_exclude/expand_implies/expand_equality/expand_reduce都在此模块。计量与计费steps 与内存预算XQVM 以steps步骤计量执行而不是以指令为单位。度量单位语义在 xqvm_py/metering.py 中定义规范文本见 spec/xqvm/METERING.md常量必须与 xqvm/src/metering.rs 逐值一致并由 scripts/check-metering-parity.py 强制常量值含义BASE_STEPS1每条指令分派的基础代价一个 NOP即一 stepCOEFF_WRITE_STEPS13写入模型稀疏表一个系数的代价按读-改-写形式标定MODEL_TERM_STEPS1把一项模型项累加进 Hamiltonian 能量的代价GRID_CELL_STEPS3网格线性表面读一个单元格的代价ROWSUM/COLSUM/ROWFIND/COLFINDSAMPLE_COPY_STEPS1写样本缓冲一个元素的代价ELEMENT_COPY_STEPS1从 vec 复制一个元素的代价辅助函数equality_expansion_steps(n)EQUALITY 展开的最坏情况步数n 项产生 n 个线性项 n(n-1)/2 个二次项全程饱和计算防溢出、model_eval_steps(sample_len, terms)、value_copy_steps(value)标量免费模型/vec 按实际内容计费——克隆模型会克隆其系数表。内存预算xqvm_py/executor.py同样镜像 RustVARIABLE_BYTES 8每个 XQMX 变量i64、VEC_ELEMENT_BYTES 16vec 每元素按 Rust Vec 倍增容量上限计、LINEAR_ENTRY_BYTES 32、QUAD_ENTRY_BYTES 48、equality_expansion_bytes(n)给出 EQUALITY 展开的最坏字节数。关键纪律贯穿 xqvm_py/executor.py先计费后分配_charge在分配前扣费超预算抛MemoryLimitExceeded计费累积且不退还因此分配-丢弃循环不可能超支先计费后执行_charge_steps在干活前扣步数付不起的指令一条都不会做饱和计数器_saturating把计费钳制在 u64 范围模拟 Rust 计数器饱和行为——否则 Python 无界整数会让两个 VM 在超长程序上对可负担性产生分歧分配器三步骤顺序_allocation_size拒绝负 size → 扣费 → 与MAX_ALLOCATION_SIZE 2^32-1比较wasm32 下usize::MAX的显式字面量见 xqvm_py/limits.py。扣费先于范围检查因此超限程序在普通预算下仍以MemoryLimitExceeded故障。check_i64是 Python 无界整数世界的守门人栈压入、模型系数、累加结果等任何可观测值离开有符号 64 位范围即抛ArithmeticOverflow从而与 Rust 的 checked arithmetic 保持同步。错误层级类型化故障xqvm_py/errors.py 定义了以XQVMError为基类的完整异常树包括但不限于StackUnderflow/StackOverflow、TypeMismatch、RegisterNotFound、InvalidOpcode、DivisionByZero、ArithmeticOverflow、MemoryLimitExceeded、InvalidAllocation、StepLimitExceeded、CallDataIndex、OutputIndex、IndexOutOfBounds、NoActiveLoop/UnmatchedLoopQUI-1289 拆分后各自独立、LoopStackOverflow、VecLengthMismatch、SizeMismatch、InvalidGridDimensions、InvalidIntegerK、SampleOutOfDomain、XQMXModeError、TruncatedInstruction、TargetNotFound等完整清单见 xqvm_py/init.py 的 re-export。这些类名不是随意的conformance harness 通过异常类名把 Python 故障映射到实现无关的故障词汇见下文所以类名的稳定性本身就是接口契约。Conformance跨实现一致性如何被强制向量格式每个一致性向量是conformance/vectors/category/name/下的一个目录含三个文件格式规范见 conformance/README.mdprogram.xqasm规范人类可读汇编源。harness 每次运行都在进程内汇编编码正确性归xqasmcrate 自测负责因此不提交预汇编字节码inputs.json{calldata: [i64|null, ...], output_slots: N, step_limit: N, memory_limit: N}。null表示宿主保留但未设置的槽位不能省略——省掉会缩短槽空间、移动CallDataIndex边界这正是向量要捕捉的分歧output_slots默认 16、step_limit默认 10_000_000、memory_limit默认 1_073_741_824均由 harness 解析一次后显式传给两个 runner两实现曾对缺省预算理解不同导致同一向量一个受限一个不限expected.json要么{outputs: [...], final_stack: [...]}成功要么{error: FAULT}故障同时提供两者或都不提供会被拒绝为向量编写错误。成功向量可附加可选steps: u64精确断言计量成本。outputs是稀疏映射未写槽省略、显式写 0 保留final_stack为 HALT 时残留栈。故障词汇表Fault identities由于 Rust 抛枚举变体、Python 抛异常类两个词汇表无法一一对应expected.json使用第三种实现无关词汇。映射表节选完整见 conformance/README.mdexpected.jsonRustxqvm::ErrorPythonxqvm_py.errorsSTACK_UNDERFLOWStackUnderflowStackUnderflowTYPE_MISMATCHRegisterType,IncompatibleTypeTypeMismatch,XQMXModeErrorUNSET_REGISTERUnsetRegisterRegisterNotFoundDIVISION_BY_ZERODivisionByZeroDivisionByZeroARITHMETIC_OVERFLOWArithmeticOverflowArithmeticOverflowSTEP_LIMIT_EXCEEDEDStepLimitExceededStepLimitExceededMEMORY_LIMIT_EXCEEDEDMemoryLimitExceededMemoryLimitExceededINVALID_SHIFTInvalidShiftInvalidShiftSAMPLE_OUT_OF_DOMAINSampleOutOfDomainSampleOutOfDomainNO_ACTIVE_LOOP/UNMATCHED_LOOP同名变体NoActiveLoop/UnmatchedLoopBAD_JUMP_TARGET/TRACE_FAILED有对应变体--Python 侧尚无独立类向量断言它们会在 Python runner 上响亮失败故障的字节位置刻意不作为身份的一部分——只比较故障本身避免向量因无关代码生成变化而变脆。测试生成与 CI 接线conformance/tests/rust.rs 与 conformance/tests/python.rs 由build.rs在cargo build时生成——每个向量在每个启用的运行时下生成一个命名#[test]向量失败即命名测试失败而非单个模糊 diff 转储Rust runner 在进程内经xqvm::Vm执行conformance/src/lib.rsPython runner 以子进程方式uv run python -m xqvm_py run执行解析其 JSON stdoutCI 的verify:parityjob 运行make -k check-parity-k 让一个目标失败后继续跑其余目标防止 Python 侧回归掩盖 Rust 侧通过或反之相关 Makefile 目标Makefileconformance-rscargo test -p xquad-conformance --no-default-features --features rust、conformance-py--features python、conformance-coverage--coverage打印向量清单、opcode-parity与metering-parity分别由 check-opcode-parity.py / check-metering-parity.py 保证 opcode 表与计量常量在 Rust/Python/规范三侧一致。一个真实向量示例conformance/vectors/arithmetic/add_basic/——program.xqasm读取calldata[0]与calldata[1]相加写入输出槽 0inputs.json给calldata: [10, 5]、output_slots: 4expected.json断言outputs: [15]、空final_stack。两个实现都必须产出这一结果。故障顺序QUI-1178操作数弹出 → 计费 → 校验spec/xqvm/SPEC.md固定了单条指令内的工作顺序先弹栈、再扣分配费、后校验。xqvm_py曾把寄存器读取排在弹栈之前在短栈verifier 拒绝与操作数故障先于寄存器读取verifier 放行两条路径上产生可观察分歧。22 个 opcode 被重排后第二路径可到达的分歧由专用向量钉死例如RESIZE的InvalidGridDimensions无条件先于寄存器读取 →vectors/xqmx-grid/resize_type_after_dimension_checkVECPUSH/SETLINE/ADDLINE/SETQUAD/ADDQUAD/EXCLUDE/IMPLIES/REDUCE的MemoryLimitExceeded仅在预算接近耗尽时可达→vectors/metering/vecpush_charge_before_type_checkATLEAST的IndexOutOfBoundsk 参数→vectors/constraints/atleast_k_range_before_model_typeATLEASTW的VecLengthMismatch→vectors/constraints/atleastw_length_before_model_typeEQUALITY的VecLengthMismatchvec 长度比较先于模型寄存器区分与计费→vectors/constraints/equality_length_mismatch_beats_model_type。实现侧的关键手法是_peek_model_size/_peek_model_gridxqvm_py/executor.py以is_model()门控的窥视来计量而非解析寄存器后再计量。ONEHOTR/ONEHOTC曾因对样本按真实维度计费、而 Rust 按 0 计费在紧预算下错误抛出MemoryLimitExceededQUI-1202_peek_model_grid修复后样本在任何预算下都计 0 费预算不再能决定故障类型。测试与调试Tracerxqvm_py/tracer.py 的Tracer实现TracerProtocolxqvm_py/executor.py 中的on_step_begin/on_step_end/on_error/on_halt回调协议verbosity1紧凑模式每条指令一行pc、opcode、操作数verbosity2详细模式追加栈快照与完整寄存器状态含变更集changed事件包含pc、opcode.name、operands、stack_before/after、pre_registers/post_registershalt 事件报告outputs_written实际写入数而非宿主预留的output_slots——历史 bug 曾把前者冒充后者输出format_trace()/format_event()提供文本化输出_format_aligned对齐各列。与 xquad / xqvm 生态的关系xqvm_py不是孤岛它通过 xqffi/src/asm.rs 的 pyo3 绑定消费 Rustxqasm汇编能力通过 conformance 与 Rustxqvm生产运行时互相钉死行为其 CLI 输出契约与 Rustxquad run二进制对齐内存计费与 xquad/tests/test_memory_parity.py 等测试共同保证两实现的内存预算行为一致。作为 XQuad 工具链的参考基准它的存在价值恰恰在于可以被取代当 Rust 运行时完全成熟这套 Python 栈要么整体退役向量成为纯参考数据要么退居原型沙盒供新 opcode 与 VM 特性在进入规范之前先行验证。理解这一过渡性定位是正确使用xqvm_py的前提。赞分享【免费下载链接】xquadA rust implementation of the Quip Networks quantum virtual machine.项目地址https://gitcode.com/gh_mirrors/xq/xquad点击查看免费下载相关推荐XQuad Conformance 一致性测试框架Rust xqvm 与 Python xqvm_py 双实现对齐的机械式验证XQuad Conformance 一致性测试框架Rust xqvm 与 Python xqvm_py 双实现对齐的机械式验证 导读 XQuad 同时交付两套xquad 使用指南XQuad 工具链的 Python 统一入口Program/Session/VM 一站式 APIxquad 使用指南XQuad 工具链的 Python 统一入口Program/Session/VM 一站式 API xquad 是 XQuad 工具链面Collaborator持久化终端揭秘node-pty Sidecar与tmux双后端如何协作会话永不丢失Collaborator持久化终端揭秘node pty Sidecar与tmux双后端如何协作会话永不丢失 Collaborator 是一款与 AI Age上一篇终极指南如何使用LanZouCloud-API解决蓝奏云上传限制难题下一篇SpaceCadetPinball游戏数据文件解析CADET.DAT和资源加载机制详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考