弯转磁铁（Dipole / SBend）
本模块介绍 PASS 中的弯转磁铁元件 SBend ，用于模拟带电粒子在扇形弯转磁铁中的运动。弯转磁铁是加速器中最基本的弯转元件，通过均匀磁场使粒子轨道偏转。
PASS 中的弯转磁铁为 厚元件 （ length > 0 ），支持完整的非线性跟踪，包括边缘角效应、边缘场效应、以及多种辛积分方案。
Fint 指定入口边缘场积分。正的 Fintx 指定出口积分；
Fintx <= 0 时继承 Fint。特别是，当 Fint > 0 时，
设置 Fintx = 0 并不会关闭出口的有限气隙项。
核心特征：
支持 rot-kick-rot (RKR) 和 drift-kick-drift-exact (DKD-exact) 两种主体模型，默认 rot-kick-rot
支持 uniform (2阶) 和 yoshida4 (4阶) 两种辛积分器
支持非线性边缘角 (wedge) 效应
支持非线性边缘场 (fringe field) 效应
支持孔径检查
以下接口中的字段用于 PASS.para.schema.elements.SBendItem 配置类；
元件名称由 Sequence.add(name, item) 的序列键给出，不是配置类字段。
参数列表
通用参数
Python 配置字段 |
JSON 键 |
类型 |
单位 |
默认值 |
说明 |
|---|---|---|---|---|---|
|
|
|
m |
|
元件出口或零长度作用点的纵向位置。 |
|
|
|
m |
|
元件长度（ \(L\) ） |
|
|
|
|
归一化二极场积分（ \(K_{0L}\) ） |
|
|
|
|
rad |
|
入口边缘角（ \(e_1\) ），默认 0 |
|
|
|
rad |
|
出口边缘角（ \(e_2\) ），默认 0 |
|
|
|
m |
|
磁铁半气隙（ \(g_{\text{half}}\) ），默认 0 |
|
|
|
|
入口边缘场积分（ \(F\) ），默认 0 |
|
|
|
|
|
出口边缘场积分，默认 0（ \(\leq 0\) 时自动设为 |
|
|
|
|
1 |
|
切片数，默认 1 |
|
|
|
|
物理模型，可选： |
|
|
|
|
|
积分器，可选： |
|
|
|
|
— |
|
孔径类型，默认 |
|
|
|
m / rad |
|
孔径参数值，默认 |
绝对正、斜多极场误差与静态 DX/DY/DPSI 准直误差使用公共 元件误差 接口。 准直只移动磁场，孔径和 SC 边界保持在设计坐标系。
扩展参数（预留）
Python 配置字段 |
JSON 键 |
类型 |
单位 |
默认值 |
说明 |
|---|---|---|---|---|---|
|
|
|
|
预留配置字段；当前跟踪不执行磁场时间表。 |
|
|
|
|
|
预留配置字段；当前跟踪不执行磁场时间表。 |
使用示例
扇形弯铁
{
"BEND1": {
"S (m)": 10.0,
"Command": "SBend",
"Length (m)": 1.5,
"K0L": 0.05,
"Num slices": 5,
"Integrator": "yoshida4",
"Aperture type": "off"
}
}
扇形弯铁，端面垂直于参考轨道，无边缘效应。
矩形弯铁
{
"BEND2": {
"S (m)": 20.0,
"Command": "SBend",
"Length (m)": 2.0,
"K0L": 0.1,
"E1 (rad)": 0.05,
"E2 (rad)": 0.05,
"Hgap (m)": 0.02,
"Fint": 0.5,
"Num slices": 10,
"Integrator": "yoshida4",
"Aperture type": "off"
}
}
矩形弯铁，含边缘角和边缘场效应。弯转角 \(\alpha = K_{0L} = 0.1\) rad，边缘角 \(e_1 = e_2 = \alpha/2 = 0.05\) rad。
薄透镜弯转
{
"BEND3": {
"S (m)": 30.0,
"Command": "SBend",
"Length (m)": 0.0,
"K0L": 0.02,
"Aperture type": "off"
}
}
零长度弯转磁铁，仅施加 \(K_{0L}\) 薄透镜动量更新，无 body 跟踪，无边缘效应。
小角度数值稳定性
极坐标漂移包含水平曲率项 \(\rho(1-\cos\theta)\)。 CPU 和 GPU 统一使用半角恒等式 \(1-\cos\theta=2\sin^2(\theta/2)\)，无需按角度分支判断。 融合 GPU 内核将半角正弦与既有的全角正弦、余弦一起预计算，供各切片复用， 内部切片路径也采用同一公式。这样可避免小角度消去误差， 也无需除以 \(1+\cos\theta\)。粒子存储精度、积分设置和物理映射 保持不变。其他 FP32 舍入误差仍然存在，跟踪精度仍需通过精度和 切片收敛检查确认。
对于没有内部空间电荷节点的静态 rot-kick-rot 映射，FP32 粒子数组在 CPU 上使用 FP64 工作坐标，在融合 GPU 内核中使用 FP64 寄存器和标量参数。 内部旋转与二极场动量更新需要抵消参考弯转量；若每个子步都舍入到 FP32，可能掩盖很小的 横向振荡位移。完整元件映射结束后再写回原粒子存储精度，积分方法和物理映射保持不变。
对于没有内部空间电荷节点的静磁弯铁，CPU 和 GPU 将纵向增量与入口坐标分开累加， 在出口一次执行 \(z_{\mathrm{out}}=z_{\mathrm{in}}+\sum_j\Delta z_j\)。 这样可避免微小切片增量反复与较大的 FP32 \(z_{\mathrm{in}}\) 相加所产生的舍入损失。 这只是增量的累加方式，不是坐标折叠；保存的纵向坐标仍然连续。 增量累加器采用所选映射的工作精度，其中静态 RKR 使用 FP64。 内部空间电荷路径仍在每个节点提供实时纵向坐标。 元件边界的存储舍入及其他有限精度误差仍然存在。
极坐标漂移还将微小的速度修正与几何路程差分开计算。令 \(g=\gamma_0^{-2}\)、\(r=-g\delta(2+\delta)/(1+\delta)^2\)，则计算 \(\beta_0/\beta-1=r/(\sqrt{1+r}+1)\)。 粒子的实际路程为 \(\ell\) 时，CPU 和 GPU 均使用 \(\Delta z=(L-\ell)-\ell r/(\sqrt{1+r}+1)\)。 这样可避免先将接近一的速度比在 FP32 中舍入为一。
坐标约定
采用 纵向坐标与参考到达时间 的连续纵向坐标。 \(T_b\) 是理想参考粒子在当前位置的实际通过时刻，不是束团质心时刻； 局部映射中的 \(\beta_0\) 和 \(P_0\) 表示当前束团参考量。 \(p_x=P_x/P_0\) 是归一化动量，不是轨迹斜率。
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\) |
纵向坐标， \(z=\zeta=\beta_b c(T_b-t_i)\) |
|
\(\delta\) |
相对动量偏差， \(\delta = P / P_0 - 1\) |
其中 \(P_0\) 为参考粒子动量， \(\beta_0 = v_0 / c\) 为参考粒子归一化速度， \(s\) 为沿参考轨道的弧长， \(t\) 为时间。
纵向动量分量定义为：
其他常用物理量：
其中 \(h\) 为参考轨道曲率， \(\rho\) 为弯转半径， \(K_0\) 为归一化二极场强， \(\chi\) 为荷质比因子（同种粒子束 \(\chi = 1\) ）。对于扇形弯铁 \(h = K_0\) 。
整体跟踪流程
一个完整的弯转磁铁由 入口边缘 、 主体 和 出口边缘 三部分组成，跟踪顺序为：
====== 入口边缘 (B=0 → B=B0) ======
YRotation(-e1) → Fringe Field → Wedge(-e1, K0)
[纯几何旋转] [非线性边缘场] [旋转+聚焦动量更新]
[B=0] [B: 0→B0] [B=B0]
↓
====== 主体 Body (B=B0) ======
切片1 → 切片2 → ... → 切片N
(参考轨迹坐标系, 辛积分器)
↓
====== 出口边缘 (B=B0 → B=0) ======
Wedge(-e2, K0) → Fringe Field → YRotation(-e2)
[旋转+聚焦动量更新] [非线性边缘场] [纯几何旋转]
[B=B0] [B: B0→0] [B=0]
入口净旋转: (-e1) + (+e1) = 0
出口净旋转: (+e2) + (-e2) = 0
→ Body 在参考轨迹坐标系中运行
完整映射为：
本体内部划分为 \(N\) 个切片时，上式展开为：
即 一个真实入口、N 个本体切片、一个真实出口。CPU 和 GPU 跟踪都在
本体循环之外施加入出口映射。内部空间电荷动量更新也只分割本体传输，不产生额外的
边缘映射。因此，增大 Num slices 不需要额外的出口积分参数。
将一块磁铁表示为多个独立 SBend 元件是另一种操作：每个元件都会执行
自己的入口和出口映射。
入口边缘 ：
出口边缘 （与入口镜像对称）：
Note
当 \(e_1 = 0\) 时，YRotation 和 Wedge 均跳过（无边缘角效应）
当
fint= 0 或hgap= 0 时，有限间隙项消失；只要 \(K_0 \ne 0\)，仍执行几何非线性边缘映射。当 \(K_0 = 0\) 时，Fringe 和 Wedge 均跳过
入口和出口的执行顺序互为镜像
出口处，边缘场由上升变为下降，因此 Fringe 使用 \(-K_0\)；Wedge 仍在同一均匀磁场中旋转，保留 \(K_0\)。
为什么是这个顺序
YRotation 的作用 ：纯几何坐标旋转，将粒子坐标从参考轨迹坐标系变换到磁铁端面坐标系。不施加任何力，仅改变观察参考系。
Fringe Field 的作用 ：在端面参考系中计算非线性边缘场效应。Fringe 公式中的粒子斜率 \(x' = p_x / p_z\) 必须是相对于磁铁端面的斜率，因此必须先做 YRotation。
Wedge 的作用 ：在均匀磁场 \(B_0\) 中旋转观测平面，同时施加边缘角聚焦动量更新。Wedge 包含几何旋转（将坐标系转回参考轨迹系）和磁场动量更新两部分。
YRotation 和 Wedge 的几何旋转方向相反，净旋转为零：
因此 body 在参考轨迹坐标系中运行，不需要任何额外旋转。
主体：DKD-exact 模型
哈密顿量
在曲线坐标系中，弯转磁铁的完整哈密顿量为：
将其拆分为传播部分（精确直漂移 \(H_D\) ）和动量更新部分（ \(H_h\) , \(H_{K_0}\) , \(H_{K_0 h}\) ）：
其中 \(H_D\) 是精确直漂移哈密顿量（保留 \(p_z\) 的根号，不做小动量展开），后三项是薄透镜动量更新。
精确漂移映射 D
传播部分的哈密顿方程给出精确直漂移：
其中 \(L_D\) 为漂移长度， \(\beta\) 为粒子实际归一化速度：
Note
“exact” 的含义：漂移部分保留精确根号 \(p_z = \sqrt{(1+\delta)^2 - p_x^2 - p_y^2}\) ，不做 \(p_x \ll 1\) 的小动量展开。近似仅在于将传播部分与动量更新部分分离（分裂算符法）。
二极动量更新映射 K
动量更新部分合并为单个薄透镜 动量更新（位置不变，仅动量跳变）：
各项物理含义：
项 |
来源 |
物理含义 |
|---|---|---|
\(h(1+\delta) L_K\) |
\(H_h\) |
曲率动量更新（参考轨道弯转） |
\(-\chi K_0 L_K\) |
\(H_{K_0}\) |
主二极弯转 |
\(-\chi K_0 h x L_K\) |
\(H_{K_0 h}\) |
弱聚焦（曲率与二极场耦合） |
\(-(\beta_0/\beta) \cdot h x L_K\) |
\(H_h\) |
路径长度效应（纵向） |
Note
对于扇形弯铁 \(h = K_0\) ，参考粒子（ \(x=0, \delta=0, \chi=1\) ）的净动量更新为 \(h L_K - K_0 L_K = 0\) 。这是正确的：在曲线坐标系中，参考粒子沿参考轨道运动， \(p_x\) 始终为 0。弯转效应已编码在曲线坐标系本身中。
uniform 积分器（2阶辛）
每个切片采用漂移-动量更新-漂移（DKD）结构，即二阶蛙跳（leapfrog）：
每个切片误差为 \(O(\Delta s^3)\) ，全局误差为 \(O(\Delta s^2)\) 。二阶辛积分器，每步都是正则变换。
yoshida4 积分器（4阶辛）
通过组合三个二阶 DKD 步构造四阶辛映射 [Yoshida 1990]：
其中 Yoshida 系数为：
Note
\(z_0 < 0\) 意味着中间一步是反向跟踪（漂移和动量更新的 “长度” 为负）。这是 Yoshida 组合方法的数学要求，在辛映射群中完全自洽。每个切片误差为 \(O(\Delta s^5)\) ，全局误差为 \(O(\Delta s^4)\) 。
积分器选择建议：
场景 |
推荐积分器 |
原因 |
|---|---|---|
快速模拟 |
uniform |
每切片 2 次漂移 + 1 次动量更新，计算量小 |
高精度模拟 |
yoshida4 |
4 阶精度，但每切片 6 次漂移 + 3 次动量更新 |
含空间电荷 |
uniform + 更多切片 |
空间电荷作用次数由 |
主体模型选择
model 可选 rot-kick-rot、drift-kick-drift-exact 或 adaptive；
adaptive 当前选择 rot-kick-rot。
RKR：极坐标输运包含参考轨道曲率，配合偶极场的动量更新。
DKD-exact：将直线精确漂移与曲率、磁场的动量更新分裂组合。
两种模型的子映射与分裂方式不同。应针对偏转角、束流振幅、动量范围及目标观测量，
增加切片数并检查轨迹、工作点和纵向输运是否收敛；不能由单个子映射的解析精确性
推断一个切片适合所有参数。integrator="adaptive" 当前采用 uniform，
不是自动误差控制。四阶积分在光滑外场中的优势不消除浮点舍入和孔径取样误差。
内部空间电荷次数由独立的 Space charge.Num kicks 决定。
入口边缘：YRotation
物理目的
YRotation 是纯几何坐标旋转，不涉及任何磁场。其目的是将粒子坐标从参考轨迹坐标系变换到磁铁端面坐标系，使后续的边缘场计算能在正确的参考系中进行。
当磁铁端面与参考轨迹法线有夹角 \(e_1\) 时，粒子相对于端面的入射斜率不等于 \(p_x / p_z\) 。YRotation 将坐标系旋转 \(-e_1\) ，使得旋转后的 \(p_x / p_z\) 成为相对于端面的斜率。
完整推导
YRotation(-e1) Wedge(-e1, K0)
───────────────── ──────────────────
坐标系: 轨迹系 → 端面系 坐标系: 端面系 → 轨迹系
磁场: B = 0 (无场区) 磁场: B = B0 (有场区)
旋转: -e1 旋转: +e1 (与 YRotation 反向)
动量更新: 无 动量更新: Δpx = K0·x·sin(e1) (聚焦)
───────────────── ──────────────────
净旋转: (-e1) + (+e1) = 0
净效果: 边缘场效应 + 聚焦动量更新
第一步：动量旋转
参考系绕 \(y\) 轴旋转角度 \(\theta\) 。这个旋转在三维空间的 \((x, z)\) 平面内进行， \(y\) 方向不受影响。因此被混合的是动量的 \(x\) 分量 \(p_x\) 和 \(z\) 分量 \(p_z\) ，而 \(p_y\) 不变。动量的标准旋转变换为：
因此：
这是纯动量旋转，不涉及力。
第二步：位置投影
关键在于曲线坐标系中 \(x\) 的定义： x 是在参考位置 \(s\) 处的横向平面上测量的横向偏移 。当参考系旋转 \(\theta\) 后，”横向平面” 的方向变了，同一物理位置在新坐标系中的 \(x'\) 值不同。
粒子在旧参考系中的轨迹为 \(\vec{r}(\lambda) = (x + \lambda p_x/p_z,\; 0,\; \lambda)\) 。新参考系的 \(z'\) 轴方向为 \(\hat{z}' = (\sin\theta, 0, \cos\theta)\) ，横向方向为 \(\hat{x}' = (\cos\theta, 0, -\sin\theta)\) 。
在新参考系中，纵向位置为零意味着：
解出 \(\lambda\) ：
新横向位置为：
代入 \(\lambda\) 并化简，利用旋转的正交性 \(p_z'\cos\theta - p_x'\sin\theta = p_z\) ，最终得到：
等价实现形式 ：
实现中写作 x_hat = x / (cos_angle * ptt) ，其中 ptt = 1 + tan_angle * px / pz ：
因此 \(x' = x / (\cos\theta \cdot p_{tt}) = x \cdot p_z / p_z'\) ，与推导一致。
第三步： y 方向
\(y\) 方向不直接参与旋转，但由于横向平面倾斜，粒子在走到新横向平面期间， \(y\) 方向因轨迹斜率产生额外偏移：
第四步： \(\zeta\) 方向
纵向坐标 \(z=\zeta=\beta_b c(T_b-t_i)\) 。旋转参考系后， \(\sin\theta \cdot x\) 是横向位置在新纵向方向上的投影（因参考系旋转导致的额外路径长度），需转换为时间增量：
其中 \(\text{time\_fac} = 1/\beta_0 + p_\tau\) 是时间-路径转换因子（见变量转换说明）。
最终公式
定义：
其中 \(\theta\) 为旋转角度（入口 \(\theta = -e_1\) ，出口 \(\theta = -e_2\) ）。
时间因子：
六维映射：
变量转换说明
归一化能量偏差 \(p_\tau\) 与存储的归一化动量偏差 \(\delta\) 满足：
因此：
推导 ：粒子总能量 \(E = E_0(1 + p_\tau)\) ，由 \(E^2 - E_0^2 = (Pc)^2 - (P_0 c)^2\) 得：
展开并利用 \(1 - 1/\gamma_0^2 = \beta_0^2\) ：
用能量偏差表示时，\(p_z\) 的表达式为 sqrt(1 + 2*pt/beta0 + pt*pt - px*px - py*py) ，代入上述关系后恰好等于 \(\sqrt{(1+\delta)^2 - p_x^2 - p_y^2}\) 。
入口边缘：边缘场（Fringe Field）
物理目的
真实磁铁的磁场在端面处不是阶跃函数，而是有一个渐变区域。这个渐变区域产生额外的非线性效应，主要是垂直方向的聚焦。
物理推导
B_y B_y = B0
↑ ┌──────────────
│ /
│ Fringe / end face
│ Field /
│ (B: 0→B0) /
│ /
│ B = 0 /
└────────────┬────────┘──────────────────────── → s
↑ ↑
YRotation Fringe Wedge / Body
(B=0) (0→B0) (B=B0)
hgap = 半气隙
Δp_y = 垂直聚焦动量更新
边缘场分布
真实磁铁端面处的磁场渐变为：
其中 \(b(s)\) 是归一化边缘场分布函数。这个渐变场对粒子产生非线性效应，主要是垂直方向的聚焦。
边缘场积分
Forest 定义边缘场积分：
其中 \(g_{\text{full}}\) 为磁铁全气隙（ \(g_{\text{full}} = 2 \times \text{hgap}\) ）。 \(F\) 描述边缘场的”强度”： \(F=0\) 对应硬边缘， \(F\) 越大边缘场效应越强。
Warning
hgap 与 g 的命名关系
hgap 参数是磁铁的 半气隙 （half gap），即上下极板间距的一半。
hgap= 半气隙 = \(g_{\text{half}}\)磁铁全气隙 \(g_{\text{full}} = 2 \times \text{hgap}\)
在边缘场代码中，辅助量 \(f_h\) 直接使用 hgap （半气隙）：
因此 \(f_h\) 是半气隙与边缘场积分的乘积。
使用全气隙定义的公式需要相应转换系数。PASS 在下面的生成函数中使用半气隙约定。
边缘场角与特征系数
边缘场映射使用下面的角度 \(\Phi_0\) 和特征系数 \(\psi=b_0\tan\Phi_0\)，其中 \(b_0=K_0\chi\)：
其中 \(x' = p_x/p_z\) , \(y' = p_y/p_z\) 是粒子斜率， \(c_2 = 2 K_0 \chi \cdot f_h\) 是线性边缘场强度参数。
代码中 yp2 = 1 + y'^2，所以 1 + yp2 = 2 + y'^2。
因此有限气隙因子为 \(1+x'^2(2+y'^2)\)。反正切项的分母仍为 \(1+y'^2\)；
这里使用的是 yp2 本身。
Note
有限气隙项使用 \(p_z\)，而非其倒数；偏导数也采用相同生成函数。
将 fint*hgap 设为零会去掉该项，因此不能据此验证有限气隙效应。
第一项 \(\arctan(x'/(1+y'^2))\) ：粒子在端面处的入射角修正。 \(x'\) 是水平斜率， \(1+y'^2\) 反映垂直运动对水平入射角的几何修正（三维方向余弦）。
第二项 \(-c_2(1 + x'^2(2+y'^2))p_z\) ：边缘场积分效应。 \(c_2\) 是边缘场强度， \((1 + x'^2(2+y'^2))\) 是斜率的高阶修正。
偏导数与力
先对 \(\psi=b_0\tan\Phi_0\) 关于独立变量 \((x', y', p_z)\) 求偏导，再用链式法则得到力的分量。对正切函数求导产生 \(b_0/\cos^2\Phi_0\) 因子；下面的量是 \(\psi\) 的偏导数。
引入中间变量 \(c_{o2} = b_0 / \cos^2\Phi_0\) , \(c_{o1}\), \(c_{o3}\) （详见公式部分），偏导数为：
力的分量（链式法则 \(k_i = \phi_1 \partial x'/\partial p_i + \phi_2 \partial y'/\partial p_i + \phi_3 \partial p_z/\partial p_i\) ）：
其中 \(\text{tfac} = -(1/\beta_0 + p_\tau)\) 来自 \(z=\zeta=\beta_b c(T_b-t_i)\) 中 \(t\) 对 \(p_z\) 的依赖。
隐式方程
边缘场映射不是简单的 动量更新（位置不变、动量跳变），而是一个 隐式映射 。原因是边缘场效应与粒子的 \(y\) 坐标非线性耦合：粒子在穿过边缘场时， \(y\) 坐标本身也在变化，因此力（依赖 \(y\) ）和位移（依赖力）相互耦合。
隐式解来自生成函数展开到二阶：
这个形式保证了正则性（保辛）：当 \(k_y y\) 很小时， \(y_f \approx y + k_y y^2/2\) ，即二阶展开。
参数
参数 |
符号 |
说明 |
|---|---|---|
|
\(F\) |
边缘场积分（fringe field integral）， \(F=0\) 为硬边缘 |
|
\(g_{\text{half}}\) |
磁铁 半气隙 （half gap），全气隙 \(g_{\text{full}} = 2 \cdot \text{hgap}\) |
|
\(K_0\) |
归一化二极场强 |
完整公式
定义辅助量：
其中 \(c_2\) 是线性边缘场强度， \(c_3\) 是六阶非线性修正（来自 \(f_{\text{sad}} = 1/(72 f_h)\) ，称为 “sixth-order achromatic detuning” 项）。
粒子斜率：
特征函数及偏导数：
这里 \(\phi_0=\Phi_0\)，而 \(\phi_1,\phi_2,\phi_3\) 分别是 \(\psi=b_0\tan\phi_0\) 关于 \(x',y',p_z\) 的偏导数。
力的分量：
六维映射：
Note
\(p_x\) 和 \(\delta\) 不变：边缘场是静磁场，不做功
\(p_y\) 的变化中的 \(-b_0 \tan(\phi_0) y_f\) 项是主要的垂直聚焦
\(-4 c_3 y_f^3\) 是六阶非线性修正
\(y_f\) 通过隐式方程求解，保证了非线性效应的精确处理和保辛性
\(x\) 的变化是 \(O(y^2)\) 量级的水平-垂直耦合
入口边缘：Wedge（边缘角）
物理目的
Wedge 描述粒子在均匀磁场 \(B_0\) 中穿过倾斜端面时的坐标变换。它同时完成两件事：
几何旋转 ：将坐标系从端面参考系转回参考轨迹参考系（与 YRotation 的旋转方向相反，互相抵消）
磁场动量更新 ：施加边缘角聚焦效应 \(\Delta p_x \propto -x\)
当 \(K_0 = 0\) （无磁场）时，Wedge 退化为纯 YRotation（证明见下文）。
计算公式
参数： \(\theta\) （楔形角度，入口 \(\theta = -e_1\) ）， \(K_0\) ， \(\chi\)
定义：
其中 \(\beta\) 为粒子实际归一化速度（见漂移映射中的公式）。
六维映射：
最终更新：
动量更新项的物理含义
将 \(p_x'\) 的公式展开：
几何旋转部分 ： \(p_x \cos\theta + p_z \sin\theta\) ，与 YRotation 的 \(\cos\theta \cdot p_x - \sin\theta \cdot p_z\) 方向相反，互相抵消
磁场动量更新部分 ： \(-b_1 x \sin\theta = -K_0 \chi x \sin\theta\) ，正比于 \(-x\) ，即边缘角聚焦
对于入口（ \(\theta = -e_1\) ），动量更新为：
这使轨道外侧（ \(x > 0\) ）的粒子获得向内的动量，即聚焦效应。等效焦距为 \(f = \rho / \sin(e_1)\) 。
Delta-ell 与 zeta 的关系
公式 Eq. 1.201 给出的是 路径长度 \(\Delta\ell\) ，而代码更新的是 纵向坐标 \(\zeta\) 。两者不同：
物理原因 ：
\(\Delta\ell\) 是粒子在 wedge 中走过的路径长度
\(z=\zeta=\beta_b c(T_b-t_i)\) ，更新 \(\zeta\) 需要时间： \(\Delta t = \Delta\ell / v = \Delta\ell / (\text{rvv} \cdot \beta_0 c)\)
\(\Delta s\) 已在 \(x'\) 和 \(\Delta y\) 的几何变换中处理了，所以 \(\zeta\) 只需要 时间修正 部分：
负号 ： \(z=\zeta=\beta_b c(T_b-t_i)\) ，时间增加导致 \(\zeta\) 减小
除以 rvv ： \(\text{rvv} = v/v_0 = \beta/\beta_0\) ，将路径长度转换为时间时需要除以粒子实际速度
Warning
不要将 \(\Delta\ell\) 直接加到 \(\zeta\) 上。 \(\Delta\ell\) 是路径长度， \(\zeta\) 是时间相关坐标，两者通过 \(-\Delta\ell/\text{rvv}\) 联系。
arcsin 的 clip 处理
Wedge 中 \(D\) 的计算用到 \(\arcsin\) ：
其中 \(A = 1/\sqrt{(1+\delta)^2 - p_y^2}\) 。理论上 \(|A \cdot p_x| \leq 1\) （因为 \(|p_x| \leq \sqrt{(1+\delta)^2 - p_y^2}\) ），但 浮点误差 可能导致 \(A \cdot p_x = 1.0000000001\) ，此时 Python 的 np.arcsin 返回 NaN 并触发 RuntimeWarning。
代码中使用 np.clip 将参数限制在 \([-1, 1]\) 范围内：
arg_px = np.clip(arg_px, -1.0, 1.0)
arg_new_px = np.clip(arg_new_px, -1.0, 1.0)
裁剪用于避免边界附近的浮点舍入使反正弦参数超出定义域。
K0=0 时 Wedge 退化为 YRotation 的证明
Wedge 的 \(p_x'\) 公式 ：
令 \(b_1 = K_0 \chi \to 0\) ：
YRotation 的 \(p_x'\) 公式为 \(p_x' = \cos\alpha \cdot p_x - \sin\alpha \cdot p_z\) 。令 \(\alpha = -\theta\) ：
动量公式一致。
位置 \(x'\) ：
令 \(b_1 = 0\) ， Wedge 的 \(x'\) 化简为：
利用旋转正交性 \(p_z' = p_x \sin\theta + p_z \cos\theta\) ，分母变为 \(2 p_z \cos\theta\) ，最终得到：
与 YRotation 的位置公式一致。
y 和 \(\zeta\) ：
当 \(b_1 \to 0\) 时， \(D \to 0\) ， \(\theta + D \to \theta\) ，所以 \(\Delta y = p_y \theta / b_1 \to \infty\) 。
这意味着 \(y\) 和 \(\zeta\) 的公式在 \(b_1 \to 0\) 时发散。因此 Wedge 的 \(b_1 = 0\) 极限不是连续的——当 \(|b_1| < \epsilon\) 时，代码直接跳转到 YRotation 分支：
if abs(b1) < const.eps:
# 直接调用 YRotation，跳过含 1/b1 的计算
self._y_rotation_cpu(x, px, y, py, z, dp, tag, mask, theta, beta0)
return
Note
Wedge 在 \(b_1 = 0\) 时通过 代码分支结构 退化为 YRotation。动量和位置的公式在 \(b_1 \to 0\) 极限下一致，但 \(y\) 和 \(\zeta\) 含有 \(1/b_1\) 因子，极限不连续，必须用分支处理。
边缘角正负号定义
e1 > 0 (聚焦):
端面法线
↗ e1
轨迹法线 ↑ ↗
| ╱ 端面
| ╱
──────────┼──╱──────────→ s (参考轨迹)
| ╱
|╱
端面法线相对于轨迹法线向弯转外侧倾斜
e1 < 0 (散焦):
|╲
| ╲
──────────┼──╲──────────→ s (参考轨迹)
| ╲ 端面
| ╲
轨迹法线 ↓ ╲ e1
╲ 端面法线
端面法线相对于轨迹法线向弯转内侧倾斜
边缘角 \(e_1\) , \(e_2\) 的正负号采用 MAD-X 约定：
\(e_1 > 0\) ：入口端面法线相对于参考轨迹法线向弯转外侧倾斜
\(e_2 > 0\) ：出口端面法线相对于参考轨迹法线向弯转外侧倾斜
常见磁铁类型：
磁铁类型 |
\(e_1\) |
\(e_2\) |
说明 |
|---|---|---|---|
扇形弯铁 |
0 |
0 |
端面垂直于参考轨迹 |
矩形弯铁 |
\(\alpha/2\) |
\(\alpha/2\) |
\(\alpha\) 为弯转角 |
通用 |
任意 |
任意 |
用户指定 |
参考文献
Xsuite Physics Guide, Sec 1.10.3 (精确弯铁), Sec 1.10.9 (边缘场), Sec 1.10.10 (楔形), Sec 1.10.12 (四极楔形修正)
Forest, E. et al., “Edge Focusing Effects in Sector Bending Magnets”
Yoshida, H., “Construction of higher order symplectic integrators”, Phys. Lett. A 150 (1990)
MAD-NG fringe field implementation: https://github.com/MethodicalAcceleratorDesign/MAD
元件内部空间电荷
正长度元件可设置 space_charge （JSON Space charge）为
ElementSpaceCharge 对象。Num slices 控制外场传输，
Space charge.Num kicks 控制 SC 积分。调度规则、共享资源、
支持的后端和示例见 元件切片与内部空间电荷。