螺线管（Solenoid）
本模块介绍 PASS 中的螺线管元件 Solenoid ，用于模拟带电粒子在纵向磁场中的运动。螺线管产生沿束流方向的均匀磁场 \(B_z\)，通过 Larmor 旋转效应耦合水平与垂直平面，同时提供横向聚焦。
PASS 中的螺线管采用 精确非线性映射 （Larmor 框架下的哈密顿量解析解）。纯螺线管（无多极场叠加）时映射零误差；叠加多极场时采用 Sol-Kick-Sol（SKS）辛积分器。
代码位置
源文件：
PASS/commands/element/solenoid.py类名：
Solenoid（继承自Command）注册名：
solenoid核心特征：
采用精确螺线管映射（Larmor 旋转 + 聚焦， \(p_z\) 逐粒子计算）
无薄透镜模式（螺线管无薄透镜极限， \(L=0\) 时无效应）
支持多极场叠加（
knl/ksl），使用 SKS 积分器支持 uniform（2阶蛙跳）和 yoshida4（4阶 Yoshida 组合）积分器
\(k_s = 0\) 时自动退化为纯漂移
色品效应通过逐粒子 \(p_z\) 自然引入
支持孔径检查
坐标约定
PASS 采用归一化曲线坐标，六维相空间变量为 \((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\) 轴）的均匀磁场：
归一化螺线管强度定义为：
其中 \(q_0\) 为参考粒子电荷， \(P_0\) 为参考粒子动量。 PASS 中用户直接指定 \(k_s\) （ ks ）。
定义半强度：
Larmor 旋转角为：
其中 \(p_z\) 为粒子的归一化纵向动量分量（逐粒子不同，见下文）， \(L\) 为螺线管长度。
物理推导
哈密顿量
在直线坐标系中，螺线管的哈密顿量为：
其中各项物理含义：
项 |
物理含义 |
|---|---|
\(-\sqrt{(1+\delta)^2 - p_x^2 - p_y^2}\) |
自由传播（精确漂移） |
\(\frac{k_s^2}{8}(x^2 + y^2)\) |
螺线管聚焦（等效四极分量） |
\(-\frac{k_s}{2}(x p_y - y p_x)\) |
Larmor 旋转（ \(x\) - \(y\) 耦合） |
Note
Larmor 旋转项 \(-\frac{k_s}{2}(x p_y - y p_x)\) 同时依赖位置和动量 ，这是螺线管与四极铁的本质区别。四极铁的踢角项仅依赖位置，可以将哈密顿量干净地分裂为漂移和踢角两部分（DKD 积分器）。螺线管的 Larmor 旋转项不可分裂为纯位置或纯动量的部分，因此 不能使用普通漂移做 DKD 积分 。
Larmor 框架与精确解
做 Larmor 变换——将横截面坐标系绕 \(s\) 轴旋转角度 \(\theta = \text{sk} \cdot s / p_z\) ，定义 Larmor 框架下的正则动量：
在 Larmor 框架中， \(p_{k1}\) 和 \(p_{k2}\) 是 守恒量 （不随 \(s\) 变化），因此纵向动量分量：
在整个螺线管内逐粒子恒定。这使得螺线管映射可以 精确求解 ，无需近似。
精确螺线管映射
给定螺线管长度 \(L\) ， Larmor 旋转角：
映射分为旋转和漂移两步：
步骤 1：Larmor 旋转 （将坐标旋转到 \(s=L\) 处的 Larmor 框架）
步骤 2：Larmor 框架中的漂移 （等效漂移长度 \(\sin\theta / \text{sk}\) ）
纵向坐标更新 ：
其中 \(\text{rvv} = \beta / \beta_0\) 为粒子速度与参考粒子速度之比：
Note
\(p_z\) 逐粒子不同（包含 \(\delta\) 和 Larmor 动量的贡献），因此映射是 精确非线性 的
当 \(k_s \to 0\) 时， \(\sin\theta/\text{sk} \to L/p_z\) ，映射退化为精确漂移
为什么螺线管没有薄透镜模式
四极铁的薄透镜极限（ \(L \to 0\) ， \(k_1 \to \infty\) ， \(k_1 L = \text{const}\) ）给出有限的动量踢角 \(\Delta p_x = -k_{1L} \cdot x\) ，物理上自洽。
螺线管的薄透镜极限（ \(L \to 0\) ， \(k_s \to \infty\) ， \(k_s L = \text{const}\) ）存在根本困难：
Larmor 旋转角 \(\theta = k_s L / (2 p_z)\) 有限 ✓
聚焦项 \(\text{sk} \cdot \sin\theta = (k_s/2) \cdot \sin\theta \to \infty\) 发散 ✗
位置和动量的缩放行为不对称：旋转角有限但聚焦力发散，薄透镜极限不存在。
因此 PASS 中螺线管 \(L = 0\) 时 无效应 （恒等映射），不提供薄透镜模式。
多极场叠加与 SKS 积分器
当螺线管内部叠加横向多极场分量（ \(k_{nl}\) / \(k_{sl}\) ）时，总哈密顿量为：
其中 \(H_{\text{mult}}\) 为多极铁踢角哈密顿量（仅依赖位置）。由于 \(H_{\text{sol}}\) 和 \(H_{\text{mult}}\) 不对易，需要分裂算符法。
PASS 采用 Sol-Kick-Sol （SKS）积分器，与四极铁的 DKD 完全平行：
其中：
Sol = 精确螺线管映射（
_solenoid_exact_cpu），处理 \(B_z\) 场Kick = 多极铁踢角（Horner 递归），处理横向多极场
漂移算子 |
踢角算子 |
场景 |
|
|---|---|---|---|
四极铁 DKD |
自由漂移 |
四极踢角 |
\(B_z = 0\) ，仅横向梯度场 |
螺线管 SKS |
螺线管映射 |
多极踢角 |
\(B_z \neq 0\) ，叠加横向多极场 |
Note
SKS 中的 “Sol” 不是自由漂移，而是螺线管精确映射。螺线管内 \(B_z\) 始终存在，粒子不是在无场空间漂移。如果错误地使用自由漂移替代螺线管映射，将丢失 Larmor 旋转效应。
uniform 积分器（2阶辛）
每个切片采用 Sol-Kick-Sol 结构，即二阶蛙跳（leapfrog）：
每个切片误差为 \(O(\Delta s^3)\) ，全局误差为 \(O(\Delta s^2)\) 。
yoshida4 积分器（4阶辛）
通过组合三个二阶 SKS 步构造四阶辛映射 [Yoshida 1990]：
其中 Yoshida 系数为：
每个切片误差为 \(O(\Delta s^5)\) ，全局误差为 \(O(\Delta s^4)\) 。
整体追踪流程
根据是否有多极场叠加，螺线管有两种追踪路径：
====== 厚透镜 (length > 0) ======
无多极场 (knl/ksl 全零):
单段精确螺线管映射 Sol(L, ks)
[零误差，无需切片]
有多极场 (knl/ksl 非零):
切片1 → 切片2 → ... → 切片N
(每个切片: Sol(ds/2) → Kick(ds) → Sol(ds/2))
其中 ds = L / N
特殊情况:
ks = 0 → 退化为纯漂移 Drift(L)
L = 0 → 无效应（螺线管无薄透镜极限）
完整映射为：
无多极场：
有多极场（ \(N\) 个切片）：
色品效应
螺线管的色品效应通过逐粒子 \(p_z\) 表达式自然引入。
在 Larmor 框架中， \(p_z\) 依赖 \(\delta\) 和 Larmor 动量 \(p_{k1}, p_{k2}\) ：
不同动量偏差 \(\delta\) 的粒子有不同的 \(p_z\) ，因此有不同的 Larmor 旋转角 \(\theta = \text{sk} \cdot L / p_z\) 和不同的等效漂移长度 \(\sin\theta / \text{sk}\) 。这就是螺线管色品的物理来源——动量依赖的旋转角和聚焦强度。
接口参数
属性名 |
JSON key |
类型 |
单位 |
说明 |
|---|---|---|---|---|
|
|
float |
m |
元件在束线中的纵向位置 |
|
|
float |
m |
元件长度 （必须 \(\ge 0\) ； \(= 0\) 时无效应） |
|
|
str |
元件名称 |
|
|
|
float |
\(\text{m}^{-1}\) |
螺线管归一化强度 \(k_s = q_0 B_z / P_0\) ，默认 0 |
|
|
list |
\(\text{m}^{-n}\) |
多极铁法向积分强度数组 \(K_{nL}\) ，默认 |
|
|
list |
\(\text{m}^{-n}\) |
多极铁斜向积分强度数组 \(K_{sL}\) ，默认 |
|
|
int |
切片数，默认 1（仅多极场叠加时有效） |
|
|
|
str |
积分器，可选： |
|
|
|
str |
孔径类型，默认 |
|
|
|
list |
孔径参数值，默认 |
Note
knl/ksl为可选参数。不指定或全零时，螺线管使用单段精确映射（零误差），忽略num_slices和integrator指定非零
knl/ksl时，启用 SKS 积分器，num_slices和integrator生效ks = 0且有长度时，元件退化为纯漂移length = 0时，螺线管无效应（不提供薄透镜模式）
使用示例
纯螺线管（精确映射）
{
"SOL1": {
"S (m)": 10.0,
"Command": "Solenoid",
"Length (m)": 1.0,
"ks": 2.0,
"Aperture Type": "off"
}
}
长度 1.0 m，归一化强度 \(k_s = 2.0\) 。使用单段精确螺线管映射，零误差。
弱螺线管
{
"SOL2": {
"S (m)": 20.0,
"Command": "Solenoid",
"Length (m)": 2.0,
"ks": 0.5,
"Aperture Type": "off"
}
}
弱场螺线管， Larmor 旋转角较小。
反向磁场螺线管
{
"SOL3": {
"S (m)": 30.0,
"Command": "Solenoid",
"Length (m)": 1.5,
"ks": -3.0,
"Aperture Type": "off"
}
}
\(k_s < 0\) 表示反向磁场， Larmor 旋转方向相反。
螺线管叠加四极场（SKS 积分器）
{
"SOL4": {
"S (m)": 40.0,
"Command": "Solenoid",
"Length (m)": 1.0,
"ks": 2.0,
"KiL": [0.0, 0.1],
"Kisl": [],
"Num Slices": 4,
"Integrator": "yoshida4",
"Aperture Type": "off"
}
}
螺线管（ \(k_s = 2.0\) ）叠加四极分量（ \(K_{1L} = 0.1\) ），4 个切片，4 阶辛积分器。 KiL 数组第 0 项为 \(K_{0L}\) （偶极），第 1 项为 \(K_{1L}\) （四极）。
零场退化（纯漂移）
{
"SOL5": {
"S (m)": 50.0,
"Command": "Solenoid",
"Length (m)": 1.0,
"ks": 0.0,
"Aperture Type": "off"
}
}
\(k_s = 0\) 时退化为纯漂移。
应用场景
低能束流传输线 ：低能段 \(\beta\gamma\) 较小，螺线管聚焦效率高于四极铁，常用于注入器和低能传输线
电子冷却器 ：螺线管约束电子束与离子束共线运动，用于冷却横向发射度
对撞机探测器螺线管 ：大型实验探测器（如 CMS、ATLAS）的螺线管磁场对束流光学有显著影响，需在 lattice 模型中精确计入
超导螺线管 ：高场超导螺线管中的多极场误差可通过
knl/ksl参数叠加建模旋转对称束流 ：螺线管的 Larmor 旋转可用于消除 \(x\) - \(y\) 耦合或产生特定旋转对称的束流分布