图形界面配置流程
================

使用 ``python -m pip install --editable ".[gui]"`` 安装可选界面，再通过
``python -m PASS.gui`` 或 ``pass-gui`` 启动。配置页编辑追踪引擎使用的输入文件；
运行页和绘图页保持独立。

中间配置概览中的全局配置与执行序列详情都折叠时，两个标题在顶部依次排列。
展开任一面板后，其内容使用可用的垂直空间。

左侧组件库的展开栏按选项数量占用高度，多余空间留在整个列表底部。
**物理模块** 依次包含 **空间电荷**、**尾场**、**束束效应**、**电子云**，
各栏可独立展开或折叠。后三项目前没有子选项，展开空栏目不会预留空白区域。

空间电荷
--------

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

* **计算配置**：管理模块开关、命名配置、切片集引用、PIC 网格和求解器。
  这是原“空间电荷全局配置”编辑器，功能不变。
* **插入计算点**：手动在指定位置插入引用命名计算配置的 ``SpaceCharge`` 命令。
  作用长度和输出选项等计算点参数的含义不变，参见 :doc:`space_charge`。

计算配置中的选项按 ``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 与光学
------------

组件库按以下顺序排列：

1. **从 MAD-X 文件导入 Twiss 点**。
2. **插入单圈传输矩阵**。
3. **生成平滑近似 Twiss 序列**。
4. **插入 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 见 :doc:`input_generation`。

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

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

单圈传输
~~~~~~~~

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

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

纵向传输支持 ``off``、``drift`` 和 ``matrix``。只有 ``matrix`` 模式显示
纵向 tune :math:`Q_s`；终点 ``Mu z`` 为 :math:`Q_s`，起点为零。
其他模式生成的纵向相位推进为零。引擎的 matrix 模式还使用束团纵向尺寸和动量展宽，
drift 模式使用滑移因子和传输长度。追踪公式参见 :doc:`twiss`。

平滑近似
~~~~~~~~

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

.. math::

   \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``，得到 :math:`s=0`
处的初始单位传输点，以及结束于 :math:`C` 的 :math:`N` 段传输。
位置为 :math:`s_i=iC/N`，相位线性分配，每段色品为 ``DQx/N`` 和 ``DQy/N``，
初始点色品为零。名称使用用户指定的前缀和点序号，短步长不会因位置舍入导致重名。

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

手动传输点与后续编辑
~~~~~~~~~~~~~~~~~~~~

原 **Twiss** 入口改为 **插入 Twiss 传输点**。一个命令描述两端之间的传输，
因此表单分为 **起点光学参数**、**终点光学参数** 和 **传输设置**。
``Mu`` 为累计相位，单位为周（:math:`2\pi`），不是弧度。

两个生成器均写入普通 ``Twiss`` 命令，不单独保存生成器配置。
插入后或重新加载 JSON 后，在序列中选择生成的命令，使用上述手动表单编辑两端参数。
生成点可以逐个修改。插入或确认编辑后，使用 **保存 JSON** 或 **另存为** 保存项目。