GUI 工具

工具 页面提供独立的物理计算与数据格式转换。在同一窗口中切换页面会保留输入， 计算不会修改当前模拟配置或保存的工程。详细公式 显示方程与数据来源， 复制公式（LaTeX） 提供可编辑的公式文本。

磁铁 ramping 文件

打开 工具 → 数据转换 → 磁铁 ramping…，可创建四极、六极、八极和多极铁使用的 归一化强度 TFS 表。

  • 导入 CSV / TXT / TFS：选择源文件、分隔符、表头和跳过行数；指定时间列及其 单位（s、ms、μs 或 ns）；把需要的源强度列映射为 K1L、K2SL 等目标列。 若 TFS 含 TIME_UNIT 元数据，则按其声明锁定时间单位选择；导出前检查强度列单位。

  • 按时间断点生成：添加正/斜 K 或 KL 列，在表格中编辑 TIME (s) 和强度值； 增减行以描述所需的分段线性程序。可用 粘贴单元格 (Ctrl+V) 从 Excel 或其他 TSV 来源粘贴矩形数值区域，以选区左上角为起点，自动增加所需行。请先添加并命名所需 强度列；表头、非有限数值和超出已有列宽的粘贴会被拒绝，原表保持不变。

  • 上升–平台–下降模板：选中一个强度列，填写开始时间、上升/平台/下降时长和 起始/平台/结束强度后应用。上升和下降时长必须为正，平台时长为零时生成三角形程序。 模板替换选中分量的波形及两端保持值；原有时间断点保留，新断点合并到共享时间网格， 其他分量保持其分段线性程序。模板强度使用选中列的单位。

使用 读取列、预览并校验 检查分量曲线后，点击 导出 ramping TFS…。 时间必须严格递增，所有数值 必须有限，同一分量不能同时含 K 和 KL 列。导出将时间换为秒，保持选定的强度单位， 并写入归一化强度元数据。预览一次显示一个所选分量，不把不同单位的强度叠加到同一坐标轴。 从 数据转换 打开时，导出不会自动修改当前元件：需要在元件编辑器中启用 Is ramping，再选择 Ramping file。

也可在元件编辑器的 Ramping 分组中点击 生成 / 导入 ramping 文件…。 生成器使用当前强度草稿初始化，并在导出前检查元件阶数与薄磁铁的 KL 要求。 导出并用于当前元件… 成功保存 TFS 后，回填属性草稿中的 Ramping file， 启用 Is ramping，并清空不兼容的旧分量文件字段。仍需应用或插入元件来保存这些修改； 未成功导出就关闭窗口时，元件草稿保持不变。

K 和 KL 是绝对归一化强度，不是实际磁场或 ramp 倍率。薄磁铁必须使用 KL 列。 运行时插值、端点保持、当前 bunch 动量归一化和入口冻结近似见 磁铁 ramping。

粒子输入与权威质量数据

离子输入质量数 A、带符号电荷态 q、质子数 Z；也可以选择非离子粒子类型。 支持电子/正电子、缪子/反缪子、τ 轻子、带电/中性 π 与 K 介子、中子/反中子、反质子。 这些类型的 A/q/Z 由类型确定并禁用编辑，不能只凭 A、Z 区分电子、缪子和介子。 中性有质量粒子可以计算运动学，但没有磁刚度，也不能由电流反推功率。

搜索支持中文、英文、元素符号、同位素记法和英文模糊匹配，如 carbon、C-12、 238U35+、muon、pi+。选择候选或按 Enter 只预览； 点击 使用搜索结果 才一起替换粒子类型、A、q、Z。 离子未写 A 时采用显示的同位素预设，未写 q 时取全剥离 q=Z；明确写错的记法不会回退为其他粒子。 Ek 等独立输入保留。大写 P、N 为磷、氮，小写 p、n 为质子、中子。 质量数据来自离线目录 PASS/tool/mass_catalog.json，其 metadata 保存 数据来源、版本、校验和与引用。缺少必要数据时报告错误，不以 A×u 替代评估质量。

  • AME2020 未舍入原子质量表 提供 3,558 条基态核素记录，主要为 中性原子质量 (u)，另含自由中子；其中 1,008 条带估算标记。 原始论文为 W. J. Huang 等，Chinese Physics C 45, 030002 (2021)，以及 M. Wang 等，030003 (2021)。

  • NIST CODATA 2022 提供电子、缪子、核子、轻核质量和 u 换算。 质子、氘核、氚核、氦-3 核、α 粒子使用直接评估值；质子质量为 938.27208943 MeV/c²。

  • PDG 2026 提供 τ、π、K 粒子质量；相应反粒子使用同一质量。

  • NIST ASD 提供逐级电离能。2026-09-11 快照有 6,019 个电离级，其中 172 级电离能未知。 原始标记、引用代码和不确定度保存在数据中；计算所需级缺失时会明确报错。

数据目录由官方 AME/CODATA/PDG 表及 ASD CSV 导出文件转换而来， 保留原始不确定度、估算标记与引用来源。随程序提供的 JSON 是 PASS 对原始数据的整理结果。

文件 不覆盖所有可能同位素和全部电荷态质量。AME 只含其列出的基态核素； PDG 保存 319 个有数值质量的编号，GUI 开放其中常用的有质量粒子。 ASD 此快照的电离阶段最高到 Z=110，缺少任意必要阶段都不能计算对应的更高电荷态。 离子质量是由中性原子质量按需修正计算的，不是每个电荷态各有独立实测质量。 不含核同质异能态，负离子仅支持 H−。保留不确定度及估算标记，权威来源不等于各项精度相同。

对基态正离子使用：

\[m_{ion}c^2=M_{atom}[u]\,(u c^2)-q m_e c^2+\sum_{j=0}^{q-1} I_j.\]

电离能项是 正号：剥离电子需要做功，不能只减电子质量。 ASD 电离能按元素提供，没有逐同位素位移；AME 估算质量会提示，不包含核同质异能态。 原始不确定度保留，但未传播全部协方差和同位素位移，因此不宣称得到严格的合成质量不确定度。 H− 另采用 NIST WebBook 所引 Lykke 等 (1991) 的电子亲和能 0.754195(18) eV；其他负离子缺少该修正，暂不计算。 未指定 Z、核素未收录或电离能不全均会报错，不静默近似。

同位素丰度加权的标准原子量不等于指定加速器离子的质量。

运动学、单位与显示精度

离子和原子使用 AMeV，表示按整数核子数归一化的动能 Ek=K/A，即 MeV/核子。 电子、缪子、τ 轻子和介子（A=0）使用 单粒子动能 MeV。 中子和反核子 A=1，每核子量与单粒子量相同；统一记除数 D=max(A,1)。 C-12 6+ 的 Ek=100 AMeV 对应完整动能 K=1200 MeV。 静止质量仍采用当前电荷态的准确评估值，不以 A*u 近似替代。

计算器结果与其他工具的参考束流栏均在 静止质量之后 显示只读的 质量比 μ， 随粒子、同位素和电荷态自动更新。 μ 无量纲，数值等于静止质量以 u 表示时的数值，与整数核子数 A 不同；数据无效时清空该栏。 同一核素改变电荷态，Z、N 和 A=Z+N 不变，但电子数及束缚能改变，实际静止质量和 μ 也会改变：

\[m_{q+1}c^2=m_qc^2-m_ec^2+I_q.\]
\[\mu=\frac{m_0}{u}=\frac{E_0}{uc^2},\qquad K=D E_k,\qquad D=\max(A,1).\]

离子显示每核子总能量 E/A (MeV)、动量 p/A (GeV/c)、静止质量 m0/A (MeV/c²)。 A=0 的粒子显示完整粒子的 E、p、m0。质量比 μ 始终对应完整粒子，放在静止质量之后， 不作为能量除数。固定 A 和 Ek 改变电荷态时，完整动能 K 不变，但准确质量的修正会改变 γ、β、动量和磁刚度。结果保留 12 位有效数字，不表示测量精度提高。 单位放在名称后的括号内。以下内部运动学方程中的 K、E、p 为完整粒子量。

\[E=E_0+K,\quad \gamma=1+K/E_0,\quad \beta=\sqrt{1-\gamma^{-2}},\quad pc=\sqrt{K(K+2E_0)}.\]

已知量可选 Ek、按当前归一化方式显示的总能量或动量、磁刚度、beta 或 gamma，并反向换算。 束流计算器显示磁刚度大小 Bρ=p/(abs(q)*e)。中性粒子没有有限磁刚度，不能选 Bρ 作为已知量。 Ek=0 时 beta=0、gamma=1、动量为零；无效参数会清空相关结果。 这一定义贯穿工具页的参考束流传递、功率、RF、发射度、磁铁和激励计算。 复制的参考数据包含 energy_normalization，A>0 的动能键名为 Ek_AMeV，A=0 为 Ek_MeV。 数值 API solve_kinematics 的动能输入采用归一化 eV，但反算输入的总能量（eV）和动量（eV/c） 仍为完整粒子量。跟踪接口及其已有质量近似保持原有定义；转入跟踪时应核对接口的单位和质量定义。

流强、功率与储能

工具提供三类计算：

  • 流强 ↔ 功率：选已知电流 (mA)、动能输运功率 (kW) 或粒子率 (1/s)， 再选择平均量或瞬时量；已输入量不在结果中重复显示。 I=Ndot*abs(q)*e、P=Ndot*K[J]；带电束流有 P[kW]=I[mA]*D*Ek/abs(q)， 其中 D=max(A,1)，Ek 的数值单位为 AMeV（A>0）或 MeV（A=0），见上述动能定义 K=D*Ek。 不需要周长；中性束流请用粒子率。可以输入已知峰值，但平均值本身不能确定峰值。 Ek=0 时不能由功率唯一反算电流。

  • 脉冲束流：真实粒子数/脉冲和实际脉冲/引出频率给出平均电流、平均功率、每脉冲动能。 可选脉宽给出脉冲内平均电流与功率；只有平顶波形才等于峰值，脉宽乘重复频率不得超过 1。

  • 环内储能与循环流强：全部真实粒子数和周长给出 f0=beta*c/C、周期、 I=N*abs(q)*e*f0 以及动能储量 N*K[J]。不能将循环电流当作靶上功率， 因为同一批粒子每圈经过而没有每圈被引出；实际引出请使用脉冲模式。

零流强或零粒子数有效。功率不含静止能量，也不是电网功率。 瞬时电流、Ek 与功率必须对应同一截面和时刻；有能散时使用粒子流加权的动能。

参考束流与导出

RF bucket、发射度、磁铁、激励页各有独立的参考粒子和 Ek。 读取束流计算器 显式复制有效的粒子类型与当前 Ek，源输入无效时不覆盖，不持续联动。 RF 需要质量、电荷、能量来求滑移因子、bucket 高度和频率；发射度归一化需要相对论 beta×gamma； 磁铁计算需要磁刚度或速度；激励页使用速度计算到达时间和 tune 换算， 可选的电压与踢角双向换算还需要磁刚度，所以这些参考输入予以保留。

图支持 SVG/PNG/PDF 和列名注明单位的 CSV 导出。 发射度与激励页将参数、结果放在右侧同一竖向滚动栏，左侧保留图形。 公式在独立窗口查看。

共振线图

共振条件为 m*Qx+n*Qy=l，系数为整数，阶数为 abs(m)+abs(n)，m、n 不同时为 0。 完整 tune 范围可以跨整数或包含负值。可独立勾选 1–12 阶，并筛选单平面、和共振或差共振。 差共振使用虚线；自定义线可独立显示与删除。

重合线按完整三元组 (m,n,l) 约分，归入最低几何阶次，只绘制一次。 2*Qx=1 仍为二阶，2*Qx=2 归入一阶。关闭低阶也会移除其重合的高阶表达。 过大的枚举会被拒绝，并提示缩小范围或减少所选阶数。

两轴默认范围均为 9–10，只插入一个名称为空的工作点 （9.47，9.43）。 绘图区占据左侧，右侧放置坐标范围及 工作点 / 共振线 标签页，可拖动分隔条调整宽度。 双击表格编辑名称、坐标；选中一行后在表格下方修改颜色、符号。 可切换显示、添加或删除行，新点名称默认为空；名称可留空，仅含空白字符也视为空。 有名称的可见点以自身颜色和符号显示在绘图区右上角的紧凑图例中，不在散点旁重复标注。 空名称的点仍正常绘制和选择；隐藏点与范围外点不进入图例。共振阶数图例保留在绘图区上方。 悬停/选择工作点可查看坐标；范围外工作点在状态文字中计数。 Matplotlib 工具栏提供缩放、平移与恢复视图。导出图形 按当前主题与视图保存 SVG、PNG 或 PDF。

粘贴 接受 CSV 或制表符分隔数据；导入 CSV 追加 UTF-8 CSV/TSV。 列格式为 Qx,Qy 或 name,Qx,Qy[,color,marker]，可有表头。 两列坐标数据的名称默认为空，也允许显式留空 name 列。 符号为 o、s、^、D、+。无效导入不追加任何行。 导出 CSV 保存包括隐藏点在内的全部工作点名称、坐标、颜色与符号，并保留空名称；显示状态仅作为本地绘图选项。 几何图不计算共振强度，也不能单独判定束流稳定性。

RF bucket 绘制

输入电压幅值 V、谐波 h、周长 C、有效同步相位 phi_s，以及 gamma_t 或直接输入 eta。 默认 100 kV、h=4、C=100 m、phi_s=0、gamma_t=6。

本节 E_r=E/D=m0*c²/D+Ek 使用 eV，q_r=abs(q)/D，D=max(A,1)。

\[\eta=\gamma_t^{-2}-\gamma^{-2},\quad \phi=\phi_s-2\pi h z_{rel}/C, \quad \frac{d\phi}{dN}=2\pi h\eta\delta, \quad \frac{d\delta}{dN}=\frac{q_r V}{\beta^2E_r}(\sin\phi-\sin\phi_s).\]

符号遵循 PASS 的小偏差 RF 与纵向漂移约定。冻结单分量时，在所选同步参考事件计算 物理相位 theta(t_s)=2*pi*integral(f dt)+phase(t_s)；有符号 q*V>0 时 phi_s=theta(t_s)，q*V<0 时再加 pi，均对 2*pi 取余。 工具使用正电压幅值与电荷绝对值；参考事件不必等于实测质心。 名义 z_center 仅为分组元数据，不追加物理相位。 RF 谐波 h 不受 Injection 分组谐波约束。稳定条件 eta*cos(phi_s)<0，eta>0 时可用 180°。 电荷、电压、Ek 或 eta 为零时不支持稳定 RF bucket。

正向哈密顿量为 H=pi*h*abs(eta)*delta²+U(theta)，theta=phi-phi_s， U=sign(eta)*q_r*V/(beta²*E_r)*(cos(phi_s+theta)-cos(phi_s)+theta*sin(phi_s))。 相邻不稳定点较低的势垒定义bucket 边界，数值求解转向点和内部等能轨道。 横轴选相位或 z_rel，纵轴选 delta 或 delta_E，后者用 delta_E≈beta²*E_r*delta。 结果页显示半高、全宽、面积、Qs、fs、回旋/RF 频率与每圈增能。 A>0 时能量半高和图轴显示 ΔE/A（MeV），增能为每核子每圈增能，bucket 面积使用 eV·s/核子。 A=0 时对应量均按单粒子计，使用 MeV 和 eV·s。 CSV 能量列以 eV_per_nucleon 或 eV_per_particle 明确标识。 数值核心仍计算完整粒子能量，显示和导出时统一除以 D。

\[Q_s=\sqrt{\frac{-h\eta q_r V\cos\phi_s}{2\pi\beta^2E_r}},\quad f_s=Q_s f_0,\quad f_0=\beta c/C,\quad f_{RF}=h f_0.\]

这是固定参数、单谐波、小动量偏差的光滑近似，不包含集体场、辐射、多谐波和捕获 ramp。 |delta|>=1 的bucket 高度会报错，不能替代跟踪。 通用背景：CERN 纵向束流动力学。

相空间绘制及发射度计算

默认提供一页独立参数，标签栏旁的 ＋ 新增页面，复制当前页 复制参数、质心和绘制设置， 自动分配新颜色；非空图例名称添加“副本”，空名称保持为空。页面可删除，但至少保留一页。 页码是稳定标识，删除页面后不重编号。所有页面共用顶部参考粒子和能量， 切换标签只切换编辑对象，勾选的各页曲线始终叠加在同一张图上；不计算多束合并发射度。

每页 绘制相空间 默认开启，绘制投影椭圆（含色散） 默认关闭，后者受前者控制。 不绘制的页面仍计算结果。各页自动使用不同颜色，可自行修改；同页 betatron 为实线，投影为虚线。 工具栏的 显示图例 默认开启；两条曲线各有独立图例名称。 空或纯空白名称不产生图例条目，但不隐藏曲线；没有有效条目时不显示图例框。 页面标签独立于图例名称。中心 x₀ (mm)、x′₀ (mrad) 默认零，同时平移两种曲线， 不改变扣除质心后的 RMS、协方差、发射度与 Twiss。

每页的参数和结果位于同一滚动区域。单页错误会清除该页结果及曲线，并在标签标记错误， 其他有效页面正常绘制。图片导出保持当前曲线和图例状态；CSV 导出所有有效页面的两种曲线， 包括隐藏曲线，使用 page_id、page_name、图例名称和 draw_betatron / draw_projected 区分来源及绘制状态，坐标使用 m、rad，包含质心偏移。无效页面不导出曲线数据； 至少有一页有效时，复制结果包含全部页面的输入、有效结果及无效页面的错误原因。

单位 π·mm·mrad 按确认的面积约定：输入 1，在公式中使用几何 rms 发射度 1e-6 m rad，对应 n=1 椭圆面积 pi×1e-6 m rad，不额外乘 π，也不隐含 4 倍 rms。 归一化发射度满足 epsilon_n=beta_rel*gamma_rel*epsilon，采用同一 π 记法。

字段名称为 Twiss β、Twiss α、Twiss γ。γ 放在参数区：选择 α、β 已知时自动算 γ； 选择 β、γ 已知时反算 α，需要另选正/负分支：

\[\gamma=\frac{1+\alpha^2}{\beta},\qquad \alpha=\pm\sqrt{\beta\gamma-1}.\]

β 必须为正，反算要求 beta×gamma≥1，β、γ 不能决定 α 的符号。 这些 Twiss 参数与相对论因子不同。

单平面模型假设 betatron 坐标与动量偏差不相关：

\[\sigma_x^2=\beta\epsilon+D^2\sigma_\delta^2,\quad \sigma_{x'}^2=\gamma\epsilon+D'^2\sigma_\delta^2,\quad \operatorname{Cov}(x,x')=-\alpha\epsilon+DD'\sigma_\delta^2.\]

投影 包含不同动量粒子的色散位移，投影发射度为 sqrt(det Sigma)； D=Dprime=0 时与 betatron 椭圆相同。 Cov 是扣除均值后的 x 与 x′ 乘积的平均，反映相椭圆的倾斜和共同变化； r=Cov/(sigma_x*sigma_xprime) 是归一化相关系数，定义存在时在 -1 到 1 之间。 它们不代表另外一类粒子。Cov 单位为 mm mrad，不加面积记法的 π。

由束斑反算时先扣色散方差；输入小于 abs(D)*sigma_delta 不相容。 Ek=0 时无法由归一化发射度唯一反算几何发射度。 n 倍协方差椭圆面积为 pi×n²×epsilon；非退化二维高斯包含率为 1-exp(-n²/2)， n=1 为约 39.35%。

已知量 保留几何发射度、归一化发射度和投影 σx 输入，并增加 投影 RMS 与相关性 → ε、Twiss：输入 σx、σx′，选择 r 或 Cov(x,x′)。 这些输入均为含色散的投影统计量。程序构造投影矩阵，并扣除色散贡献：

\[ \begin{align}\begin{aligned}\begin{split}\Sigma=\begin{pmatrix}\sigma_x^2 & \operatorname{Cov}(x,x')\\ \operatorname{Cov}(x,x') & \sigma_{x'}^2\end{pmatrix},\quad B=\Sigma-\sigma_\delta^2\begin{pmatrix}D^2 & DD'\\DD' & D'^2\end{pmatrix},\end{split}\\\epsilon=\sqrt{\det B},\quad \beta=B_{11}/\epsilon,\quad \alpha=-B_{12}/\epsilon,\quad \gamma=B_{22}/\epsilon.\end{aligned}\end{align} \]

投影矩阵和 B 均须半正定，否则输入不相容。r 模式要求两个 RMS 均为正且 |r|≤1； 零 RMS 时须选择协方差模式且 Cov=0，结果中的 r 显示“未定义”。 ε=0 时仍显示零发射度及可计算统计量，反算 Twiss 显示“未定义”，曲线可退化为线段或点。 原有发射度/束斑输入模式仍保留给定的 Twiss。结果同时显示 betatron 与投影 RMS、发射度， 即使投影曲线关闭也继续显示投影结果；Twiss 结果对应 betatron。

磁铁参数换算

使用参考粒子或直接输入 带符号 B*rho=p/(q*e)，要求有效磁长为正。 直接模式忽略被禁用的参考输入。场与归一化强度保留符号，不额外作发射度式的 beta×gamma 归一化。

  • 二极铁：k0=B/(Bρ)=1/rho、theta=K0L=k0*L、integral B dl=(Bρ)*theta。 L 为有效弧长，零场时半径无有限值。

  • 四极铁：k1=G/(Bρ)、K1L=k1*L、fx≈1/K1L、fy≈-1/K1L， G=dBy/dx，焦距为薄透镜估算。

  • 六极/八极铁：n=2/3，G_n=d^n By/dx^n、k_n=G_n/(Bρ)、K_nL=k_n*L， 在 (r,0) 处 By=G_n*r^n/n!。支持梯度、归一化强度、积分强度/梯度以及给定半径处磁场。 2!、3! 与 PASS 实际偏转角一致。

  • 螺线管：Ks=Bz/(Bρ)、kappa=Ks/2、theta=kappa*L、 integral Bz dl=(Bρ)*Ks*L。theta 是 PASS 傍轴参考粒子的 Larmor 旋转参数。 聚焦系数为 kappa²；f≈1/(kappa²*L) 仅为弱薄透镜估算，不是有限长螺线管的精确焦距。

四极、六极、八极、螺线管默认已知量分别为归一化 k1、k2、k3、Ks。 前三类多极铁的磁极半径使用 mm，计算时转为 m： Bp[Gauss]=10000*(Bρ)*k_n*r[m]^n/n!，n=1、2、3。 支持理想极面场及其反算，保留场极性，场大小为 abs(Bp)。 螺线管显示轴向场 Bz[Gauss]=10000*(Bρ)*Ks；仅凭孔径半径和 Ks 无法确定铁芯极面场， 后者需要磁路几何和场模型。不包含边缘场、饱和、磁滞或线圈电流标定。

激励计算与绘制

对应 PASS/commands/element/exciter.py 中的 single_fm、single_fm_am、dual_fm、dual_fm_am。 输入以 rad 为单位的带符号名义踢角、周长、激励 tune 或频率、扫频全宽、周期、双路扫频偏移（默认 0.5 个周期）及 AM 参数。 默认使用 tune 模式；切换 tune/频率输入方式时保留实际中心频率和宽度。 参数按参考束流、激励波形、AM 和采样窗口平铺显示。 角度输入、数值结果、图轴和摘要均使用 rad，以 1e-6 形式的科学计数法显示。

\[\theta_0=\text{Kick angle (rad)},\quad f_c=Q_{excite}f_0,\quad \Delta f=\Delta Q f_0,\quad t_{arrive}=t_{0,start}+t_{elapsed}-\frac{z_{rel}}{\beta c}.\]

不添加名义束团槽位偏移，z 不折叠。波形使用 \(u=t_{arrive}-t_{0,start}\)， 两个 DDS 都从零相位启动，启动前信号为零；只有扫频进度对周期取余，累计相位保持连续。 输入踢角反号使波形反号，包络和频谱仍显示幅值大小；输入踢角为零时冲量为零。 单频相位为 phi=2*pi*fc*u+pi*df*tau*(tau-T)/T，其中 tau=u % T。 双频将两路分别积分相位的 DDS 信号相加，每路都扫描完整带宽；DDS1 按设定的扫频进度 偏移领先 DDS2，并非两路正弦相差固定相位。偏移不是半周期时弹出警告。 只设一个踢角，作为两个 DDS 信号的共同幅值；没有分路幅度输入，也不自动除以二。 因此无 AM 时双路信号峰值上界为 \(2|\theta_0|\)。 详细公式窗口列出频率、相位积分和完整 AM 公式。

所设 z_rel 改变 FM 和 AM 共用的到达时间。预览与跟踪都直接使用配置的踢角作为 归一化横向动量幅度，见 激励器（Exciter）。 角度单位采用近轴参考粒子近似 \(\Delta u'\simeq\Delta p_u\)； 不进行逐粒子速度修正，也不随束流能量自动缩放幅度。

AM 在 \(u=t_{arrive}-t_{0,start}\) 处连续计算，归一化使用启动时固定的圈频。 它在 \(u=t_{ext}\) 发散，因此 AM 绘图中所有采样粒子的经过时间必须小于该值。 这里用固定束流参数预览外加信号，不预测束流响应、损失或发射度增长。 可叠加逐圈到达相位对应的采样点，查看偏转角/包络、DDS 频率、AM 因子、Hann 窗单边振幅谱。 DDS1/DDS2 标签及 CSV 列在频率交叉后仍保持通道身份。

结果包括基准偏转角、采样峰值/RMS、频率、采样率和频率间隔。 按平滑频率上界每周期至少 24 点采样，最多 200000 点；高频长窗口会提示缩短时间跨度。 扫频频率跳变时相位保持连续，但仍可能展宽频谱；FFT 间隔为 1/窗口时长，采样峰值并非全局解析上界。 波形 CSV 使用秒、弧度和 Hz；频谱 CSV 为 frequency_Hz、kick_amplitude_rad。 参数和结果在同一竖向滚动栏，支持常规图形导出。

电压与踢角换算

点击 电压换算… 打开独立的 电压 ↔ 踢角 窗口，电压和踢角输入同时显示。 输入电压后按回车计算踢角，输入踢角后按回车计算电压。 两个方向共用主页面选定的参考粒子和动能，以及间距 d（mm）和极板有效长 L（m）。 修改极板间距、极板长度或参考束流时，根据当前电压重新计算踢角； 只有提交踢角输入才反算电压。 V 是带符号极板间峰值电压差（V），踢角以 rad 为单位并保留符号。 均匀横向电场下的参考粒子估算为：

\[E=\frac{V}{d},\qquad F=qE,\qquad \Delta t=\frac{L}{\beta_0c},\qquad \Delta P_u=\frac{qVL}{d\beta_0c},\qquad B\rho=\frac{P_0}{|q|},\]
\[\theta_0\simeq\frac{\Delta P_u}{P_0} =\operatorname{sgn}(q)\frac{VL}{d\beta_0c B\rho}.\]

公式中的 d 使用米。\(B\rho\) 是正磁刚度幅值，电荷符号显式计入。 正电压使正电荷沿选定横向的正方向偏转；电荷或电压反号时结果反号；V 或 L 为零时 角度为零。该式统一适用于质子和离子参考粒子，因为磁刚度已包含电荷绝对值。

反算公式为：

\[V=\operatorname{sgn}(q)\frac{\theta_0 d\beta_0c B\rho}{L}.\]

反算要求 \(L>0\)：零长度在正算时得到零踢角，无法由此唯一确定电压。 窗口显示电压、踢角、电场和过板时间。回车只执行换算，不回填主页面，也不关闭窗口。 点击 填入基准踢角 才会把当前角度 复制到波形的角度输入；随后修改硬件或参考输入不会自动覆盖该角度。 将选定结果填写到主 Exciter 配置的 Kick angle (rad) 即可， 元件本身不再配置电压、间距或长度。

换算采用近轴参考粒子近似，并要求通过电极期间的波形变化很小，正弦波对应 \(\omega L/v_s\ll1\)。这是名义参考换算，不是有限长度电场跟踪模型。 迁移旧电压输入时，只保留所选能量下的名义参考系数，不复现原逐粒子速度因子和 随参考能量变化的幅度。

数据格式转换

打开或拖入 OMC3 SDDS、HDF5、CSV、TFS，选择数据、预览后另存为。 源文件保持只读，支持 OMC3 SDDS ↔ CSV/TFS、HDF5 ↔ CSV/TFS 及 CSV ↔ TFS。 不提供数据编辑及 SDDS ↔ HDF5 直接互转。安装 GUI 可选依赖即可； 脚本单独使用时执行 python -m pip install "pass-sim[conversion]"， 安装 PyLHC sdds 与 turn-by-turn。从 GitHub 克隆仓库或下载并解压源码后， 也可以在包含 pyproject.toml 的目录中执行 python -m pip install --editable ".[conversion]" 安装。

SDDS 专门支持 OMC3 的 LHC/TbT SDDS1 数组结构，由 PyLHC sdds 读写。 turn_by_turn 是 OMC3 使用的 Python 读取库，并不是另一种文件格式。 不支持其他 SDDS 结构、SPS 专用读取方式或旧版 ASCII TbT 文件。 导出的每行包含 BPM、BUNCH、TURN 及选中的 X 和／或 Y。 左侧勾选 BPM，右侧选择束团和圈数区间；三个标识列始终保留。 圈号、行号从 0 开始，结束位置不包含在内；行范围和数值筛选作用于 BPM／束团／圈范围选择后的表格。

常用区显示束团、圈范围、X/Y 和输出格式；行筛选、类型映射和参数选择收进 默认折叠的 高级选项。折叠后已经启用的高级选择仍生效，并显示提示。 BPM 搜索只改变显示，全选可见／取消可见 只操作当前搜索结果，保留隐藏项的选择。 预览上方显示实际选择数量、声明的单位、采集时间是否保留及圈号重新编号说明； 缺失单位明确显示“未声明”。

CSV/TFS 转回时，将源列映射为 BPM、BUNCH、TURN、X、Y。 必须包含两个平面，且组成完整的 BPM × 束团 × 连续圈采样； 重复采样、缺失组合或圈号间断会报错。输出为二进制 SDDS1，保留 float32／float64 位置精度，并用 turn_by_turn.read_tbt(..., datatype="lhc") 回读检查。 输出圈号从 0 重新编号；缺少采集时间时使用 acqStamp=0 并提示。 BPM 名称及字符串参数必须为 ASCII。其他 SDDS 数组会列为未导出项； 不转换单位或坐标，也不推断文件中缺失的单位。

GUI 预览检查整个选择范围能否转回 OMC3 SDDS，包括显示的前 500 行之外的数据。 不完整的表格仍能导出 CSV/TFS；CSV/TFS 不满足要求时禁用 SDDS 另存为并说明原因。 SDDS 按块扫描所选采样；CSV/TFS 在内存中检查完整表格。这些是格式与结构检查， 不等于运行 OMC3 物理分析。

预览最多显示 500 行，不限制导出范围。SDDS 数组和 CSV/TFS 按整体读入内存， SDDS 表格导出按块处理。HDF5 按有限范围读取，需要明确选择数据集， 支持等长一维列、二维矩阵／平面和网格点长表。PASS 的 (slice, y, x) 场 可选择 网格点长表，切片输入 0,:,:、坐标路径输入 /slice_id,/y,/x，导出第一个切片。任务支持取消。

CSV 可附带校验内容的 .metadata.json，保存单位、类型和参数 （包括精确的采集时间戳），往返转换时请将其与 CSV 保存在一起。 TFS 保存可兼容 headers 及 PASS 元数据。HDF5 输出使用 /table/<列名>， 不重建任意源文件层级。ParticleMonitor 选择结果转换为 Layout="table" 的普通表格， SourceLayout 保留原布局；这些选择结果按普通表格读取。 若要对 TFS 长表导出的轨迹做频谱分析，应先选择 record=1 的轨迹行及单个粒子 ID。 修改选择后需重新预览，覆盖输出需要确认，不能覆盖源文件。 源文件变化检查也包含 CSV 元数据附属文件。 多文件发布不是原子操作，取消时可能保留已经完成的输出文件。

不依赖 Qt 的函数位于 PASS.tool.data_conversion：inspect_file、 preview_file、convert_sdds 和 convert_hdf5。例如 convert_sdds("a.sdds", "a.csv", DataSelection(bpms=["BPM.1"], turns=(0, 100))) 导出 BPM.1 所有束团的前 100 圈；convert_sdds("a.csv", "b.sdds") 由五个标准列重建 OMC3 SDDS；convert_hdf5("a.csv", "a.h5") 创建 HDF5 表格。 自定义反向映射使用 DataSelection(tbt_columns={"BPM": "name", "BUNCH": "bunch", "TURN": "turn", "X": "x", "Y": "y"})。 调用返回输出路径、行数和说明，默认禁止覆盖已有文件。 脚本可使用 preview_file(path, selection, check_sdds=True)，在限制显示行数的同时， 通过返回的 sdds_check 获取完整选择范围的检查结果。

尾场数据导入

在转换工具中选择 导入尾场…，生成标准时域尾场 TFS。选择源文件与分量， 指定数值列，并声明源坐标轴、单位、符号、归一化与参考 beta。文件包含普通 文本表头时，设置需跳过的行数。预览归一化后的数据与校验提示，再将每个分量 分别保存为 TFS。WakeField 跟踪仅接受这些标准 TFS，外部表格的解释设置保留在 导入器中。修改导入设置或源文件后需要重新预览。

距离数据需要选择源坐标表示 beta_c_tau （\(s=\beta_{\mathrm{ref}}c\tau\)）还是 c_tau``（:math:`s=c\tau`）， 默认为 ``beta_c_tau。切换到相同空间阶数的分量时保留自定义单位；改变空间 阶数或长度归一化时明确提示检查单位，不会静默替换用户填写的缩放。

在 导入预设名称 中命名可复用的设置，再选择 保存预设… 或 加载预设…。 带版本的 JSON 预设保存名称及完整导入选项，包括列映射与物理约定，不保存 源文件路径或哈希。加载预设后须重新预览所选源文件，才能导出。 TFS 复核预设仅保存格式与重构选项，物理元数据始终从所选 TFS 读取。

选择已有标准 TFS 可只读复核文件声明的物理元数据与曲线，不会重新导出文件。 阻抗 TFS 复核显示实部与虚部，并可选择跟踪模型使用的重构方法。 大表预览保留端点与分组极值，不采用等间隔抽行；摘要中的最大幅值、末点/峰值 比和最小/最大采样间距按完整表格计算。预览减少显示点数不会改变导出样本。

导出成功或完成 TFS 复核后，复制分量 JSON 将只读 分量配置 页中的片段 复制到剪贴板，包含文件模型与显式固定速度，以及所需的空间幂次或重构设置。 检查文件路径与参考速度后，可将其放入算法组的 Components 列表；复制操作 不会修改当前仿真配置。

该专用入口应用尾场物理约定，单位与方向换算后保留原始采样位置。 通用 另存为 TFS 保留一般表格数据，不推断尾场物理；尾场导入不将延迟 转换为圈号，也不重采样。零延迟填写完整右极限，检查非零表尾的截断影响， 并在文件声明的参考速度下使用响应。有限束长 wake potential 需要先单独 反卷积，才能作为点电荷尾函数导入。CSV 示例、命令行转换、Python API 与 跟踪配置见 标准尾场 TFS 与外部文件转换。 外部阻抗频谱可通过命令行与 Python API 转换；GUI 导入时间轴或距离轴上的 点电荷尾函数，并可复核已有标准尾场或阻抗 TFS。