# 有限电极几何、电势与单离子轨迹计算

本模块是单离子、无空间电荷条件下的准静态电场教学求解器。它使用参数化有限电极几何；没有使用实测装置 CAD，也没有进行实物标定。结果属于模型计算，不能直接替代实验装置的高压与真空设计验收。

## 1. 几何与坐标

物理坐标 x、y 为径向，z 为离子阱轴。三维场景的台面坐标对应：

- bench X = z；bench Y = (x−y)/√2；bench Z = 30 mm + (x+y)/√2。
- 四根完整有限圆柱 RF 电极沿 z，中心方位为 0°、90°、180°、270°。圆柱半径默认 1.15 r₀，中心轴半径为 r₀+杆半径，因此最近金属表面距阱心 r₀。
- 杆长默认 max(12 mm, 4.8 z₀)。杆两端为实际平面端面，而非无限长杆。
- 两个中空端电极的最近端面位于 z=±z₀，光学通孔半径 0.22 r₀，圆柱体外半径 0.78 r₀，锥形鼻部前沿外半径 0.48×0.78 r₀。
- 锥段长度 min(0.55 mm, 0.22 z₀)，后部体长 min(0.9 mm, 0.35 z₀)。外锥面、外圆柱面、内孔面、前后环形端面均参与导体边界处理。
- 未求解安装支架、线缆、介电陶瓷、实际腔体、表面贴片电荷或离子间库仑相互作用。显示装配中的这些部件不应被解释为已计算的电极边界。

几何由 `createElectrodeGeometry` 统一提供给场景和求解器，改变 r₀、z₀、杆长会重新构造并求解几何，不是只把理想四极势按 r₀ 缩放。

## 2. 电压约定

RF 输入是两组 RF 电极之间的差分峰值 Vpk。第 i 根杆的电压为：

`Vᵢ(t) = (−1)ⁱ [ Vpk cos(2π fRF t + φ₀) + Uradial ] / 2`。

每组电极相对参考地的 RF 峰值为 Vpk/2；Vpk 不是每组对地峰值，也不是峰峰值。两端电极均为 Uend。界面中的径向 DC 参数 Uradial 也采用两组之间差分电压。

计算两个独立单位电压解：杆 0 为 1 V、其余导体为 0；正 z 端电极为 1 V、其余为 0。矩形接地盒具有径向 90° 旋转及 z 镜像对称，另外四个单位电压解由精确坐标变换得到。六个基函数对任意电极电压线性叠加。

## 3. Laplace 数值方法和外边界

在真空中求解 `∇²Φ = 0`。内部普通节点采用各向异性七点差分；邻近电极的网格线与有限圆柱、锥面、孔面及环形端面的交点由解析几何计算，使用 Shortley–Weller 非均匀距离差分。若一条网格边穿过薄金属，即使两端节点均在真空，也施加第一次导体交点的 Dirichlet 边界。

一个坐标方向的离散二阶导数为：

`2/(d₊+d₋) × [(Φ₊−Φ₀)/d₊ − (Φ₀−Φ₋)/d₋]`。

导体交点的电位为已知值。SOR 解线性方程，默认松弛系数 1.82。它不是有限元、不是边界元，也不是实物场标定。未使用理想四极势系数替代有限几何解。

外边界为**有限矩形接地计算盒**，不是无穷远自由空间：默认径向半宽 4.4 r₀（还必须容纳杆外表面及至少 1.1 r₀ 空隙），轴向半宽为 max(杆长/2, z₀+端电极总长)+1.5 r₀。这个接地盒是明确的模型假设，不能被当作显示腔体的实际形状。界面可选径向半宽 4.4、5.5、7 r₀，源代码接口也支持改变此参数，以检查外边界敏感性。

默认三档空间精度的名义每 r₀ 节点间隔数为 4、6、8。为了包含对称端点，实际间距会略小。轴向节点数上限为 401；较长、较细的几何可能得到较粗的轴向网格，此时会提示端电极尖部未充分分辨。

## 4. 插值、电场、有效势

电位使用 C1 连续的三次张量插值。电场为**同一插值电位的解析负梯度**，因此不会以一个无关的示意场生成轨迹。网格节点上的二阶导数使用对称电场导数，平均插值函数的左右二阶导数，以保持镜像对称。这个 C1 插值函数不严格满足连续 Laplace 方程；节点残差不代表任意插值点的 Laplacian 误差。模块保留并输出中心 DC 曲率迹 `laplaceOriginDcVm2` 和相对最大 DC 曲率分量的百分比 `laplaceOriginDcRelativePercent`，不强行把迹置零。参考 standard 的迹约 −1.21×10³ V/m²（相对轴向曲率约 8.2%），fine 约 −6.70×10² V/m²（约 4.5%）；这些值必须与中心频率细化结果分开评估。

射频伪势：

`Ψ(r) = q² |E_RF,peak(r)|² / (4 m Ω²)`，其中 `Ω=2π fRF`。

热图默认显示 `(Ψ + qΦDC − qΦDC(0)) / e`，单位 eV。RF 箭头表示峰值场方向；实际瞬时 RF 场按 cos(Ωt+φ₀) 反向。伪势只适用于微运动与慢运动可分离的近似，局部正曲率不保证完整 RF 系统全局稳定，也不等于已形成冷却后的多离子晶体。

导体区域不作为真空场显示。计算盒外的网格点明确遮罩，物理量在内存中为 NaN，导出 JSON 为 null；它们不代表零电场。`evaluateField` 返回 `outsideDomain`，底层插值在域外的零占位值不得用作物理结果。

## 5. 轨迹

对单个带电粒子积分 `m r̈ = q [ EDC(r) + ERF,peak(r) cos(Ωt+φ₀) ]`，使用 velocity-Verlet。这里保留真实时变 RF 力，而不是只在谐振近似中画预设椭圆。初位置、初速度、初始 RF 相位、质量、差分 RF 幅值、频率与端电压均参与计算。

该轨迹实验未叠加激光冷却随机散射、气体碰撞和空间电荷；主平台原有冷却与荧光模块有自己的近似。两者应作为不同模型结果解释。

底层 API 每 RF 周期步数默认 48；操作界面默认 160，可选 64、96 或 160。再次以 dt/2 积分，在完全相同的物理时刻比较原始每一步坐标。报告共同时间、共同时间位置差及最大差。轨迹在导体碰撞、离开接地计算盒、初始点位于导体或域外时中止。每次积分最多 200000 步，达到预算时终止状态为 `step limit`，实际时长可能短于要求时长。粗细步长的预算分别计算，因此比较可能只覆盖共同前缀；`comparisonCoversFullTrajectory` / `coversFullTrajectory` 为 false 时不能称为完整末端误差。

## 6. 数值诊断及参考结果

必须区分以下量：

1. `maxResidualV`：离散 Laplace 方程以对角系数归一化后的最大节点残差，单位 V。它是迭代收敛量，不是完整连续 PDE 误差，也不是 V/m² 的原始 Laplacian。
2. `boundaryRmsPercent`、`boundaryMaxPercent`：在独立、非网格节点的解析电极表面采样，用实际 C1 三次插值电位计算六个 1 V 基函数的表面误差。它们反映边界附近插值质量，不能用小节点残差替代。
3. 网格细化后的实际物理量差异：频率、中心 DC 电位、势能曲线和轨迹均应独立比较。细化差值是误差指示，不是经过证明的误差界。
4. 外接地盒大小及迭代容差敏感性。

参考参数：r₀=0.55 mm，z₀=2.5 mm，杆长 12 mm，Vpk=200 V，fRF=20 MHz，Uend=8 V，Uradial=0，质量 39.962 u，q=+e。结果如下；频率由阱心有效势曲率得到。

| 精度 | 网格 x×y×z | 网格间距 x/z (µm) | SOR 次数 | 归一化最大残差 (V) | 表面插值 RMS / 最大误差 | 轴向 / 径向频率 (MHz) |
|---|---:|---:|---:|---:|---:|---:|
| preview | 37×37×101 | 134.44 / 136.50 | 113 | 1.32×10⁻⁷ | 3.365% / 19.049% | 0.02959281 / 1.43390736 |
| standard | 55×55×151 | 89.63 / 91.00 | 125 | 3.32×10⁻⁸ | 2.483% / 11.864% | 0.03003666 / 1.43407979 |
| fine | 73×73×201 | 67.22 / 68.25 | 149 | 4.24×10⁻⁹ | 1.863% / 11.287% | 0.03005070 / 1.43403613 |

standard→fine 的参考轴向频率差约 0.047%，径向约 0.0030%；这不意味着电极尖边附近场也达到了同等精度。表面最大插值误差仍可超过 10%，应避免把这些位置当作已准确解析的发射场、击穿场或表面效应数据。三次插值的场采样邻域尺度随诊断一起给出。

局部曲率矩阵可能有负本征值；负号频率表示指数增长率的大小，而非负实振动频率。极细长几何可将轴向场屏蔽到远低于数值容差：模块根据节点残差、电压和网格尺度给出保守的曲率分辨指标。低于该指标时 `curvatureResolved=false`，不把一个极小正数认证为稳定；这个指标本身也不是严格后验误差界。

## 7. 独立检验

`tests/electrode-field.test.mjs` 包含 22 项检验，涵盖：

- 几何尺寸和光学通孔、有限端面、锥面碰撞判定；
- 两个单位解的收敛及离散最大原理范围；
- 调和制造解 `x²−y²+0.3xy+0.2xz+0.4yz+2z−3x+7` 在普通节点和解析曲面截断 stencil 上的残差；参考 preview 共 3802 点、其中 504 个曲面邻接点，最大归一化残差 7.1×10⁻¹⁵ V；这检验了 stencil 一致性，不是有限阱完整误差界；
- 六基函数的旋转、镜像、叠加线性及电压约定；
- 对同一插值势作独立小差分验证 E=−∇Φ；
- 伪势 V²、f⁻²、m⁻¹、q² 标度；
- 中心 RF 零点、轴向曲率正号及三档网格细化；
- 固定 r₀ 而改变有限端电极间距，确实改变数值解；
- 弱曲率不被直接认证为稳定；
- 导体和域外遮罩、直线自由运动、真实同时间 dt/2 比较；
- 初始无效位置、积分预算与共同时间覆盖判定。

## 8. API

- `createElectrodeGeometry(parameters)`：返回可直接用于显示的几何尺寸。
- `solveElectrodeBasis(parameters)`：同步求解，返回可结构化克隆的两组体素电位、变换约定和诊断。完整体素留在 worker 内，UI 不接收大体积解。
- `evaluateUnitBasis(solution, pointMm)`：六个单位电位的原始三线性采样，供底层节点和对称性检查；不用于显示电场。
- `evaluateElectrodeBasis(solution,{xUm,yUm,zUm,hessian})`：六个实际查询基函数的三次电位、电场，及可选曲率。
- `evaluateField(solution,parameters)`：当前 DC、RF 峰值和瞬时电势/电场，伪势与有效势。
- `samplePotentialGrid(solution,parameters)`：二维 x–y 或 x–z 热图；每行从负第二坐标到正第二坐标。
- `integrateIonTrajectory(solution,parameters)`：时变 RF 单离子轨迹和同时间步长细化比较。
- `fieldMetrics(solution,parameters)`：中心曲率本征频率、局部分辨指示和几何因子。
- `validateManufacturedStencil(solution)`：独立调和多项式 stencil 检查。

`electrode-worker.js` 接受 `{id,type:'simulate',params}`，输出 progress/error/result。缓存几何单位解；改变电压、频率、初态或图像范围时复用单位解，改变电极几何、空间网格或计算盒大小时重新求解。导出的结果包含参数、计算方法、边界假设、二维网格、轨迹和诊断，可重新运行复核。

## 9. 方法来源

- Shortley, G. H. & Weller, R. *The numerical solution of Laplace's equation*. Journal of Applied Physics **9** (1938). [原始论文 DOI](https://doi.org/10.1063/1.1710426)。本模块采用曲面附近不等距 Dirichlet 差分的思想；并未声称复现所有原论文算法。
- Jomaa, Z. & Macaskill, C. *The Shortley–Weller embedded finite-difference method for the 3D Poisson equation with mixed boundary conditions*. Journal of Computational Physics **229**, 3675–3690 (2010). [原始研究](https://www.sciencedirect.com/science/article/abs/pii/S0021999110000446)。本模块只使用 Dirichlet 边界，并非该论文完整的混合边界高阶算法。
- 本实现的插值、SOR 参数、有限接地盒与质量/电荷约定均由本代码明确给出；原论文不能替代本实现的网格细化检验。