图形界面配置流程
使用 python -m pip install --editable ".[gui]" 安装可选界面，再通过
python -m PASS.gui 或 pass-gui 启动。配置页编辑追踪引擎使用的输入文件；
运行页和绘图页保持独立。
中间配置概览中的全局配置与执行序列详情都折叠时，两个标题在顶部依次排列。 展开任一面板后，其内容使用可用的垂直空间。
左侧组件库的展开栏按选项数量占用高度，多余空间留在整个列表底部。 物理模块 依次包含 空间电荷、尾场、束束效应、电子云， 各栏可独立展开或折叠。后三项目前没有子选项，展开空栏目不会预留空白区域。
空间电荷
在 物理模块 中点击 空间电荷 标题，可展开或折叠其子菜单，交互与外层模块一致。 折叠操作本身不修改项目，也不丢弃当前表单；没有返回菜单项。
计算配置：管理模块开关、命名配置、切片集引用、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。节点间距由范围和节点数计算。
配置中不再包含 Chamber。各 SC 点设置 Aperture type 和 Aperture value，
默认解析为网格同尺寸矩形。孔径用于损失判断，并在 FD/DST 中同时定义导体壁。
不同 FD 管壁使用独立缓存求解器，共享配置网格；FFT 共享核，孔径仅用于损失。
初始化时检查有限 PIC 孔径完整位于网格内，DST 必须使用完整网格矩形。
管壁上或外部粒子在求场前损失。
Twiss 与光学
组件库按以下顺序排列：
从 MAD-X 文件导入 Twiss 点。
插入单圈传输矩阵。
生成平滑近似 Twiss 序列。
插入 Twiss 传输点。
MAD-X 入口支持下述采样方式。两个生成器均先点击 预览生成，再点击 插入到 Sequence。预览不修改项目，显示命令数量、位置范围、计算得到的 beta、 步长、总相位推进和前 100 个点。插入时写入全部生成点，包括未在预览表格显示的点。 名称冲突时自动添加数字后缀，预览显示最终名称。若同一环周范围内已有光学传输， 预览会提示新增传输可能造成重复传输。
修改生成参数会使预览失效，并禁用插入按钮，直到重新预览。 序列、全局周长或未确认的 JSON 发生变化，也会阻止插入旧预览。 周长默认读取全局值，插入时将全局周长同步为生成器显示的值，并保留已有命令。 离开已修改的生成器时，界面会询问是否放弃尚未插入的草稿。
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 传输。 同一 S 的不同光学状态保留为入端、出端状态，通过零长度 Twiss 传输表达光学跳变。 因此最终位置不一定全部等间距。同一位置先执行 Twiss，再执行附加薄元件或场误差。 源光学已包含设计线性聚焦，显式插入的薄元件是附加作用，不会从源光学中扣除或替换 设计聚焦。因此，附加线性误差仍可能改变追踪工作点，而重采样的基础光学保持源工作点。
单圈传输
输入名称、周长 \(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；表单标签标明了“完整工作点”：
界面以 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 入口改为 插入 Twiss 传输点。一个命令描述两端之间的传输，
因此表单分为 起点光学参数、终点光学参数 和 传输设置。
Mu 为累计相位，单位为周（\(2\pi\)），不是弧度。
两个生成器均写入普通 Twiss 命令，不单独保存生成器配置。
插入后或重新加载 JSON 后，在序列中选择生成的命令，使用上述手动表单编辑两端参数。
生成点可以逐个修改。插入或确认编辑后，使用 保存 JSON 或 另存为 保存项目。