束团重整（ReorganizeBunch）

本模块介绍 PASS 中的束团重整命令 ReorganizeBunch ，用于在模拟过程中动态调整束团的分组方式。

功能说明

ReorganizeBunch 命令 只修改束团的索引范围 （ start_idx 和 end_idx ）， 不修改任何粒子坐标 （x, px, y, py, z, dp, tag 等）。

Note

本命令仅重整束团的索引分配，不涉及物理上的散束或合束。真正的散束（bunch lengthening）和合束（bunch compression）是通过调节高频腔的电压和相位等参数实现的物理过程，而非索引重分配。

适用场景：

• 合并 ：将多个束团的索引合并为更少的束团。粒子的 z 坐标保持不变，只是索引范围重新分配。例如注入时谐波数 \(h=4\) 产生 4 个束团，合并为 1 个束团

• 拆分 ：将现有束团的索引重新分组为更多束团

代码位置

• 源文件： PASS/commands/reorganize.py

• 类名： ReorganizeBunch （继承自 Command ）

• 注册名： reorganizebunch

• Schema 类： ReorganizeBunchElement （ PASS/para/schema/elements.py ）

接口参数

属性名	JSON key	类型	单位	说明
s	S (m)	float	m	命令在环中的 s 位置
name	name	str		命令名称，由序列键名自动填入
mode	Mode	str		操作模式，可选： merge （合并束团）、 split （拆分束团）
start_turn	Start turn	int		生效起始圈数（含，从 0 开始计数）
end_turn	End turn	int		生效结束圈数（不含）。设为 -1 表示不限制上限，持续到模拟结束
new_num_bunch	New num bunch	int		新的束团数量（必须 \(\ge 1\) ）

物理说明

ReorganizeBunch 命令的设计理念是： 粒子的物理位置由 tracking 过程决定，束团身份只是索引标签。

粒子的 z 坐标随 tracking 自然演化（通过 RF 腔的能量调制和漂移中的滑相效应），不需要人为调整。ReorganizeBunch 只负责重新分配索引范围，使后续的诊断、切片等操作能正确识别新的束团结构。

索引分配方式

总粒子数 \(N_{\text{total}}\) 被尽可能均匀地分配到 new_num_bunch 个束团中：

\[\begin{split}N_k = \left\lfloor \frac{N_{\text{total}}}{n} \right\rfloor + \begin{cases} 1 & k < N_{\text{total}} \bmod n \\ 0 & \text{otherwise} \end{cases}\end{split}\]

其中 \(n\) 为新束团数， \(k = 0, 1, \ldots, n-1\) 。前 \(N_{\text{total}} \bmod n\) 个束团各多分一个粒子。

使用示例

以下示例展示如何在第 500 圈将 4 个束团合并为 1 个束团：

{
    "ReorganizeBunch1": {
        "S (m)": 0.0,
        "Command": "ReorganizeBunch",
        "Mode": "merge",
        "Start turn": 500,
        "End turn": -1,
        "New num bunch": 1
    }
}

应用场景

• 散束后合并索引 ：注入时使用高谐波数（如 \(h=4\) ）产生多个束团，然后关闭或降低 RF 电压使束团自然散开。在散束完成后使用 ReorganizeBunch 将索引合并为 1 个束团

• 再聚束后重新分组 ：散束后重新施加 RF 电压使粒子重新聚束，使用 ReorganizeBunch 将索引重新分组

• 束团填充方案调整 ：在不同模拟阶段使用不同的束团分组方式