PolyXRD

多晶 X 射线衍射 (XRD) 图谱综合分析套件
峰检测  ·  多物相定性检索  ·  Rietveld 结构精修  ·  Le Bail 晶胞精修  ·  指标化  ·  3D 结构可视化  ·  三库外挂检索 (COD 无机物 / COD 全库 / PDF2-2004)

       

🌐 English documentation: [README-EN.md](README-EN.md)

PolyXRD 是一个面向材料学 / 化学 / 晶体学研究者的 多晶 X 射线衍射 (XRD) 图谱综合分析桌面软件。它把"加载原始 XRD 数据 → 预处理 → 峰检测 → 多物相定性检索 → Rietveld 结构精修 → 晶胞精修 → 全谱拟合 → 出报告"整条工作流集成在一个统一的、带 中文/英文/日文 三语言界面的 PySide6 (Qt6) 桌面应用里。

核心设计哲学：

• 无需 Python 环境 — 安装包内置完整 Python 3.10 + PySide6 + pymatgen + scipy，目标机器开箱即用。
• 程序与数据库彻底分离 — 主程序（安装包 / 便携包）不内置任何数据库，三个数据库各自独立打包、独立下载、独立挂载。无机物库默认发布瘦身索引式（362 MB，不内嵌 CIF），CIF 由本地 cod/cif 目录或 COD 在线接口按需提供。
• 算法可控 + 结果可复现 — 预处理/拟合的每一步参数可保存、可回放，项目文件 (.polyxrd JSON) 全序列化。
• UI 与算法分层 — MVVM 架构，services/ 层是纯算法、不依赖 Qt，可独立单元测试。

📋 版本变更记录：见 docs/CHANGELOG.md。 🏗️ 代码结构与分层说明：见 docs/代码结构说明.md。

格式支持扩展：岛津 .RAW 二进制解析 + 导出损坏修复（详见 docs/CHANGELOG.md §2.9.0）：

• 新增岛津 XRD .RAW 二进制格式：支持 PCXRD 导出的私有容器，968/976/1608 三种变长头子类型自动适配；θ 轴记录模式自动折算 2θ；摇摆曲线/极图等非 2θ 扫描明确拒绝、不污染相分析。106 个真机样本 103 正确解析 + 3 个按非 2θ 正确跳过，与官方导出 .txt 逐数值 18/18 完全一致（maxΔ2θ = 0.0000°）。
• 修复两列文本导出的静默数据损坏：强度量级大到占满场宽时两列粘连成单列、下游 np.loadtxt 读不出；改为仅在溢出时补显式分隔符，正常输出与原厂格式逐字节一致。
• 批量转换脚本 scripts/convert_xrdata_to_txt.py：幂等 + 陈旧自检（解析器修复后自动重写脏输出）+ 同名冲突消歧。
• 本版无检索/精修算法改动，基准与 v2.8.0 一致（A 级 top10 36/48 · MRR 0.407；B 级 top20 26/48）。

📦 安装包与 SHA-256 校验值见 v2.9.0 Release（只含 Setup + SHA256；数据库与 PDF2 外挂，不随分发）。

上一版 v2.8.0（COD-Inorg 检索质量修复：候选去重 + 候选列表扩至 20，A 级 top10 24→36/48 · MRR 0.407）：👉 下载 v2.8.0

• 多物相定性检索：d-I 峰匹配 + Hanawalt 复合 + FoM 打分 + 化学式/元素过滤 + 矿物关键词 → Top-N 候选
• 候选检索约束（M09）：密度区间 density_range、名称/化学式模糊直搜 find_phases_direct、综合约束过滤 apply_restraints、搜索预设存取
• 四类元素过滤语义：必有 (must_have，全部命中) / 含有 (must，至少一个) / 可能 (maybe，仅放宽允许池) / 没有 (exclude)。未勾选元素默认并入"没有"形成闭环；LIGHT_ELEMENTS (O/C/H/N/S) 支持一键"设为含有"
• FoM 加权互斥匹配：参考峰与实验峰一一对应贪心匹配（避免密集相被高估）+ 强峰加权 + 特异性项 + 强度余弦
• 交互式元素过滤器（118 种元素周期表选择器）
• 多物相联合拟合：生成计算谱 → 与实验谱最小二乘 → 各相 质量分数 (%)
• 组合选择：候选峰位掩码分支定界，联合覆盖最大 + 纯金属 ≤20% 硬约束；同化学式多型按峰位差异择优（phase_structure_resolver.py）

• 结构精修（引擎能力分层）：
  • 真 Rietveld（结构自由度：坐标/占位/ADP + S·ZMV 定量）→ GSAS-II / FullProf / MAUD；
  • 内置引擎 = 免结构全谱拟合（Le Bail 级，快）：用 CIF |F|² 参考峰 + 每相各向同性晶胞缩放
    • March-Dollase 织构 + Chebyshev 背景 + 统计权，无需安装外部程序即可给出可用的 wR/Rp； 它不精修原子坐标/占位/ADP，因此其 wt% 为相对定量而非严格质量分数。
  • 顺序/自动/手动三种精修策略对以上引擎通用。
  • ⚠️ 指标口径：Rwp/Rexp/GOF 一律基于统计权（stat_weights="poisson"）。 显式改用单位权（"none"）时 Rexp/GOF 无物理意义，界面会显示"不可解读"。
• Le Bail 晶胞参数精修：仅精修 a/b/c/α/β/γ，无需原子占位，适用于未知结构的晶胞测定
• 指标化（M15）：内置立方 / 四方 / 六方三系指标化（services/indexing.py，验收：立方 Si → a≈5.43 Å）；外部 Treor / Dicvol 留接口
• 3D 晶体结构可视化（M17）：CIF 浏览器内嵌 3D 晶胞 + 原子球视图，自动按空间群展开非对称单元（services/structure_viz.py）
• 结构模拟：从空间群/原子占位 → 计算 XRD 图谱 (Lorentz-Polarization 校正 + B 因子)
• hkl 指标化 (d→hkl)，230 种空间群标准化 (spglib)
• 基于 PDF2-2004 的空间群（72.8%）与晶胞（81.8%）映射，命中相可直接作精修起始结构
• 外部精修程序集成（M25）：FullProf 自动生成 .dat/.pcr → fp2k 批处理 → 解析 .sum 回写 Rwp/Rexp/Rp/GoF² 与各相 R_Bragg/晶胞/含量；GSAS-II / MAUD 一键"导出 + 拉起 GUI"

• .polyxrd 项目保存/打开/另存为（JSON 格式参数 + 图谱全归档）
• 导出：峰列表 CSV / PNG+SVG 图像 / 多物相报告 PDF / 批量报告 / 选中物相 CIF
• 脚本化接口（services/scripting.py）

• PySide6 (Qt6) + PyQtGraph 双画布（主图 + 残差图），支持可停靠面板
• 主谱与残差条 5:1 分栏、X 轴双向同步；绘图 X 轴自适应（滚轮以光标为中心缩放、左键拖拽平移）
• 简体中文 / English / 日本語 三语言切换，切换无需重启；切换语言整页重翻译（页面内部 + 停靠面板 + 工具栏/菜单/动作提示；只重设静态文案，不动运行期数据），三语翻译键集全量对齐
• 全链路 UTF-8，跨语言 Windows 不乱码 —— 所有文本 I/O 显式指定编码；读取用户文件用 utf-8-sig 免疫 BOM；由 scripts/check_utf8_encoding.py 静态守护
• 白天/深色主题，Fusion 风格，HiDPI 适配；纵坐标线性 / log / sqrt 切换
• 交互式元素周期表（双击选择，带原子量与特征波长）
• 单实例运行：重复双击不会开出多个窗口，而是把已在运行的窗口切到前台
• 数据库管理对话框：三个槽位各自显示「已挂载/未挂载」、记录数、体积，并直接标明该槽位对应哪个下载包

• 路径优先级：GUI 导入的持久化路径 (~/.polyxrd/user_db_paths.json) > 默认位置（存在才用）> ~/.polyxrd/cif_db/ 兜底
• 导入时自动校验库类型：三库表名有重合（COD 无机物与 PDF2 都叫 phases），选错槽位会提示而非静默失败
• 导入后立即生效，无需重启；物相分析面板的「数据库源」下拉同步刷新，未挂载的源自动置灰
• 三个库完全独立，可只装其中一个；一个都不装也能用内置的 106 种参考物相

① 下载 PolyXRD-Setup-vX.Y.Z.exe (Windows x64) 或 Portable 便携包（解压即用）
   ↓
② 安装 (默认 C:\Program Files\PolyXRD\) 后直接运行 PolyXRD.exe
   ↓
③ 按需下载数据库包 —— 各库独立，需要哪个下哪个
   解压到任意目录（必须真正解压到磁盘，不要直接在压缩包里打开）
   ↓
④ 启动 PolyXRD → 菜单「数据库 ▸ 外挂数据库管理…」
   对话框每个槽位上都写着「下载包：… → 解压出 …」，照对上即可，在该行点「导入…」
   → 立即生效，无需重启
   ↓
⑤ 开始使用!

发布口径：Release 提供 Setup 安装包 + Portable 便携包 + 两个 COD 索引库包 （Setup 241 MB / Portable 369 MB / 无机物索引 134 MB / 全库索引 206 MB）。 PDF2-2004 包为 ICDD 版权库，不随 Release 分发，需要时自行准备库文件。

瘦身无机库说明：索引式无机库不含内嵌 CIF。本机若有 COD 原始 cod/cif/ 归档（四级分片目录）则直接按需读取；没有时会自动回退到 COD 官网接口按编号下载 CIF 并缓存（需要联网）。若希望完全离线且单文件自包含， 可改用完整内嵌版 COD_inorganics.sqlite（1.19 GB），两者数据一致。

关于 PDF2-2004 库：该库为 ICDD 商品数据库，受版权保护，本仓库不分发、Release 不提供下载。 持有正版授权的用户可自行准备 PDF2_2004.sqlite 并在「外挂数据库管理…」中作为 PDF2 槽位导入； 未授权时该槽位留空即可，其余功能不受影响。

一个库都不装也能用：程序内置 106 种常见参考物相。 详细说明与排错见上方各段落（外挂数据库管理对话框各槽位已自带说明）。

# 1. 克隆仓库
git clone https://github.com/PolyXRD/PolyXRD.git
cd PolyXRD

# 2. 创建虚拟环境 (Python 3.10+)
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Linux/macOS

# 3. 安装依赖
pip install -r requirements.txt

# 4. 启动应用
python -m polyxrd.main

# 5. 跑测试
python -m pytest -q

仓库根目录的 run_dev.bat 已封装好 PYTHONPATH，双击即可：

run_dev.bat

它直接跑仓库里的 src/，永远是最新代码，不必等 PyInstaller 构建完成， 适合功能验收 / 手测。打包版与源码版的差异只在分发方式，业务代码同源。

:: 改 build.bat 顶部的 set APPVER= 后:
build.bat

build.bat 会依次完成：生成图标 → PyInstaller 打包 → 自检 dist 内无业务数据库 → Inno Setup 编译安装包 → 打便携包 → 生成三个独立数据库包 → 计算 SHA-256。

注意：默认不打包任何数据库。如需把库内嵌进二进制，用 POLYXRD_WITH_DB=1。

仅校验 / 重新生成发布产物（不重新构建 exe）：

pwsh -NoProfile -File scripts\verify_release.ps1 -Version X.Y.Z

① 文件 → 打开 → 载入一个 .xrdml / .txt 样品 (或直接拖放文件到窗口)
② 预处理面板: SNIP-40 扣背景 → SG w=11 p=3 平滑 → Max 归一化
③ 峰检测: 自动阈值 → 搜索
④ 物相检索: 勾选「COD 无机物库」→ 必有元素 [Mg, Al, O] → 搜索
   → Top 候选: MgAl₂O₄ Spinel ✅
⑤ Rietveld 精修: 选中共存相 → 精修向导 → 内置引擎 → 顺序策略
   → 精修完成, 查看 wR 与残差图
⑥ 需要时: CIF 浏览器看 3D 晶胞 / 指标化求晶胞参数 / 导出报告 (CSV/PDF)

启动稳健性设计：单实例守卫用内核命名互斥量实现 —— 上一个实例 无论正常退出还是被任务管理器强杀，都不会影响下一次启动；守卫本身"拿不准就放行"， 绝不因为残留状态把用户挡在门外。

PolyXRD 基于众多高质量开源项目构建 —— Python / PySide6 (Qt6) / PyInstaller / Inno Setup / pymatgen / spglib / scipy / NumPy / pandas / Matplotlib / PyQtGraph / LMFIT / GSAS-II / powerxrd / platformdirs 及 Crystallography Open Database（无机物相数据源），感谢各上游项目的维护者与贡献者社区（ICDD PDF-2 2004 为商业数据库，不随附、不转发，需用户自行取得授权）。

最新版本与全部变更记录见 docs/CHANGELOG.md；二进制产物（Setup 安装包 + 两个 COD 索引库包）前往 👉 Releases 页面 下载。SHA-256 校验值随 Release 附件发布，下载数据库包后建议核对（截断的库能被 SQLite 打开，但读到尾部记录才会报错）。

Copyright (c) 2026 PolyXRD Team.

This software is free for academic research and education. Commercial use is prohibited without a separate written license from the copyright holder. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

版权所有 (c) 2026 PolyXRD Team。

本软件可供学术研究与教学免费使用。 未经版权持有人单独书面许可，禁止用于商业用途。 软件按原样提供，不提供任何担保。

完整条款见 LICENSE（英文）与 LICENSE-CN（中文）；商业授权联系：sshztx@outlook.com。 使用时请同时遵守上游 PySide6 (LGPL/GPL)、pymatgen、COD 等第三方许可证条款。