统计监视器（StatMonitor）

简介

StatMonitor 是束流统计监视器，在指定纵向位置逐圈记录束团的统计量，包括质心位置、束流尺寸、发射度、 Twiss 参数、高阶矩及束流损失等。它是评估束流品质演变和诊断束流动力学行为的核心工具。

代码位置 ： PASS/commands/monitor/statistic.py
类名： StatMonitor ，注册名 "statmonitor"
核心特征 ：
- 逐圈计算束团在 6D 相空间的统计量（一阶至四阶矩）；
- 由二阶矩导出发射度和 Twiss 参数（beta、alpha、gamma）；
- 记录束流损失数与损失百分比；
- CPU 使用 numpy 向量化计算， GPU 使用 CUDA 核函数 + warp 归约；
- 每圈数据追加写入 CSV ，最后一圈统一转换为 TFS 格式；
- 仅统计存活粒子（ tag > 0 ），已丢失粒子不计入。

工作原理

统计量计算

对于束团中的 \(N\) 个存活粒子（ \(\text{tag} > 0\) ），各阶矩定义为：

一阶矩（质心）：

\[\langle x \rangle = \frac{1}{N} \sum_{i=1}^{N} x_i\]

二阶矩：

\[\langle x^2 \rangle = \frac{1}{N} \sum_{i=1}^{N} x_i^2\]

协方差：

\[\langle x \, p_x \rangle = \frac{1}{N} \sum_{i=1}^{N} x_i \, p_{x,i}\]

束流尺寸（标准差）：

\[\sigma_x = \sqrt{\langle x^2 \rangle - \langle x \rangle^2}\]

同理计算 \(\sigma_{p_x}\), \(\sigma_y\), \(\sigma_{p_y}\), \(\sigma_z\), \(\sigma_{\delta}\) 。

发射度与 Twiss 参数

由二阶矩导出 2D 发射度：

\[\varepsilon_x = \sqrt{\sigma_x^2 \, \sigma_{p_x}^2 - \sigma_{x,p_x}^2}\]

其中 \(\sigma_{x,p_x} = \langle x \, p_x \rangle - \langle x \rangle \langle p_x \rangle\) 为协方差。

Twiss 参数：

\[\beta_x = \frac{\sigma_x^2}{\varepsilon_x}\]

\[\alpha_x = -\frac{\sigma_{x,p_x}}{\varepsilon_x}\]

\[\gamma_x = \frac{\sigma_{p_x}^2}{\varepsilon_x}\]

不变量校验：

\[\gamma_x \, \beta_x - \alpha_x^2 = 1\]

垂直方向（ y ）的公式形式完全相同，将下标 x 替换为 y 即可。

高阶矩

偏度（三阶标准化矩）：

\[S_x = \frac{\langle x^3 \rangle - 3 \langle x \rangle \sigma_x^2 - \langle x \rangle^3}{\sigma_x^3}\]

峰度（四阶标准化矩）：

\[K_x = \frac{\langle x^4 \rangle - 4 \langle x \rangle \langle x^3 \rangle + 2 \langle x \rangle^2 \langle x^2 \rangle + 4 \langle x \rangle^2 \sigma_x^2 + \langle x \rangle^4}{\sigma_x^4}\]

束流损失

\[N_{\text{loss}} = N_{\text{total}} - N_{\text{alive}}\]

\[\text{loss\%} = \frac{N_{\text{loss}}}{N_{\text{total}}} \times 100\%\]

其中 \(N_{\text{total}}\) 为束团初始宏粒子数， \(N_{\text{alive}}\) 为当前存活粒子数。

GPU 实现

GPU 版本使用 CUDA 核函数 calc_all_stats ，采用 grid stride loop 遍历粒子，每个线程在寄存器中累加 22 个统计量，经 warp 归约（ __shfl_down_sync ）和 block 归约后，通过 atomicAdd 写入全局结果。块数上限为 512 （因 atomicAdd 竞争开销）。

接口参数

属性名	JSON key	类型	默认值	说明
`s`	`"S (m)"`	float	必填	监视器在束线中的纵向位置
`cmd_name`	`"name"`	str	必填	监视器名称（由序列键名自动填入）
`command`	`"Command"`	str	`"StatMonitor"`	命令类型标识

Note

StatMonitor 无额外配置参数。统计对象为该位置处束团内的所有存活粒子（ tag > 0 ），无需指定粒子编号。

输出文件

每个束团每个监视器位置生成一对文件：

CSV （逐圈追加）： {hms}_stat_beam{bid}_bunch{bid}_Np_{Np}_s_{s:.4f}.csv
TFS （最后一圈由 CSV 转换）： {hms}_stat_beam{bid}_bunch{bid}_Np_{Np}_s_{s:.4f}.tfs

输出目录为 output_dir_stat 。

TFS 文件头：

@ Name             PASS Statistic Data
@ Time             2026-07-14 00:11:03

输出列（共 34 列）：

列名	分组	说明
`turn`	基本	圈数
`xAverage`	质心	水平位置均值 \(\langle x \rangle\)
`pxAverage`	质心	水平动量均值 \(\langle p_x \rangle\)
`sigmaX`	束流尺寸	水平位置标准差 \(\sigma_x\)
`sigmaPx`	束流尺寸	水平动量标准差 \(\sigma_{p_x}\)
`yAverage`	质心	垂直位置均值
`pyAverage`	质心	垂直动量均值
`sigmaY`	束流尺寸	垂直位置标准差
`sigmaPy`	束流尺寸	垂直动量标准差
`zAverage`	质心	纵向位置均值
`dpAverage`	质心	动量偏差均值
`sigmaZ`	束流尺寸	纵向位置标准差
`sigmadp`	束流尺寸	动量偏差标准差
`xEmittance`	发射度	水平 2D 发射度 \(\varepsilon_x\)
`yEmittance`	发射度	垂直 2D 发射度 \(\varepsilon_y\)
`betax`	Twiss	水平 beta 函数
`betay`	Twiss	垂直 beta 函数
`alphax`	Twiss	水平 alpha 函数
`alphay`	Twiss	垂直 alpha 函数
`gammax`	Twiss	水平 gamma 函数
`gammay`	Twiss	垂直 gamma 函数
`invariantx`	校验	水平不变量 \(\gamma_x \beta_x - \alpha_x^2\) （应等于 1）
`invarianty`	校验	垂直不变量（应等于 1）
`xzAverage`	关联	\(\langle x \, z \rangle\)
`xyAverage`	关联	\(\langle x \, y \rangle\)
`yzAverage`	关联	\(\langle y \, z \rangle\)
`xzDevideSigmaxSigmaz`	关联	\(\langle x \, z \rangle / (\sigma_x \, \sigma_z)\) 归一化关联
`beamLossTotal`	损失	丢失粒子数
`lossPercent`	损失	损失百分比
`xSkewness`	高阶矩	水平偏度
`xKurtosis`	高阶矩	水平峰度
`ySkewness`	高阶矩	垂直偏度
`yKurtosis`	高阶矩	垂直峰度
`Ek`	能量	束团动能

使用示例

以下 JSON 片段在 \(s = 0.0\) m 处放置一个统计监视器：

"SM1": {
    "S (m)": 0.0,
    "Command": "StatMonitor"
}

统计监视器不需要额外参数，只需指定位置和命令类型。模拟运行过程中会逐圈记录该位置处束团的统计量。

多位置监视

可在不同位置放置多个统计监视器，比较束流沿束线的统计量变化：

"SM_start": {
    "S (m)": 0.0,
    "Command": "StatMonitor"
},
"SM_mid": {
    "S (m)": 100.0,
    "Command": "StatMonitor"
},
"SM_end": {
    "S (m)": 250.0,
    "Command": "StatMonitor"
}

应用场景

束流品质评估 ：逐圈监测发射度、束流尺寸、质心位置的变化，评估束流品质是否稳定或退化
发射度测量 ：由二阶矩计算发射度和 Twiss 参数，与设计值对比验证
束流损失诊断 ：通过 beamLossTotal 和 lossPercent 监测束流损失率，定位损失发生的圈数和位置
非线性效应识别 ：通过偏度和峰度的高阶矩信息，判断束流分布偏离高斯分布的程度，识别非线性共振或色散耦合
动量 spread 监测 ： sigmadp 和 sigmaZ 反映纵向束流品质，配合纵向动力学研究
关联诊断 ： xzAverage 等关联量可用于诊断色散耦合或横向-纵向耦合