merlin-learning git:20261012.5ce3b3eA

Immutable. This exact content never changes and is served at /api/v1/blob/541848435fe1abf8.

---
name: merlin-learning
description: 用 Quandela MerLin 在 CPU 上批量计算无损光子线路的完整 Fock 概率，以及指定输出概率对相移的自动微分梯度。
---

# MerLin 光子层推断与梯度

<!-- BEGIN NATIVE SDK ACCESS -->
## 原生 SDK 路径

本能力同时支持 **MerLin 的原生公开 API**。用户需要 自定义光学电路、QuantumLayer、测量策略与 Torch 训练 时，由 Agent 在固定依赖环境中编写和运行任务代码，不限于下文便捷 Tool 的预设模型。

使用 `node scripts/sdk-access.mjs inspect merlin-learning` 定位环境，按[完整 SDK 工作流](../quantum-sdk-workbench/references/workflow.md)执行。模块导航：`merlin`、`perceval`；导航不是 API 白名单。

下文关于模型、门集、输入与预算的限制描述便捷 Tool 的合同；原生 SDK 另受上游版本、可选依赖、宿主资源与用户授权约束。已禁用或被拒绝的动作不能借代码路径绕过。执行状态和科研验收分别报告。
<!-- END NATIVE SDK ACCESS -->


Agent 经 Harness 调用 `merlin_local` 的 `evaluate_merlin_layer`。用于分析光子量子层的可微响应；完整训练模型、准确率对比和实机推断需要其他工作流与证据。

输入模式数、Fock `occupation`、目标 `targetOccupation`、`BS`/`PS` 操作序列及二维 `phases`。每个 phase 行是一次参数取值，各列按线路中 PS 出现的顺序绑定。`BS.theta` 使用 Perceval Rx 约定：对角元 cos(theta/2)，非对角元 i sin(theta/2)；所有角度为弧度。目标与输入光子总数必须相同；MerLin SLOS 后端要求输入至少一个光子。每条线路至少有一个 PS，参数可跨批次比较。

Tool 显式使用完整 `FOCK` 空间而非 MerLin 默认的 `UNBUNCHED` 空间，保留光子聚束事件且不进行后选择。返回 `basis` 明确列出概率列对应的模式占据数；`phaseGradients` 是对应批次的目标输出概率对各 PS 角度的偏导，采用 CPU float64 自动微分。检查 `probabilitySums`，并用有限差分检验关键参数点；目标梯度不代表模型精度提升或量子优势。模拟假定光子不可区分、理想无损器件，无有限 shots 统计噪声。

固定 [merlinquantum 0.4.1](https://github.com/merlinquantum/merlin)（MIT）与 Perceval 1.2.1，避免较新 Perceval 的不兼容模块变更。先运行 `node scripts/setup-paper-tools.mjs merlin-learning`；调用不安装依赖、不连接云、不加载任意用户模型。SDK 缓存使最大副作用登记为 workspace-write。`execution` 控制部署资源，模式、光子、批次数不设测试规模上限。

当前为 L1，`scientificValidation=not_evaluated`。开发期 permanent 参照和梯度回归不构成科研结论或最终科学验收。