标记（Marker）

本模块介绍 PASS 中的标记器元件 Marker ，用于在束线中标记一个特定的纵向位置，不改变任何粒子坐标。

标记器代码位于 PASS/commands/element/marker.py ，类名为 Marker ，注册名为 marker 。标记器的核心特征如下：

零长度元件 （ length = 0.0 ，不可配置），不占据束线物理空间
不做任何粒子坐标变换 ，粒子穿过标记器时所有相空间坐标保持不变
支持孔径检查 ，通过 aperture_type 和 aperture_value 参数控制， execute_cpu 中仅调用 check_aperture_cpu 函数
GPU 追踪为空操作 （ execute_gpu 为 pass ），不执行任何计算

标记器的主要作用包括：

在束线序列中标记关键位置（如测量点、对撞点、注入点等），便于后续分析
作为排序基准点，其他元件可参考标记器位置进行布局
在输出和日志中标识物理位置，不参与粒子追踪

物理说明

标记器不产生任何电磁场，不施加任何力，也不改变粒子状态。粒子穿过标记器时，所有六个相空间坐标（ \(x, p_x, y, p_y, z, \delta\) ）保持不变：

\[x \leftarrow x\]

\[p_x \leftarrow p_x\]

\[y \leftarrow y\]

\[p_y \leftarrow p_y\]

\[z \leftarrow z\]

\[\delta \leftarrow \delta\]

标记器仅记录其在束线中的纵向位置 \(s\) ，用于序列排序和位置标注。

当配置了孔径检查（ aperture_type 不为 off ）时，标记器在 execute_cpu 中调用 check_aperture_cpu 函数，对存活粒子（ \(\text{tag} > 0\) ）进行横向坐标（ \((x, y)\) ）的孔径边界检查。超出孔径边界的粒子将被标记为丢失（ tag 取负），并记录丢失位置和圈数。孔径检查的详细原理与各类型定义详见 孔径 章节。

接口参数

标记器的所有接口参数如下表所示：

属性名	JSON key	类型	单位	说明
`s`	`S (m)`	float	m	元件在束线中的纵向位置
`length`	（固定 0.0，不可配置）	float	m	元件长度（恒为 0，不可配置）
`name`	`name`	str		元件名称（由序列 JSON 的键名自动填入）
`aperture_type`	`Aperture Type`	str		孔径类型，默认 `off` ，不区分大小写
`aperture_value`	`Aperture Value`	list		孔径参数值，默认 `[]` ，含义随类型而异

孔径类型可选值

aperture_type 不区分大小写，内部统一转换为小写后匹配。可选值如下：

类型	aperture_value	说明
`off`	忽略	不做孔径检查（默认）
`default`	忽略	默认 ±1m 矩形孔径
`circle`	`[r]`	圆形， \(r\) 为半径
`rectangle`	`[w, h]`	矩形， \(w\) 为半宽， \(h\) 为半高
`ellipse`	`[a, b]`	椭圆， \(a\) 为半长轴， \(b\) 为半短轴
`rectcircle`	`[w, h, r]`	矩形与圆的交集
`rectellipse`	`[w, h, a, b]`	矩形与椭圆的交集
`racetrack`	`[w, h, a, b]`	跑道形（矩形 + 椭圆端）
`octagon`	`[w, h, d]`	八角形（矩形切 45° 角）
`polygon`	`[[x1,y1], ...]`	多边形顶点列表，自动闭合

Note

标记器无需提供 Length (m) 字段，长度在代码中固定为 0。

Command 字段应设为 Marker 。

off 和 default 类型忽略 aperture_value 。各孔径类型的详细物理说明与判定条件见 孔径 章节。

使用示例

基本用法

以下示例在 \(s = 12.5\) m 处放置一个标记器，标记对撞点位置，不启用孔径检查：

{
    "IP": {
        "S (m)": 12.5,
        "Command": "Marker"
    }
}

"IP" 为元件名称，由 CommandSequence 自动读取并赋给 name 属性。

带孔径检查的标记器

标记器也可配置孔径检查，用于在该位置检测超出束流管边界的粒子。以下示例在 \(s = 12.5\) m 处放置一个圆形孔径（半径 0.05 m）的标记器：

{
    "IP": {
        "S (m)": 12.5,
        "Command": "Marker",
        "Aperture Type": "circle",
        "Aperture Value": [0.05]
    }
}

多个标记器组合

多个标记器可在同一束线中重复使用，例如标记对撞点、注入点和测量点：

{
    "IP": {
        "S (m)": 12.5,
        "Command": "Marker"
    },
    "Injection_Point": {
        "S (m)": 0.0,
        "Command": "Marker"
    },
    "Measurement_Point": {
        "S (m)": 105.3,
        "Command": "Marker",
        "Aperture Type": "rectangle",
        "Aperture Value": [0.05, 0.03]
    }
}

应用场景

对撞点标注 ：在对撞机中标记束流对撞位置，便于亮度计算和束束作用元件定位
注入点标注 ：标记注入元件的位置，便于注入器与主环的衔接
测量点标注 ：标记监视器（Monitor）所在位置，便于数据分析与物理量提取
序列排序基准 ：利用标记器的 s 位置作为参考，组织束线中其他元件的排列顺序
孔径监测 ：在关键位置（如对撞点、注入点）配置孔径检查，监测束流损失，无需额外添加物理元件