XQuad 编译指南：读懂 `problem.compile()` 生成的 encoder / verifier / decoder 三份 XQASM-北京尧图网络

【免费下载链接】xquadA rust implementation of the Quip Networks quantum virtual machine.项目地址https://gitcode.com/gh_mirrors/xq/xquad点击查看免费下载problem.compile()是 XQuad 约束编程层xqcp的核心出口它把你在 Python 里录制的动作列表输入、模型、目标项、约束、输出声明一次性编译成三份相互独立的.xqasm程序——encoder、verifier、decoder。本指南以xqcp的实际编译器源码与规范为据逐段讲解这三份汇编的生成规则、寄存器分配约定、calldata/输出契约以及如何借助xquadCLI 静态检查编译产物。读完你可以独立读懂任何xqcp编译产物并在编译结果与预期不符时快速定位问题。一次调用三趟独立编译problem.compile()返回一个 CompiledPrograms包含三个字段encoder、verifier、decoder各自是一段完整的.xqasm源码字符串。为什么是三个而不是一个因为 XQVM 指令集里没有调用求解器的指令——建模型、校验样本、解码答案必须由宿主在两次 VM 运行之间完成详见 Three Programs三程序架构由 spec/xqvm/SPEC.md 定义不是xqcp的附加设计。关键在于这是三趟完全独立的编译。compile()内部依次调用compile_encoder、compile_verifier、compile_decoder见 xqcp/compiler.py、xqcp/compiler.py、xqcp/compiler.py三个函数遍历同一份Problem._actions动作列表却各自只提取不同子集为某个程序计算出的任何东西都不会带进另一个程序不存在共享的中间表示。Problem本身只是一个动作记录器每次 DSL 调用input()、define_model()、range()、stow()、model.linear[i].add()、apply_equality()、output()等都会向_actions追加一条Action(kind, data)见 xqcp/problem.py。完整动作种类清单由 spec/xqcp/COMPILER.md 给出包括input、define_model、range_start/range_end、iter_start/iter_end、stow、add_linear/add_quadratic、onehot_row/onehot_col、exclude、implies、equality、atleast/atleastw、slack、reduce、branch、output_decl/output_append、vec_init/vec_push等。编译前的最后一道闸字节码验证三个字符串生成完毕后若安装了xqffi扩展包compile()还会对每个程序运行 Rust 字节码验证器xqffi.verifier.verify_source()做结构、跳转目标、循环嵌套、寄存器类型状态、栈深度检查任何一条失败都会以ValueError抛出program verification failed: ...。未安装xqffi时此步骤被静默跳过xqcp在纯源码环境下依然可用见 xqcp/problem.py。这是编译期兜底但验证器是静态逐基本块的检查网格范围、循环边界、i64溢出等运行时量不在其保证范围内——这一点到最后一节结合 CLI 再展开。从 Knapsack 示例读出 encoder原文档用一个贯穿全书的具体例子讲解examples/knapsack/runner.py的build_problem()即 Constraints 中把不等式转成等式一节展示过的原代码一字未改。该问题声明 4 个输入、1D BINARY 模型、一个SLACK EQUALITY容量约束以及一个selected输出num_items problem.input(num_items, typeTypes.Int) weights_in problem.input(weights, typeTypes.Vec) values_in problem.input(values, typeTypes.Vec) capacity_in problem.input(capacity, typeTypes.Int) problem.define_model(sizenum_items, domainDomain.BINARY) with problem.range(0, num_items) as i: vi problem.stow(vi, values_in.get(i)) problem.model.linear[i].add(-vi) indices problem.vec() coeffs problem.vec() with problem.range(0, num_items) as i: indices.push(i) coeffs.push(weights_in.get(i)) problem.slack(indices, coeffs, num_items, capacity_in) problem.model.apply_equality(indices, coeffs, capacity_in, 100) selected problem.output(selected, typeTypes.Vec) with problem.range(0, num_items) as i: selected.append(problem.sample.getline(i))对这份问题定义调用compile()programs.encoder得到的就是下面这段汇编; Inputs PUSH 0 INPUT r0 PUSH 1 INPUT r1 PUSH 2 INPUT r2 PUSH 3 INPUT r3 ; Allocations LOAD r0 BQMX r4 ; Objective PUSH 0 LOAD r0 RANGE LVAL r5 LOAD r5 VECGET r2 STOW r6 LOAD r5 LOAD r6 NEG ADDLINE r4 NEXT VEC r7 VEC r8 PUSH 0 LOAD r0 RANGE LVAL r9 LOAD r9 VECPUSH r7 LOAD r9 VECGET r1 VECPUSH r8 NEXT LOAD r0 LOAD r3 SLACK r7 r8 ; Constraints LOAD r3 PUSH 0x64 EQUALITY r4 r7 r8 ; Output PUSH 0 OUTPUT r4 HALT两个细节值得先记住。其一PUSH 0x64就是100即传给apply_equality的 penalty——编译器只把少数常见 penalty 值以十六进制渲染以便阅读fmt_int的实现见 xqcp/expression.py映射表是{100: 0x64, 200: 0xC8}其余常量一律十进制。其二这段汇编对应的是build_problem()的问题形状与命令行--n无关寄存器编号和指令条数只取决于 Python 代码里input()、stow()、vec()、define_model()的调用次数而不是运行时传入的物品个数。compile_encoder在做什么动作列表的两次分区按 spec/xqcp/COMPILER.md 的定义encoder 先把整条动作列表切成四段Inputs所有input动作、模型动作那条define_model、Bodydefine_model之后、第一个output_decl之前的所有动作、Output 动作output_decl及其之后属于 decoder 的地盘encoder 不发射。_partition_program的实现见 xqcp/compiler.py。Body 再按深度 0 的块边界切成 objective 与 constraint 两个区块一个顶层块只要包含任一约束动作onehot_row/onehot_col/exclude/implies/equality/atleast/atleastw/inequality即_CONSTRAINT_KINDS集合见 xqcp/compiler.py就整体归类为约束块否则是目标块。; Objective 与; Constraints 两个注释块正是这两个分区顺序固定为先目标后约束与你 Python 里的书写顺序无关。Knapsack 的目标循环和SLACK调用都写在apply_equality之前且它们本身不是约束动作所以被一并放进了目标区。唯一让这个分区意外的情况是branch分支臂里嵌套约束调用——_has_constraint会下探到每个分支臂见 xqcp/compiler.py此时约束照常生效但会打印在; Objective 之下详见 Control Flow。输出段是固定的三板斧PUSH 0/OUTPUT r{model}/HALT。因为 encoder 唯一的输出——它构建好的模型——永远落在 slot 0。寄存器分配一个递增计数器寄存器分配是一个贯穿全程序的递增计数器从r0起步_RegisterAllocator见 xqcp/problem.pyspec/xqcp/COMPILER.md 固定了顺序输入优先每个problem.input()调用按调用序占r0、r1……cols 寄存器仅 2D 模型有由define_model()在模型寄存器之前分配它保存列数模型寄存器由define_model()分配。其余一切按调用序填坑循环变量range()/iter()按需分配、stow 值每个stow()一个寄存器若传入既有RegLoad则复用其寄存器——这正是循环累加器的做法、vec()寄存器、输出寄存器。Knapsack 是 1D 模型4 个输入占r0-r3模型占r4之后全部按调用序——目标循环的LoopVar与stow得r5/r6两次vec()得r7/r8。2D 的情形见 Inputs and Model Shape一个输入占r0cols 占r1模型占r2且访问(row, col)坐标时会经IDXGRID做row * cols col展平。计数器越过r255会在编译期直接抛RuntimeError在生成任何汇编之前。分配与两个优化模型分配块; Allocations 发射size_expr与对应的分配器指令BINARY 域用BQMX、SPIN 域用SQMX、INTEGER 域用XQMX先压k再压size2D 模型随后是{rows_expr} {cols_expr} RESIZE r{model}。见 xqcp/compiler.py。两个值得一提的优化当size N * N且两个乘数都引用同一寄存器时编译器发射LOAD r{N}; SQR而不是LOAD; LOAD; MUL_emit_size_expr见 xqcp/compiler.pystart 为0的range直接以end作为计数免去一次SUB_emit_range_start只对非零 start 发射SUB见 xqcp/compiler.py。compile_verifier把 encoder 重放一遍验证器的工作原理是一个关键设计它重放 encoder。为什么约束的操作数——例如apply_equality收到的索引向量与系数向量——在编译期只是VecRef寄存器句柄不是数据那些向量要等 encoder 里的VECPUSH指令在 VM 运行时执行完毕才真正存在而且常常嵌套在循环里。一个拥有自己独立寄存器文件的程序无法继承这份状态。所以验证器重新执行 encoder 的输入、循环、stow、分支与向量构建丢弃所有模型变更并在流的相同位置把每个约束替换成对样本的检查。这样它在每个约束站点上的寄存器与向量状态就和 encoder 完全一致。这也解释了为什么验证器沿用 encoder 的寄存器编号、而不是自建一套固定布局以及为什么它接收 encoder 的 calldata。它会在 encoder 水位high-water mark之上额外申请寄存器源码中_VERIFIER_REG_COUNT 9见 xqcp/compiler.py其中 8 个构成规范文档描述的通用工作集第 9 个k_reg仅供 INTEGER 域域检查使用偏移寄存器用途base0sample样本XQMXSAMPLE 模式来自 calldata 槽k1base1valid有效性标志int输出 slot 1base2energy能量int输出 slot 0base3size模型声明尺寸域检查边界与 REDUCE 计数器种子base4acc加权和累加器base5posLIDX位置兼作域检查的循环变量base6elemLVAL元素base7auxREDUCE 影子计数器超过r255同样在编译期抛RuntimeError。Knapsack 的 encoder 停在r11所以验证器的样本落在r12、valid 标志落在r13; Inputs PUSH 0 INPUT r0 PUSH 1 INPUT r1 PUSH 2 INPUT r2 PUSH 3 INPUT r3 PUSH 4 INPUT r4 PUSH 5 INPUT r12 ; Model shape LOAD r0 STOW r15 ; Validity checks PUSH 1 STOW r13 ; Check every declared variable is in the models domain PUSH 0 LOAD r15 RANGE LVAL r17 LOAD r17 GETLINE r12 COPY PUSH 0 EQ SWAP PUSH 1 EQ OR LOAD r13 AND STOW r13 NEXT ; Objective (replayed for state, not for energy) PUSH 0 LOAD r0 RANGE LVAL r5 LOAD r5 VECGET r2 STOW r6 NEXT VEC r7 VEC r8 PUSH 0 LOAD r0 RANGE LVAL r9 LOAD r9 VECPUSH r7 LOAD r9 VECGET r1 VECPUSH r8 NEXT ; Constraints PUSH 0 STOW r16 PUSH 0 VECLEN r7 ITER r7 LIDX r17 LVAL r18 LOAD r17 VECGET r8 LOAD r18 GETLINE r12 MUL LOAD r16 ADD STOW r16 NEXT LOAD r16 LOAD r3 LTE LOAD r13 AND STOW r13 ; Energy ENERGY r4 r12 STOW r14 ; Output PUSH 0 OUTPUT r14 PUSH 1 OUTPUT r13 HALT这份清单里最值得细读的三处模型直接INPUT进r4——即 encoder 分配给它的那个寄存器重放时所有引用无需重编号即可解析。BQMX被跳过但尺寸表达式被重放并 stow 进r15因为域检查需要这个上界。目标循环原样重放stowr6对结果毫无影响但照样执行——后面的约束可能读那个寄存器而重放并不去分析哪些 stow 是必要的。注意目标区的NEG/ADDLINE被丢弃了重放的只是制造状态的部分。容量检查用的是LTE而不是EQknapsack 用slack()加apply_equality()构造约束slack 扩展后的等式本质上是对真实变量的不等式。SLACK指令不被重放所以r7/r8里只有 4 个物品项、没有 slack 项。域检查与约束检查的语义域检查以模型声明的尺寸r15从define_model重放而来为界运行slack 与REDUCE辅助变量位于该尺寸之后不做域检查。BINARY 模型检查0/1SPIN 模型检查-1/1源码中低/高边界为(0, 1)与(-1, 1)见 xqcp/compiler.pyINTEGER 模型检查0 x kk用模型声明时的那一个而不是样本自报的。onehot_row、onehot_col、exclude、implies这类纯二值约束在 SPIN 模型上于编译期直接抛RuntimeError而不是发射一条在那边毫无意义的检查_BINARY_ONLY_KINDS与reject_unsupported见 xqcp/compiler.py、xqcp/compiler.py。每种约束的检查语义由 spec/xqcp/COMPILER.md 的Check Semantics表固定equality检查sum(coef[k]*sample[idx[k]]) b被slack扩展过的equality检查 binequality检查sum capacityatleast/atleastw检查 kexclude检查sample[a]*sample[b] 0implies检查sample[a] sample[b]onehot_row/col用ROWSUM/COLSUM 1reduce检查sample[w] sample[a]*sample[b]。加权和核心equality/inequality/atleastw共享是PUSH 0 / STOW acc起头、ITER内LIDXVECGETGETLINEMULADD累加、最后与valid做AND收尾的固定骨架每个检查发射器都保证栈净零、循环前初始化累加器因此嵌套在循环或分支臂里的检查也能通过字节码验证器的类型状态与 must-init 阶段。slack 检测是一个预扫描_scan_slack_equalities见 xqcp/compiler.py以(indices.reg, coeffs.reg)为键维护存活表vec()分配会清掉含该寄存器的键这是唯一的重置点也是按迭代重建向量得以成立的原因slack置位equality查表决定发LTE还是EQ键在消费后不被清除——对同一对 slack 扩展向量的两次 equality 在 encoder 里都是不等式。若slack()与消费它的apply_equality()落在不同循环或分支作用域编译期直接报错。编译期拒绝的三类程序有三类程序在编译期被拒绝而不是发射一条注定错误的检查见 xqcp/compiler.py 与reject_unsupported模型系数读取model.linear[i]、model.quadratic[i, j]作为读取会发射GETLINE/GETQUAD——encoder 里读的是半成品模型验证器里读的是 calldata 里的成品模型两个程序之间会无声地不一致非 BINARY 模型上的纯二值约束如上所述寄存器耗尽8 个验证器寄存器越过r255。另外reduce不在约束集里但出现在动作流中VM 在REDUCE执行时于model.size处分配辅助变量验证器不能运行REDUCE于是用一个从声明尺寸播种的影子计数器跟踪同一索引在每个reduce站点读取计数、stow 进 encoder 自己的stow_reg链式reduce()由此解析再自增。计数器只有在没有任何东西先撑大模型时才正确因此编译会拒绝任何出现在reduce之前、或与其共享循环/分支块的模型增长约束atleast/atleastw/inequality/slack 扩展等式见_check_reduce_orderingxqcp/compiler.py。compile_decoder样本加一个标量解码器使用自己的寄存器布局_DecoderRegisters见 xqcp/compiler.py寄存器用途r0样本XQMXSAMPLE 模式r1调用方放在 calldata slot 1 的那唯一一个标量r2起每个声明的输出一个输出向量按声明序r10起每个打开的循环一个循环变量按嵌套深度循环寄存器坐在输出之上且不低于r10所以最常见的单循环程序恰好发射文档化夹具里的那个r10输出超过 8 个时循环基址整体上移而不与输出冲突。对每次problem.output()调用decoder 发射一个输出块VECI r{out}分配输出向量接着是填充块的range/VECPUSH/GETLINE等动作最后PUSH {slot} / OUTPUT r{out}。Knapsack 的 decoder; Inputs PUSH 0 INPUT r0 PUSH 1 INPUT r1 ; num_items ; Decode selected VECI r2 PUSH 0 LOAD r1 RANGE LVAL r10 LOAD r10 GETLINE r0 VECPUSH r2 NEXT ; Output PUSH 0 OUTPUT r2 HALTdecoder 内部没有独立的num_items概念只有传进来的那一个标量with problem.range(0, num_items) as i里的num_items在 encoder 里是InputRef到 decoder 里就成了LOAD r1——即两行之前读进 slot 1 的那个寄存器。哪个标量被传进来是程序自己的选择而不是固定的N头部注释; num_items会标注它让调用方看清 slot 1 该放什么。若 decoder 块引用了第二个不同的标量compile()直接拒绝——decoder 只有一枚标量可传无法向调用方说明两个里该给哪个。decoder 块允许引用什么、禁止引用什么完整清单见 Outputs and Decoding样本getline/value/case/rowfind/colfind/rowsum/colsum七种读法、自己的循环变量、一个标量向量输入、problem.vec()分配、模型系数、已关闭循环的变量一律拒绝。iter()在 decoder 块里也被拒绝——ITER遍历向量寄存器而 decoder 的 calldata 只有样本和一个标量没有可遍历的向量改用range()加problem.sample逐位读取。branch()同样被拒条件臂里的.append()会被静默丢弃留下空输出向量。输出类型必须是Types.Vec没有非 Vec 分支。decoder 的表达式重写是全量的_rewrite_decoder_expr样本读重定向到r0循环变量映射到自身打开的循环寄存器InputRef(Int)/RegLoad解析到r1任何节点要么解析到 decoder 寄存器、要么报错不会漏掉而发射一个 decoder 从未写过的录制期寄存器那正是历史上解码器读到自己的循环索引这类缺陷的来源。calldata 与输出契约三个程序的 calldata 顺序与输出槽都由各自的编译来源固定宿主必须严格匹配程序Calldata按序输出Encoder每个problem.input()一项按调用序Slot0模型Verifier每个problem.input()一项按调用序然后是模型、样本Slot0energyslot1validDecoder样本、N每个problem.output()一项按声明序examples/knapsack/runner.py的run()正是按这个契约驱动的见 examples/knapsack/runner.pyencoder 前vm.set_calldata([n, weights, values, capacity])vm.set_output_slots(1)与build_problem()里四次problem.input()的顺序和 encoder 唯一输出槽一一对应verifier 前vm.set_calldata([n, weights, values, capacity, model, sample])vm.set_output_slots(2)decoder 前vm.set_calldata([sample, n])vm.set_output_slots(1)。输出槽数默认0程序对从未分配的槽执行OUTPUT会在运行时抛OutputIndex两种解释器上都一样参见 Limits and Errors。不必手动重建 verifier 的 calldata 顺序Problem.verifier_calldata()直接返回按序的名字列表——knapsack 就是[num_items, weights, values, capacity, model, sample]——宿主可以拿它和自己的值做 zip实现见 xqcp/problem.py 与 xqcp/compiler.py。用xquadCLI 静态检查编译产物programs.encoder、programs.verifier、programs.decoder都是普通 Python 字符串——打印其中一个就是最快的看看问题定义到底编译成了什么的方式本页所有汇编清单都是这么产出的。接下来xquadCLI 可以不借助任何 Python 宿主对单个程序做静态检查xquad asm把.xqasm汇编成字节码.xqb它是唯一能打印高亮源码片段错误含NamedSource/SourceSpan的子命令xquad dism把字节码反汇编回可读清单与asm互为往返xquad verify对程序运行结构、跳转目标、循环嵌套、寄存器类型状态、must-init、栈深度六阶段检查——与problem.compile()在装有xqffi时自动跑的是同一套验证失败的典型输出是Error: × register r0 read at byte 0x0000 before being written。CLI 由xqclicrate 构建但安装命令与二进制名不同cargo install xqcli装出来的命令叫xquad或在本仓库cargo build -p xqcli --release产物在target/release/xquad。完整命令参考见 CLI编译一节不改变它的任何行为。xquad verify与xquad dism对三个程序原样可用但xquad run不行三个程序的输入不全是纯整数——上面的 encoder 在 calldata 位置1、2需要两个向量而 CLI 的--calldata只接受逗号分隔的i64列表。把整数传给期望向量的位置不会解析失败而是在运行时、程序真正使用该值时才失败$ xquad run --text knapsack.encoder.xqasm --calldata 2,10,20,5 Error: xqvm::runtime_error × register r2 holds int, expected vecint要让这三个程序跑真实 calldata需要一个能构造向量、模型与样本的宿主——xquad.vm的VM/VMBackend、xquad.program的Program/Session都是这样的表面全面介绍见 Running Programs。CLI 在本环节的角色是静态的先汇编、反汇编、验证程序结构再把它交给能提供足够丰富 calldata 的宿主去运行。另外xquad verify --text与xquad run --text会把汇编错误压平成纯字符串而丢弃源码跨度调试汇编语法时优先用xquad asm拿带高亮的错误。小结从问题定义到三份可审计的程序problem.compile()的价值在于它把约束编程的意图落成了三份可独立验证、可审计的产物encoder 只负责把输入与模型动作翻译成模型构建指令verifier 通过重放把每个约束变成对样本的检查并独立重算能量decoder 用样本一个标量把答案解码回问题的语言。读懂这三份汇编的关键线索始终是寄存器分配顺序输入 → cols → 模型 → 调用序、验证器对 encoder 水位之上工作寄存器的约定、以及每个程序固定的 calldata/输出契约。一旦编译产物与预期不符打印字符串 xquad asm/dism/verify这条静态检查链路足以定位绝大多数问题规范的权威细节在 spec/xqcp/COMPILER.md动作表、重放规则、检查语义、分支编译、编译后验证编译器行为则以 xqcp/compiler.py 与 xqcp/problem.py 的实现为准回归测试见 xqcp/tests/test_xqcp.py。赞分享【免费下载链接】xquadA rust implementation of the Quip Networks quantum virtual machine.项目地址https://gitcode.com/gh_mirrors/xq/xquad点击查看免费下载相关推荐XQuad 三程序架构Encoder / Verifier / Decoder详解从 xqcp 编译到端到端求解实战XQuad 三程序架构Encoder / Verifier / Decoder详解从 xqcp 编译到端到端求解实战导读 XQuadQuip Netw读懂 AI 生成的 JavaScriptEasy-Vibe 前端原理速成指南读懂 AI 生成的 JavaScriptEasy Vibe 前端原理速成指南本指南基于 Easy Vibe 仓库中 docs/de de/appendix/教程文档如何快速掌握Mermaid Live Editor新手入门完整指南如何快速掌握Mermaid Live Editor新手入门完整指南还在为画技术图表而烦恼吗想要一个简单高效的图表创作工具吗Mermaid Live Ed前端开发者工具数据可视化上一篇JiYuTrainer终极指南如何快速解除极域电子教室控制限制下一篇Peewee Playhouse 扩展库完全指南从 SQLite 增强、PostgreSQL 扩展到底层数据库工具的全景解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

XQuad 编译指南：读懂 `problem.compile()` 生成的 encoder / verifier / decoder 三份 XQASM

相关推荐

Psalm 的 MissingClosureReturnType 全面解析：从触发机制、错误级别到自动修复

ant-design-blazor Slider 滑动输入条组件完全指南：API、双滑块、刻度与 Tooltip 实战

Scanopy UniFi 集成测试环境搭建指南：从 UniFi OS Server 部署到端到端验证

更多资讯

UC网盘下载不限速办法：亲测有效的免费提速思路与操作指南

Flutter跨平台开发鸿蒙旅行攻略App全流程实践与适配避坑指南

广东省SHP数据处理指南：行政区划与路网分析实战

钉钉集成API Java实战：Token缓存与高频消息推送避坑指南

树莓派Pico C/C++开发环境搭建：CLion+SDK+OpenOCD调试实战

Linux下查看线程的实用方法：从ps、top到pidstat全掌握

今日更新

Susi AI API实战指南：susi_alexa_skill如何用Node.js调用chat.json获取智能回答

换新电脑了？KeyStats 恢复码数据找回完全指南，端到端加密统计一键重建

重建二叉树：由前序与中序遍历序列还原二叉树的原理与 Java 实现（YCBlogs 剑指 Offer 精讲）

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？