高频加速腔（RFCavity）
本模块介绍 PASS 中的高频加速腔元件 RFCavity ，用于模拟带电粒子在射频电场中的纵向加速运动。高频加速腔是同步加速器、直线加速器和回旋加速器中最核心的元件之一，通过周期性电场为粒子提供能量增益，维持同步粒子的能量并控制纵向束流动力学（同步振荡、束团压缩、纵向接受度等）。
PASS 中的高频加速腔建模为 薄透镜 （ length = 0 ）的瞬时能量 kick ，采用 精确相对论能量-动量关系 和 移动参考系 。纵向变换弃用了传统的一阶线性化近似，改用精确的 \(E^2 = p^2 + m_0^2\) 关系，避免了线性化带来的 \(O(\delta^2)\) 误差和参考系变换中的 \(\beta_1/\beta_0\) 因子问题。
代码位置
源文件：
PASS/commands/element/rfcavity.py类名：
RFCavity（继承自Command）注册名：
rfcavity核心特征：
薄透镜模型，瞬时能量 kick
精确相对论能量-动量变换（ \(E^2 = p^2 + m_0^2\) ），无线性化近似
移动参考系：每圈更新束流参考能量（ \(E_k, \gamma, \beta, p_0, B\rho\) ）
横向动量重缩放（绝热阻尼）： \(p_x \leftarrow p_x \cdot \beta_0\gamma_0 / (\beta_1\gamma_1)\)
归一化发射度 \(\epsilon_N = \beta\gamma\epsilon\) 严格守恒
支持 dp 接受度（纵向孔径）检查
支持固定值和 TFS 文件（Ramping）两种参数输入方式
支持多圈加速模拟
RF 谐波数是腔的状态属性，对所有束团统一；它与束流的束团分组数相互独立
坐标约定
PASS 采用归一化曲线坐标，六维相空间变量为 \((x, p_x, y, p_y, \zeta, \delta)\) ：
变量 |
符号 |
定义 |
|---|---|---|
|
\(x\) |
水平偏移（相对于参考轨道） |
|
\(p_x\) |
归一化水平动量， \(p_x = P_x / P_0\) |
|
\(y\) |
垂直偏移 |
|
\(p_y\) |
归一化垂直动量， \(p_y = P_y / P_0\) |
|
\(z_{\mathrm{rel}}\) |
粒子相对所属束团中心的纵向坐标 |
|
\(\delta\) |
相对动量偏差， \(\delta = P / P_0 - 1\) |
其中 \(P_0\) 为参考粒子动量， \(\beta_0 = v_0 / c\) 为参考粒子归一化速度。每个束团还保存一个固定的实验室坐标中心
其中 \(h_{\mathrm{group}}\) 是束流的束团分组数， \(h_{\mathrm{id}}\) 是该束团的分组编号。粒子的实验室纵向位置为
z 数组只存储 \(z_{\mathrm{rel}}\) ；需要计算 RF 相位或到达时间时，元件再显式加上 \(z_{\mathrm{center}}\)。
物理推导
RF 腔的物理本质
RF 腔产生纵向（沿束流方向）振荡电场 \(E_s(t) = E_0 \sin(\omega_{\text{rf}} t + \varphi_s)\) 。粒子穿过腔体时获得的能量增益取决于到达时刻，因此 RF 相位必须由实验室纵向位置 \(z_{\mathrm{lab}}\) 计算，而不是只使用束团内的相对坐标 \(z_{\mathrm{rel}}\)。
设机器周长为 \(C\) ，等效半径 \(R = C / (2\pi)\) ，RF 腔谐波数为 \(h_{\mathrm{rf}}\) ，RF 电压为 \(V\) ，设定相位为 \(\varphi_s\) 。粒子的方位角为 \(\theta = z_{\mathrm{lab}} / R\) ，其 RF 相位为：
其中 \(\varphi_{\text{off}}\) 为附加相位偏移（详见后文）。
phi_offset 的用途
phi_offset 是施加在所有粒子上的常数相位偏移，用于平移 RF 波形的时间基准。其主要用途包括：
多腔相位对齐 ：当多台 RF 腔沿环分布、腔间距不是 RF 波长的整数倍时，每台腔需要独立的相位修正以保持同步。
多谐波系统 ：不同谐波数的腔共享同一频率基准时，通过 \(\varphi_{\text{off}}\) 实现各腔独立的相位调节。
相位微调（phase trim） ：在运行中通过
phi_offset微调腔的有效相位，而不改变phase给出的标称相位设定。束团参考粒子的实际相位还包含其 \(z_{\mathrm{center}}\) 对应的方位项。
物理上， \(\varphi_{\text{off}}\) 旋转整个 \(\sin\) 曲线，使得粒子的实际相位变为 \(\varphi_s + \varphi_{\text{off}} - h_{\mathrm{rf}}\theta\) 。
束团分组数与 RF 谐波数
束流的 \(h_{\mathrm{group}}\) 只定义束团中心网格；RF 腔的 \(h_{\mathrm{rf}}\) 只定义 RF 波形在一圈内的周期数。两者不要求相等，也不要求互为整数倍。RFCavity 对奇数和偶数谐波使用同一公式，不施加额外相位补偿。
当 \(h_{\mathrm{rf}}/h_{\mathrm{group}}\) 为整数时，各束团中心位于等价 RF 相位；否则不同束团中心可能看到不同相位和不同参考能量增益。这是给定分组与 RF 配置的直接物理结果，程序不会自动修改相位。
能量 kick
每个粒子的能量增益为：
其中 \(q/A\) 为荷质比。对每个束团，参考粒子定义为 \(z_{\mathrm{rel}}=0\) ，其实验室位置为 \(z_{\mathrm{center}}\) ，参考能量增益为：
\(\Delta E_{\text{ref}}\) 用于更新该束团的移动参考系，因此束团中心粒子的 \(\delta\) 保持在 0 附近。不同束团的参考增益可以不同。
一阶线性化近似及其问题
传统方法在将能量偏差 \(dE\) 转换为动量偏差 \(\delta\) 时，采用一阶泰勒展开：
其中 \(dE = E - E_0\) 为粒子相对参考粒子的能量偏差。这是精确关系
在 \(\delta \to 0\) 处的一阶近似。展开的误差为 \(O(\delta^2)\) 。
问题 1：大 delta 时精度差
当 \(\delta\) 较大（如 \(\pm 30\%\) 的注入接收度）， \(O(\delta^2)\) 项可达 \(\sim 0.01\) ，远超浮点精度，引入不可忽略的系统性偏差。
问题 2：参考系变换引入额外的 beta1/beta0 因子
在移动参考系中，参考能量从 \(E_0\) 变为 \(E_1 = E_0 + \Delta E_{\text{syn}}\) 。传统方法假设参考系变换时 \(\delta\) 不变，推导如下：
从 \(dE = \delta \cdot \beta^2 \cdot E_{\text{total}}\) 出发，旧参考系中 \(dE_0 = \delta \cdot \beta_0^2 \cdot E_0\) ，新参考系中 \(dE_1 = \delta \cdot \beta_1^2 \cdot E_1\) 。若假设 \(\delta\) 不变，则：
进一步将 \(\beta_1^2 E_1 / (\beta_0^2 E_0)\) 近似为 \(\beta_1 / \beta_0\) （仅在 \(E_1 \approx E_0\) 即弱加速时成立），得到：
这是一个 三重近似 ：
一阶线性化 ： \(dE \approx \delta \cdot \beta^2 \cdot E_{\text{total}}\) （截断 \(O(\delta^2)\) ）
delta 不变假设 ：参考系变换时 \(\delta\) 不变（实际 \(\delta = p/p_0 - 1\) 依赖于 \(p_0\) ）
弱加速近似 ： \(\beta_1^2 E_1 / (\beta_0^2 E_0) \approx \beta_1/\beta_0\) （仅在 \(E_1 \approx E_0\) 时成立）
在强加速场景（如从注入到引出能量变化数倍），第 3 步近似显著失效。
精确能量-动量变换
PASS 弃用上述全部近似，直接从精确相对论关系出发。所有物理量采用自然单位制（ \(c = 1\) ）， \(m_0\) 、 \(p_0\) 、 \(E\) 均以 eV 为单位。能量-动量关系为：
跟踪链路如下：
Kick 前 ：粒子动量 \(p_{\text{old}} = p_{0,\text{old}} \cdot (1 + \delta)\) ，绝对总能量：
施加 kick ：
恢复动量 ：
计算新 \(\delta\) （相对于新参考动量 \(p_{0,\text{new}}\) ）：
为什么精确方法不需要 beta1/beta0 因子
精确方法直接追踪每个粒子的绝对总能量 \(E_{\text{particle}}\) 和绝对动量 \(p_{\text{particle}}\) 。 RF kick 改变的是能量（ \(E_{\text{new}} = E_{\text{old}} + \Delta E\) ），然后从能量精确恢复动量（ \(p = \sqrt{E^2 - m_0^2}\) ），最后除以新参考动量得到 \(\delta\) 。
这个过程中：
不需要 \(dE \to \delta\) 的线性化（直接用 \(E \to p\) 的精确关系）
不需要假设 \(\delta\) 不变（ \(\delta\) 由 \(p_{\text{particle}} / p_{0,\text{new}}\) 直接计算）
不需要 \(\beta_1/\beta_0\) 缩放因子（参考系变换已隐含在 \(p_{0,\text{new}}\) 中）
因此三重近似全部被绕过， \(\beta_1/\beta_0\) 因子自然不出现。
此变换在物理定义域内不使用纵向线性化，只需两次 sqrt 运算（numpy 向量化，成本可忽略），适用于大 \(\delta\) 和强加速场景。
Warning
输入参数必须保证 kick 后的粒子总能量和参考总能量不低于静止能量。若设置了非物理的过强减速，使 \(E_{\mathrm{new}} < m_0\) ，动量平方根将失去实数定义；当前实现不会自动修正这类输入。
移动参考系
PASS 采用移动参考系（moving reference frame）：每次 RF kick 后，每个束团的参考能量更新为包含其 \(\Delta E_{\text{ref}}\) 的新值：
每个束团参考粒子的 \(\delta\) 始终保持在 0 附近，避免了固定参考系中 \(\delta\) 持续增长导致的数值精度问题。
横向动量重缩放与绝热阻尼
RF kick 是纯纵向能量增益，不改变粒子的绝对横向动量 \(P_x\) 。但由于参考动量 \(P_0\) 增长，归一化横向动量 \(p_x = P_x / P_0\) 必须重缩放：
此缩放 精确 ，不是近似（因为 \(p_0 c = \beta \gamma m_0 c^2\) ，所以 \(p_{0,\text{old}} / p_{0,\text{new}} = \beta_0 \gamma_0 / (\beta_1 \gamma_1)\) ）。
物理意义 ：归一化发射度 \(\epsilon_N = \beta\gamma\epsilon\) 是绝热不变量（Liouville 定理）。当 \(p_0\) 增长时，几何发射度 \(\epsilon\) 按 \(1/(\beta\gamma)\) 收缩，即绝热阻尼（adiabatic damping）。横向动量重缩放保证了 \(\epsilon_N\) 严格守恒：
跟踪流程
输入: z_rel, z_center, dp(=δ), px, py, tag,
bunch参数(β₀, γ₀, m₀, q/A, Ek, p₀, C)
1. 计算 RF 相位
z_lab = z_rel + z_center
φ_particle = phase + φ_off - h_rf·z_lab/R
2. 能量 kick
ΔE_kick = (q/A)·V·sin(φ_particle) [逐粒子]
ΔE_ref = (q/A)·V·sin(phase + φ_off - h_rf·z_center/R)
[逐束团标量]
3. 更新束流参考（移动参考系）
E_total1 = E_total0 + ΔE_ref
γ₁ = E_total1 / m₀
β₁ = √(1 - 1/γ₁²)
p₀_new = γ₁·m₀·β₁
Ek₁ = E_total1 - m₀
4. 精确 δ 更新
p_old = p₀_old·(1+δ)
E_old = √(p_old² + m₀²)
E_new = E_old + ΔE_kick
p_new = √(E_new² - m₀²)
δ_new = p_new / p₀_new - 1
5. 横向动量重缩放（绝热阻尼）
scale = β₀γ₀ / (β₁γ₁)
px *= scale
py *= scale
6. dp 接受度检查（超出 → 标记丢失）
7. 更新丢失粒子信息
RFCavity 不修改也不折叠 z_rel。
接口参数
属性名 |
JSON key |
类型 |
默认值 |
说明 |
|---|---|---|---|---|
|
|
float |
0.0 |
RF 电压（V） |
|
|
int |
1 |
谐波数 \(h\) |
|
|
float |
0.0 |
标称 RF 相位 \(\varphi_s\) （rad）；束团中心的实际相位还包含 |
|
|
float |
0.0 |
附加相位偏移（rad），用于多腔相位对齐和相位 trim |
|
|
str |
None |
Ramping 数据文件路径（TFS 格式），提供后覆盖固定值参数。每行对应一圈，所需列名： |
|
|
bool |
True |
开关 |
属性名 |
JSON key |
类型 |
默认值 |
说明 |
|---|---|---|---|---|
|
|
float |
-1.0 |
dp 接受度下限 |
|
|
float |
1.0 |
dp 接受度上限 |
属性名 |
JSON key |
类型 |
默认值 |
说明 |
|---|---|---|---|---|
|
|
float |
必填 |
元件在束线中的纵向位置 |
|
|
str |
必填 |
元件名称 |
|
|
str |
|
横向孔径类型 |
|
|
list |
|
横向孔径参数 |
Ramping 数据文件
当 RF 参数需要随圈数变化时（如能量 ramping ），可提供 TFS 格式的数据文件。 TFS （ Table File System ）是一种带元数据的表格格式，文件中可包含标题、注释等文档信息，列通过列名识别而非位置。
所需列名（大小写不限，顺序不限）：
HARMONIC—— 谐波数VOLTAGE—— RF 电压（V）PHASE—— 标称 RF 相位（rad）PHI_OFFSET—— 附加相位偏移（rad）
读取时列名自动转换为小写，因此 Harmonic 、 voltage 、 phase 等任意大小写组合均可。每行对应一圈（第 0 行 = 第 0 圈）。若圈数超出文件行数，使用最后一行数据。文件还可包含 TITLE 、 DATE 等元数据头信息，由 tfs-pandas 库自动解析。
使用示例
示例 1：基本加速腔
{
"RFCavity_1": {
"S (m)": 0.0,
"Command": "RFCavity",
"Voltage (V)": 100000,
"Harmonic": 1,
"Phase (rad)": 0.3,
"Is enabled": true
}
}
对质子单束团（ \(z_{\mathrm{center}}=0\) 、 \(\varphi_{\mathrm{off}}=0\) ），参考粒子每圈获得 \(\Delta E = V \sin(0.3) \approx 29552\) eV 的能量增益。
示例 2：带 dp 接受度和相位偏移的腔
{
"RFCavity_2": {
"S (m)": 500.0,
"Command": "RFCavity",
"Voltage (V)": 200000,
"Harmonic": 4,
"Phase (rad)": 0.5236,
"Phi offset (rad)": 0.05,
"Dp aperture": [-0.02, 0.02],
"Is enabled": true
}
}
\(\varphi_s = \pi/6 = 0.5236\) rad ， 4 次谐波， dp 接受度 \(\pm 2\%\) ，附加相位偏移 0.05 rad 。
示例 3：Ramping 腔（TFS 文件输入）
{
"RFCavity_3": {
"S (m)": 0.0,
"Command": "RFCavity",
"RF data file": "D:/PASS/para/rf_data.tfs",
"Is enabled": true
}
}
TFS 文件中每行指定该圈的 HARMONIC 、 VOLTAGE 、 PHASE 、 PHI_OFFSET 。
示例 4：禁用腔
{
"RFCavity_4": {
"S (m)": 0.0,
"Command": "RFCavity",
"Voltage (V)": 100000,
"Harmonic": 1,
"Phase (rad)": 0.3,
"Is enabled": false
}
}
Is enabled = false 时，腔体不执行任何操作（no-op ）。
应用场景
同步加速器加速 ：从注入能量到引出能量的加速过程，移动参考系保持 \(\delta\) 在小量级，数值精度好
纵向束流动力学 ：同步振荡、束团拉伸/压缩、纵向 Emittance 控制
多谐波加速 ：多个 RF 腔串联使用，不同谐波数实现束团塑形
能量 ramping ：通过 TFS 文件输入实现电压/相位随圈数变化，模拟真实加速器运行方案
纵向接受度研究 ：通过 dp aperture 参数设定纵向接受度，研究束流损失边界
验证测试
tests/test_rf_verification.py —— 18 组共 28 项测试，全部通过：
束团参考粒子 \(\delta \approx 0\) （精度 \(< 10^{-12}\) ）
单束团基准情形（ \(z_{\mathrm{center}}=0\) 、 \(\varphi_{\mathrm{off}}=0\) ）的参考能量增益 \(\Delta E = (q/A) V \sin(\varphi_s)\)
精确能量-动量关系 \(E^2 = p^2 + m_0^2\)
相位依赖性（不同 \(z_{\mathrm{lab}}\) 的粒子获得不同 kick ）
移动参考系（束流参考能量正确更新）
绝热阻尼（ \(p_x\) 按 \(\beta_0\gamma_0/(\beta_1\gamma_1)\) 缩放）
归一化发射度守恒（相对误差 \(< 10^{-15}\) ）
死粒子不被 kick
零电压退化为 no-op
dp 接受度检查
多圈加速（10 圈后能量正确， \(\delta\) 仍为 \(\sim 0\) ）
与独立参考实现的全量对比（ \(< 10^{-10}\) ）
低 \(\gamma\) （非超相对论， \(\beta = 0.417\) ）
大 \(\delta\) （ \(\pm 30\%\) ，非线性区）
离子（ \(q/A \neq 1\) ）
相位偏移 \(\varphi_{\text{off}}\)
禁用腔（
is_enabled = false）多束团实验室坐标、非整倍谐波关系和奇偶谐波统一处理