孔径（Aperture）

本模块介绍 PASS 中的 孔径检查系统 （ Aperture ），用于在粒子追踪过程中检查粒子是否超出束流管的横向孔径边界。孔径检查是束流损失模拟的核心环节，能够标识并记录因横向坐标超出物理管道限制而丢失的粒子。

孔径模块位于 PASS/utils/aperture.py ，提供 CPU 和 GPU 两种实现 （分别通过 check_aperture_cpu 和 check_aperture_gpu 函数调用），在每次元件追踪后被自动调用。调用时传入当前元件的纵向位置 \(s\) 和当前圈数。

孔径检查仅在粒子的横向坐标 \((x, y)\) 上进行，不涉及纵向坐标。每个元件可独立设置孔径类型和参数，支持 10 种孔径几何形状。

接口参数

孔径系统通过两个参数控制：

属性名

JSON key

类型

说明

aperture_type

Aperture Type

str

孔径类型，不区分大小写，可选值见下文

aperture_value

Aperture Value

list

孔径参数值，含义随类型而异

Note

aperture_type 不区分大小写，内部统一转换为小写后匹配。 off 和 default 类型忽略 aperture_value 。

丢失粒子处理

当粒子被判定为丢失时，系统执行以下操作：

  • tag 取负 ： \(\text{tag} \leftarrow -|\text{tag}|\) ，保留粒子 ID 信息，仅将符号取负以标记为丢失

  • lost_position ：记录丢失位置的纵向坐标 \(s\) ，即当前元件的纵向位置

  • lost_turn ：记录丢失时的圈数

已丢失的粒子 （ \(\text{tag} < 0\) ）在后续孔径检查中将被跳过，不再重复标记。仅对存活粒子 （ \(\text{tag} > 0\) ）执行孔径检查。

各孔径类型详解

以下逐一介绍 10 种孔径类型的参数定义与丢失判定条件。

off（关闭）

参数 ：无 （ aperture_value 被忽略）

说明 ：不做任何孔径检查，所有粒子均保留。

x y OFF

default（默认矩形）

参数 ：无 （ aperture_value 被忽略）

说明 ：使用默认的 ±1m 矩形孔径，等价于 rectangle 类型且 aperture_value = [1.0, 1.0] 。

丢失条件 ：

\[|x| > 1.0 \quad \text{或} \quad |y| > 1.0\]
x y +1m -1m

circle（圆形）

参数 ： aperture_value = [r] ，其中 \(r\) 为圆半径。

丢失条件 ：

\[x^2 + y^2 > r^2\]
x y r

rectangle（矩形）

参数 ： aperture_value = [w, h] ，其中 \(w\) 为半宽， \(h\) 为半高。

丢失条件 （满足任一即丢失）：

\[|x| > w\]
\[|y| > h\]
x y w h

ellipse（椭圆）

参数 ： aperture_value = [a, b] ，其中 \(a\) 为半长轴 （ x 方向）， \(b\) 为半短轴 （ y 方向）。

丢失条件 ：

\[\left(\frac{x}{a}\right)^2 + \left(\frac{y}{b}\right)^2 > 1\]
x y a b

rectcircle（矩形内切圆）

参数 ： aperture_value = [w, h, r] ，其中 \(w\) 为矩形半宽， \(h\) 为矩形半高， \(r\) 为圆半径。

孔径区域为矩形与圆的 交集 （粒子需同时在矩形和圆内才存活）。

丢失条件 （满足任一即丢失）：

\[|x| > w \quad \text{或} \quad |y| > h\]
\[x^2 + y^2 > r^2\]
x y w h r

Note

红色虚线为矩形边界，蓝色实线为圆边界。孔径区域为两者的交集。

rectellipse（矩形内切椭圆）

参数 ： aperture_value = [w, h, a, b] ，其中 \(w\) 为矩形半宽， \(h\) 为矩形半高， \(a\) 为椭圆半长轴 （ x 方向）， \(b\) 为椭圆半短轴 （ y 方向）。

孔径区域为矩形与椭圆的 交集 （粒子需同时在矩形和椭圆内才存活）。

丢失条件 （满足任一即丢失）：

\[|x| > w \quad \text{或} \quad |y| > h\]
\[\left(\frac{x}{a}\right)^2 + \left(\frac{y}{b}\right)^2 > 1\]
x y w h a b

Note

红色虚线为矩形边界，蓝色实线为椭圆边界。孔径区域为两者的交集。

racetrack（跑道形）

参数 ： aperture_value = [w, h, a, b] ，其中 \(w\) 为矩形半宽， \(h\) 为矩形半高， \(a\) 为椭圆端 x 方向半轴， \(b\) 为椭圆端 y 方向半轴。

跑道形孔径由中间矩形和两端的半椭圆组成。椭圆端中心位于 \((\pm w, 0)\) 。

生存条件 （满足任一即存活）：

矩形区域内：

\[|x| \le w \quad \text{且} \quad |y| \le h\]

椭圆端区域内 （ \(|x| > w\) 时）：

\[\left(\frac{|x| - w}{a}\right)^2 + \left(\frac{y}{b}\right)^2 \le 1\]

丢失条件 ：不在矩形内且不在椭圆端内。

x y w h a b

Note

橙色圆点标记椭圆端中心位置 \((\pm w, 0)\) 。

octagon（八角形）

参数 ： aperture_value = [w, h, d] ，其中 \(w\) 为半宽， \(h\) 为半高， \(d\) 为半对角间隙 （切角距离）。

八角形为矩形切去 45° 角后得到的形状。 \(d\) 越大，切角越大； \(d = 0\) 时退化为矩形。

丢失条件 （满足任一即丢失）：

\[|x| > w \quad \text{或} \quad |y| > h\]
\[|x| + |y| > w + h - d\]
x y w h d

polygon（多边形）

参数 ： aperture_value = [[x1, y1], [x2, y2], ...] ，顶点列表，自动闭合 （最后一个顶点连接回第一个顶点）。

丢失条件 ：点在多边形外部。

使用 射线法 （ ray casting ）判断点是否在多边形内部：从待测点出发沿水平方向发射射线，统计与多边形边的交点数：

  • 交点数为奇数 → 点在多边形内部 （存活）

  • 交点数为偶数 → 点在多边形外部 （丢失）

x y P1 P2 P3 P4 P5 P6

参数总览表

类型

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], ...]

多边形顶点列表，自动闭合

使用示例

以下 JSON 片段展示了各孔径类型的配置方式。孔径参数作为元件属性, 与 S (m) 、 Command 、 Length (m) 等字段并列:

圆形孔径 :

"Drift1": {
    "S (m)": 10.0,
    "Command": "Drift",
    "Length (m)": 0.5,
    "Aperture Type": "circle",
    "Aperture Value": [0.1]
}

矩形孔径 :

"Drift2": {
    "S (m)": 10.5,
    "Command": "Drift",
    "Length (m)": 0.3,
    "Aperture Type": "rectangle",
    "Aperture Value": [0.06, 0.04]
}

椭圆孔径 :

"Drift3": {
    "S (m)": 11.0,
    "Command": "Drift",
    "Length (m)": 0.2,
    "Aperture Type": "ellipse",
    "Aperture Value": [0.06, 0.04]
}

跑道形孔径 :

"Drift4": {
    "S (m)": 11.5,
    "Command": "Drift",
    "Length (m)": 0.4,
    "Aperture Type": "racetrack",
    "Aperture Value": [0.03, 0.05, 0.02, 0.05]
}

八角形孔径 :

"Drift5": {
    "S (m)": 12.0,
    "Command": "Drift",
    "Length (m)": 0.3,
    "Aperture Type": "octagon",
    "Aperture Value": [0.05, 0.03, 0.01]
}

多边形孔径 :

"Drift6": {
    "S (m)": 12.5,
    "Command": "Drift",
    "Length (m)": 0.2,
    "Aperture Type": "polygon",
    "Aperture Value": [[0.05, 0.0], [0.025, 0.043], [-0.025, 0.043], [-0.05, 0.0], [-0.025, -0.043], [0.025, -0.043]]
}

关闭孔径检查 :

"Drift7": {
    "S (m)": 13.0,
    "Command": "Drift",
    "Length (m)": 0.5,
    "Aperture Type": "off"
}