凸轨磁铁（Bump）

Bump 是固定机器坐标中的双平面脉冲偏转磁铁。所有经过它的存活粒子均受力。 入射坐标与磁场动量更新使用同一套固定机器坐标。Injection 偏置指定注入面处的入射束， 其在横向涂抹中的作用见 多圈注入与横向涂抹。 该理想模型用于固定能量的注入涂抹，动量增量相对注入参考动量归一化。 本模型不包含加速时的强度换算、磁铁边缘场、极面聚焦和场误差。

接口字段属于 PASS.para.schema.elements.BumpItem。元件出口位置由 s 指定； 名称由序列键给出。标准孔径字段为 aperture_type 和 aperture_value。

Python 配置字段

JSON 键

类型

单位

默认值

说明

waveform_file

Waveform file

str

—

必填

TIME、HKICK、VKICK 三列实数；至少两行、数值有限、时间严格递增。

time_mode

Time mode

reference / particle

—

'particle'

particle 使用实验室到达时间，reference 使用逐圈参考时钟。

time_offset

Time offset (s)

float

s

0.0

加到取样时间上，所有批次共享全局原点。

length

Length (m)

float

m

0.0

零长度薄透镜动量更新，否则使用正向 DKD。

num_slices

Num slices

int

1

1

严格正整数，每片仅施加对应比例的积分动量增量。

enabled

Enable

bool

—

True

控制磁场作用；关闭时仍执行漂移与孔径检查。

space_charge

Space charge

ElementSpaceCharge | None

—

None

正长度支持已有内部空间电荷中点作用方案。

强度是无量纲积分动量增量:

Kx = Delta Px / P0; Ky = Delta Py / P0
px += Kx; py += Ky
每片：D(L/(2*N)) -> K(Kx/N, Ky/N) -> D(L/(2*N))

它们不是精确几何斜率，不再除以 (1+delta)。 逐粒子模式在每个作用中心通过局部参考粒子到达时间计算:

t = t0 - z/(beta0*c)

坐标保持连续。reference 模式按调用圈号求规定机器时钟的逆函数，不包含粒子 z 或局部飞行时间；particle 模式在实际局部作用中心事件采样。

这里 t0 是理想参考粒子的实际通过时间，z = beta0*c*(t0-t)。 名义分组槽位位置不加到 z 上，也不保存独立的粒子或束团 到达修正。 Time offset (s) 加在最终波形查询时间上。薄 Bump 作用保持 t0、z 和总动量偏差 不变；厚元件按每段参考半漂移的飞行时间推进 t0。

传输与损失处理

正长度时，每片依次执行半漂移、横向动量更新和后半漂移。内部空间电荷作用于 等长纵向子区间的中点；根据外场切片数，作用点可能位于磁场作用中心（磁场动量更新之后）， 也可能位于片间边界，并使用该位置的粒子状态与参考时间。 没有生效的内部空间电荷时，每个束团每次通过元件仅在出口检查一次孔径。 有 \(K\) 个内部 SC 节点时，每个 SC 入口在计算源项前检查一次，出口再检查 一次，共 \(K+1\) 次。关闭磁场动量更新时仍保留这些检查。薄 Bump 在元件所在位置 检查，其余外场切片边界不增加检查。两个检查位置之间越界后又返回孔径内的轨迹 不会被记录。刚损失的粒子不进入 SC 源项，也不接受其动量增量。每个节点仍对参与计算 的粒子执行 PIC 计算域有效性检查。 内部作用位置的安排见 空间电荷效应（SpaceCharge）。

正向传输要求纵向动量为正：

\[1+\delta>0,\qquad (1+\delta)^2-p_x^2-p_y^2>0.\]

在首次动量更新之前（包括薄 Bump），以及磁场动量更新之后、内部空间电荷计算或后续漂移之前， 检查这些条件。不满足条件的粒子被标记为损失并停止运动，后续反向动量更新不能使其恢复。 这些动量有效性检查独立于 SC 节点和出口处的孔径检查。CPU 与 GPU 使用相同的传输和 观察顺序。粒子坐标支持 float32/float64，波形时间与插值使用 float64。

波形边界

采用包含端点的线性插值。早于某一平面首个已提供时间时，保持该平面的首值； 晚于最后时间时，保持其末值。存活粒子发生越界查询时，每个元件在其生命周期内 警告一次，警告中列出两平面各自的已提供时间范围。尚未注入和此前已损失的粒子 不触发该警告。

允许提供负时间数据；注入前磁场有变化时，应写入相应时间段。 如果首个时间为零，更早到达的粒子将使用零时刻的值并触发警告。 正常退坡应明确以零结束；若末值非零，表结束后仍持续施加该末值。

convert_cisp_bump 的水平和垂直 CSV 可以有不同的行数、时间节点和时间范围， 也允许时间范围完全不重叠。转换使用两者全部时间节点的并集，各平面在自己的 已提供范围外独立保持端点值，不截断较长波形。生成的 TFS 仍使用 TIME、HKICK 和 VKICK 三列。 转换和读取保留 float64 精度，包括相邻但不同的时间节点。 三列必须为实数数值列；复数、布尔值及字符串列会被拒绝，不会转换成实数动量增量。

可选的成对 TFS 头 HKICK_START/HKICK_END 和 VKICK_START/VKICK_END 以秒记录各平面原始的已提供区间。 这样，即使查询位于合并表的时间范围内，也能对超出某一平面原始范围的情况警告。 各区间的起止时间必须对应 TIME 节点，且相应列在该区间外必须保持端点值。 没有这些头时，两平面均使用整张表的时间范围。

可选 TFS 头为 TIME_UNIT=”s” 和 KICK_CONVENTION=”delta_p_over_p0”， 冲突值会被拒绝。