注入与粒子生成（Injection）
本模块介绍 PASS 中的注入命令 Injection ，用于在模拟起始位置生成特定粒子分布并注入束流。注入命令支持为每个束团独立设置横向分布、纵向分布、束流参数、偏移等，是粒子模拟的入口环节。
Injection 支持单圈和多圈注入。入射分布、注入时序及横向偏置决定各批粒子进入 环内的状态；随时间变化的 Bump 磁铁可进一步改变粒子在环内的横向运动。
可直接执行的输入生成及跟踪流程见 最小示例，坐标约定见下文 纵向坐标与参考到达时间。
接口参数
下表列出公开的 Python 配置字段、JSON 键及默认值。注入命令在序列中的键必须为 injection，运行时命令名称由该键给定。束团字典由 InjectionItem.bunches 生成。
Python 字段 |
JSON 键 |
类型 |
默认值 |
说明／单位 |
|---|---|---|---|---|
|
|
|
|
注入位置，单位 m；必须为 0。 |
|
|
|
|
保持 Injection。 |
|
|
|
|
正整数束团分组数，必须等于束团配置数。 |
|
|
|
|
整数或 None；None 使用非确定性种子。复现还要求输入及执行顺序相同。 |
|
|
|
|
每组一个 BunchConfig；空分组的真实粒子数与宏粒子数均设为零。 |
束团参数
每个束团以 bunch0 、 bunch1 、 … 为键，值为包含该束团全部参数的字典。参数按横向、纵向、束流、分布、偏移五组分类说明如下。
对于质量数 \(A=Z+N>1\) 的离子，参考粒子的每核子静能采用
\(m_0=M_{\mathrm{ion}}c^2/A\)，由随包质量数据库的
ion_mass(A, Z, q) 给出。数据库从中性原子质量中扣除已剥离电子的质量，
再加上累计电离能，不再将每个核子的质量统一近似为一个原子质量单位。
电子／正电子及单质子跟踪保留既有常量。
跟踪、分布生成、GUI 能量／动量偏移换算、自动设计时钟和输入校验共享这套质量。 动能和动量仍按每核子表示；内部保存的电荷数与质量数之比的大小为 \(|q|/A\)， RF 另行计入电荷符号，因此物理能量增量采用带符号的系数 \(q/A\)。 数据库不支持的粒子或电荷态会明确报错。改变质量会改变参考速度、磁刚度及派生的设计时钟； 显式提供的 RF 频率表属于物理波形输入，不会自动重新标定。
横向参数
Python 字段 |
JSON 键 |
类型 |
单位 |
默认值 |
说明 |
|---|---|---|---|---|---|
|
|
float |
|
水平 Twiss 参数 \(\alpha_x\) |
|
|
|
float |
|
垂直 Twiss 参数 \(\alpha_y\) |
|
|
|
float |
m |
|
水平 Twiss 参数 \(\beta_x\) |
|
|
float |
m |
|
垂直 Twiss 参数 \(\beta_y\) |
|
|
float |
m·rad |
|
水平 RMS 几何发射度 \(\varepsilon_x\) |
|
|
float |
m·rad |
|
垂直 RMS 几何发射度 \(\varepsilon_y\) |
|
|
float |
m |
|
水平色散函数 \(D_x\) |
|
|
float |
|
水平色散导数 \(D_{px}\) |
|
|
|
str |
|
横向分布类型，可选： |
纵向参数
Python 字段 |
JSON 键 |
类型 |
单位 |
默认值 |
说明 |
|---|---|---|---|---|---|
|
|
float |
m |
|
纵向 RMS 尺度；coasting 模式中表示均匀区间全宽 \(\sigma_z\) |
|
|
float |
|
动量展宽 RMS 值 \(\sigma_{\delta}\) |
|
|
|
str |
|
纵向分布类型，可选： |
|
|
|
float |
V |
|
有符号的物理射频电压（ |
|
|
float |
rad |
|
匹配参考事件处的物理波形相位 \(\phi_s\)，见 匹配计算中的射频相位和电荷符号 |
|
|
int |
|
束团分组编号 \(h_{\mathrm{id}}\) ，决定名义分组位置 \(z_{\mathrm{center}}=h_{\mathrm{id}}C/h_{\mathrm{group}}\) |
|
|
|
float |
m |
|
射频腔相对于注入点的纵向位置，用于将 s_rf 处生成的分布逆向传播到 s=0 注入点 |
|
|
float |
|
束团级平均动量偏差 \(\delta_0\) ，叠加到每个粒子的 dp 上。与 |
|
|
|
float |
eV |
|
束团级动能偏差，内部转化为 |
束流参数
Python 字段 |
JSON 键 |
类型 |
单位 |
默认值 |
说明 |
|---|---|---|---|---|---|
|
|
float |
eV/u |
|
每核子动能 |
|
|
int |
|
该束团全部注入事件计划注入的真实粒子总数 |
|
|
|
int |
|
该束团全部注入事件计划注入的宏粒子总数 |
|
|
|
int |
|
从第 0 圈计数、不含端点的停止圈数；正整数，默认 1 |
|
|
|
int |
|
注入间隔，每 |
分布参数
Python 字段 |
JSON 键 |
类型 |
单位 |
默认值 |
说明 |
|---|---|---|---|---|---|
|
|
bool |
— |
|
是否从文件加载粒子分布 |
|
|
str |
— |
|
分布文件路径（ |
|
|
str |
— |
|
|
|
|
bool |
— |
|
是否保存初始分布 |
|
|
list |
— |
|
在偏置施加后替换首批的前若干行，格式为 |
|
|
str 或 null |
— |
|
含 |
|
|
object 或 null |
— |
|
为每个初始 dp 生成完整的 x/y 笛卡尔网格，在偏置施加后替换首批坐标 |
偏移参数
水平偏移 （ Offset x ）和垂直偏移 （ Offset y ）结构相同，各包含以下子参数：
Python 字段 |
JSON 键 |
类型 |
单位 |
默认值 |
说明 |
|---|---|---|---|---|---|
|
|
bool |
— |
|
是否启用偏移 |
|
|
bool |
— |
|
是否从文件加载偏移数据 |
|
|
str |
— |
|
偏移数据文件路径 （ |
|
|
str |
— |
|
历史兼容字段，保存时保留原值。偏移表的 |
|
|
float |
— |
|
位置偏移量 |
|
|
float |
— |
|
动量偏移量 |
其他束团参数
Python 字段 |
JSON 键 |
类型 |
默认值 |
说明／单位 |
|---|---|---|---|---|
|
|
|
|
初始注入参考到达时间，单位 s；None 时由自动设计时钟确定。 |
|
|
|
|
初始分布表格式：hdf5-gzip1、hdf5 或 tfs。 |
|
|
|
|
水平 OffsetConfig，字段见上表。 |
|
|
|
|
垂直 OffsetConfig，字段见上表。 |
表中默认值是配置默认值，不代表完整物理输入。高斯分布生成需要显式给出正的发射度。harmonic_number 属于 InjectionItem，也用于匹配分布初始化，不能作为 BunchConfig 字段填写。
输入文件
{
"Beam Name": "proton",
"Number of Protons": 1,
"Number of Neutrons": 0,
"Number of Charges": 1,
"Transition Gamma": 4.8,
"Number of turns": 5,
"Circumference (m)": 251.327,
"Backend (gpu/cpu)":"cpu",
"Number of GPU devices": 1,
"Device Id": [
0
],
"Output directory": "./output",
"Is plot figure": true,
"Sequence": {
"injection": {
"S (m)": 0.0,
"Command": "Injection",
"Harmonic Number": 1,
"bunch0": {
"Kinetic Energy per Nucleon (eV/u)": 45e6,
"Number of Real Particles": 100000000000,
"Number of Macro Particles": 100000,
"Is Load Distribution from File": false,
"Distribution File Path": "",
"Total Injection Turns": 1,
"Injection Interval": 1,
"Alpha x": -2.614303952,
"Alpha y": 1.57442348,
"Beta x (m)": 0.5,
"Beta y (m)": 0.5,
"RMS geometric emittance x (m'rad)": 0.00019999999999999998,
"RMS geometric emittance y (m'rad)": 9.999999999999999e-05,
"Dx (m)": 0.0,
"Dpx": 0.0,
"Sigma z (m)": 30,
"Sigma dp/p": 0.005,
"Transverse dist": "gaussian",
"Longitudinal dist": "matchz",
"RF Voltage (V)": 100e3,
"RF Phase (rad)": 0.5235987755982988,
"Harmonic ID of this bunch": 0,
"RF S Position Refer to Injection Point (m)": 0.0,
"Offset x": {
"Is Offset": false,
"Is Load From File": false,
"File Path": "",
"File Time Kind": "turn",
"Offset Position (m)": 0.0,
"Offset Momentum (rad)": 0.0
},
"Offset y": {
"Is Offset": false,
"Is Load From File": false,
"File Path": "",
"File Time Kind": "turn",
"Offset Position (m)": 0.0,
"Offset Momentum (rad)": 0.0
},
"Is Save Initial Distribution": true,
"Insert Particle Coordinate": [[0,0,0,0,0,0]]
}
},
"StatMonitor1":{
"S (m)": 0.0,
"Command": "StatMonitor"
}
}
}
纵向坐标与参考到达时间
在给定的格架位置，bunch.t0 是束团 b 理想参考粒子的实际通过时刻
\(T_b\)。连续存储的纵向坐标是以米表示的时间差：
z 为正表示早到。理想参考粒子不等于自动重新居中的束团质心，也不保证是稳定的
RF 同步粒子。不保存粒子级或束团级到达修正状态。六维粒子坐标保持配置的存储精度，
时间和 RF 中间量使用 float64。局部相位约化不回写 p.z。
参考变换
同一物理位置的纯参考变换保持到达时间和机械动量：
注入和重分组在各自实现中完成所需的坐标换算；PASS/core/bunch.py 更新参考能量参数。
零长度 RF 作用满足 \(T_b'=T_b\)，
因此 z 乘以新旧参考速度比。粒子还接受真实 RF 能量增量，这与纯归一化变换不同，
见 射频腔（RFCavity）。
输运按参考飞行时间推进参考事件。长度 L 的精确直线漂移满足 \(\Delta T_b=L/(\beta_b c)\)、\(\Delta t_i=LE_i/(cP_{s,i})\)。 其他传输映射保留各自声明的近似。四极磁铁的强度仍按参考动量归一化，具体映射见相应元件页。
固定宏粒子权重
同一束流的所有非空束团必须使用相同的宏粒子代表数，由初始输入中的 “真实粒子数 / 宏粒子数”确定；不同权重的输入会被拒绝。 这一固定值适用于所有预先安排的注入批次。注入只激活预留粒子，不按当前粒子数量、 损失数量或目标束团重新缩放权重。
排序和重分组保留这一标量权重，空束团也保持相同值，不分配逐粒子权重或
尾场电荷数组。取整后的诊断真实粒子数不用于反推权重。
Slicer、SpaceCharge 和 WakeField 使用相同且固定的 bunch.ratio，
仅 tag > 0 的粒子参与计算。注入和损失只改变存活粒子数，不改变其余粒子的权重。
参考动量变换精度
注入粒子的动量偏差按以下公式转换到循环束的参考系：
这一形式避免了两个接近 1 的数相减。CPU/GPU 共用的注入路径先以 FP64
计算变换，再按配置的粒子精度保存结果。参考动量相同时，输入 dp
原样保留，包括很小的 FP32 动量偏差。六维粒子数组仍统一采用配置指定的
FP32 或 FP64 类型。
多圈注入与横向涂抹
注入时序与粒子数量
每个束团独立设置注入时序。令 Total Injection Turns 为 \(T\)，
Injection Interval 为 \(\Delta n\)，则注入发生在
停止圈数本身不包含在注入事件内。Number of Macro Particles 是该束团计划
注入的宏粒子总数 \(N\)。每批分配 \(\lfloor N/N_{\mathrm{event}}\rfloor\)
个粒子，余数全部加入首批；分配数为零的事件不增加粒子。
模拟必须执行所有分配了粒子的事件，才能注入完整的粒子数量。对于启用了
Is Save Initial Distribution 的非空注入源，分布仍在最后一个计划事件
保存，即使该事件不增加粒子。全部粒子注入完毕且所有请求的保存成功后，
后续 Injection 调用立即返回，不再搜索注入时间表或记录额外圈号。
预留粒子的 tag=0，不参与跟踪、电荷沉积和统计，也不计为损失。
每次注入只激活当前批次。tag>0 表示存活，tag<0 表示损失并保留损失处
的坐标。已注入粒子的身份 abs(tag) 在排序和损失后保持不变。
前述固定宏粒子权重在注入及后续存储期间始终保持不变。
注入批次标记粒子进入环内的时刻。纵向束团分组由 Harmonic Number 和
Harmonic ID of this bunch 单独定义。完成注入后不再加载新粒子，
已有环流粒子继续通过晶格元件，并受到仍然生效的磁铁波形作用。
入射分布与偏置
当 Is Load Distribution from File=true 时，每个束团读取自己的 HDF5 或 TFS 表格，
其中必须包含 x、px、y、py、z、dp 六列。位置单位为米，
动量使用指定注入参考动量归一化。Distribution File Mode 控制行的选取：
sequential：各次注入依次读取连续行，文件至少应包含该束团计划注入的总行数。repeat：每次均从第零行开始读取本批所需的行数，文件至少应容纳最大批次。 重复使用源坐标仍会生成身份不同的新粒子。
未启用文件加载时，Injection 按所选横向和纵向分布生成各批粒子。
生成与加载的粒子都会施加配置的水平色散及 Offset x / Offset y；
这些偏置仅在注入时施加。文件偏置根据 turn 或 time (s) 列，在当前
注入圈号或入射参考粒子的物理通过时间处线性插值，后者包含显式
Reference arrival time (s) 设置带来的偏移。圈号节点必须为非负整数；
以秒为单位的时间节点可以为负。节点必须严格递增，所有数值必须有限。
位置与动量列分别为 x (m) / px (rad) 或 y (m) / py (rad)。
预检会检查每个启用的表是否覆盖本次运行中实际有粒子注入的事件。
域外查询会报错，不会在表的定义域外保持端点值。
Insert Particle Coordinate、Insert Particle File 与 Scan Grid 是
互斥的三种显式坐标来源，均在上述偏置施加后、转换到环流参考系之前，替换首批的
前若干行。首批必须有足够的预留粒子；替换不会增加计划粒子数或改变宏粒子权重。
显式坐标文件使用与普通分布文件相同的六个小写坐标列，但其坐标不再施加动量偏移、
色散或横向偏置。文件全部行只在首批使用一次，不导入文件内的 tag。
文件行数不足、坐标含非有限值或纵向动量非正时，会在激活该批之前报错。
当网格或显式文件覆盖整个首批、且未启用普通分布文件加载时，跳过不再使用的随机
分布生成。部分替换时，剩余粒子仍按通常方式生成并施加偏置。
若手动坐标在唯一的有效注入批次中提供了完整分布，同样跳过无用的随机生成， 无需为 Gaussian 背景设置正发射度。真正多批注入中只手动替换首批时， 后续生成批次的随机数序列保持原有行为。 完整手动束团不再消耗最终被丢弃的随机采样，因此同一 Injection 命令中后续 随机生成束团的固定种子坐标可能与旧版本不同。当前版本使用相同种子和配置 重复运行仍可复现。
即使环流束已经加速，入射物理动量仍由指定的注入能量决定。 Injection 在保持物理动量和到达时间的条件下，将入射动量及纵向坐标转换到 目标束团参考系，定义见 纵向坐标与参考到达时间。
笛卡尔扫描坐标
Scan Grid 在一个束团内生成 x、y 轴与 dp values 的完整笛卡尔积，
每个 dp 值对应一套完整 x/y 网格。x 索引变化最快，其次为 y，最后为 dp。
该配置仅生成初值；所有追踪指令与物理效应仍由用户选择。
"Scan Grid": {
"X range (m)": [-0.01, 0.01],
"Y range (m)": [-0.008, 0.008],
"Number of x points": 21,
"Number of y points": 17,
"dp values": [-0.01, 0.0, 0.01],
"px": 0.0,
"py": 0.0,
"z (m)": 0.0
}
该网格包含 1071 个粒子，首批必须至少预留 1071 个宏粒子。范围包含两端点；
单点轴要求两端点相同，多点轴要求两端点递增。点数必须为正整数，dp 值必须有限
且不重复，每个点都必须满足 \(1+\delta>\sqrt{p_x^2+p_y^2}\)。
固定的 px、py 与 z (m) 默认均为零。其中 px、py 为相对于
入射参考动量归一化的机械动量，不是几何斜率。
Python 可使用 ScanGridConfig，或调用
PASS.utils.scan_grid.generate_scan_grid(x_values, y_values, dp_values)。
后者返回 coordinates``（列为 ``[x, px, y, py, z, dp]）、indices
（列为 [dp_index, y_index, x_index]）和三个坐标轴，也支持固定 px、
py、z 关键字参数。
指定坐标在入射参考系内精确成立。若环流参考动量或时钟不同，参考变换可能改变
所存储的 dp 与 z，但保持物理动量和到达时间不变。分析应使用注入后的
实际初始坐标，按初始 dp 分组，因为 RF 随后可能改变 dp。扫描粒子保持通常的
束流权重，并参与所配置的集体效应。
Bump 磁铁与横向涂抹
涂抹注入通过逐批改变入射束的位置和动量、环流轨道，或同时改变两者，
使注入粒子逐步填充横向相空间。Offset x 和 Offset y 指定注入点处
的入射束坐标；凸轨磁铁（Bump） 在环上施加水平和垂直脉冲磁铁冲量。
所有经过 Bump 的存活粒子都会受力，包括先前批次已经注入的粒子。
入射坐标与 Bump 跟踪使用同一套固定机器坐标。应分别指定注入面处的入射中心
和实际磁铁波形；轨道位移本身不等于磁铁引起的动量增量。
逐粒子时间模式在 \(t_i=t_0-z_i/(\beta_0c)\) 加上 Time offset (s)
后查询波形，表格应覆盖需要偏转的粒子的到达时间。
参考时间模式、插值和脉冲边界行为见 Bump 文档。
Injection 在注入面生成或加载粒子，并施加指定偏置。后续输运和损失检查 由晶格元件执行。其中 静电偏转器（ElSeparator） 在粒子实际通过该元件时 计算静电偏转以及与电极或真空壁的接触。在 ES 出口给定的粒子从该平面 开始跟踪，Injection 不额外施加几何接受截断。
注入过程的观测
在需要的观察位置和圈数配置 分布监视器（DistMonitor），保存已经注入的粒子。
在 \(s=0\) 处，Injection 先于监视器执行，因此快照包含当前批次。
开启 Include injection metadata 后，输出增加 particle_id、
injection_turn 和 injection_batch。圈号和批次从零开始；每个源束团
独立编号批次，逐粒子匹配应使用 particle_id。
三种输出格式（tfs、hdf5 和 hdf5-gzip1）均排除预留位置、保留损失粒子，
并记录 NumPending。分析监视器处的存活相空间时，应选择 tag>0；
损失粒子的坐标属于其损失位置。环流粒子数及统计矩的演化可用
统计监视器（StatMonitor） 观测。
粒子分布类型简介
在 PASS 程序中初始粒子分布由 Injection 命令实现，在 Injection 命令中，可以单独为每个束团设置不同的分布信息。
横向粒子分布
目前 PASS 程序支持生成的横向粒子分布有 水平垂直解耦的 2D 高斯分布 、 4D KV分布 、 4D 水袋分布 、 4D 抛物线分布 、 uniform-real 和 uniform-phase 。
输入发射度 \(\varepsilon_x,\varepsilon_y\) 均为 RMS 几何发射度，单位为 m rad。uniform-real 和 uniform-phase 分别强调实空间矩形均匀投影与两个独立的相空间椭圆均匀分布；这里的 phase 指横向相空间。以下分布均指加入色散与注入偏移之前的本征横向坐标。
其中 KV、水袋和抛物线分布在 4D 相空间 \((x, p_x, y, p_y)\) 中定义一个广义的超椭球边界。为了简化推导，先取 Twiss alpha 为零，并引入 归一化坐标 ：
其中 \(a, b, c, d\) 分别是束流在对应维度上的 最大物理包络边界（硬边界） 。在此归一化坐标系下，4D 超椭球边界简化为单位超球：
Twiss alpha 非零时，相应的归一化动量需包含剪切项 \(\alpha_x x+\beta_xp_x\)，y 平面同理；仅缩放物理动量不能消除相空间倾斜。
下面详细介绍各横向粒子分布。对于 4D 分布，其在 1D 平面的投影具有统一的幂函数形式。设 4D 相空间中分布密度为 \(f(r^2) \propto (1-r^2)^{\alpha}\) （ alpha ge 0 ，定义在 4D 单位球 \(B^4\) 内），则对任意单一归一化坐标 \(u\) 的 1D 边缘分布为：
其中 \(n=4\) 为相空间维数。对于均匀分布在 \(n\) 维球面 \(S^{n-1}\) 上的分布（如 KV），其 1D 投影为：
各分布的 1D 投影汇总如下：
分布 |
4D密度 |
\(\alpha\) |
1D投影幂次 |
1D投影形式 |
|---|---|---|---|---|
uniform-real（2D方块直积） |
— |
— |
0 |
\(\rho(u) = \mathrm{const}\) |
uniform-phase（2D圆盘直积） |
\(B^2\times B^2\) 内为常数 |
— |
\(\frac{1}{2}\) |
\(\rho(u) \propto \sqrt{1-u^2}\) |
KV（ \(S^3\) 球面） |
\(\delta(r-1)\) |
— |
\(\frac{1}{2}\) |
\(\rho(u) \propto \sqrt{1-u^2}\) |
Waterbag（ \(B^4\) 均匀） |
\(1\) |
0 |
\(\frac{3}{2}\) |
\(\rho(u) \propto (1-u^2)^{3/2}\) |
Parabolic（ \(B^4\) , \(1-r^2\) ） |
\((1-r^2)^1\) |
1 |
\(\frac{5}{2}\) |
\(\rho(u) \propto (1-u^2)^{5/2}\) |
下面详细介绍各横向粒子分布：
独立2D高斯分布（Gaussian）
在 \(x-p_x\) 与 \(y-p_y\) 相空间中分别独立生成服从高斯分布的横向坐标。粒子在横向相空间中的分布采用 \(4\sigma\) 截断，即仅保留满足：
\[|x| \le 4\sigma_x, \quad |y| \le 4\sigma_y\]的粒子。
对于二维相空间高斯分布 （ \(x-p_x\) 与 \(y-p_y\) ），不同 RMS 发射度对应的粒子包含比例如下：
\(\epsilon/\epsilon_{\mathrm{rms}}\)
截断范围
保留粒子比例
1
\(1\sigma\)
39.346934029%
2
\(\sqrt{2}\sigma\)
63.212055883%
4
\(2\sigma\)
86.466471676%
6
\(\sqrt{6}\sigma\)
95.021293163%
9
\(3\sigma\)
98.889100346%
16
\(4\sigma\)
99.966453737%
表中比例对应相空间不变量的椭圆截断；代码采用 x、y 位置坐标的独立截断，不能将该表的比例直接解释为实际接受率。
具体截断比例可通过下面的函数进行计算：
import numpy as np def fraction_by_emittance(epsilon, epsilon_rms): fraction = 1 - np.exp(-epsilon / (2 * epsilon_rms)) print(f"eps/eps_rms = {epsilon/epsilon_rms}, particle proportion = {fraction:.9%}") for epsi in (1, 2, 4, 6, 8, 9, 16, 25, 36): fraction_by_emittance(epsilon=epsi, epsilon_rms=1)4D KV（Kapchinskij-Vladimirskij）分布
在 \(x-p_x-y-p_y\) 四维相空间中生成 均匀分布在四维超椭球表面上 的粒子分布，是一种只存在于四维球壳上的理想化分布。这种分布下粒子产生的空间电荷场在束团内部是严格线性的，该结论适用于理想连续的自由空间横向模型；有限粒子采样及导体边界会改变其结果。
积分掉两个维度后，KV 分布在任意 2D 平面 （如 \(x-p_x\) 平面） 上的投影是一个均匀填充的椭圆。进一步积分掉一个维度后，KV 分布在 1D 平面的投影是一个半椭圆 （或半圆） 分布。具体推导如下：KV 分布均匀分布在 4D 超球面 \(S^3\) 上（ \(r^2 = 1\) ），对 \(u_x\) 求 1D 边缘分布需在 \(S^3\) 上对其余三个坐标积分：
\[\rho(u_x) \propto (1-u_x^2)^{\frac{n-3}{2}} = (1-u_x^2)^{\frac{1}{2}}\]即 1D 投影幂次为 \(\frac{1}{2}\) 。
Note
根据积分可得：在 \(x-p_x\) 与 \(y-p_y\) 相平面上KV分布的全发射度为RMS发射度的4倍。
即 KV 分布下所有粒子均处在 \(2\sigma\) 截断范围内。但是在程序中依然设置为保留满足：
\[|x| \le 4\sigma_x, \quad |y| \le 4\sigma_y\]的粒子。
4D 水袋（Waterbag）分布
在 \(x-p_x-y-p_y\) 四维相空间中生成 均匀分布在四维超椭球内部 的粒子分布。
积分掉两个维度后，水袋分布在任意 2D 平面 （如 \(x-p_x\) 平面） 上的投影呈抛物线分布。进一步积分掉一个维度后，水袋分布在 1D 平面的投影是一个 \(\frac{3}{2}\) 次幂抛物线型分布。具体推导如下：水袋分布均匀分布在 4D 超球 \(B^4\) 内（ \(f(r^2) = 1\) ，即 \(\alpha = 0\) ），对 \(u_x\) 求 1D 边缘分布需在 \(B^4\) 上对其余三个坐标积分，剩余部分为半径 \(\sqrt{1-u_x^2}\) 的 3D 球：
\[\rho(u_x) \propto V_3\!\left(\sqrt{1-u_x^2}\right) \propto (1-u_x^2)^{\frac{3}{2}}\]其中 \(V_3(R) \propto R^3\) 为 3D 球体积。即 1D 投影幂次为 \(\frac{3}{2}\) 。
Note
根据积分可得：在 \(x-p_x\) 与 \(y-p_y\) 相平面上水袋分布的全发射度为RMS发射度的6倍。
即水袋分布下所有粒子均处在 \(\sqrt{6}\sigma\) 截断范围内。但是在程序中依然设置为保留满足：
\[|x| \le 4\sigma_x, \quad |y| \le 4\sigma_y\]的粒子。
4D 抛物线（Parabolic）分布
在 \(x-p_x-y-p_y\) 四维相空间中生成 密度从中心向外围随着r的增加呈抛物线递减 的粒子分布，这种分布比水袋分布更贴近真实加速器中偏向中心聚集的束流。
积分掉两个维度后，抛物线分布在任意 2D 平面 （如 \(x-p_x\) 平面） 上的投影呈平方抛物线分布。进一步积分掉一个维度后，抛物线分布在 1D 平面的投影是一个 \(\frac{5}{2}\) 次幂抛物线型分布。具体推导如下：抛物线分布的 4D 密度为 \(f(r^2) \propto (1-r^2)^1\) （ \(\alpha = 1\) ），对 \(u_x\) 求 1D 边缘分布：
\[\rho(u_x) \propto (1-u_x^2)^{\frac{n-1}{2}+\alpha} = (1-u_x^2)^{\frac{3}{2}+1} = (1-u_x^2)^{\frac{5}{2}}\]即 1D 投影幂次为 \(\frac{5}{2}\) 。
Note
根据积分可得：在 \(x-p_x\) 与 \(y-p_y\) 相平面上抛物线分布的全发射度为RMS发射度的8倍。
即抛物线分布下所有粒子均处在 \(\sqrt{8}\sigma\) 截断范围内。但是在程序中依然设置为保留满足：
\[|x| \le 4\sigma_x, \quad |y| \le 4\sigma_y\]的粒子。
uniform-real（实空间矩形均匀分布）
在 \(x-p_x\) 与 \(y-p_y\) 相空间中分别独立生成 2D 均匀方块分布。对于每个横向平面，在归一化坐标 \((u, v)\) 中于 \([-1, 1] \times [-1, 1]\) 方块区域内均匀采样，再通过 Twiss 参数映射到物理坐标。理想连续分布的 RMS 发射度等于输入参数 \(\varepsilon\) ，位置坐标半宽的平方为其方差的 3 倍，位置投影处在 \(\sqrt{3}\sigma\) 截断范围内。这种分布可以模拟电子枪等产生的初始束流。
积分掉一个维度后，位置投影是一个常数（均匀）分布。由于 \(u_x\) 和 \(v_x\) 独立均匀分布在 \([-1, 1]\) 上，对 \(v_x\) 积分后：
\[\rho(u_x) = \frac{1}{2} = \mathrm{const} \propto (1-u_x^2)^{0}\]即 1D 投影幂次为 \(0\) 。
因此，本征 \(x-y\) 密度在半宽分别为 \(\sqrt{3\varepsilon_x\beta_x}\) 和 \(\sqrt{3\varepsilon_y\beta_y}\) 的矩形内均匀。Twiss alpha 非零时，物理相空间中的方块变为平行四边形，动量投影不一定均匀。色散、后续传输及多个注入回合的叠加也会改变实空间密度。旧类型
uniform已被uniform-real替代，不再接受旧名称。uniform-phase（双平面椭圆相空间均匀分布）
两个横向相空间椭圆分别均匀填充，且两平面独立采样。令 \(\gamma_u=(1+\alpha_u^2)/\beta_u\)，定义 Courant–Snyder 不变量及作用量：
\[I_u=\gamma_u u^2+2\alpha_u u p_u+\beta_u p_u^2=2J_u, \qquad u\in\{x,y\}.\]支持域是两个实心椭圆的直积：
\[I_x\le4\varepsilon_x,\qquad I_y\le4\varepsilon_y.\]直接面积采样使用彼此独立的 \(U_u\sim\mathcal U(0,1)\) 和 \(\theta_u\sim\mathcal U(0,2\pi)\)：
\[r_u=\sqrt{4\varepsilon_u U_u},\qquad u=\sqrt{\beta_u}\,r_u\cos\theta_u,\qquad p_u=\frac{r_u}{\sqrt{\beta_u}} \left(\sin\theta_u-\alpha_u\cos\theta_u\right).\]生成分布的中心协方差为 \(\varepsilon_u\begin{pmatrix}\beta_u&-\alpha_u\\-\alpha_u&\gamma_u\end{pmatrix}\)，因此 RMS 几何发射度等于输入值 \(\varepsilon_u\)，边界不变量为其四倍。两个归一化作用量 \(q_u=I_u/(4\varepsilon_u)\) 独立且均匀分布在 \([0,1]\)。
归一化作用量公式要求相应平面的发射度为正。当 \(\varepsilon_u=0\) 时，该平面生成于 \(u=p_u=0\)；随后仍按既有流程叠加色散和注入偏移。
实空间密度具有矩形支持域，但并不均匀。取 \(a=2\sqrt{\varepsilon_x\beta_x}\)、\(b=2\sqrt{\varepsilon_y\beta_y}\)，有
\[\rho(x,y)=\frac{4}{\pi^2ab} \sqrt{1-\frac{x^2}{a^2}}\sqrt{1-\frac{y^2}{b^2}}, \qquad |x|\le a,\quad |y|\le b,\]矩形外密度为零。单个位置坐标的投影为半椭圆，与相应 KV 投影形状相同。
当横向作用量相互独立是合理假设时，可用该分布近似双平面涂抹后的束流。它不生成涂抹轨道，也不自动实现相关或反相关涂抹。非耦合线性光学中的相混合只混合相位，并不会消除作用量相关性。
uniform-phase 与 KV 可以具有相同的单平面投影和 RMS 发射度，但联合作用量不同：uniform-phase 填充 \(0\le q_x,q_y\le1\)，KV 则满足 \(q_x+q_y=1\)。4D 水袋填充的支持域为 \(I_x/(6\varepsilon_x)+I_y/(6\varepsilon_y)\le1\)。三者的理想作用量相关系数依次为 \(0\)、\(-1\) 和 \(-1/2\)。uniform-real 与 uniform-phase 在各自支持域内均具有常数相空间密度；这两个名称并非互斥的数学分类。
纵向粒子分布
目前 PASS 程序支持生成的纵向粒子分布有 2D高斯分布 、 非聚束束流分布 、 指定 RMS 束长的射频匹配分布 、 指定 RMS 动量展宽的射频匹配分布 ：
2D高斯分布（Gaussian）
在 \(z-\delta\) 相空间中分别生成服从高斯分布的纵向坐标。粒子在纵向相空间中的分布采用 \(4\sigma\) 截断，即仅保留满足：
\[|z| \le 4\sigma_z\]的粒子。
非聚束束流分布（Coasting）
在 \(z-\delta\) 相空间中生成 \(z\) 服从均匀分布， \(\delta\) 服从高斯分布的纵向坐标。均匀区间为 [-sigma_z/2, sigma_z/2]，此时 Sigma z (m) 表示区间全宽；生成整环分布时应将 sigma_z 设为环周长。
指定 RMS 束长的射频匹配分布（MatchZ）
在 \(z-\delta\) 相空间中生成同时满足射频参数及纵向束长限制 （ \(\sigma_z\) ） 的纵向坐标。粒子在纵向相空间中的分布采用 \(2\sigma\) 截断，即仅保留满足：
\[|z| \le 2\sigma_z\]的粒子。
指定 RMS 动量展宽的射频匹配分布（MatchDp）
在 \(z-\delta\) 相空间中生成同时满足射频参数及动量展宽限制 （ \(\sigma_{\delta}\) ） 的纵向坐标。粒子在纵向相空间中的分布采用 \(2\sigma\) 截断，即仅保留满足：
\[|z| \le 2\sigma_z\]的粒子。
匹配求根使用完整 RF 桶内连续分布的归一化中心矩，使其 RMS 满足输入目标。动量积分先用不完全伽马函数解析计算，再对按分布自然宽度缩放后的 z 自适应积分，并显式划分积分区间以捕捉窄峰。这提高了矩的计算精度，不改变分布密度、RF 势能或匹配目标。粒子采样随后另行施加截断，因此最终有限样本的 RMS 仍可能与该目标不同。
RF 匹配采样还施加 bucket 哈密顿量接受范围的 0.9 比例限制。超过模型最大尺度的请求会调整为该最大值的 0.99 倍。这些条件与 z 截断共同作用，所得样本 RMS 不一定等于输入匹配目标。
两种匹配分布均分批生成候选点，仍在相同的 RF 桶外接矩形内均匀抽样。 每个候选点按相同顺序消耗三个均匀随机数，分别用于 z、动量偏差和接受阈值。 每批候选数不超过尚需生成的粒子数，因此不会在填满束团后额外消耗候选点。 在兼容条件下，经检查的 MT19937 状态转移使 NumPy 能批量生成原有 Python 随机数流，再将推进后的状态及缓存的高斯随机值写回；否则直接使用 Python 随机数生成器。种子语义和后续随机数流保持不变。
仅依赖动量的概率上界可提前排除必然被拒绝的候选点，省去这些点的 RF 势能计算。 在稳定的单谐波 RF 桶内，将正定符号下的哈密顿量写为
其中 \(\delta=(P-P_0)/P_0\)、\(f_0=\beta c/C\)。令 \(T=|H_0|>0\)、\(B=|H_{\max}|>0\)，原有接受密度满足
若候选点已有的随机阈值超过该上界，完整密度判断也必然拒绝它。实现保留了保守的 浮点舍入余量，并在上界所需的数值条件不适合时回退到完整判断。其余候选点仍使用 原有密度和哈密顿量条件判断；已有 z 截断也可提前检查。这改变计算开销，保持 匹配目标、分布密度和截断条件不变。
匹配计算中的射频相位和电荷符号
对于 matchz 和 matchdp，RF Phase (rad) 表示参考粒子在匹配 RF
位置到达时的物理射频波形相位。对于 射频腔（RFCavity） 中的波形，输入为
\(\phi_s=\theta(t_s)=2\pi\int_0^{t_s}f(t)\,dt+\phi(t_s)\)，包含时钟相位，
并非仅指相位偏移参数。匹配输入显式指定该事件处的相位；Injection 不根据跟踪质心
推断它，也不从名义分组坐标 z_center 添加相位。
匹配仍使用现有的冻结、单谐波、小相对动量偏差模型。令 \(\delta=(P-P_0)/P_0\)、\(\eta=\gamma_t^{-2}-\gamma^{-2}\)、 \(\phi=\phi_s-2\pi h z_{\mathrm{rel}}/C\)，模型方程为
其中 \(q\) 是以元电荷为单位的有符号电荷数，\(V\) 为输入的有符号电压， \(E\) 为每粒子总能量（eV）。当 \(A=N_p+N_n>0\) 时，使用 \(q_r=q/A\) 和 \(E_r=E/A\)；电子和正电子（\(A=0\)）使用 \(q_r=q\) 和 \(E_r=E\)。因此稳定相位必须满足 \(qV\eta\cos\phi_s<0\)。例如 \(V>0\) 且 \(\eta>0\) 时，电子的 稳定物理相位为 0，正电荷粒子的稳定物理相位为 \(\pi\)。桶边界采用该稳定相位 所在分支两侧相邻鞍点中较低的势垒。电荷符号修正不改变匹配分布模型，也不增加 多谐波、爬坡、辐射或集体场匹配。
旧版负电荷 Injection 输入若曾手动加 \(\pi\) 来补偿无符号电荷计算，应去掉 该补偿并填入物理相位。GUI RF bucket 工具 保留独立的有效相位 约定：\(qV<0\) 时，GUI 相位为物理相位加 \(\pi\)，再对 \(2\pi\) 取模。GUI 输入约定不变。
多束团纵向坐标
源分布的 z 表示相对于源参考粒子的米制时间差，\(z_s=\beta_s c(T_s-t_i)\)。 源参考事件由规定机器时钟、注入圈号和槽位选择，初始时刻也可显式指定，见 自动设计时钟与初始化。写入目标束团前应用
机械动量同时重归一化，物理时间和动量不变。z 不做环周折叠。 RF 直接采样 \(T_d-z_d/(\beta_d c)\)。
名义槽位位置在写日志或输出时由 harmonic_id*C/harmonic_number 计算，
不保存 bunch.z_center 属性。ZCenter/zCenter 输出字段
记录此派生元数据，下图中的 z_center 也表示该名义位置。
它与 slice_table['z_center'] 不同：后者保存各切片区间的中心，供切片和尾场计算使用。
若匹配分布在距注入点 \(s_{rf}\) 的 RF 位置定义，初始化仍采用线性逆传播 \(z(0)=z(s_{rf})+\eta s_{rf}\delta\)，其中 \(\eta=1/\gamma_t^2-1/\gamma^2\)。这属于声明的线性分布近似。
束团填充方案
Note
束团 ID （ bunch_id ）严格按照从 0 开始、步长 1 递增的顺序编号，由输入文件中 bunch0 、 bunch1 、 … 的键名决定。束团数量由输入文件中 bunch 键的数量决定。
harmonic_id 必须唯一，并完整覆盖 \(0,1,\ldots,h_{\mathrm{group}}-1\) 。因此输入中束团数等于 Harmonic Number ；未填充的槽位也要声明为宏粒子数为 0 的空束团。GUI 会自动为未填写的槽位补齐这些空束团声明。
全填充 ：所有分组都包含非零宏粒子，中心依次位于 \(0,C/h_{\mathrm{group}},\ldots,(h_{\mathrm{group}}-1)C/h_{\mathrm{group}}\)
部分填充 ：保留完整的分组编号，但将未填充槽位对应束团的宏粒子数设为 0
运行时仅在分配的粒子区间长度为零（start_idx == end_idx）时，才判定该槽位为空。
空槽跳过粒子计算及逐束团监视文件输出。尚未注入的预留粒子和已经损失的粒子仍是
已分配的记录，因此存活粒子数为零不等于空束团，全部损失后的损失统计会继续记录。
后续 SortBunch 或 ReorganizeBunch 可以将粒子分入原本的空槽，此后该槽正常参与计算。
空槽仍保留少量参考时间、参考能量更新及共享效应的时间同步，以保证后续重分组所用
参考状态有效。
下图为环形布局下的束团分组示例。圆环代表加速器周长 \(C\) ，标记点为名义槽位 \(z_{\mathrm{center}}\) 。分组编号按顺时针方向递增。上图为 \(h_{\mathrm{group}}=4\) 全填充；下图为 \(h_{\mathrm{group}}=5\) 部分填充，其中分组 1、3、4 由空束团占位：
色散耦合
如果注入点存在色散函数 \(D_x\) 和 \(D_{px}\) ，则在生成横向分布后自动施加色散耦合：
其中 \(\delta\) 为粒子的动量偏差。这确保了粒子分布与纵向动量展宽在物理上自洽。
动量偏差
注入时可以为整个束团施加平均动量偏移 \(\delta_0\) 。粒子分布生成时 \(\delta\) 服从均值为 0 的分布（如高斯分布 \(\delta \sim \mathcal{N}(0, \sigma_\delta)\) ），施加偏移后变为 \(\delta \sim \mathcal{N}(\delta_0, \sigma_\delta)\) ，即分布中心从 0 平移到 \(\delta_0\) 。\(\delta_0\) 是叠加量，不是粒子的总 \(\delta\) 。这用于模拟注入能量偏移、参考动量偏移等场景。
支持两种输入方式（互斥，若同时为非零值则报错）：
动量偏差 （
Momentum Offset dp）：直接给出 \(\delta_0\) （无量纲，相对于参考动量的偏差）动能偏差 （
Kinetic Energy Offset (eV)）：给出 \(\Delta E\) （单位 eV），内部转化为 \(\delta_0\)
精确转换公式
动能偏差 \(\Delta E\) 到动量偏差 \(\delta_0\) 的转换，采用精确的相对论能量-动量关系：
其中 \(E\) 为总能量（ \(E = E_k + m_0\) ）， \(p\) 为动量， \(m_0\) 为静止质量。参考粒子（无偏差）的参数为：
施加动能偏差 \(\Delta E\) 后，粒子总能量变为 \(E_1 = E_0 + \Delta E\) ，对应动量为：
因此动量偏差为：
此公式 完全精确 ，无任何近似，与 RF 腔中采用的精确 \(E^2 = p^2 + m_0^2\) 变换保持一致。
一阶线性化近似
对式 \(\delta_0 = p_1/p_0 - 1\) 在 \(\Delta E \to 0\) 处做一阶泰勒展开。由 \(E \, dE = p \, dp\) 得：
其中 \(\beta = p_0 c / E_0\) 为参考粒子速度。由于 PASS 中 \(\delta = \Delta p / p_0\) 为相对动量偏差，参考动量 \(p_0 = \beta \gamma m_0 = \beta E_0\) ，故：
此近似截断了 \(O(\delta_0^2)\) 及更高阶项。在小偏差时精度足够，但大偏差时误差显著。
精确与近似对比
下表以质子（ \(E_k = 45\) MeV ， \(\beta = 0.299\) ）为例，展示不同 \(\Delta E\) 下两种公式的差异：
\(\Delta E\) (eV) |
精确 \(\delta_0\) |
近似 \(\delta_0\) |
相对误差 |
|---|---|---|---|
1,000 |
1.137126e-5 |
1.137132e-5 |
0.000005% |
10,000 |
1.137073e-4 |
1.137132e-4 |
0.000052% |
100,000 |
1.136544e-3 |
1.137132e-3 |
0.000517% |
1,000,000 |
1.131311e-2 |
1.137132e-2 |
0.0514% |
10,000,000 |
1.084146e-1 |
1.137132e-1 |
4.89% |
50,000,000 |
4.717485e-1 |
5.685659e-1 |
20.5% |
在小偏差（ \(\Delta E < 100\) keV ）时两种公式几乎无差异，但在大偏差（如 \(\Delta E > 1\) MeV ）时线性近似误差超过 0.05%，在 \(\Delta E = 50\) MeV 时误差高达 20%。PASS 采用精确公式以覆盖大偏差场景。
施加顺序
动量偏差 \(\delta_0\) 在纵向偏移之前施加到每个粒子的 \(\delta\) 上：
因此后续的 rf_position 逆向传播（ \(z \leftarrow z + \eta \, s_{\text{rf}} \, \delta\) ）和色散耦合（ \(x \leftarrow x + D_x \, \delta\) ）均使用包含 \(\delta_0\) 的 \(\delta\) 值，确保物理自洽。
分布类型选择
根据上面的输入文件，将生成在横向满足 Gaussian 分布，在纵向满足 MatchZ 分布的束团。修改下面这两行参数，可调整生成的束团分布类型：
"Transverse dist": "gaussian",
"Longitudinal dist": "matchz"
其中横向分布的取值为： gaussian 、 kv 、 waterbag 、 parabolic 、 uniform-real 、 uniform-phase ，纵向分布的取值为： gaussian 、 coasting 、 matchz 、 matchdp 。
在生成纵向 gaussian 与 coasting 分布时，不需要射频相关参数，在生成 matchz 与 matchdp 分布时，需要提供射频参数。
1D 投影理论曲线
下图展示了 uniform-real、uniform-phase、KV、水袋和抛物线分布的位置理论投影。所有曲线均归一化至 \(\int_{-1}^{1} \rho(u) \, du = 1\)，横轴为位置坐标除以其支持域半宽：\(u\in[-1,1]\)。uniform-phase 与 KV 曲线重合。可以清晰看到从 uniform-real（平顶）到抛物线分布（尖峰）的幂次递增趋势。
Figure 1. 1D projections of transverse distributions (theory)
模拟结果
下面将展示保持上述输入文件中 Twiss、发射度、射频等参数不变，只改变分布类型时，模拟所得粒子分布图片。
横向 Gaussian 分布：
Figure 2. Transverse gaussian distribution: x-px
Figure 3. Transverse gaussian distribution: y-py
Figure 4. Transverse gaussian distribution: x-y
横向 KV 分布：
Figure 5. Transverse KV distribution: x-px
Figure 6. Transverse KV distribution: y-py
Figure 7. Transverse KV distribution: x-y
横向水袋分布：
Figure 8. Transverse waterbag distribution: x-px
Figure 9. Transverse waterbag distribution: y-py
Figure 10. Transverse waterbag distribution: x-y
横向抛物线分布：
Figure 11. Transverse parabolic distribution: x-px
Figure 12. Transverse parabolic distribution: y-py
Figure 13. Transverse parabolic distribution: x-y
横向 uniform-real 分布：
以下 uniform-real、uniform-phase 图及联合作用量对比图来自 example/01_generate_distribution 的 transverse 算例实际生成的 HDF5 注入输出，每种分布包含 100,000 粒子，纵向为高斯分布。横向输入为 \(\varepsilon_x=200\) mm mrad、\(\varepsilon_y=100\) mm mrad、\(\beta_x=\beta_y=0.5\) m、\(\alpha_x=-2.614303952\)、\(\alpha_y=1.57442348\)，色散为零。
Figure 14. Transverse uniform-real distribution: x-px
Figure 15. Transverse uniform-real distribution: y-py
Figure 16. Transverse uniform-real distribution: x-y
横向 uniform-phase 分布：
图 17. 横向 uniform-phase 分布：x-px
图 18. 横向 uniform-phase 分布：y-py
图 19. 横向 uniform-phase 分布：x-y，支持域为矩形，但密度并不均匀。
图 20. 联合作用量 \(q_x=I_x/(4\varepsilon_x)\) 与 \(q_y=I_y/(4\varepsilon_y)\)。红线标出 uniform-phase 正方形、水袋三角形及 KV 直线的边界；颜色表示实测每格粒子数，四图共用同一对数色标。
纵向 MatchZ 分布：
Figure 21. Longitudinal matchz distribution: z-pz
纵向 MatchDp 分布：
Figure 22. Longitudinal matchdp distribution: z-pz
纵向 Gaussian 分布：
Figure 23. Longitudinal gaussian distribution: z-pz
纵向 Coasting 分布：
Figure 24. Longitudinal coasting distribution: z-pz
初始分布输出格式
启用 save_init_dist 时，各 BunchConfig 支持
output_format="hdf5"``（默认，不压缩）、
``"hdf5-gzip1"``（gzip-1 + shuffle）或 ``"tfs"；JSON 参数位于对应
bunchN 块中的 "Output format"。此参数只控制初始分布输出，
载入文件时按扩展名识别输入格式。详见 表格输出格式。
在该源最后一个计划注入事件中，完成同一事件所有源的注入后，按稳定粒子 ID 找到
包含该源记录（含损失记录）的当前束团并保存快照，不会等待其他源在未来圈结束。
若该源分散到多个当前束团，每个束团独立保存一个文件，使每个文件只使用一套当前参考量。
每份快照包含整个当前束团，包括其他源的粒子和未来批次尚未激活的零 tag 预留位置；
行数据不按原始源筛选，原来已空的槽不生成快照。未改变分组时保留原文件名；
该源发生迁移、分裂或分组网格改变后，文件名增加 _groupN 标识当前束团。
多圈注入时，先前批次可能已经
传输或丢失，因此它不保留每个粒子的出生坐标。用于 DA 分析的逐粒子注入初值由
ParticleMonitor 在每次注入事件中另行捕获。
载入分布时读取六维坐标列作为新的入射分布，不通过文件中的 tag、损失历史或
参考元数据恢复束流状态。
保存时先写完整的私有临时文件，再发布到最终路径，不覆盖已有目标。 若该路径已有快照或输入分布，保留原文件并报错。保存失败后可在中断的注入事件重试， 不会重复注入同一批粒子。已经成功发布的组文件保留并在重试时跳过；全部所需组保存 成功后才将该源标记为完成。若发布成功后才收到异常，则用文件身份确认本次已发布的 完整快照，重试不会将它误判为外来已有文件。保存成功前须将跟踪停留在该事件。
快照文件头的 Ek、m0 描述当前束团参考量；InjectionKineticEnergy
单独保留生成入射分布时使用的源能量。ReferenceArrivalTime``（s）、
``ReferenceBeta 与 ReferenceMomentum``（eV/c，离子按每核子计）对应注入后
保存事件的参考量。因此，存活粒子的动量为 ``ReferenceMomentum * (1 + dp)，
到达时间为 ReferenceArrivalTime - z / (ReferenceBeta * c)。
HarmonicId、HarmonicNumber、ZCenter``（m）记录当前分组，``BunchId
标识当前束团；SourceBunchId、SourceHarmonicId、SourceHarmonicNumber
保留原注入源标识。保存的 z 仍为 z_rel。这些参考量只适用于存活粒子；损失行保留丢失事件时的坐标。
发射度、Twiss 参数等其他生成设置不代表快照中测得的统计量。
HDF5 载入仅读取当前批次的六个坐标切片，每批读取后关闭文件。
TFS 缓存列索引和批次边界的字节偏移，再读取所需批次；文件大小或修改时间变化
会使缓存失效。两种方式均不长期持有文件句柄，也不缓存完整坐标表。
sequential 依次读取源文件行；repeat 每批从首行重新读取。
运行前校验也按有界分块扫描 HDF5、TFS 分布，覆盖第一批之后的全部数据行。 它检查坐标列、有限数值、物理纵向动量及总行数，缓存只保留行数和诊断信息， 不保留完整坐标表。显式插入粒子文件采用相同的分块预检查；实际插入时仍一次 读取其用于第一批的完整输入。