数学函数可逆编译（Math Function Compilation）¶

English · 简体中文

类别 C5 · 模块 oracq.infrastructure.mathfunc · 阶段 V2

概述¶

把纯 Python 数学函数（math / cmath 子集）编译为定点可逆量子线路（input model 词汇中的 FO，函数 oracle）。公开契约是 reversible_function 范式：输入保持不变，输出与 status 按位 XOR 更新，所有临时寄存器自动复净——线路实现的是有限字长下的函数 \(\tilde F\)，不声称精确表示连续数学函数。编译链为 Python AST → MIR 0.1（有类型 SSA 图）→ 模块化 RIR；初等函数用 Chebyshev–Clenshaw 多项式在配置区间上近似。使用教程见普通数学函数自动生成，MIR 格式见 math-ir。

接口与输入模型¶

compile_function(function, *, fmt=None, inputs=None, constants=None, helpers=None,
                 output_names=None, config=None, max_unroll=128, entry=None)
lower_math_ir(program, *, fmt=None, config=None, output_names=None)

API 入口：compile_function、lower_math_ir

function：普通函数对象或 def 源码字符串；源码只允许 math / cmath 导入与纯函数定义（模块 docstring 与 __future__ 导入被忽略），entry 指定多函数源码的入口（缺省最后一个）。
inputs：{参数名: "real" | "complex" | "bool" | Index(width)}；缺省按注解推断（float / int → real、complex → complex、bool → bool）。
constants：生成期常量（含默认参数）；helpers：辅助函数命名空间（不支持递归）；max_unroll：静态 range 循环展开上限。
fmt：FixedFormat（缺省 (12, 6)，必须有符号）；config：MathConfig(degree=6, intervals=())，degree 为数学核多项式阶数（1..32），intervals 逐函数替换近似区间。
lower_math_ir：由 MIR 单独降低（可换 fmt / config），供 JSON 往返后重建。

返回 CompiledFunction（oracq.compile_function 顶层再导出）。属性：

属性	含义
`operation` / `program()`	生成的 `Operation` / 完整 RIR 程序
`math_ir`	入口 `MathProgram`（含全部 helper 函数）
`fmt`	定点格式回显
`input_layout` / `output_layout`	参数到物理寄存器的展开（复数拆 `_real` / `_imag`，bool 1 位，`Index` `width` 位）

寄存器为各输入、输出（缺省 out / out_i，可由 output_names 命名）加 status（2 位）。模块属性：oracle_paradigm="reversible_function"、math_function、math_ir_version="0.1"、fixed_width / fixed_fraction、math_config、update_semantics、correctness="pending"；入口模块附完整 math_ir JSON。

实现要点¶

前端不执行源码：副作用语句、while、递归、lambda 在编译期拒绝；静态 range 循环展开为直线上；if / 三元表达式 / 布尔短路编译为 select 节点——两分支电路都被计算，未走分支的算术错误经 status 掩码（如 0 if x == 0 else 1/x 在 x = 0 处不置位）。捕获的数值型全局名字与 constants 都成为生成期常量。

MIR 是顺序 SSA 图（节点引用的下标严格小于自身），MathProgram.validate() 校验操作元数与类型约束，dumps / loads JSON 往返。降低器 NumericEmitter 全部使用局部寄存器并在出口 XOR 输出后伴随重放整帧，实现自动 compute / XOR / uncompute；重叠的只读参数按无别名调用 ABI 复制。复数四则与初等函数按恒等式分解为实核（如 \(e^{x+iy} = e^x(\cos y + i\sin y)\)，\(\arctan\) 系经 log / sqrt 恒等式）；整数指数幂用平方乘（上限 128），一般幂走 \(\exp(b\log a)\)；atan2 由幅值比加象限修正合成。

初等核 elementary_kernel：在区间上取 degree+1 个 Chebyshev 节点经典采样、量子侧 Clenshaw 递推求值，配方（区间、阶数、系数）写入模块属性 math_approximation；越出近似区间置 status 位 1，log / asin / atanh 等的定义域违例置位 0（位 0 = 定义域失效、位 1 = 值域 / 字长越界）。核按 (函数名, fmt, config) 缓存复用。Index 输入按无符号整数嵌入定点字的 fraction 偏移处（要求 width + fraction < fmt.width）。适用边界：无自动区间推导、误差证明与最优算术电路选择，近似区间必须覆盖各个中间数学核的输入。

验证方案¶

类别 C5（数据访问层，判定准则见 ../development/validation-plan.md §2）：查询语义逐点正确 + 输入保留 / XOR 更新 / 复净。三层证据位于 tests/core/test_mathfunc.py:MathFunctionTests：

结构：test_helper_module_reuse_and_roundtrip——helper 去重（同一调用点只留一个 call 节点）、MIR JSON 往返、按重建 MIR 降低得到的 RIR 与直接编译逐字节一致；test_source_is_not_executed_and_effects_rejected（副作用 / 递归 / while / 文件操作被拒且源码不被执行）。
数值：test_all_elementary_families_construct——math / cmath 的全部 16 个实初等族在实 / 复输入下构造出闭合程序，polar / rect / conjugate 多返回值路径亦覆盖；test_roe_is_a_compiled_pure_function——Euler ROE 面通量整链编译，helper 族标签齐全。另有 test_nonzero_output_xor_superposition_and_inverse（叠加输入与非零输出初值下的 XOR 语义、双调用自逆）与 test_unused_branch_error_is_masked（未走分支的除零被 status 掩码）。
绑定：无独立绑定见证——编译产物是闭合模块、不含抽象槽位，与 validation-coverage.md 的 mathfunc 行一致。

已知缺口与计划阶段¶

定点量化误差界的显式见证未补：字长、阶数、区间与系数已进模块属性，但"给定 fmt / degree 下输出偏差不超过多少"没有自动化断言。登记为阶段 V2，与 validation-coverage.md 的 mathfunc 行一致。

数值验证¶

论文级数值实验见 tests/verification/verify_mathfunc.py（真实后端执行，无模拟替身），直接补齐上一节的误差界缺口。实验设计：覆盖 examples/math_functions.py 全部 5 个函数与 applications/roe_formulas.frozen_roe_face（6 实输入 + 2 个 Index(2) + 2 个生成期常量 + 双输出），FixedFormat(6,2)/(8,3) 两种格式；rir-pysparq 叠加穷举（单输入全域 2^6/2^8 分支，多输入逐轴纤维 + 联合立方体，Index 全域 16 组联合）。oracle 为按 fixed_arithmetic 语义独立实现的定点仿真机 _Fx（mul/div/sqrt 幅度向零截断、add/sub 模 wrap、status 位 0 = 定义域失效、位 1 = 值域/字长越界、select 掩码未选分支而 helper 调用合并全部参数旗标、helper 形参不参与折叠），初等核另按 math_approximation 系数逐比特复现 Clenshaw 递推——因此"实现误差"对照的是量化后的系数配方，"方法误差"（配方 vs 真函数）单独报告。结果：除 guarded_reciprocal 外全部案例与 _Fx 仿真逐比特一致（max_error = 0，覆盖数千个无旗标分支），guarded_reciprocal 全域误差 ≤ 1 量子（除法截断界）且全域无旗标；status 旗标（rho=0 除零、rho<0 平方根、c2≤0、z=±i、核区间越界、中间量字长越界含 wrap 后除零）逐分支符合预测（misflagged = 0）；三后端（rir-pysparq / reference / adapter-pysparq）振幅两两偏差 0.0；基态确定性（输入保持、输出 XOR、locals 复净）6 函数全过。工作区实测 358–2178 比特，OriginIR-ext 24 比特预算不适用。

案例	规模	后端路径	指标	数值
polynomial 全域穷举	6.2 / 8.3，64 / 256 分支	rir-pysparq	max_error	0 / 0（exact_fraction 1.0）
guarded_reciprocal 全域穷举	6.2 / 8.3，64 / 256 分支	rir-pysparq	max_error	0.94 / 0.98 量子（全域 status = 0）
pressure 纤维 + 立方体	两格式，192+64 / 768+64 分支	rir-pysparq	max_error / 常量量化偏差	0 / 1.4（6.2）、0 / 0.578（8.3）
roe_speed 纤维 + 立方体	两格式，256+16 / 1024+16 分支	rir-pysparq	max_error	0 / 0
phase_response 纤维 + 立方体	两格式，192+16 / 512+16 分支	rir-pysparq	max_error / 方法误差	0 / 1.770（6.2）、0 / 1.349（8.3）
frozen_roe_face 索引联合 + 纤维	16 + 96 分支 × 两格式	rir-pysparq	max_error	0 / 0（left/right 双输出）
核方法误差（信息性）	4001 点网格，degree=3	经典对照	exp / sin / cos	0.148 / 0.195 / 0.364
跨后端对拍（6 案例）	16–64 分支	rir-pysparq / reference / adapter-pysparq	max_pairwise_deviation	0.0
基态确定性	6 函数	rir-pysparq	failures	0

复现命令：

PYTHONPATH=src <含 pysparq+uniqc 的解释器> tests/verification/verify_mathfunc.py

产物：out/verification/mathfunc.json（28 个案例全过，总运行约 185 秒）。