多极铁（Multipole）
本模块介绍 PASS 中的通用多极铁元件 Multipole ，用于模拟带电粒子在任意阶多极磁铁中的运动。与四极铁、六极铁、八极铁等单阶元件不同，多极铁通过 knl / ksl 数组同时支持任意阶（含混合阶）多极分量，适用于场误差注入、组合多极元件、高阶多极铁等场景。
PASS 中的多极铁支持 厚元件 （ length > 0 ）和 薄透镜 （ length = 0 ）两种模式，厚元件采用精确漂移-踢角-漂移（DKD-exact）辛积分方案，支持 uniform（2阶）和 yoshida4（4阶）两种辛积分器。踢角采用 Horner 嵌套求值，与 Xsuite kick_simple_single_coordinates 在公式层面完全一致。
代码位置
源文件：
PASS/commands/element/multipole.py类名：
Multipole（继承自Command）注册名：
multipole核心特征：
支持任意阶多极分量（
knl/ksl数组，最高阶由数组长度决定）支持正常分量（
knl）和斜分量（ksl）及其组合支持薄透镜模式（
length = 0，仅施加多极踢角）支持厚透镜模式（
length > 0，DKD-exact 辛积分）支持 uniform（2阶蛙跳）和 yoshida4（4阶 Yoshida 组合）积分器
Horner 嵌套求值，向量化实现，无逐粒子分支
零场（所有
knl/ksl分量为零）时自动退化为纯漂移支持孔径检查
单阶退化与四极铁/六极铁/八极铁逐粒子一致
坐标约定
PASS 采用与 Xsuite 一致的归一化曲线坐标，六维相空间变量为 \((x, p_x, y, p_y, z, \delta)\) ：
变量 |
符号 |
定义 |
|---|---|---|
|
\(x\) |
水平偏移（相对于参考轨道） |
|
\(p_x\) |
归一化水平动量， \(p_x = P_x / P_0\) |
|
\(y\) |
垂直偏移 |
|
\(p_y\) |
归一化垂直动量， \(p_y = P_y / P_0\) |
|
\(\zeta\) |
纵向坐标， \(\zeta = s - \beta_0 c t\) |
|
\(\delta\) |
相对动量偏差， \(\delta = P / P_0 - 1\) |
其中 \(P_0\) 为参考粒子动量， \(\beta_0 = v_0 / c\) 为参考粒子归一化速度， \(s\) 为沿参考轨道的弧长， \(t\) 为时间。
纵向动量分量定义为：
荷质比因子：
对于同种粒子束 \(\chi = 1\) 。
多极磁场与归一化强度
通用多极磁铁的磁场在横向平面内展开为泰勒级数。用复数表示：
其中 \(K_n\) 为 \(n\) 阶归一化多极强度（单位 \(\text{m}^{-n-1}\) ）， \(N\) 为最高阶数。 \(1/n!\) 是泰勒展开的自然系数。
展开前几阶：
阶数 \(n\) |
\(n!\) |
元件类型 |
磁场表达式 |
|---|---|---|---|
0 |
1 |
二极铁 |
\(B_y + i B_x = \frac{P_0}{q_0} K_0\) |
1 |
1 |
四极铁 |
\(B_y + i B_x = \frac{P_0}{q_0} K_1 (x + i y)\) |
2 |
2 |
六极铁 |
\(B_y + i B_x = \frac{P_0}{q_0} \frac{K_2}{2} (x + i y)^2\) |
3 |
6 |
八极铁 |
\(B_y + i B_x = \frac{P_0}{q_0} \frac{K_3}{6} (x + i y)^3\) |
归一化积分强度定义为：
其中 \(L\) 为磁铁长度， \(K_{nL}\) 为正常分量， \(K_{nsL}\) 为斜分量。PASS 中用户通过 knl 数组指定 \([K_{0L}, K_{1L}, K_{2L}, \ldots]\) ，通过 ksl 数组指定 \([K_{0sL}, K_{1sL}, K_{2sL}, \ldots]\) 。
Note
MAD-X 导出的 KNL / KSL 值与 PASS 的 knl / ksl 定义完全一致，均为积分强度 \(K_{nL}\) ，可直接填入，无需手动计算阶乘。 \(1/n!\) 由代码内部的 Horner 递推自动处理。
整体追踪流程
根据磁铁长度，多极铁有两种追踪模式：
薄透镜模式 （ \(L = 0\) ）
====== 薄透镜 (length = 0) ======
单次多极踢角 Kick(knl, ksl)
[位置不变，仅动量跳变]
厚透镜模式 （ \(L > 0\) ）
====== 厚透镜 (length > 0) ======
切片1 → 切片2 → ... → 切片N
(每个切片: Drift(ds/2) → Kick(ds) → Drift(ds/2))
其中 ds = L / N
knl_eff = kn * ds, ksl_eff = ks * ds
若所有 knl/ksl 分量为零：退化为单次精确漂移 Drift(L)
完整映射为：
薄透镜：
厚透镜（N 个切片）：
其中每个切片的 DKD 映射为：
Note
薄透镜模式不改变粒子的位置坐标 \((x, y, z)\) ，仅施加动量踢角
厚透镜模式的色品等效应通过精确漂移中的 \(p_z\) 表达式自然引入
当所有
knl/ksl分量为零时，厚透镜退化为纯漂移，避免无意义的空踢角循环
物理推导
哈密顿量
在直线坐标系中（多极铁无曲率， \(h = 0\) ），通用多极铁的哈密顿量为：
其中求和项为势能部分。将其拆分为传播部分（精确漂移 \(H_D\) ）和踢角部分（ \(H_K\) ）：
踢角映射
由哈密顿方程 \(\Delta p_x = -\frac{\partial H_K}{\partial x} \Delta s\) ， \(\Delta p_y = -\frac{\partial H_K}{\partial y} \Delta s\) ，对积分强度 \(K_{nL} = K_n \cdot \Delta s\) 求得：
其中 \((x+iy)^n\) 的实部对应正常分量，虚部对应斜分量。
Note
复数场约定为 \(B_y + i B_x = \frac{P_0}{q_0} \sum_n \frac{K_n}{n!} (x+iy)^n\) （ 不含共轭 ）。使用共轭 \(\overline{(x+iy)^n}\) 会导致 \(\Delta p_y\) 符号错误，此约定已通过六极铁交叉验证确认。
Horner 嵌套求值
多极踢角的核心是计算多项式：
其中 \(c_n = \chi \cdot K_{nL} / n!\) 。直接展开高阶项计算量大且数值不稳定。PASS 采用 Horner 嵌套求值，与 Xsuite kick_simple_single_coordinates （ track_magnet_kick.h:182-228 ）在算法层面一致。
Horner 递推从最高阶系数开始，逐步向下：
index = order
dpx_mul = chi * knl[order] / order! # 最高阶系数
dpy_mul = chi * ksl[order] / order!
while index > 0:
zre = dpx_mul * x - dpy_mul * y # Re[(dpx_mul + i*dpy_mul) * (x + iy)]
zim = dpx_mul * y + dpy_mul * x # Im[(dpx_mul + i*dpy_mul) * (x + iy)]
index -= 1
dpx_mul = chi * knl[index] / index! + zre
dpy_mul = chi * ksl[index] / index! + zim
dpx = -dpx_mul # px 取负（弧度约定）
dpy = +dpy_mul # py 不取负
其中 zre 和 zim 是复数乘法 \((\text{dpx\_mul} + i \cdot \text{dpy\_mul}) \cdot (x + i y)\) 的实部和虚部。
最终踢角为：
注意 \(\Delta p_x\) 取负（弧度约定）， \(\Delta p_y\) 不取负。
各阶展开结果
将 Horner 递推展开，前几阶结果为：
阶数 |
\(\Delta p_x\) （正常分量） |
\(\Delta p_y\) （正常分量） |
|---|---|---|
\(n=0\) |
\(-\chi K_{0L}\) |
\(0\) |
\(n=1\) |
\(-\chi K_{1L} \cdot x\) |
\(+\chi K_{1L} \cdot y\) |
\(n=2\) |
\(-\chi K_{2L}/2 \cdot (x^2 - y^2)\) |
\(+\chi K_{2L} \cdot x y\) |
\(n=3\) |
\(-\chi K_{3L}/6 \cdot (x^3 - 3xy^2)\) |
\(+\chi K_{3L}/6 \cdot (3x^2 y - y^3)\) |
斜分量的踢角通过复数乘法 \(i \cdot z^n\) 自然交换实虚部：将上表中 \(\Delta p_x\) 的正常分量公式移至 \(\Delta p_y\) ，将 \(\Delta p_y\) 的正常分量公式移至 \(\Delta p_x\) 并取负。
Note
Horner 递推对任意阶 \(N\) 通用。当 knl / ksl 数组只有单阶非零分量时，多极铁退化为对应的单阶元件（四极铁/六极铁/八极铁等），踢角公式与硬编码版本逐粒子一致。
精确漂移映射
漂移部分采用精确漂移（Table 1.1, map D, Eq. 1.86-1.88），与四极铁/六极铁/八极铁完全相同：
其中：
精确漂移保留了 \(p_z\) 的完整非线性，自然引入色品、高阶色散和路径长度效应。
辛积分器
Uniform（2阶蛙跳）
每个切片执行 Drift-Kick-Drift：
这是2阶辛积分器，截断误差 \(O(\Delta s^2)\) 。
Yoshida4（4阶组合）
将3个 DKD 步组合为4阶辛积分器：
其中 Yoshida 系数为：
截断误差 \(O(\Delta s^4)\) 。
自然包含的效应
DKD-exact 对理想多极铁自然包含所有非线性效应，无需额外项：
效应 |
来源 |
|---|---|
自然色品 |
精确漂移中 \(p_z\) 的 \(\delta\) 依赖性 |
高阶非线性色散 |
\(p_z\) 的完整平方根表达式 |
路径长度效应（ \(R_{56}\) 等） |
精确漂移的 \(z\) 更新 |
各阶多极踢角的完整非线性 |
Horner 递推保留 \((x+iy)^n\) 的所有项 |
唯一近似来源是积分器的截断误差（uniform 为 \(O(\Delta s^2)\) ，yoshida4 为 \(O(\Delta s^4)\) ）。
与 Xsuite 的差异：hxl 曲率修正
Xsuite 的 Multipole 元件支持 hxl 参数（水平参考轨迹旋转角），用于描述 组合功能磁铁 ——即参考轨道在磁铁内有弯曲的多极元件。PASS 当前不实现 hxl ，仅支持直铁（ hxl = 0 ）。
Xsuite 中 hxl 产生三组修正（源码 track_magnet_kick.h:97-143 ）：
修正项 |
触发条件 |
表达式 |
|---|---|---|
rot_frame |
\(h_{xl} \neq 0\) （与 knl 无关） |
\(\Delta p_x \mathrel{+}= h_{xl}(1+\delta)\) ， \(\Delta \zeta \mathrel{+}= -\frac{\beta_0}{\beta} h_{xl} x\) |
k0h 修正 |
\(h_{xl} \neq 0\) 且 \(k_{0L} \neq 0\) |
\(\Delta p_x \mathrel{+}= -\chi \, k_{0L} \cdot \frac{h_{xl}}{L} \cdot x\) |
k1h 修正 |
\(h_{xl} \neq 0\) 且 \(k_{1L} \neq 0\) |
\(\Delta p_x \mathrel{+}= \chi \, k_{1L} \cdot \frac{h_{xl}}{L} \cdot (-x^2 + \frac{1}{2}y^2)\) ， \(\Delta p_y \mathrel{+}= \chi \, k_{1L} \cdot \frac{h_{xl}}{L} \cdot xy\) |
其中 rot_frame 修正描述参考轨迹偏转的几何效应， 与磁场分量无关 ——即使 knl/ksl 全为零（纯漂移），只要 \(h_{xl} \neq 0\) 就会触发。 k0h 和 k1h 修正则是曲率与多极分量的耦合项，需要同时满足 hxl 和对应的 knl 分量非零。
Note
PASS 多极铁设 \(h_{xl} = 0\) ，三组修正均为零，与 Xsuite 直铁（
hxl=0）在 kick 公式层面完全一致当 \(h_{xl} = 0\) 时，无论 knl/ksl 取何值，PASS 与 Xsuite 的结果逐粒子一致（已验证，精度 \(< 10^{-12}\) ）
若需模拟组合功能磁铁（有弯曲参考轨道的多极元件），需在 PASS 中增加
hxl支持，这是未来扩展项
接口参数
属性名 |
JSON key |
类型 |
默认值 |
说明 |
|---|---|---|---|---|
|
|
float |
必填 |
元件在束线中的纵向位置 |
|
|
str |
必填 |
元件名称 |
|
|
float |
必填 |
磁铁长度， \(= 0\) 为薄透镜 |
|
|
list |
|
正常分量积分强度数组 \([K_{0L}, K_{1L}, \ldots]\) |
|
|
list |
|
斜分量积分强度数组 \([K_{0sL}, K_{1sL}, \ldots]\) |
|
|
int |
1 |
厚透镜切片数 |
|
|
str |
|
积分器，可选： |
|
|
str |
|
孔径类型 |
|
|
list |
|
孔径参数值 |
Note
knl 和 ksl 数组长度不需要相同，短的数组自动补零。最高阶数 \(N\) 由较长数组的长度决定（ \(N = \max(\text{len}) - 1\) ）。
使用示例
薄透镜多极铁（场误差注入）
{
"MPE1": {
"S (m)": 10.0,
"Command": "multipole",
"Length (m)": 0.0,
"KiL": [0.0, 0.0, 0.001, 0.0005],
"KiSL": [0.0, 0.0, 0.0003, 0.0001],
"Aperture Type": "off"
}
}
零长度多极铁，含二阶和三阶场误差分量。用于模拟磁铁安装误差或加工误差对束流的影响。
厚透镜多极铁（组合元件）
{
"MP1": {
"S (m)": 20.0,
"Command": "multipole",
"Length (m)": 0.5,
"KiL": [0.0, 0.3, 5.0, 200.0],
"KiSL": [0.0, 0.0, 0.0, 0.0],
"Num Slices": 5,
"Integrator": "yoshida4",
"Aperture Type": "off"
}
}
厚透镜组合多极铁，同时含四极、六极、八极正常分量，5 个切片，4 阶辛积分。
单阶多极铁（等价于八极铁）
{
"MP2": {
"S (m)": 30.0,
"Command": "multipole",
"Length (m)": 0.0,
"KiL": [0.0, 0.0, 0.0, 500.0],
"KiSL": [0.0, 0.0, 0.0, 200.0],
"Aperture Type": "off"
}
}
仅含三阶分量（ knl=[0,0,0,500] ， ksl=[0,0,0,200] ），等价于一个正常+斜八极铁薄透镜。与 Octupole 元件逐粒子一致。
高阶多极铁（十极铁）
{
"MP3": {
"S (m)": 40.0,
"Command": "multipole",
"Length (m)": 0.0,
"KiL": [0.0, 0.0, 0.0, 0.0, 10000.0],
"KiSL": [0.0, 0.0, 0.0, 0.0, 0.0],
"Aperture Type": "off"
}
}
四阶多极铁（十极铁）， knl=[0,0,0,0,10000] 。专用元件只支持到八极（三阶），多极铁可支持任意阶。
应用场景
场误差注入 ：将 MAD-X 导出的磁铁场误差以多极铁形式插入束线，模拟安装误差和加工偏差
组合多极元件 ：同一位置同时施加多个阶数的多极踢角（如四极+六极+八极组合）
高阶多极铁 ：十极铁（ \(n=4\) ）、十二极铁（ \(n=5\) ）等超出专用元件范围的高阶元件
非线性效应研究 ：研究高阶多极场对束流动力学的影响，如动态孔径、共振驱动
MAD-X 兼容 ：
knl/ksl定义与 MAD-X 完全一致，可直接导入 MAD-X 序列
参考文献
Xsuite Physics Guide, Sec 1.10.3 (精确漂移), Sec 1.10.5 (多极铁)
Xsuite 源码：
xtrack/beam_elements/elements_src/multipole.h,track_magnet.h,track_magnet_kick.h,track_magnet_drift.hYoshida, H., “Construction of higher order symplectic integrators”, Phys. Lett. A 150 (1990)
MAD-X 物理手册：多极磁场与非线性传输
Wiedemann, H., “Particle Accelerator Physics”, Ch. 4 (非线性束流动力学)