孔径（Aperture）

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

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

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

几何构造和损失处理统一放在本文件中。build_aperture({"Type": ..., "Value": ...}) 构造几何对象；mask(x, y) 包含管壁，strict_mask(x, y) 排除管壁。 这些判断函数接受 NumPy 或 CuPy 坐标数组，在相同后端返回 mask，不修改粒子。 aperture_bounds(geometry) 返回几何范围，供初始化校验使用。

check_aperture_gpu 支持下列全部类型及 float32、float64 粒子坐标，直接在设备上 记录损失。CUDA 核启动前校验几何参数，尺寸可输入整数或浮点数，空束团不启动核。 已损失粒子保留原损失位置和圈数，不属于当前束团范围的粒子不受影响。 CPU 执行不依赖 CuPy。这里的 GPU 支持仅指孔径模块，PIC 与 SpaceCharge 跟踪仍仅支持 CPU。

接口参数

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

属性名

JSON key

类型

说明

aperture_type

Aperture Type

str

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

aperture_value

Aperture Value

list

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

Note

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

丢失粒子处理

CPU 和 GPU 均只保留严格位于孔径内部的粒子。接触任意物理壁即损失，包括多边形 边和顶点；矩形并不要求 x、y 同时达到边界。

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

  • 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 矩形；SpaceCharge 则将 default 解析为 其配置网格同尺寸的矩形，见 空间电荷效应（SpaceCharge）。

丢失条件 ：

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

circle（圆形）

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

丢失条件 ：

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

rectangle（矩形）

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

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

\[|x| \ge w\]
\[|y| \ge 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 \ge 1\]
x y a b

rectcircle（矩形内切圆）

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

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

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

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

Note

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

rectellipse（矩形内切椭圆）

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

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

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

\[|x| \ge w \quad \text{或} \quad |y| \ge h\]
\[\left(\frac{x}{a}\right)^2 + \left(\frac{y}{b}\right)^2 \ge 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| < w \quad \text{且} \quad |y| < h\]

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

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

内部接缝 \(|x|=w\) 处仅当 \(|y|<\min(h,b)\) 时存活；接缝不是物理壁。 其他不在严格内部区域的粒子均损失。

x y w h a b

Note

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

octagon（八角形）

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

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

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

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

polygon（多边形）

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

丢失条件 ：点位于边、顶点或多边形外部。射线法前先用 CPU/GPU 一致的 小浮点容差检查边界。

使用 射线法 （ 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"
}