ARPES风格能带图谱绘图工具
本文档为第一性原理ARPES风格能带绘图工具的更新版本技术说明。在初代版本ARPES风格连续能带图谱绘图工具实现二维高斯网格化、多轨道RGB混色及对称路径重构的基础上，本版本针对高对称路径采样稀疏、能带交叉区域轨道成分复杂、背景底噪干扰以及多批次绘图参数复用等问题，新增了五大核心数据处理与定量分析模块，使该工具从单纯的“谱图渲染脚本”升级为集“数据加密、定量统计、单带剖析、权重截断与持久化管理”于一体的综合后处理平台。
一、 模块升级
1. 蛇形能带正逆序自动识别与同步保形插值引擎
第一性原理后处理软件（如VASPKIT）导出的能带数据通常采用“奇偶能带正逆序交替（蛇形排布）”格式，以避免连线绘图时产生跨图回折线。
- 方向归一化与断点切分：
脚本按能带索引（Band-Index）将数据拆分为独立能带块，自动检测首尾K坐标方向。
- 能量与权重同步插值：
支持保形三次插值（PCHIP，消除过冲振荡）、标准三次样条插值（Cubic）与线性插值（Linear）。在相邻原始K点间按设定倍数加密，并对分波权重施加非负约束，杜绝负权重伪影。
- 边缘柔化：
结合一维能带曲线高斯平滑、二维各向异性高斯涂抹以及非线性Gamma边缘柔化矫正，使能带中心至背景边缘呈现自然的连续过渡质感。插值后的完整数据按原蛇形格式自动导出至独立目录。
2. 能量窗口能带三区筛选与轨道占比卡片式详表
在设定目标K路径区间与纵坐标能量窗口后，系统自动遍历全能带数据库，凡在所选K区间内能量跨度与目标窗口存在交集的能带均被完整收录，并按空间拓扑关系划分为三个区块输出：
- 上方穿越能带：
能带主体位于窗口上方，仅底部探入或上下贯穿目标能量窗口。
- 窗口内完整能带：
整条能带在当前K区间内完全位于能量窗口上下限之间。
- 下方穿越能带：
能带主体位于窗口下方，仅顶部探入目标能量窗口。
- 卡片式定量报表：
每条能带以多行对齐结构展示其全带能量范围、窗口内能量范围、K点覆盖率、各元素自旋通道总权重分担比例、前六名主导分波轨道（均值、峰值及占比）以及用户自定义组合态在该能带上的响应强度，并同步保存为文本报表。
3. 单带沿K路径分段杂化剖析与特定能带独立导出
针对存在避免交叉或轨道特征反转的关键能带，系统提供单带深度剖析与定向提取功能：
- 分段演化轨迹追踪：
输入指定能带编号后，程序除统计各轨道全局均值、峰值位置坐标及积分占比条形图外，还会沿K路径逐点追踪主导轨道的切换边界，自动归纳出不同动量区间内的前两名主导杂化态及其极值特征。
- 特定能带组合绘图：
支持通过单号、逗号分隔或区间表达式（如仅绘制某一条或某几条特定能带）进行全局绘图过滤，或建立专属的特定能带对比绘图任务。
- 单带数据文件拆分导出：
支持将选定能带、窗口内能带或全部能带单独拆分为独立数据文件，并在文件表头自动写入该能带的各轨道贡献百分比摘要注释，便于外部绘图软件直接调用。
4. 权重分位数统计、亮度上下限截断与重新归一化
为解决部分投影轨道背景杂散信号过强或局部极值点掩盖弱能带细节的问题，在生成预览图前引入了定量截断与重归一化引擎：
- 窗口内权重分布预检：
自动统计并列表展示当前画图区域内所有总能带与分波轨道的最小值、非零最小值、平均值、90%分位数、99%分位数及最大值，为阈值设定提供精确数据支撑。
- 上下限截断与重归一化：
支持设置背景归零下限（低于下限的权重全部置零）与强度封顶上限（高于上限的权重归化为上限值）。同时支持对截断后的数据按有效上限等比例重新归一化至指定目标值。
- 全局与多态定向规则：
用户可选择对所有文件及轨道执行全局统一截断，或通过多选模式仅对特定文件、特定同名轨道施加独立的截断与归一化规则，并支持将处理后的数据按“含插值网格”或“原始未插值网格”重新导出为标准数据文件。
5. JSON配置
程序首次加载数据时会自动构建全能带PEBS统计数据库，并将用户设定的插值参数、自定义轨道组合、画图范围、特定能带筛选列表及亮度截断规则统一序列化保存为JSON配置文件。在后续运行或预览调优阶段修改画图范围时，用户可一键读取并沿用历史配置，避免重复输入。
二、 升级版工作流与输出目录规范
运行脚本后，系统按以下标准化阶段推进交互：
- 历史配置检测与插值初始化：
检测是否存在历史设定文件；若新建任务，则依次配置插值倍数、插值算法与一维曲线平滑度，完成全能带正序化插值与预分析建库。
- 自定义多态组合与画图区间设定：
自由组合不同原子的分波轨道；随后设定K路径裁剪区间、是否启用镜像对称映射以及纵坐标能量窗口范围。
- 窗口能带报表审阅与单带剖析：
终端输出三区能带轨道占比详表；用户可输入任意能带编号查阅沿K路径的分段演化报告，并设定全局或专属能带编号过滤规则，按需导出单带数据文件。
- 权重分布审阅与截断归一化：
查看窗口内各轨道权重分位数统计表，配置全局或指定轨道的上下限截断及重归一化参数，按需导出截断后的数据集。
- 实时预览闭环调优与批量出图：
基于预览图实时微调对比度、底噪灰度、高斯涂抹半径、Gamma柔化指数、图片尺寸、字体属性、能量窗口及截断规则，确认无误后一键批量生成全部灰度图、彩色杂化图及特定能带专属图谱。
标准化输出目录结构：
ARPES_Plots_Final/：存放最终生成的单态灰度图、多态加和灰度图、RGB混色图及特定能带专属图谱。
Interpolated_Data/：存放插值加密后的完整能带文件、窗口能带统计报表（
Window_Bands_Orbital_Summary.txt）及持久化配置文件（arpes_plot_settings.json）。Interpolated_Data/Single_Band_PEBS/：存放按单条能带拆分导出的数据文件及单带深度剖析报告。
Interpolated_Data/Truncated_Interp_Data/与
Truncated_Raw_Data/：分别存放含插值与原始未插值网格下的亮度截断及重归一化数据文件。
三、 进阶版大语言模型（AI）复现指南
若需使用AI大模型从零构建包含上述全部进阶特性的完整Python脚本，请直接复制以下结构化提示词发送给AI：
请编写一个完整的Python交互式脚本，用于处理第一性原理计算输出的 EBS*.dat 与 PEBS_*.dat 能带数据，生成ARPES风格连续能带图谱并提供定量能带分析。请严格实现以下技术规范：
- 蛇形能带解析与保形插值：
按 # Band-Index 拆分能带并提取真实整数编号。自动检测VASPKIT奇偶能带的正逆序方向，对逆序能带先翻转为正序递增，仅在相邻K点坐标相等的断点处切分片段。支持使用 scipy.interpolate.PchipInterpolator、cubic或linear对能量和所有轨道权重同步插值加密，支持一维高斯曲线平滑，权重列严格裁剪为非负值。导出插值文件至独立目录时需还原原能带正逆序方向并更新NKPTS表头。
- 窗口能带三区筛选与卡片式报表：
根据用户设定的K路径区间（含对称模式）和能量窗口 [E_MIN, E_MAX]，筛选所有与该窗口存在能量交集的能带，按“上方穿入能带”、“完全位于窗口内能带”、“下方穿入能带”分为三个区块输出。每条能带以多行卡片形式展示全带能量、窗口内能量、K覆盖率、各文件总权重分担比例、前6名主导轨道（均值、峰值、占比）及自定义组合态强度，同步保存报表文本。
- 单带多态演化剖析与单带文件导出：
支持输入指定能带编号，统计该带各轨道均值、最大值、峰值所在(K, E)坐标及占比条形图，并沿K路径检测主导轨道切换边界，分段输出主导杂化态演化过程。支持按能带编号组合（单号、逗号或范围）进行全局过滤或创建专属特定能带绘图任务。支持将单条能带导出为“元素-band编号-pebs.dat”格式文件，并在表头写入各轨道占比摘要。
- 权重范围统计与亮度截断重归一化：
在生成预览图前，输出当前窗口内所有EBS与PEBS各轨道权重的最小值、非零最小值、均值、90%与99%分位数及最大值表格。支持不截断、全局统一截断或针对指定文件与指定多个轨道态的定向截断（低于下限w_min归零，高于上限w_max封顶），并可选是否按有效上限重新归一化至目标值（如1、10、1000）。支持将截断/归一化后的数据按“插值后网格”或“原始未插值网格”导出。
- 二维渲染与Gamma柔化：
使用 numpy.histogram2d 与 scipy.ndimage.gaussian_filter 进行二维高斯展宽，引入Gamma指数柔化边缘并叠加可控背景灰度。支持单态灰度图、多态加和灰度图与RGB线性Alpha混色图输出。
- 配置持久化与预览闭环：
将所有参数、自定义任务、能带筛选、截断规则及全能带PEBS预分析库保存为JSON文件，支持启动时直接载入。预览循环中支持实时修改对比度、底噪、高斯半径、Gamma值、插值参数、图片尺寸、字体属性、能量窗口（更新后支持二次确认沿用能带设定）及亮度截断配置。声明 matplotlib.use('Agg') 兼容无头服务器环境。
四、 进阶功能应用注意事项
- 插值算法选择建议：
对于大多数第一性原理能带数据，强烈建议优先使用默认的保形三次插值（
pchip）。该算法严格保持数据单调性，在能带极值点与权重突变处不会产生三次样条插值（cubic）常见的非物理过冲振荡。 - 亮度截断与重归一化配合策略：
当需要将两个权重绝对值差异极大的轨道（例如强局域的d轨道与微弱杂化的p轨道）在同一张RGB彩色图中突出对比时，可在定向截断模式中分别对弱轨道设置上限截断并同时开启重新归一化至相同目标值（如均为1.0），即可在混色图中清晰观测二者的空间交叠关系。
- 历史配置文件更新：
当更换计算体系或工作目录下的能带文件发生变更时，建议在启动脚本时选择不沿用旧的JSON设定文件，以便系统重新扫描新体系的轨道表头并重建全能带预分析数据库。
