# 光学工作台模型、实体遮挡与设备接口

本次升级将同一套光学计算同时提供给三维工作台和原二维后备视图。绘图中的光束宽度可以放大以便观看，以下数值计算始终使用实际毫米尺度。光学模块不绘制真实的光在真空中的可见散射；彩色光束是用于对准的教学可视化。

## 坐标和几何

- 工作台 X/Y/Z 是右手坐标，单位 mm。离子阱中心固定为 `(0,0,0)`。设备 `z` 和射线 `z` 是相对于中心光轴的高度偏移；绘图时统一加 `BEAM_HEIGHT=30 mm`。设备底座与其光学中心不能混淆。
- `angle` 是绕 Z 轴的方位角（度）；`pitch` 是从水平面向上的仰角（度）。激光以此定义传播方向；透镜/AOM/物镜/反射镜以此定义表面法向。
- 法向 `n=(cos yaw cos pitch, sin yaw cos pitch, sin pitch)`。反射镜的法向指向镀膜正面外侧，只有 `k_in·n<0` 的正面入射才使用完整三维矢量式 `k_out=k_in−2(k_in·n)n`。背面及有限厚度基片吸收光。反射镜、透镜、物镜、双色镜和滤光片是被动器件，没有电源开关；旧配置的禁用标记不取消其光学作用。水平镜角改变 δ，反射光方位角改变 2δ；俯仰也改变出射光的垂直分量。
- 光学面、有限圆孔径和不透明机械实体共同查找最近交点。光线落在镜架、支杆、底座、激光/仪器外壳、台面、腔壁或电极上即终止；未进入光学口径但落在整个器件之外才自由传播。关闭器件不移除实体。成像光路也检查实体遮挡。
- 真空腔有明确的有限孔口与 AR 窗口，单次声明强度透射率为 0.995。35° 出射束与45°成像共用40°宽窗口，其余参考束经90°、135°、215°、270°与315°窗口。剖视显示不改变挡光几何。窗口折射、镀膜偏振与干涉不求解。
- 几乎平行的光学面仅排除法向投影绝对值小于 10⁻⁶ 的不稳定数值交点。最多计算 14 次光学相互作用；达到上限会在 `trace.warnings` 标出截断。

## 高斯光束及焦点

使用理想 TEM00、M²=1、空气/真空折射率 n=1 的标量近轴模型。`waistMm` 是源处的 **1/e² 强度半径**，不是直径。波长从 nm 转为 mm。定义：

```
q = (s−s_waist) + i z_R
z_R = π w0² / λ
q(s+d) = q(s)+d
q_lens = q_in / (1−q_in/f)
w²(q) = λ |q|² / (π Im q)
```

平面镜改变中心光线方向，不改变高斯 q；焦点随后沿反射后的方向继续传播。每段局部焦点距离为 `−Re(q)`，它可以位于该段之前或之后，**只有 `focusInSegment=true` 时才是该段中实际可达的束腰**。`waistMinimumMm=sqrt(λ Im(q)/π)` 是该局部束的理论最小半径；它不保证处于平台边界或下一个器件之前。

每段提供 33 个等距半径样点，并额外插入段内真实束腰点，避免绘图采样跳过很窄的焦点。`waistProfile` 提供三维位置、局部距离、从源累计距离和真实半径；可直接用于包络和束腰曲线。

薄透镜的中心射线在局部横向两个方向使用 `slope_out=slope_in−offset/f`。透镜倾斜会改变局部基底和射线指向，但并未求解大角度非近轴折射、球差、彗差和像散；入射角大于 10° 时，`trace.warnings` 明确提示圆对称近轴近似的限制。该提示是教学有效性边界，不是一个新的物理阈值。

中心光线最近接阱中心的位置用于计算 `miss` 与 `waist`。只有该位置沿传播方向位于真实可达光段内，才使用离子处相对高斯照明 `overlap=T exp(−2 miss²/w²)`；在离子前被实体截住的光不能通过末端距离外推继续照亮离子。镜和透镜的固定强度透射率分别为 0.97、0.98；AOM效率可调。孔径功率使用偏心圆孔的二维Gaussian积分，经角度代换作复合Simpson数值计算；倾斜孔采用投影内接圆的保守近似，AOM实际半孔径为3.9 mm。该方法不计算截光后的衍射，仍继续用单一q。多次经过阱区时选用可达段中最大的局部照明，不叠加相干干涉。

机械遮挡使用与三维装配尺寸对应的解析盒、有限圆柱、环柱、锥形中空电极及孔口布尔运算。电极来自同一个 `createElectrodeGeometry`，并转换到工作台坐标。照明使用几何主光线；成像另外用96条瞳面射线求机械遮挡比例，不求解边缘衍射、表面散射分布或部分瞳的波动PSF；细线缆、小螺钉、螺纹和机械碰撞不参与。剖视会隐藏外壳，但不会让隐藏的金属对计算透明。

AOM为含集成 RF 驱动和选级光阑的有效双程组件；关闭驱动后工作衍射支路中断，内部零级废光不逐段显示。其出口方向在该模型中保持输入方向，频移为 `2 f_AOM`（显式单程时为 `f_AOM`）；未逐段建模声光布拉格衍射角、猫眼/回返镜。频移按每段记录，因此阱区之后遇到的 AOM 不会反过来改变离子处频率。

## 成像和设备通道

成像仍使用已有有限共轭薄物镜、集成中继和相机的校准模型。几何收集立体角与探测器PSF/噪声模型分开计入。面板NA控制实际可见光阑；物镜、真空窗、15.6 mm相机入口限制保守接受锥，瞳面射线与照明射线使用同一实体几何。窗透射0.995每经过一次计入一次；不因中心射线畅通便假定整个瞳面畅通。物镜轴的角度接受、相机横向接受是教学对准响应；它们不能替代实际成像系统的波动光学或标定曲线。

当前的冷却模型有单一 397 nm 频谱和方向、单一 866 nm 再泵浦通道、独立的423 nm激发与375 nm电离通道，因此每个波长只允许一台激光源。重复拖入该激光会重新定位并启用原通道，不会出现一台被计算忽略的第二光源。纯函数和恢复接口对显式重复波长抛出中文错误。

同样，当前只建模一条 AOM 调制链、一条物镜→相机链，以及一个 RF、示波器、电源和真空通道；这些角色重复放置会移动原设备。单例删除后可从库恢复，其规范 ID 保持与参数控制一致。透镜、反射镜、双色镜与滤光片可以增加多件，每个新器件有独立且唯一的 ID。电子设备按固定支路预接线；选择型号替换已连接仪器，移除或禁用会中断对应有效输出。AOM 使用独立集成 RF 驱动。电子设备位置不直接改变电学输出，但其外壳会挡光；电缆长度和阻抗网络不在本版计算。

离子阱不能经拖动、数值设置、设备删除或导入坐标移动。导入时重建唯一 `trap`，固定中心与朝向。

## JavaScript 接口

```js
import { createBench, DEVICE_LIBRARY, traceLaser, calculateOpticalEnvironment } from './bench.js';
const core = createBench(null, { headless: true, onSelect, onChange });
```

`headless:true` 不调用 Canvas、DOM、动画帧或窗口事件，初始化不触发回调。三维包装层管理摄像机、射线拾取和鼠标；原 `createBench(canvas)` 的二维视图继续可用。

- `traceLaser(laser, devices, context?)`：纯函数，返回 `segments`、`encounters`、阱区照明、频移与近似警告；`blockedBy` 给出阻挡实体，`blockedBeforeIon` 区分离子之前与之后截束。
- `calculateOpticalEnvironment(devices, traces?, context?)`：纯函数，产生供物理模型使用的光学环境，包括 `beamPaths`、`imagingBlockedBy` 和范围说明。预计算 `traces` 可避免重复计算。
- `setOpticalContext({trapGeometry,instruments,solids})`、`getOpticalContext()`：设置/读取当前有限电极和额外仪器遮挡几何。`trapGeometry` 接受几何参数或 `createElectrodeGeometry` 结果；所有光学坐标仍为相对30 mm光轴的工作台 mm。
- `scene.setConnections([{from,to,kind,points?,fromPosition?,toPosition?}])`：三维预接线显示；显式连接坐标采用绝对 world mm，电学门控由通道模型处理。
- `getDevices()`、`getSelected()`、`getEnvironment()`、`getTraces()`：返回隔离的快照；`getTraces()` 包含所有嵌套 q、方向、焦点和包络样点。
- `addDevice(libraryKeyOrSpec, position?)`：返回新增或重新定位的设备快照；选择该设备并触发一次更改和选择回调。`position` 可含 x/y/z/angle/pitch。
- `removeDevice(id)`：成功返回 true；固定阱、锁定设备和不存在设备返回 false。
- `setDevice(id, patch)`：保留 ID 与类型，更新位置、角度、焦距和通道属性并重算。
- `setDevices(snapshot)`：原子校验并恢复；不触发回调，以支持应用初始化。
- `placementAt(clientX,clientY)`：二维视图使用当前投影反算桌面坐标；三维包装层应覆盖为其桌面平面拾取。
- `setInteraction('move'|'rotate'|'orbit'|'pan')`、`getInteraction()`：二维后备支持移动/旋转，orbit 在后备中按平移处理；三维包装层提供真实摄像机旋转。
- 原有 `select/reset/setView/setRunning/setMetrics/resize/fit/destroy` 接口保留。

设备库 key 为 `laser397`、`laser866`、`laserPI`、`laser375`、`dichroic`、`dichroicPI`、`achromat`、`filter`、`mirror`、`lens`、`aom`、`objective`、`camera`、`rf`、`scope`、`dc`、`vacuum`。后两者的类型分别为 `supply`、`pump`。

## 已验证的物理与交互契约

`tests/bench-v3.test.mjs` 新增 14 项检验：镜面 2δ、三维俯仰反射、复 q 解析焦点、焦距改变束腰、镜后焦点、无浏览器初始化、插入/删除改变光路、单例重放/恢复、重复光源拒绝且不污染状态、固定阱、深快照、离子之后的频移不倒流、AOM/电学规范通道、倾斜透镜有效性提示。既有 `tests/bench.test.mjs` 的 13 项参考结果继续通过，包括参考光路约 150 μm 冷却束腰以及 15 s 后可分辨离子。

## 原始教学来源

- Franz X. Kärtner，MIT 6.974 *Fundamentals of Photonics / Quantum Electronics*，§2.4–2.6。特别是 Gaussian ABCD law、自由传播与薄透镜 q 变换，印刷页 103–106，式(2.259)–(2.263)：[MIT OpenCourseWare 课程原讲义](https://ocw.mit.edu/courses/6-974-fundamentals-of-photonics-quantum-electronics-spring-2006/bf3bdeb971819ddc9c68719d28bb2745_classnotes.pdf)。公式采用本项目显式声明的正 Im(q) 约定；不同相量约定可能出现复共轭。
- Oxford Physics，*Optics Lectures*，Gaussian beam 与薄透镜传播章节：[牛津物理课程原讲义](https://users.physics.ox.ac.uk/~Foot/C2/pdf/optics-lectures-2012.pdf)。

以上来源支撑传播方程，不为教学对准响应、固定器件透过率或三维外观提供实验标定；这些近似已在上文逐项区分。


当前修正反例、独立孔径积分数值、原厂探头/NA来源和剩余近似见[REALITY_AUDIT.md](REALITY_AUDIT.md)。

## 双波长光电离与合束布局

参考397/866 nm从135°窗口进入，与45°成像轴正交。397 nm通过AOM、透397/反866的双色镜，再与866 nm共轴通过f=80 mm消色差透镜。该镜位于距阱心62 mm处，参考阱处半径分别约147.74与183.40 μm。消色差按理想共焦距建模；未引入真实玻璃色散。

423/375 nm通过第二片双色镜和聚焦镜，从215°窗口进入。双色镜按波长选择一条主支路：反射带R=.97，透射带T=.96，损失余量不作为第二条有效光路。角度改变会改变实际反射方向。新375激光与其它激光具有相同的移动、转动、俯仰、实体遮挡及设备供电规则。集成中性原子供给独立于两束光的启停；新增装载要求两步光均到阱区。

物镜主平面距阱心68 mm，f=40 mm，主像距97.1429 mm，14倍集成中继后总放大率20倍。NA仍受真空窗、电极及相机入口限制。397 nm带通滤片放在成像束内才生效；滤片孔径参与收集接受锥，谱透射由物理层分别作用于荧光与各波长背景。默认峰值透射.88、FWHM10 nm、带外透射10⁻⁴。倾斜只做投影孔径，未计算干涉滤片的入射角谱移。

工作台“光路与AOM说明”展示双程AOM内部功能顺序。模块选择两次+1级，频移为+2fRF；.82为整个模块的强度效率。猫眼回返、PBS和波片不作为独立可拖器件，未模拟内部对准和布拉格角。

原理来源：NIST中性钙能级 https://physics.nist.gov/PhysRefData/Handbook/Tables/calciumtable5.htm ；Fernandez-Gonzalvo与Keller的423/375 nm实验 https://pmc.ncbi.nlm.nih.gov/articles/PMC9831988/ ；Donley等双程AOM https://www.nist.gov/publications/compact-double-pass-acousto-optic-modulator-system 。