图形界面

使用 python -m pip install pass-sim 从 PyPI 安装界面。 默认安装和 pass-sim[cpu] 均包含 CPU 计算功能与 GUI。 使用 pass-sim[gpu] 或等价的 pass-sim[cpu,gpu] 增加 NVIDIA GPU 依赖。 模拟后端需在输入配置中单独选择，安装 GPU 依赖不会自动启用 GPU 运行。 也可以从 GitHub 克隆仓库或下载并解压源码，在包含 pyproject.toml 的目录中 执行 python -m pip install --editable . 安装。 通过 python -m PASS.gui 或 pass-gui 启动。

启动时优先准备输入 schema，配置页无需加载跟踪命令即可进入可编辑状态。 计算、绘图和格式转换依赖随后继续在后台加载；这些资源的准备状态不影响编辑配置。

  1. 打开 PASS 输入 JSON、.passproj 工程文件或工程文件夹， 或创建新的输入配置。文件夹入口优先使用 project.passproj；没有该文件时， 要求文件夹中恰有一个 .passproj 文件，不会搜索子目录。

  2. 设置全局参数、注入与执行序列。每份属性表单通过 应用修改 写入输入； 未应用的表单与 JSON 文本均为草稿。

  3. 在执行序列工具栏选择 校验，处理报告中的错误。校验范围与报告见 JSON 输入文件检测。

  4. 保存输入或工程，在 运行 页面选择输入并启动模拟。

  5. 打开结果目录，或在 绘图 页面载入输出。

运行 页的 输出根目录 设置父目录路径，旁边可选的 任务名称 可指定 output/capture_sc/ 这样的目录。后者初始直接填写 default，并非占位提示； 已有自定义名称保持显示。 留空或填写 default 时使用精确到分钟的单层 output/YYYY_MM_DD_HH_MM/， 例如 output/2026_10_30_18_39/；比较时去除首尾空白且不区分大小写， 例如 " DEFAULT " 具有相同效果。内部子目录及结果文件命名规则不变， 自动或自定义名称重名时均创建带不补零的 _1、_2 等后缀的同级目录。 对应的输入参数为 Task name， 项目将运行页的选择保存为 run.task_name。设置优先级和重新运行规则见 可编辑项目。

配置页编辑跟踪引擎使用的同一份输入。可编辑工程文件、旧工程转换、运行快照、停止和重新运行见 可编辑项目。独立计算工具位于 工具 页面，详见 GUI 工具。 分析 页面采用与 工具 相同的图标与文字左侧导航，四个并列入口为 统计数据频谱、PM 粒子频谱、频率图分析 和 动力学孔径。 统计数据频谱用于 StatMonitor 的质心、束宽等逐圈统计量；PM 粒子频谱用于 ParticleMonitor 的逐粒子轨迹。各入口分别保留文件、参数和分析结果。 FFT 频谱与频率图可读取模拟结果或外部数值文件；共用 Python 函数、支持格式 和数值约定见 频谱分析与频率图。 分析 → 动力学孔径 用于分析在 Injection 中配置的扫描粒子的观测存活区域。

动力学孔径工作流

在选定的 Injection 束团的 插入粒子 → 扫描粒子 中启用 生成 x–y 扫描网格， 配置以 mm 为单位的 x/y 范围、各轴点数和初始 dp 列表。 每个 dp 对应完整 x/y 网格，固定的 px、py 和 z 默认均为零。 表单显示扫描粒子总数；选择已有束团时载入其保存的网格。 汇总仅显示 Nx × Ny × Ndp = N 个粒子；编辑网格不会修改已配置的宏粒子数或注入时间表。 通过普通 Injection 编辑器应用束团修改。坐标与参考变换约定见 注入与粒子生成（Injection）。

在普通序列编辑器中配置 ParticleMonitor 的位置、同位置 Order、粒子 tag 范围、 记录圈数、输出格式与写入间隔。每个束流、每个监视器输出一个文件。 写入间隔只控制缓冲，记录区间内的每一圈都会保存。扫描生成仅属于 Injection。

在 分析 → 动力学孔径 的 PM 文件 中选择一个当前 PM HDF5 或完成导出的 TFS 文件， 文件内的注入记录提供初始坐标。读取与分类在可取消的后台操作中执行。可按初始 dp 切换，选择存活状态或丢失圈数 着色。显示孔径边界 默认开启，也可关闭以仅显示采样点。图轴为实际初始 x/y，单位 mm。目标圈号表示该监测位置的 采样事件，不能仅凭圈号断言已经完成整圈。缺失初值或末次采样不会自动判为存活。 完整数值可导出为 CSV/NPZ，图形可导出为 PNG/PDF/SVG。取消导出时可能保留已完成写入的 文件；已完成的导出会明确显示成功。

绘图方式 → 多个 dp：边界叠加 用不同颜色和线型显示所选初始 dp 组的边界。 dp 列表初始全选，可逐项勾选或使用全选/清空按钮。内部丢失孔洞及分离的存活区 仍然保留，无法绘制边界的组会明确提示。切回单 dp 模式可查看散点和丢失圈数着色。 图形导出保存当前显示的视图。

启动与文件拖放

打开文件的对话框默认进入当前 .passproj 文件所在文件夹；独立 JSON 模式下进入 该 JSON 所在文件夹。尚未打开文档时，从源码运行默认进入 PASS 项目目录，普通安装则 使用工作目录。浏览外部文件时不使用项目的临时解压目录；输入中相对路径的解析规则不变。

主窗口先显示，再在后台线程加载参数模型、科学计算库和工具模块。导航、主题、帮助和绘图 页面可以立即使用。配置和运行页面在参数模型就绪前显示加载提示，随后自动启用控件、 文件菜单和文档拖放，不必等待其余工具资源。尚未就绪的工具显示加载提示。 模块加载完成后，首次进入某个工具时才创建该工具的 控件和初始图像，不在后台创建尚未访问的工具页面。在同一窗口内切换工具会保留已输入的参数。

状态栏显示资源就绪状态。在此之前，波形/电极预览、MAD-X 预览/导入和 Bump CSV 转换 只显示简短状态提示，不在界面线程等待模块导入；加载完成后可重新执行这些操作。 文件读取和实际计算仍需要时间，首次创建工具页面也可能产生短暂停顿。

可向窗口及其子编辑器拖入一个本地 .passproj、工程文件夹或 PASS 输入 JSON。 替换前先检查文件内容，再确认是否替换；有未保存修改时提供保存、放弃和取消选项。 无效文件或取消操作会保留当前文档。在项目模式下，输入 JSON 可替换当前输入、 作为另一份配置加入项目，或作为独立文档打开。配置选择器显示输入数量， 导入配置… 可向同一项目添加配置。这些配置是独立方案；运行页的 Beam 1 专指双束运行时可选的第二束，并不等于项目中的第二份配置。

在绘图和分析页外拖入单个 OMC3 SDDS/HDF5 文件会打开转换工具（见 数据格式转换），不替换束流参数。 CSV/TFS 可选择用于转换、绘图、统计数据频谱或 PM 粒子频谱，直接拖入转换页则选择转换。 NPY/NPZ/TSV/TXT/DAT 拖入后打开分析页，直接向分析页拖入 CSV/TFS/HDF5 也用于分析。 绘图或分析页处于活动状态时，拖到窗口空白处或标签栏也由当前页面处理。 频谱和 FMA 自动扫描列与数组，选择信号和参数后点击运行分析。 动力学孔径保持在当前页面，并按已选终点圈数自动读取、分析当前 ParticleMonitor HDF5 或完成导出的 TFS 文件。 绘图 和 分析 均支持一次拖入多个数据文件，以及通过顶部 打开文件… 多选文件。 每个文件打开为独立标签页，分别保存数据选择、参数、图形、缩放位置和导出结果。 新分析标签沿用当前分析类型，随后可独立调整。再次拖入同一文件也会新建标签，便于绘制不同视图。 标签显示文件名，悬停可查看完整路径；支持拖动排序和单独关闭。关闭正在读取或计算的标签时， 先取消并等待该页后台任务结束，其他标签仍可使用。关闭全部标签后可继续新建或打开文件。 在单个绘图标签内仍可添加比较文件，用于叠加、差值等比较；批量拖入用于建立独立图形。 工程、输入 JSON 和转换工具仍采用单文件入口；不能把工程或 JSON 与数据文件混合批量打开。 如需同时打开另一个项目，在命令行再次启动 pass-gui 进程即可。

绘图和分析视图提供贯穿当前绘图区的细水平、垂直十字线，始终跟随鼠标位置。 曲线在竖线对应的最近实际样本处单独显示标记；散点图突出鼠标附近的实际数据点。 数值框位于十字线交点附近，显示所标记点的数值；没有对应数据时显示鼠标坐标。 数据标记不会移动十字线，也不生成插值样本。 即使绘图减少了显示点数，取值仍使用底层完整数据。 频谱提示包括频率、幅值和相位；FMA 包括对象标识和频率漂移；动力学孔径包括初始坐标、 dp、粒子标识及存活/丢失信息。十字线可关闭，在离开图轴或按住鼠标拖动平移、缩放时隐藏， 松开后恢复悬停取值，无需退出工具栏的平移或缩放模式； 导出图片不包含十字线和鼠标提示。

属性顺序与分区

属性表单与 JSON 源码分别保留草稿。源码通过 应用源码 或 放弃源码修改 处理。 两处同时存在未应用的修改时，先放弃其中一份草稿，再应用另一份；保存前须处理未应用修改。 Injection、空间电荷、尾场与电子云的表单以整体方式应用，每次应用对应一个撤销步骤； 取消修改 恢复已应用的参数。草稿不会自动备份，手动保存与恢复见 可编辑项目。

属性标题旁显示只读的 Command 类型，可编辑参数从名称、位置 s、长度开始。 元件本身的场强和几何参数排在前面，随后是 Model、Integrator 与切片数。 界面的排列独立于 schema 的继承顺序与打开的 JSON 中键的排列。

序列命令（包括 Injection 和 SortBunch）均显示 Order。 留空或输入 null 使用默认命令优先级；若同一 s 位置的任一命令指定了 Order，该位置所有命令都须填写互不重复的整数顺序。

插入或复制命令、插入生成的光学传输点、导入 MAD-X 项目后，JSON 中的 Sequence 也会按执行顺序自动排序：先按引擎容差分组后的位置，再按 Order 或默认命令优先级。 排序条件相同的命令保留原有相对顺序。排序成功后，每个具有显式 Order 的位置组 按原有执行顺序重新编号为 10、20、30……，每个位置容差组均重新起号。 若一组的 Order 全部省略或为 null，则保留默认优先级行为，不自动赋予显式编号。 如果排序字段无效或不完整，例如同位置的 Order 缺失或重复，则保留 JSON 当前顺序和数值， 由校验报告问题。仅打开文件或应用 JSON 源码不会触发此自动排序或重新编号； 撤销操作会同时恢复此前的序列排列和 Order 数值。

例如二极磁铁 SBend 的顺序为：名称、S (m)、Length (m)、K0L、 E1 (rad)、E2 (rad)、Hgap (m)、Fint、Fintx、Model、 Integrator、Num slices，之后依次为 场误差、安装误差、孔径、Ramping、 内部空间电荷 分区。每个分区包含其开关与相关参数，使用轻边框保持整体感， 全部常驻展开，不设折叠按钮。未启用的内部空间电荷参数仍显示并禁用。

安装误差分区将开关与 DX、DY、DPSI 放在一起。MAD-X 逐元件导入也提供安装误差复选框， 与场误差共用误差 TFS，只移动磁场，孔径和 SC 边界固定。 Twiss 传输导入不提供安装误差选项，详见 元件误差。

其他磁铁沿用相同次序与分区，只显示各自支持的参数。射频腔的射频数据、 激励器的频率与幅度调制、Slicer 的切片范围、监视器的参考光学与分析范围， 也按用途分区；保存电场、电势、电荷密度及保存圈数集中在 诊断输出 中。 Twiss 保留起点光学、终点光学与传输设置分区。

Injection 的束团编辑器分为 束团与注入、横向分布、纵向分布、 分布文件、注入偏移、插入粒子 和 分布输出，沿用轻边框样式，全部展开。 注入摘要位于粒子数和时间表附近。手动坐标、粒子文件和扫描网格集中在 插入粒子 中， 仍为互斥的指定坐标方式。分布输出 将保存开关与格式放在一起；关闭保存时禁用格式控件， 保留已选格式。

注入偏移 中的 Momentum Offset dp``（无量纲 dp/p）和 ``Kinetic Energy Offset (eV) 是同一偏移的两种表示。修改任一项时，另一项根据 当前粒子种类和束团参考动能，通过相对论能量–动量关系同步换算。 修改参考动能时，保留最后编辑的偏移值并更新其换算显示；载入已有输入时也会补全换算显示。 应用表单时，JSON 保存最后编辑的偏移项，另一项写为零，避免重复指定同一偏移。

结构化数组参数

属性栏中的数组和嵌套参数使用专门控件，不需要输入 JSON 括号、逗号或记忆数组排列。 完整输入仍可通过 JSON 源码页编辑。

  • 保存圈数：每行填写起始圈、结束圈（含上限）和正整数步长。 添加单圈 使起止圈相同，添加区间 添加一段范围；全部圈 填入当前仿真范围。 空表表示不保存。圈数从 0 开始，单圈写为 [turn]，区间写为 [start, end, step]。

  • PhaseAdvanceMonitor 的 分析圈数范围：结束圈不包含在范围内， 每段至少包含两圈，空表表示不分析。

  • 手动插入粒子：六列数值表分别填写 x、px、y、py、束团相对 z 和 dp/p。 每行一个粒子，界面显示行数对应的粒子数量，不能超过首次注入的宏粒子数。 手动坐标替换该注入块内的粒子，不会额外增加配置中的粒子总数。

  • 孔径参数：按形状显示带单位的尺寸输入。 圆形、矩形、椭圆、矩形与圆/椭圆交集、跑道形和八边形分别显示半径、半宽、半轴或切角等参数， 单位为 m；多边形使用有顺序的 x/y 顶点表。 在同一表单内切换形状，会保留各形状已经填写的尺寸。 应用时拒绝无效尺寸、退化多边形及无效的八边形切角。

  • 动量接受范围：提供自定义开关，以及 dp/p 上下限； 取消自定义时使用引擎默认的 -1 至 1。

  • KiL / KiSL / Field error KNL / Field error KSL：使用“阶次—数值”表。 0 阶为二极，1 阶为四极，2 阶为六极；未列出的阶次补零，删除一行不会改变更高阶次。 不允许重复阶次。积分强度的 n 阶单位为 m 的 -n 次方。

  • GPU 设备列表：逐行输入整数设备编号，检查重复，设备数量由列表自动计算； CPU 后端下禁用该列表。

  • Slicer 的 显式切片范围：使用 z 上下限数值框，选择 explicit 后启用， auto 不写入显式范围。元件的 内部空间电荷 提供开关、命名配置选择、kick 数、 孔径、输出开关与独立保存圈数表。

表格支持数值单元格、增删行和较大的 表格窗口。 右键可粘贴表格行、复制、调整行序或清空；表格获得焦点时也支持 Ctrl+V。 可以直接粘贴制表符或逗号分隔的数值行，无需转换为 JSON；无效粘贴不会改变已有数据。 表格窗口支持一次添加多行，点击 应用表格 前修改保留在窗口内； 之后再应用属性表单以更新输入。数值编辑支持科学计数法并保留很小的浮点数。 保存时也会提交正在编辑的数值单元格。即使打开的 JSON 省略了可选 bunch 参数， 界面仍会显示这些参数的默认控件。

空间电荷

使用 SC 切片 建立 z_periodic Slicer。通用切片默认 z_rel； 尾场使用 z_rel 或 arrival_phase。兼容项 Periodic 由 Coordinate 决定， 旧输入仅有 Periodic=true 时仍解释为 arrival phase。 切换到 arrival_phase 自动选择等长度切片和显式区间 [-C,0]； 以后修改环长时需重新检查区间。切片不改写连续粒子 z，RF 不重新划分已保存区间， 结构重分组后必须再次显式执行 Slicer。

在 物理效应 中点击 空间电荷 标题，可展开或折叠其子菜单，交互与外层模块一致。 折叠操作本身不修改项目，也不丢弃当前表单；没有返回菜单项。

  • 全局配置：管理模块开关、命名配置、切片集引用、PIC 网格和求解器。

  • 插入计算点：手动在指定位置插入引用命名计算配置的 SpaceCharge 命令。 作用长度和输出选项等计算点参数的含义不变，参见 空间电荷效应（SpaceCharge）。

全局配置中的选项按 Method 和 Solver 联动：

  • pic 只列出 fft_free_space、fd_dirichlet、dst_dirichlet， 沉积方式默认 CIC，也可选 TSC。

  • frozen 和 quasi-frozen 只列出圆形高斯、椭圆高斯、均匀圆盘、均匀椭圆 四个自由空间解析求解器，沉积方式仍显示但禁用。

  • frozen 启用固定源分布中心 Center X/Y，并按公式启用对应尺寸： 圆形高斯为 Sigma；椭圆高斯为 Sigma X/Y；均匀圆盘为 Radius； 均匀椭圆为 Semi-axis A/B。只有椭圆公式启用 Angle。

  • quasi-frozen 根据每个切片当前粒子的统计量计算中心、尺寸和方向， 固定分布参数输入框仍显示但禁用。解析模式下网格参数用于诊断输出采样和默认孔径。

Center X/Y 是源分布中心；Angle 是局部 x 主轴的逆时针转角（rad）； Sigma 是高斯单轴 RMS 尺寸；Radius 是均匀圆盘的外半径； Semi-axis A/B 是均匀椭圆的半轴。中心和尺寸单位均为 m。 这些尺寸描述电荷源分布，不是管壁或粒子损失孔径。切换选项后，不适用字段仍显示但禁用， 保存时写为 null，避免将其他公式的参数带入当前配置。

网格范围输入 可选 全宽 或 半宽，两个方向均以 m 为单位填写； 不使用的一组保存为 null。节点间距由范围和节点数计算。

各 SC 点设置 Aperture type 和 Aperture value， 默认解析为网格同尺寸矩形。孔径用于损失判断，并在 FD/DST 中同时定义导体壁。 不同 FD 管壁使用独立缓存求解器，共享配置网格；FFT 共享核，孔径仅用于损失。 初始化时检查有限 PIC 孔径完整位于网格内，DST 必须使用完整网格矩形。 管壁上或外部粒子在求场前损失。

解析求解器不能保存电势，界面不允许新启用该项；已导入的 true 可以取消。 内部 SC 继承父元件孔径，冲突的旧子孔径会被引擎覆盖。 Num kicks 决定内部 SC 节点数，与父元件输运 Num slices 不同。

注入、时钟、RF 与脉冲元件

Injection 应用表单时保留合法 harmonic ID 排列。Harmonic Number 可直接编辑， 填写分组数后点击 更新谐波槽数，或直接应用表单。增大时自动补齐真实粒子数和宏粒子数均为零的空槽， 沿用当前束团的参考参数，为新槽设置各自的 harmonic ID 和默认参考到达时间。 例如只填充四个分组中的一个时，只填写 bunch0，将其 harmonic ID 设为 0、分组数设为 4， 其余三个槽自动置空。GUI JSON 草稿和导入输入中的束团条目不足时，也会在应用源码或保存/运行时补齐。 保存的输入仍保留完整槽结构；空槽不需要单独配置粒子参数，也不会生成监视器文件。 束团选择器的提示和摘要会标明空槽。该分组数仍与 RFCavity 的 RF 谐波独立。

当前槽置空 和 其余槽置空 将对应粒子数置零并清除粒子来源，保留参考参数、harmonic ID 和分组数。 缩小分组数只移除 harmonic ID 超出新范围的空槽；非空槽须先置空。 这些操作在应用表单前均为草稿。新增/复制非空束团优先使用已有空槽，仅在所有槽都非空时增加分组数。 复制空槽不会创建新槽。删除束团后保留空槽，分组数和其他 harmonic ID 均不变； 如需移除槽，请显式减小 Harmonic Number。 批次摘要显示计划总量、首次/后续批次数量、末次注入圈和宏粒子权重；新增束团沿用已有权重。 分布文件支持 sequential 和 repeat。 随机种子与参考到达时间可清空为 null。电极损失使用独立 ElSeparator 配置。 整数文本输入支持 1e5、2.5e3 等精确整数科学计数法，保存为普通 JSON 整数； 拒绝非整数结果、NaN 和无穷大。粒子数字段仍不受有符号 32 位上限限制， 已有范围限制的控件保持各自范围。

共同设计时钟由初始束流、环周长和启用的 RF 波形自动计算，全局配置不再输入时钟表。 它独立于集体效应对实际粒子的影响。需要保留外部 RF 频率程序时，使用分量的直接频率模式。 设计计算与迁移限制见 自动设计时钟与初始化。

RFCavity 分量支持内联/文件、谐波/直接频率模式。电压、相位与直接频率可选择常数或共享 Time (s) 的时间表。文件需有 TIME/VOLTAGE/PHASE，直接频率模式另需 FREQUENCY， 谐波模式的文件则不得包含 FREQUENCY；应用时清除不适用的互斥输入。 物理波形预览使用跟踪器相同的频率积分，绘制各分量与总电压，可指定物理时间窗口。 预览不计算多谐波势阱。旧腔级参数和按圈 RF 文件需要按物理时间迁移，不能只改字段名。

元件库提供 Bump 与新版电压/几何 ElSeparator。必填物理量保持空白，填完才能应用。 Bump 预览 TIME/HKICK/VKICK，并可将两平面 CISP CSV 转换为一个 TFS 文件。 转换保留两平面时间节点的并集，各自区间之外采用端点值。 预览的参数校验、文件路径、TFS 格式、数据及单位错误均显示中文说明。 横向动量增量为积分 ΔP/P0；预览包含时间偏移，并在各平面的原始时间范围外保持端点值。 两份 CSV 的时间节点和范围可以不同，转换时保留它们的并集。 预览ES 显示倾转电极、循环束无场区和有场区，并在束流坐标中用虚线绘制独立真空孔径。 rectcircle/rectellipse 只绘制实际交集的边界，不把两个完整组成边界同时当作孔径。 电极覆盖任意局部 v，图中只截取有限范围显示。 ES 的 硬件参数 分组使用中文标签：电压差 V、积分电压 VL、场隙宽度、 隔板位置、隔板厚度和倾角，保留对应单位与 JSON 参数名。 须填写 Gap 和 Septum position；缺项会提示具体字段。 V、VL 均未填时允许只预览几何，不计算电场；应用和运行要求二选一。 V 单位为 V，VL 为电压差沿纵向的积分，单位为 V·m。 Distribution File Mode 的输入框和展开列表按选项文本加宽，支持完整查看 sequential/repeat。 S 是出口，入口为 S-Length；零强度仍有材料损失，零长度支持一次 VL 薄冲量。

Exciter 使用带符号 Kick angle (rad) 设置幅度，以 1e-6 形式的科学计数法显示， 提供 tune/频率选择及 FM/AM 字段联动。 元件不再输入电压、间隙和长度；激励工具按指定参考粒子和能量提供电压与踢角的双向换算。 新建草稿默认使用 tune 模式， Excite tune = 0.47、Sweep tune = 0.02；已有频率模式输入保留其 Hz 数值。 四极、六极、八极和多极铁开放 Is ramping 与 Ramping file， 读取以物理时间为自变量的归一化强度 TFS 表，见 磁铁 ramping。 Ramping 分组中的 生成 / 导入 ramping 文件… 支持上升–平台–下降模板和 数值表粘贴；成功导出后在属性草稿中回填文件路径、启用 ramping 并清空旧分量文件字段， 应用或插入元件后保存修改。具体操作见 GUI 工具。 其他磁铁元件暂不开放 ramping。

横向反馈

横向反馈 组件区提供 TransversePickup 与 TransverseFeedback。 先添加拾取器，再通过反馈的 Pickup 字段选择其序列名称；每个拾取器必须恰好配对一个反馈。 反馈草稿的系数和增益初始为零，跟踪前应填写 FIR 系数、圈数延迟、增益及可选限幅。 两个节点均须放在真实传输边界。相位约定、滤波器设计和诊断见 逐束团横向反馈。

反馈参数面板中的 生成 FIR 系数… 打开系数生成窗口。 所引用拾取器的 Plane 决定生成 x、y 或两个方向的系数。 各方向分别填写 tune 和拾取器到反馈点的相移；这两项初始留空，不从机器配置猜测。 相移单位为 rad，表示同一序列圈号下的有符号相位差；反馈点在上游时可以为负。 S (m) 位置不能决定相移，也不要在相移中重复计入已由圈数延迟表示的整圈相位。

两个方向共用设计方法、系数数量和延迟。方法可选 minimum_norm （默认）或 flat； GUI 接受 3–256 个系数，其中 flat 至少需要五个，延迟必须为至少一圈的整数。 256 个系数的上限仅用于 GUI，design_feedback_fir 辅助函数没有这一上限。 先点击 计算并预览，检查结果后再点击 填入草稿；设计无效时，参数草稿保持不变。 平坦响应只描述目标 tune 附近的局部性质，不保证闭环稳定性，也不自动选择增益。

填入时替换所有测量方向的系数列表，清空未测量方向的系数，并同步 Delay turns。 增益保持原值，包括初始的零增益。生成的系数仍可手动编辑；点击 应用 或 插入 后才保存草稿。设计输入仅为 GUI 临时控件，保存的仍是已有系数和延迟字段， 不增加 JSON 字段或电子学模型。

尾场

尾场 → 全局配置 管理总开关及命名模型/求解器配置。打开时将已有尾场点的内联 参数分别收集为独立命名配置草稿，不合并原来的定义。应用配置重命名时同步更新点引用； 仍被引用的配置不能删除。尾场点 设置配置引用、位置、切片集和单点开关。 总开关与单点开关均开启才执行；即使引用同一配置，各点也保留独立历史状态。 旧的内联 Groups 输入仍受支持。JSON/API 表达见 尾场（WakeField）。 配置内可添加、复制、移除命名求解组和分量。 支持 direct、fft、recursive、modal、partitioned_fft、time_fft 六类求解器， history、网格、记忆长度和周期边界控件随模式变化。 编辑器覆盖九类模型、custom 分量的空间幂次，以及 fixed/factorized/ideal 速度模型， 由共享 schema 检查组合。文件模型要求明确单位、坐标轴、符号、积分量约定和 reference beta， 不会猜测未知外部文件约定。

电子云

物理效应 → 电子云 提供 全局配置、插入电子云切片 和 电子云作用点。 先建立命名配置、选择模式与求解器，再插入引用该配置的作用点。 全局 Enabled 与单点 Is enabled 必须同时开启。 即使引用同一配置，各作用点也拥有独立电子云状态。 界面写入 电子云（ElectronCloud） 描述的普通输入格式。

模式与求解器选择

模式

求解器

行为与切片要求

frozen

uniform_round_free_space、fft_free_space、fd_dirichlet 或 dst_dirichlet

固定电子云施加横向束流踢角；不依赖 Slicer。

build_up

round_gaussian_beam

预设圆高斯束流驱动电子运动及壁面发射；不计电子云自场，也不反踢束流。需要 Slicer。

coupled

fd_dirichlet

已保存束流切片的真实粒子驱动电子，计入电子云 PIC 自场与横向束流踢角。需要 Slicer。

编辑器将源参数、网格与边界、电子运动与壁面发射分组，按模式和求解器显示适用控件。 电子密度是以 m−3 为单位的真实电子数密度，在动态模式中仅表示初始密度。 电子云圆盘半径、圆形真空室半径和束流 RMS sigma 是三个独立参数。 必填项包括密度和圆盘半径；动态模式还须填写真空室半径、正的最大时间步长和正的束流 sigma。 Beam sigma 仅控制 build_up；coupled 保留 schema 的必填字段，实际使用已保存束流粒子。 整个初始电子圆盘须严格位于真空室内部。

静态自由空间求解器接受 default/off 边界；FD 支持现有导体孔径形状； DST 要求完整网格矩形。动态模式使用 Build up 中的圆形真空室。 耦合网格的 Nx/Ny 须为不小于 5 的奇数，网格全宽须覆盖真空室直径， 网格间距不得超过真空室半径的一半。这些条件只检查几何是否得到基本分辨， 用户仍需选择并检验数值分辨率。动态表单还提供均匀磁场、磁场梯度、初始能量、 初级与二次发射、宏电子数上限、积分步数上限和单步壁面碰撞上限。 不指定随机种子时写入 JSON null；显式整数种子使相同输入的采样可复现。

每个动态作用点都须显式插入或选择 Purpose=general、Coordinate=z_rel 的 Slicer，与作用点处于相同 S (m)，并在执行顺序中先于作用点。 切片须覆盖全部存活粒子，周期切片与束束专用切片不适用。 结构重组后须重新执行 Slicer；电子云作用点不会自动生成或刷新切片。 校验 会报告缺失的配置/切片引用，以及不兼容的执行顺序或坐标。

作用点提供位置、顺序、配置引用、切片集、作用长度、单点开关、Save fields 和 Save turns。作用长度缩放 frozen/coupled 的踢角，不负责输运束流； build_up 仍要求该字段，但它不改变该模式的电子动力学。实际输运需另行添加。 输出圈数从零计数，[start, end, step] 范围包含两端； 只有开启 Save fields 并选择输出圈数才保存，空 Save turns 不输出。

全局编辑器支持新增、复制、重命名和移除命名配置。 应用重命名时同步更新作用点引用；仍被引用的配置不能移除。 切换模式、求解器和边界形状时保留编辑草稿，切回原选择可恢复输入。 应用将完整修改记为一个撤销步骤，取消恢复已应用输入；关闭总开关保留已经保存的配置定义。 JSON 或项目保存后重新打开，保留三种模式的参数及 null 种子。

跨项目输入复制作用点时，同时复制命名配置；动态作用点还复制引用的 Slicer 定义。 重名时添加后缀，并更新新副本的引用，不改写目标原有总开关。 动态复制会比较规定物理时钟，不同时提供明确选择；冻结云复制无需选择时钟。 复制输入定义不会转移运行中作用点的电子状态。

结果文件

绘图页支持 CSV、TFS 和 DistMonitor 一维 HDF5 列。 可同时载入多个文件，选择 beam/bunch/turn 快照，筛选存活/损失粒子和注入批次， 查看配套参考量与未注入粒子计数。 仅对拥有配套逐行或快照参考时间与 beta 的存活粒子生成 arrival_time_s； 损失粒子的冻结坐标不使用后续活粒子参考量换算。 缺失数值不会打乱列之间的行对应。多维 SC 文件进入独立场视图，不当作粒子表。

显示方式可选择自动、折线或散点。自动模式对包含 tag 或 particle_id 的粒子表 使用散点，其余表格使用折线；缺失样本会断开折线，单个有限样本显示为点。 大量数据的预览会减少显示点数，但不修改原始数据。 坐标轴显示所选列名，每份已加载文件分别记忆坐标列、显示方式和粒子筛选条件。

摘要显示总行数、筛选行数与有限点数。关闭当前数据 卸载当前文件； 文件载入支持取消。 HDF5 表格读取在数据块之间检查取消请求。载入后的数组是一份独立快照，后续修改源文件 不会悄悄改变已显示或导出的数据；需要使用新数据时应重新载入文件。

相空间预设在对应列存在时选择 x–px、y–py、z–dp、x–y 或到达时间–dp。 轴标签使用已有列单位和参考量元数据，不猜测普通 CSV 的物理单位。 密度与投影 将全部有限 X/Y 配对分入 8–256 个箱，显示二维计数及两个方向的边缘计数； 这里统计宏粒子行数，不按电荷加权。 大数据的密度统计在后台执行。再次修改选择会丢弃旧计算结果；最新选择计算完成后， 显示对应预览并启用图像导出。直方图仍统计全部有限配对，电子云源视图仍使用保存的 电子数权重。

选定基线后可叠加、计算 A−B 或 (A−B)/B。要求 X 数值及行序完全一致且有限，单位、 坐标与参考态约定兼容，提供 particle_id 时其顺序也须一致；不隐式排序、插值或换算单位。 相对差的基线为零或非有限值时输出 NaN。密度模式须先切换到折线或散点再比较。

导出数据 使用完整筛选行和所有数值列，保留 NaN 与数值类型，同时生成带哈希验证的 pass-table-metadata-v1 格式 .csv.metadata.json；应将它与 CSV 一起保留， 重新读取会拒绝过期或不支持的 sidecar。导出图像 用完整筛选数据及完整范围生成 独立 PNG/SVG/PDF，不使用缩减后的预览数据。高级图形提供 Matplotlib 导航工具栏； 导出使用当前选择并显示进度；取消时可能保留已经完成的文件。 CSV 与元数据文件应配套保留。

SC 场数组须按 (slice, y, x) 保存，并包含匹配的 x/y 网格、slice_id 和 delta_z。 可选择场量与切片，并叠加保存的实际孔径轮廓。原始电荷密度、电势和积分 Ex/Ey 的单位 分别为 C/m²、V·m 和 V；勾选 除以 Δz：显示切片平均量 后得到 C/m³、V 和 V/m， 要求切片宽度为正有限值且单位已知。页面显示保存的求解器、势零点及边界元数据。 场数据导出按 y/x 行序展开所选切片，保留原始场量，平均量选项额外添加对应列；不重新求场。

电子云 HDF5 输出使用独立的 电子云视图 选择器，按实际保存的数据提供 瞬时场图、带权电子分布 和 时间历史。 冻结解析场输出包含场，冻结 PIC 还可包含宏电子采样； build_up 提供源与历史，coupled 另外提供最后保存物理时刻的场。 元数据标明模式、求解器、源长度及场对应时刻。

源视图可选择实际保存的 x、y、ux、uy、uz 或 weight 列。 二维直方图与边缘投影按箱累加保存的电子数权重，表示给定源长度内的真实电子数， 不是宏电子行数，也不是体密度。历史视图以物理时间区间的结束时刻 time_end``（秒）为横轴，默认显示 ``n_electrons_after， 还可选择已保存的发射、壁面碰撞、推进步数等诊断量。

电子云场的体电荷密度、数密度、电势和电场单位分别为 C/m³、m−3、V 和 V/m。 它们已经是物理瞬时场，不提供 SC 的切片宽度相除操作。 所选视图可导出为带元数据 sidecar 的 CSV，或 PNG/SVG/PDF 图像。 源导出保留保存的粒子权重，历史导出保留全部诊断列及阶段 ID，场导出使用保存的网格； 导出使用完整选定数据。

Twiss 与光学

组件库按以下顺序排列：

  1. 从 MAD-X 文件导入 Twiss 点。

  2. 插入单圈传输矩阵。

  3. 生成平滑近似 Twiss 序列。

  4. 插入 Twiss 传输点。

MAD-X 入口支持下述采样方式。两个生成器均先点击 预览生成，再点击 插入到 Sequence。预览不修改项目，显示命令数量、位置范围、计算得到的 beta、 步长、总相移和前 100 个点。插入时写入全部生成点，包括未在预览表格显示的点。 名称冲突时自动添加数字后缀，预览显示最终名称。若同一环周范围内已有光学传输， 预览会提示新增传输可能造成重复传输。

修改生成参数会使预览失效，并禁用插入按钮，直到重新预览。 序列、全局周长或未确认的 JSON 发生变化，也会阻止插入旧预览。 周长默认读取全局值，插入时将全局周长同步为生成器显示的值，并保留已有命令。 离开已修改的生成器时，界面会询问是否放弃尚未插入的草稿。

MAD-X 来源与参考束流

逐元件导入和 Twiss 点导入均提供 数据来源：已有 Twiss/TFS 沿用 TFS 工作流， MAD-X sequence 通过 cpymad 加载 .seq 或 .madx 源文件； cpymad 是 PASS 必选依赖，安装 PASS 时自动安装。

选择 sequence 来源后，指定 Sequence 文件 与 格架名称，后者默认为 ring， 支持 MAD-X LINE 和 SEQUENCE 定义。束流来源 可选 文件中的 BEAM 或 PASS 束流配置。文件方式要求明确的束流声明；PASS 方式必须选择 PASS 参考束团，显示为 Injection 名称与 bunchN，不会默认使用第一个束团。 该选择为 MAD-X 提供一个参考束流，不会覆盖 PASS 的束流配置。

导入 Twiss 点或插入 PhaseAdvanceMonitor 时，光学计算 提供 MAD-X TWISS 与 PTC TWISS。普通逐元件导入无需计算光学。 使用 PTC 四极端场的模型需要选择 PTC；其输出会转换为受支持的无耦合 Twiss 映射约定。 不支持的闭轨、垂直色散或耦合会停止导入。逐元件转换保留 sequence 中的四极 F1/F2 和受支持的直磁铁端场控制参数，见 物理入口和出口端场映射。 其他尚不支持的端场参数仍会停止导入，不会被静默忽略。

先执行 预览导入，再 导入到 Sequence。预览包含格架名称、MAD-X 版本、 参考束流选择及来源警告；预览与导入复用同一次加载结果。 修改源文件、格架名称、束流选择或光学计算选项会使对应缓存失效。 修改脚本引用的其他文件后，使用 重新加载 sequence 强制重新加载并预览。 原有采样、BPM 与几何检查选项仍然适用。Python 工作流与 PTC 导数换算见 方式四：直接加载 MAD-X SEQUENCE 或 LINE。

导入元件时批量设置属性

逐元件导入时，勾选 按元件类型批量设置属性，选择 元件类型 与 要统一设置的属性，点击 添加属性设置 并填写值。可为同一类型或不同类型添加多项设置。 例如，将本次导入的所有 SBend 的 Model 设为 rot-kick-rot， 所有 Quadrupole 的 Num slices 设为 20。 仅覆盖本次导入中匹配类型的指定属性；未选择的属性和已有 Sequence 条目保留原值。 Command、位置与长度使用来源数据。

预览会校验覆盖后的元件并列出批量设置，无效设置会阻止插入。 显式 Order 仍须满足同位置所有命令均指定且互不重复的要求。 设置保留在草稿与保存的导入配方中。改变孔径形状时，先添加 Aperture type， 再添加 Aperture value，使数值编辑器使用所选几何形状。

普通 SBend 属性表单也提供 rot-kick-rot，与 adaptive、 drift-kick-drift-exact 并列；Quadrupole 的对应矩阵模型为 mat-kick-mat。

MAD-X 采样方式

采样方式 默认选择 保留原始位置。选择 等间距插值 后启用正整数 一圈分段数 N，生成从 0 到 C、间距 C/N 的 N+1 个基础点。 该模式禁用并忽略 是否合并连续 Drift，不设高级插值参数菜单。

点击 预览导入 可查看实际间距、基础点数、附加拆分位置数、Twiss command 数量 和水平、垂直两个平面的完整相位差，再点击 导入到 Sequence。 导入结果仅包含重采样点及必要拆分点，不同时导入原始 Twiss 行。 导入仍追加到当前 Sequence；若用于替换已有传输，应先移除那部分旧传输。 修改采样参数或源文件后，缓存的导入结果会失效。

插值共同使用原始相位、beta 和 alpha：在每个源区间内，用五次 Hermite 多项式 表示累计相位，其一阶、二阶导数在两端匹配 beta 和 alpha 给出的值， 再由同一个多项式求出 beta、alpha。色散采用三次 Hermite 插值，在支持的无耦合、 参考轨道近轴约定下，以 DPX 作为 DX 的斜率。公式及 Python API 见 输入文件生成（命令行模式）。

源文件必须覆盖 0 至 LENGTH，beta 为正，累计相位保持展开、递增，并与 Q1/Q2 一致。 缺少端点时不做外推。程序检查整个相位多项式的斜率为正；若检查失败，需要从 MAD-X 导出更密集的源数据。仅增加 N 不能恢复源文件中缺失的信息。 源值和总相位差保持到浮点精度；核对 TFS 头中的工作点时允许文件输出舍入误差。

薄元件和场误差保留原始位置，并在此处拆分 Twiss 传输。 零长度 BPM 标记和显式选择的监视器也保留准确位置；有限长度 BPM 的监视器位于中心。 同一 S 的不同光学状态保留为入端、出端状态，通过零长度 Twiss 传输表达光学跳变。 因此最终位置不一定全部等间距。同一位置先执行 Twiss，再执行附加薄元件或场误差。 源光学已包含设计线性聚焦，显式插入的薄元件是附加作用，不会从源光学中扣除或替换 设计聚焦。因此，附加线性误差仍可能改变跟踪工作点，而重采样的基础光学保持源工作点。

MAD-X BPM 导入

MAD-X 的 MONITOR、HMONITOR、VMONITOR 使用相同的 BPM 导入选项。 BPM 处理 中的 在 BPM 位置插入 PASS monitor 默认不勾选。 勾选后选择 Monitor 类型 并填写 Monitor 参数，即可在选中的 BPM 处添加 StatMonitor、ParticleMonitor、DistMonitor 或 PhaseAdvanceMonitor。 参数控件与普通监视器编辑器一致。逐元件导入采用以下规则：

BPM 长度与记录开关

长度

未启用记录或 BPM 未选中

已启用记录且 BPM 选中

L = 0

Marker

在 S 处放置所选监视器

L > 0

长度为 L 的一个 Drift

半段漂移 → S-L/2 处的监视器 → 半段漂移

TFS S 表示 BPM 出口，因此 S-L/2 为其中心。启用记录不额外添加 Marker。 不记录时，有限长度 BPM 漂移可与相邻漂移合并；启用记录后，合并仍保留中心监视器。

默认记录所有 BPM。勾选 只选择匹配的 BPM 可限制范围。BPM 名称 接受原始 MAD-X 精确名称，以逗号或换行分隔；BPM 正则 每行填写一个正则表达式，表达式内的 逗号会保留。两项均不区分大小写，取匹配结果的并集；正则表达式采用搜索匹配。 启用筛选但两项均为空时，不选择任何 BPM。未匹配的 BPM 仍按默认规则转换。 无效正则表达式会使预览报错。

严格检查几何一致性 默认不勾选。启用后，局部位置、传输区间或周长不一致会导致 导入失败。逐元件模式要求累计长度与每个元件出口一致；Twiss 模式检查传输区间， 不要求采样行长度之和等于周长。即使未启用严格检查，漂移合并也始终要求物理区间连续。

源文件含有 BPM 时，预览还会打开可滚动的 BPM 转换表，显示原始名称、出现序号、 MAD-X 类型、长度、原始出口 S、是否插入 monitor、测量位置、转换结果及合并后的 最终项目。每个最终项目列出名称、命令、S、长度与合并状态，便于区分同名的多个 BPM，也能追溯已并入更长漂移的 BPM。

ParticleMonitor 必须填写 Max tag。用圈数范围表设置 DistMonitor 的 Save turns 和 PhaseAdvanceMonitor 的 Turn ranges；空范围分别表示 不保存分布和不进行相位推进分析。相位推进监视器的光学参数从各 BPM 源行 读取；有限长度 BPM 的光学参数沿半段漂移反向传输到监视器中心，色散转换到 PASS 单位。 闭轨偏置默认为零，如需扣除偏置，应根据生成的跟踪模型显式设置。

两个 Twiss 导入模式保留 Twiss 传输，并在上述监视器位置插入或拆分传输点， 等间距插值也保留准确的中心位置。修改 BPM 设置会使导入预览失效。 筛选与严格检查设置会保存在导入草稿及配方中。 Python API 和监视器选项见 MAD-X BPM 标记与监视器。

单圈传输

输入名称、周长 \(C>0\)、tune \(Q_x,Q_y\) 和一组周期光学参数 \(\alpha_x,\alpha_y,\beta_x,\beta_y\)，表单按此顺序排列。 Beta 必须为正，由用户独立输入，不使用平滑近似公式推导。 水平色散 \(D_x\)、色散导数 \(D'_x\) 和单圈色品 DQx、DQy 也直接显示在同一表单中，不设高级参数折叠区。所有数值输入必须有限。

生成器将 alpha、beta 和色散复制到两端，设置 S previous (m) = 0、 S (m) = C，起点的水平和垂直 Mu 为零，终点分别为 \(Q_x,Q_y\)。 因此，虽然两端周期光学函数相同，传输长度仍为 \(C\)，相移仍为 \(2\pi Q\)。

纵向传输支持 off、drift 和 matrix。只有 matrix 模式启用 纵向 tune \(Q_s\)；终点 Mu z 为 \(Q_s\)，起点为零。 其他模式生成的纵向相移为零。引擎的 matrix 模式还使用束团纵向尺寸和动量展宽， drift 模式使用滑移因子和传输长度。跟踪公式参见 Twiss 参数输运（Twiss）。

平滑近似

输入 \(C>0\)、正的完整 tune \(Q_x,Q_y\) 和正整数 一圈分段数 \(N\)。计算平滑近似 beta 时，不应只填写 tune 的小数部分，例如应输入 9.47，而不是 0.47；表单标签标明了“完整工作点”：

\[\beta_x = \frac{C}{2\pi Q_x},\qquad \beta_y = \frac{C}{2\pi Q_y},\qquad \Delta s = \frac{C}{N}.\]

界面以 num_points=N+1 调用 generate_smooth_twiss，得到 \(s=0\) 处的初始单位传输点，以及结束于 \(C\) 的 \(N\) 段传输。 位置为 \(s_i=iC/N\)，相位线性分配，每段色品为 DQx/N 和 DQy/N， 初始点色品为零。名称使用用户指定的前缀和点序号，短步长不会因位置舍入导致重名。

Alpha 默认为零。常数 alpha、色散、色散导数和单圈色品直接显示在表单中， 不设高级参数折叠区，保留现有生成器的行为。 标准平滑光学使用零 alpha；非零常数对应自定义传输矩阵序列。 纵向模式与单圈表单一致。该入口仅生成 Twiss 命令，不生成 SpaceCharge 计算点。

手动传输点与后续编辑

选择 插入 Twiss 传输点 可添加传输映射。一个命令描述两端之间的传输， 因此表单分为 起点光学参数、终点光学参数 和 传输设置。 Mu 为累计相位，单位为周（\(2\pi\)），不是弧度。

两个生成器均写入普通 Twiss 命令；项目还会保存生成设置和 MAD-X 导入源文件。 插入后或重新加载 JSON 后，在序列中选择生成的命令，逐个编辑两端参数。 独立输入使用 保存 JSON，完整项目使用 保存项目。 在 项目内容 中可以载入生成设置，重新预览和插入，不会自动覆盖已经手动修改的命令。

Exciter 预览使用实际局部参考到达时间与连续 z： t = T_start + elapsed - z/(beta*c)。 DDS 相位从共同启动时刻 T_start 积分频率，扫频回扫时保持连续。 双频默认错开半个扫频周期，使用其他偏移时给出警告；名义束团槽位不平移该预览。 两个 DDS 信号共用一个踢角设置。AM 与 FM 使用同一连续的粒子经过时间， 归一化使用启动时的参考钟频率。角度作为归一化横向动量增量施加， 不会随跟踪中的束流能量自动缩放。 RF 命令属性使用 Components 列表配置规定的物理时间波形。

工具

工具 提供束流参数计算器、共振线图、RF bucket、相空间绘制与发射度计算、 磁铁参数换算、激励计算和数据格式转换。计算独立于当前模拟输入。 离子与原子使用每核子动能 AMeV；A=0 的粒子使用每粒子动能 MeV。 粒子质量取自随程序提供的评估质量数据。单位、公式、数据来源与操作见 GUI 工具。

主题与控件

顶部可选择深色、浅色或跟随系统的主题。窗口与侧栏尺寸、主题及执行序列的列设置 保存在本机。拖动表头分隔线调整列宽，右键选择其他列；名称、Command 和位置列始终显示。 执行序列按引擎的位置分箱和命令优先级排列，悬停位置列可查看完整数值。

左侧组件库默认展开 输入配置（必需）。物理效应 中的空间电荷、尾场、束束效应和电子云 具有独立子菜单。

当前模式适用的属性字段保持展开，长表单可滚动。展开 使编辑器占据整个工作区， 还原 恢复原布局并保留草稿。下拉框通过单击选项改变选择；展开列表后的滚轮 仅用于浏览选项。

帮助与本地文档

主题按钮旁的 帮助 菜单提供 在线说明文档 （中文 / English）、源代码、 阅读本地文档 （中文 / English）、重新编译本地文档 和 关于 PASS。 网页链接和本地 HTML 均使用系统默认浏览器打开。

本地编译需要完整 PASS 源码，并在启动 GUI 的同一个 Python 环境中安装文档依赖。 在源码目录执行:

python -m pip install --editable ".[docs]"

每次点击 重新编译本地文档 都使用 GUI 的 Python 解释器，对中英文文档进行完整的 Sphinx HTML 构建。编译在独立进程中运行，界面仍可操作。进度窗口显示实时日志， 并提供停止按钮；关闭进度窗口后编译继续，可通过帮助菜单中的 查看编译日志 重新打开。 编译期间禁止重复启动；编译过程中关闭 PASS，会询问是否停止编译后退出。

每次构建写入独立的 docs/build/gui/<timestamp-id>/ 目录。只有构建成功、没有 Sphinx 警告且各语言首页均存在时，才更新 docs/build/gui/latest.json 指向新结果。 失败或停止编译后，上一次成功的文档仍可阅读。构建目录保留，重新编译不会删除旧结果。 阅读本地文档 直接打开已保存的结果，不会触发重新编译；没有 GUI 构建结果时， 尝试读取常规命令行输出 docs/build/html/。尚无本地页面时，提供立即编译和在线文档入口。 缺少源码、依赖或文件系统错误会显示原因和处理提示；GUI 不会自动安装依赖。 不包含源码目录的普通安装可阅读在线文档，但无法本地编译。

关于 PASS 的项目简介、作者、机构、版权、许可证和操作均同时显示中英文。 每位作者独占一行，包含中文姓名、英文姓名和可点击的邮箱。说明文档、源代码和 问题反馈均为可点击链接。许可证优先在只读窗口显示原文，本地文件缺失时打开在线许可证。

从源码目录运行时，版本取自该源码目录的 pyproject.toml；普通安装包使用安装元数据。 修改源码版本后需重启 GUI，无需仅为刷新此版本显示重新安装；依赖或入口点变化时仍需 执行安装。复制版本与环境信息 同时包含正在运行的 PASS 版本、安装包元数据版本， 以及 Python、PySide6、操作系统和架构，便于反馈问题。