纵向切片（Slicer）

Slicer 命令把每个束团中的存活宏粒子分配到纵向切片，并将结果写入束团拥有的命名 SliceSet。切片是局部分类操作：不会重排任何粒子数组，也不会改变束团归属。

坐标与时间的通用定义见纵向坐标与参考到达时间。选择切片坐标和命名切片集后，在使用它的集体效应命令之前执行 Slicer。

配置格式

输入命令名称为 Slicer，并通过用户定义的 slice set 选择集合：

{
    "sc_slicer": {
        "S (m)": 12.5,
        "Command": "Slicer",
        "Slice set": "space_charge",
        "Coordinate": "z_periodic",
        "Slice model": "equal_particle",
        "Number of slices": 128,
        "Z range mode": "auto",
        "Save turns": [[0], [100, 1000, 100]]
    }
}

范围参数按模式分别放置，不接受平铺的 Z min、Z max 或 Number of sigma 字段。

auto

直接使用当前存活粒子的实际最小值和最大值，是最宽的数据驱动范围，不会排除观测到的离群粒子。若全部存活粒子的所选坐标相同，则保留真实的零跨度，不人为添加宽度。

explicit

使用 Explicit 中给出的固定束团相对坐标范围：

"Z range mode": "explicit",
"Explicit": {"Z min": -0.30, "Z max": 0.30}

所有范围都在命令执行时解析。z_rel 或 z_periodic 模式下，显式范围外的粒子进入对应边界切片并记录警告；不会静默丢弃。小于下限进入切片 N-1，大于上限进入切片 0。

切片编号按所选坐标从大到小排列：切片 0 对应最大坐标区间，切片 N-1 对应最小坐标区间。

接口参数

以下表格列出 Slicer 序列命令支持的参数。表格中的 JSON 键名采用输入文件的写法；PASS 内部会统一转换键名大小写。

通用命令参数

参数名	键名	类型	默认值 / 是否必填	说明
`command`	`"Command"`	str	必填	必须为 `"Slicer"`，用于选择 Slicer 命令实现。
`s`	`"S (m)"`	float	必填	更新切片数据时的环上纵向位置。
`name`	序列对象键名	str	序列键必填	当前命令实例名称。序列加载器会将该名称传给命令用于诊断。
`slice_set`	`"Slice set"`	str	必填	要更新的束团级 `SliceSet` 名称，例如 `"space_charge"` 或 `"beambeam_ip1"`。
`slice_model`	`"Slice model"`	str	`"equal_length"`	粒子到切片的分配模型，仅接受 `"equal_length"` 和 `"equal_particle"`。
`coordinate`	`"Coordinate"`	str	`"z_rel"`	`z_rel` 为连续时间切片；`z_periodic` 为 SC 环周折叠切片； `arrival_phase` 使用尾场观察时钟；`collision_z` 用于显式 CrossingAngle 区间。 SC 必须显式选择 `z_periodic`。
`purpose` / `configuration`	`"Purpose"` / `"Configuration"`	str / str 或 null	`"general"` / null	`beam_beam` 要求匹配的 IP 配置以及 `z_rel` 或 `collision_z`；其显式区间必须覆盖全部存活粒子。坐标和顺序规则见束束相互作用（BeamBeam）。
`num_slices`	`"Number of slices"`	int	10	纵向切片数，必须至少为 1。当存活粒子数更少时，该配置值仍然保留。
`z_range_mode`	`"Z range mode"`	str	`"auto"`	选择范围模式：`"auto"` 或 `"explicit"`。
`save_turns`	`"Save turns"`	整数列表的列表	`[]`	可选快照圈数：`[turn]` 或 `[start, end, step]`。
`periodic`	`"Periodic"`	bool	false	非聚束束流 WakeField 的全环到达相位投影，要求 equal_length 及长度为 C 的显式区间。
`max_phase_slip`	`"Max phase slip"`	float	0.05	WakeField 允许的每参考圈最大已观测相位变化，以圈为单位，范围 (0, 0.1]；诊断切片只记录，不拒绝。

范围模式参数

auto 不需要模式专属参数块；explicit 必须提供 Explicit 块。

模式 / 参数名	键名	类型	默认值 / 是否必填	说明
`auto`	`"Z range mode"`	str	可选	使用当前存活粒子的实际最小值和最大值，包含观测到的离群粒子。
`explicit`	`"Z range mode"`	str	可选	使用固定范围；该模式必须同时提供 `Explicit`。
`explicit` 块	`"Explicit"`	object	显式模式必填	包含 `Z min` 和 `Z max` 的模式专属对象。
`z_min`	`"Z min"`	float	显式模式必填	所选切片坐标下限，必须小于 `Z max`。
`z_max`	`"Z max"`	float	显式模式必填	所选切片坐标上限，必须大于 `Z min`。

配置校验

在束流初始化阶段，引用同一个 Slice set 的多个 Slicer 命令必须具有完全一致的 Slice model、Number of slices、范围模式及（显式模式下的）显式参数块。配置冲突会抛出 ValueError，并指出两个相关的序列命令。执行时，如果显式范围不能覆盖全部存活粒子，会记录警告；超出范围的粒子会被限制到第一个或最后一个切片。

同一束流中的命名 SliceSet 可以被同类物理模块的多个启用命令共用，例如多个 WakeField 命令。不同模块必须使用不同名称：尾场与束束作用不能引用同一个集合。输入检查会指出冲突的切片集、模块和命令。不同束流中的同名集合彼此独立。多个配置相容的 Slicer 命令仍可更新同一个集合；此规则不改变显式更新频率，也不会自动重新切片。同一输入检查还要求 Purpose=beam_beam 的集合仅供 BeamBeam 使用，即使当前没有 BeamBeam 命令读取它。不读取切片的命令，例如作用长度为零的 IBS，不登记为切片消费者。

output_format``（JSON ``"Output format"）默认为 "hdf5-gzip1" （gzip-1 + shuffle），也支持 "hdf5"``（不压缩）和 ``"tfs"。此选项只影响逐粒子信息，切片汇总仍保存为 TFS 和 CSV。 HDF5 结构和读取方式见表格输出格式。

切片模型

旧输入中的 equal_charge 或 Equal particle 应改为 equal_particle；不再接受这些旧名称。

切片 ID 按选定的切片坐标从大到小排列：切片 0 是 z 最大的区间，切片 N-1 是 z 最小的区间。

equal_length 将范围划分为 N 个等宽切片：

\[i = N-1-\operatorname{clip}\left(\left\lfloor \frac{z-z_{min}}{\Delta z}\right\rfloor,0,N-1\right), \qquad \Delta z = \frac{z_{max}-z_{min}}{N}.\]

对于非零范围，equal_length 生成的 FP64 边界必须有限且严格递增。若舍入使相邻边界重合， Slicer 会报错，不会自动修改区间或切片数。此要求同时适用于 auto 和 explicit；必要时应选择可表示的区间或减少切片数。

equal_particle 只对临时的 z 数组和索引排序，按粒子秩分配切片 ID，再将 ID 写回原粒子顺序。粒子池本身不会改变。即使多个粒子具有相同坐标，秩分配仍能使各切片粒子数尽量均衡。保存的边界包络这些按秩分配的成员，同时决定 SpaceCharge、WakeField 和 ECloud 使用的宽度与中心。

对 \(n>0\) 个存活粒子，将所选坐标递增排序为 \(s_0,\ldots,s_{n-1}\)。内部边界 \(i=1,\ldots,N-1\) 的秩分割点为 \(k_i=\lceil in/N\rceil\)。以分位比例 \(i/N\) 的线性分位数 \(q_i\) 为候选，保存边界为

\[\begin{split}e_i=\operatorname{clip}(q_i,L_i,U_i),\qquad [L_i,U_i]= \begin{cases} [s_{k_i-1},s_{k_i}],&0<k_i<n,\\ [s_{n-1},z_{max}],&k_i=n. \end{cases}\end{split}\]

首尾边界保持为 \(e_0=z_{min}\) 和 \(e_N=z_{max}\)。已在合法间隙内的候选值不变，粒子的秩 ID 和各片计数也不变，包括 \(N>n\) 时的空片。这些区间是成员的闭包络：共享端点或重复坐标处的归属由 slice_id 决定，不能按等长切片的半开坐标区间重新分类。重复坐标仍可能产生零宽切片；密度与消费者要求见下文。

使用 explicit 范围时，包络保证针对切片所用的裁剪后坐标。粒子存储坐标和实际成员极值不变。ECloud 仍会拒绝实际成员超出切片边界的情况；裁剪不代表这些粒子在物理上已进入区间。

当 auto 范围在坐标 \(z_0\) 处具有零跨度时，保存的全部 z_min 和 z_max 都等于 \(z_0\)，全部 delta_z 为零。equal_length 将全部存活粒子放入切片 0，其余切片为空；equal_particle 保留按秩分配。没有存活粒子的束团仍保留空结果。

未分配任何粒子记录的槽只缓存零电荷切片几何并刷新观测时刻，不执行粒子切片，也不保存该槽的快照。保留的几何供电子云等有历史状态的效应推进零电荷时间区间。含已丢失粒子记录或为后续注入预留记录的束团仍按通常流程更新和保存切片。对于未分配记录且使用 auto 区间的槽，ElectronCloud 仅以束团参考时刻作为零电荷观测点，不会把空切片的极小回退宽度当作物理脉冲；显式指定的空区间仍然保留。

如果存活粒子数小于 N，最多只有这些粒子数目的切片能够非空。其余切片仍然保留，粒子数为 0，并记录警告。effective_num_slices 保存 \(\min(N_{live},N)\)；不会修改用户设置的网格大小。

SliceSet 数据

每个束团都有类似 bunch.slice_sets["space_charge"] 的映射。命令执行后，slice_id 是与当前束团粒子区间对齐的整数数组；已损失粒子的 ID 为 -1。slice_table 包含每个切片的数组：

z_min、z_max、z_center: 所选切片坐标中的边界和中心，按从大 z 到小 z 排列（切片 0 是大 z 区间）。
z_particle_min、z_particle_max: 本次 Slicer 执行时，每片存活宏粒子成员在所选坐标中的实际最小值与最大值。使用显式区间裁剪前的坐标，因此可能超出保存的切片边界。空片的极值为 NaN；实际零宽的非空片两端相等。束束 PIC 用这些成员边界进行头尾采样。等粒子数切片按实际秩分配成员求极值，不使用分位数几何边界替代。
delta_z: 每个切片的 z_max - z_min。
macro_count: 存活宏粒子数。
real_charge: 等效真实粒子数，即 macro_count * bunch.ratio，不是库仑。若需要物理电荷，还要乘以带符号的粒子电荷和元电荷。
lind_density: 线性真实粒子密度，即 real_charge / delta_z。非空零宽切片的密度未定义，记录为 NaN；空切片的密度为零。
effective_num_slices: 当前存活粒子群能够填充的切片数上限。

零宽切片仍可用于诊断和将切片视作点源的尾场模型。SpaceCharge 等要求有限密度的消费者会拒绝非空零宽切片。此时应使用有物理依据的有限宽度 explicit 区间，并选择 equal_length 等能够为非空切片提供有限宽度的模型。仅指定显式范围不会消除按秩切片内部重合的边界。 SpaceCharge 仍要求全部保存切片的宽度为正，包括空切片；此既有要求不变。

结果还记录 valid_turn 和 valid_s。之后如果发生全局重分组，所有依赖粒子的字段都会清空；必须等待新的 Slicer 命令执行后，空间电荷或束束效应才能继续使用这些结果。

快照输出

Save turns 是可选的命令级参数，不属于共享 SliceSet 的配置。每项为 [turn] 或 [start, end, step]，两端均包含。切片器每圈仍会计算，只有被选中的圈数才写出文件。每次保存会在 output/.../slice/ 中写出同一时刻的粒子 HDF5 文件（可选 TFS，含 tag、z、slice_id 和损失信息）与逐切片 TFS 汇总，汇总另保存一份 CSV。粒子文件与 TFS 汇总的元数据都记录圈数、位置、Beam、Bunch、切片集合、模型和坐标约定。

超过总圈数的结束圈会截断到最后一圈并记录警告；起始圈大于等于总圈数的范围会被忽略并记录警告。负起始圈也会截断，同时保持原始 start + k*step 的选圈序列。end < start、非整数值和非正步长仍属于配置错误。

职责边界

SortBunch 和 ReorganizeBunch 负责全局束团分组，并且可能重排全部粒子数组。由于粒子范围可能改变，它们会使已有的 SliceSet 全部失效。随后由 Slicer 在序列指定位置重新计算目标集合。空间电荷和束束效应等需要切片的效应可以引用不同名称的集合，因此可以使用不同切片网格。

Important

每次实际执行 SortBunch 或 ReorganizeBunch 后，都必须重新执行 Slicer，才能继续使用切片信息。 排序或重分组会清空原有 slice_id 和 slice_table。后续命令需要使用的每个命名 SliceSet 都必须重新计算，即使同一圈内此前已经执行过 Slicer。

实际执行顺序示例（每个 Slicer 更新后续命令所引用的切片集）：

正确：SortBunch       -> Slicer -> SpaceCharge
正确：ReorganizeBunch -> Slicer -> WakeField
错误：Slicer -> SortBunch -> SpaceCharge

最后一种顺序需要在 SortBunch 与 SpaceCharge 之间再执行一次 Slicer。使用切片的命令不会自动重建失效结果。此规则对 CPU 和 CUDA 均适用。当现有粒子顺序和束团归属没有改变时，Slicer 本身并不要求先执行 SortBunch。

分组操作与参考变换见束团重分组（ReorganizeBunch）。

粒子坐标采用连续的束团相对坐标 \(z_{rel}\)。z_rel 切片直接使用该坐标；z_periodic 和 arrival_phase 使用临时投影，三种模式都不会替换粒子存储坐标。

切片坐标与复用

默认 Coordinate=z_rel 直接按连续时间坐标 \(z=\beta_b c(T_b-t_i)\) 分箱，用于连续尾场时间。 SpaceCharge 必须使用下文的独立选项 z_periodic。独立选项 arrival_phase 为非聚束束流尾场构造临时周期到达投影； Periodic=true 是该选项的别名。连续 z 加上名义分组位置不能重建物理环位置。

后续命令使用最近一次 Slicer 保存的 z 区间、宽度和成员，直到用户再次执行 Slicer。RF 不缩放、不平移、不重建这些数组。当前参考事件下， z_rel 局部宽度 \(\Delta z\) 对应 \(\Delta t=\Delta z/(\beta_b c)\)，中心对应 \(T_b-z_{slice}/(\beta_b c)\)。因此保存的是当前 z 坐标中的区间，不是冻结的物理时间区间。用户负责控制复用误差。结构性重分组使旧的局部索引失效，需要显式执行新的 Slicer。

尾场源在发出时保存采样的物理时间和宽度，后续参考变化不移动历史源。周期到达相位切片另有共同观测窗口，该近似见尾场（WakeField）。准静态 SpaceCharge 使用按环周折叠后的 z 区间；对于任意速度展宽，以速度缩放的时间坐标不等于严格同时的三维空间分布。

Z range mode 支持 auto 和 explicit。粒子存储使用配置的 float32 或 float64，局部分箱中间量使用 float64。CPU 与 CUDA 保存的切片边界、中心、宽度和密度表均使用 float64。粒子存储为 float32 时，CUDA 将局部工作坐标提升为 float64，避免切片几何的舍入使等间距尾场网格变得不等间距；跟踪粒子坐标不变。快照保存连续 z、参考时间、beta 和坐标定义；周期快照还保存 slice_coordinate。密度单位是每米真实粒子数，不是 C/m。

碰撞坐标区间外，输出元数据 ZCoordinate="z_rel" 描述原始粒子 z 列，是输出元数据，不是输入选项，也不是默认值赋值。Coordinate 标识所选切片投影； CoordinateDefinition="z=beta*c*(T-t)"、ReferenceArrivalTime``（秒）和 ``ReferenceBeta 定义原始粒子坐标。到达相位快照还保存 ObservationTime （秒）、ObservationVelocity``（米/秒）及 ``SliceCoordinateDefinition。这些字段与 Circumference 一起定义保存的观测窗口，其时间参数可以与束团参考参数不同。

SliceSet 运行时接口

命令配置会在初始化阶段转换为每个束团独立的 SliceSet。以下字段可供空间电荷、束束效应及诊断模块读取；它们是 Slicer 的输出，不是额外的 JSON 输入参数。

字段	类型	切片前是否有效	说明
`name`	str	是	`Slice set` 指定的用户名称。
`model`	str	是	规范化后的切片模型名称。
`num_slices`	int	是	配置的网格切片数。
`z_range_mode`	str	是	规范化后的范围模式。
`explicit`	`ExplicitRange` 或 None	是	显式模式下的规范化范围边界。
`slice_id`	int 数组	否	与当前束团粒子区间对应的切片 ID；已损失粒子为 `-1`。
`slice_table`	数组字典	否	每个切片的几何和粒子统计数组，详见前文 SliceSet 数据章节。
`valid_turn`	int 或 None	否	生成该结果时的模拟圈数。
`valid_s`	float 或 None	否	生成该结果时的序列位置。

空间电荷的环周折叠切片

Coordinate=z_periodic 构造临时坐标：

\[z_{slice,i}=[(z_i+C/2)\bmod C]-C/2.\]

环周必须有限且为正，折叠不依赖规定时钟。CPU/GPU 均支持 equal_length、 equal_particle 以及 auto、explicit 范围。auto 使用存活粒子折叠坐标的最小值和最大值；explicit 必须位于 \([-C/2,C/2]\) 内。整环网格使用该完整范围，并保留空切片；较窄范围外的折叠坐标进入边界切片。束团跨越折叠边界时，auto 范围可能覆盖接近整圈。

SpaceCharge 只接受该坐标。SC 配置要求对应 Slicer 显式设置 "Coordinate": "z_periodic"；SC 对缺少坐标元数据、z_rel、arrival_phase 均报错。这仍是逐束团的共同参考速度近似，折叠不会重建任意速度展宽下的严格同时分布，也不会合并不同束团中的重叠粒子群。

WakeField 拒绝 z_periodic，因为折叠中心不保留连续到达时间。SC 和尾场应使用分别命名的切片集。Periodic 标志选择 arrival_phase；包括输出文件在内，具体模式由 Coordinate 标识。

非聚束束流尾场的周期到达切片

Coordinate=arrival_phase 要求 equal_length、explicit 及长度为 C 的区间 \([z_{min},z_{max}]\)，例如 Explicit={"z min": -C, "z max": 0} 或中心对称区间 [-C/2,C/2]。每次显式更新令 \(a=n+s/C\)， \(\Psi(t)\) 为规定回旋频率的时间积分。物理窗口端点及线性坐标映射为

\[ \begin{align}\begin{aligned}T_L=\Psi^{-1}(a-z_{max}/C),\qquad T_R=\Psi^{-1}(a-z_{min}/C),\\v_{obs}=\frac{C}{T_R-T_L},\qquad T_{obs}=T_L+\frac{z_{max}}{v_{obs}}.\end{aligned}\end{align} \]

加速时相邻窗口也在规定时钟的圈边界相接；若使用瞬时频率确定窗口长度，就会产生重叠或间隙。中心对称区间对应 \(T_{obs}=(T_L+T_R)/2\)。 CPU/GPU 构造

\[u_i=\frac{v_{obs}}{C}(T_{obs}-t_i),\qquad z_{phase,i}=z_{max}-C[(z_{max}/C-u_i)\bmod1].\]

切片表示窗口 \([T_L,T_R)\)，直到下次用户更新前保留该观测事件。允许不同束团参考时间和速度；参与同一周期尾场的全部粒子群必须拥有相同的已保存观测窗口与周长。切片 0 最早到达，损失粒子 ID 为 -1，存储 z 不折叠。恰好位于周期接缝的相位映射到 \(z_{phase}=z_{max}\)，即窗口起点和切片 0。被排除的右端点的相位按周期等价映射到窗口起点，不归入最后一片，也不额外生成源通过事件。相位滑移诊断继续使用连续、未取模的相位 \(u_i\)。

使用尾场同位置 Slicer 和因果历史。复用周期快照不会推进其观测窗口；每个新的物理源通过事件需要用户更新快照，这与复用局部 z 区间不同。SpaceCharge 使用独立的 z_periodic SliceSet。每参考圈一次穿越近似与收敛要求见尾场（WakeField）。

Max phase slip 默认 0.05 圈，范围 (0, 0.1]。Slicer 记录相邻观测之间的连续相位变化而不拒绝诊断输出，WakeField 检查此限制。同圈重复更新使用相同的上一圈基准，失效操作重置该诊断。它不能重建未采样的穿越，也不能证明短波长模收敛。

等长切片的索引采用 FP64 运算，并在除法后核对相邻的已保存边界，避免将刚位于边界下方的 FP32 坐标误分到相邻切片。CPU、CUDA 和 CUDA 批处理路径的分类与输出表使用同一组已生成边界。按坐标递增方向，等长切片区间左闭右开，最后一个区间包含最大端点。这不改变粒子数组或局部投影的存储精度。