AutoPhaseAnalysis

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png"> <img src="assets/banner-light.png" alt="AutoPhaseAnalysis" width="600"> </picture> </p> [](https://github.com/jomat733-ops/AutoPhaseAnalysis/releases) [](https://jojusmathew.github.io/AutoPhaseAnalysis/) [](LICENSE)     用于 **自动X射线衍射（XRD）相位识别** 和 **Rietveld精细化** 的桌面GUI应用程序。加载衍射图案，命名化学系统（或提供自己的CIF文件），然后点击运行 — **树搜索** （通过 [`dara`](https://github.com/CederGroupHub/dara)）自动探索候选相位组合，对每个相位组合进行完整的Rietveld精细化，并返回带有交互式图表的排名解决方案、相位权重分数、晶格参数、拟合指标（Rwp/Rp/GOF）和可导出的精细化文件。 **无需手动峰值匹配。无需手动建立精细化模型。** 图案输入，排名精细化的相位组成输出 — 通常在几分钟内。 📚 **文档:** [jojusmathew.github.io/AutoPhaseAnalysis](https://jojusmathew.github.io/AutoPhaseAnalysis/) --- ## 功能 **分析** - **自动相位匹配 + Rietveld精细化** — dara的树搜索组装候选相位组合并精细化每一个相位组合；您无需手动选择峰值或建立精细化模型。 - 加载 `.xy`、`.xye`、`.xrdml`、`.raw`、`.rasx`、`.scn`、`.txt` 图案。 - **批量分析队列** — 加载多个图案，它们会按照相同的设置顺序分析：实时每文件队列、每文件结果，并带有切换器，以及一个失败的文件不会影响其他文件的分析。 - 在 [晶体学开放数据库（COD）](https://www.crystallography.net/) 中按化学系统搜索，并/或提供本地CIF文件 — 通过限速并行精细化扩展到具有 **1000+候选结构** 的系统。 - 固定您已知存在的相位（例如，内部标准）。 - 在搜索前将预期的相位反射叠加到原始图案上。 - 快速和高级精细化模式（零点、样品高度、不对称性、尺寸展宽、择优取向、背景扣除）。 **稳健性** - **搜索预算与最佳恢复** — 大型搜索被限制（30分钟/5000组合）；应用程序不会无限期挂起，而是停止并返回到目前为止找到的最佳匹配，并附有明确的警告。 - **弹性COD获取** — 自动镜像回退（`crystallography.net` → `qiserver.ugr.es`）和 **自我修复CIF缓存**：在下一次运行中检测和修复中断的下载，而不是静默搜索降级的候选池。 **结果与工作流** - 带有交互式Plotly图表、相位表、晶格参数和原始 `.lst` 输出的排名解决方案。 - 导出绘图数据、交互式HTML、文本报告和 **Origin-style出版物图表** （300-dpi PNG或矢量PDF/SVG）。 - **参数预设** 在GUI和MCP服务器之间共享，以及会话恢复和最近文件列表。 - 可选的无头 **MCP服务器** 用于从AI代理驱动整个管道。 --- ## 要求 - **Python 3.13** （开发和测试版本为3.13.5）。 - **macOS、Linux或Windows.** - **首次运行需要互联网访问** （获取BGMN二进制文件）以及每次搜索新的化学系统与COD。 一旦化学系统的CIF被缓存，BGMN被安装，重复运行即可离线进行。 BGMN二进制文件在首次使用时会自动下载/安装到每个用户的目录（`~/.autophaseanalysis/bgmn`）— 无需手动设置。 --- ## 安装 ### 选项1 — 下载应用程序（macOS） 无需Python。 从 [**发布页面**](https://github.com/jomat733-ops/AutoPhaseAnalysis/releases) 获取打包的应用程序： 1. 下载 `AutoPhaseAnalysis-0.1.0-macos-arm64.zip` （Apple Silicon）。 2. 解压并将 `AutoPhaseAnalysis.app` 拖入 **应用程序**。 3. 在首次启动时，macOS会警告应用程序来自未识别的开发者 — 右键单击应用程序 → **打开** （或在 **系统设置 → 隐私和安全** 下允许）。 应用程序是临时签名的，但未经过公证。 > **Windows:** 打包的Windows版本应用程序将很快发布。 在此期间，Windows（和Linux）用户可以从下面的源代码运行。 ### 选项2 — 从源代码运行 ```bash git clone https://github.com/jomat733-ops/AutoPhaseAnalysis.git cd AutoPhaseAnalysis python3.13 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt ``` > `dara` 依赖项被固定到特定的提交版本，该版本已针对应用程序的兼容性补丁（`app/patches.py`）进行了编写。 请勿在未经重新验证这些补丁的情况下取消固定。 --- ## 运行 安装了打包的应用程序？直接从应用程序启动 **AutoPhaseAnalysis**。 从源代码： ```bash python main.py ``` 在首次启动时，应用程序将下载BGMN引擎（几秒钟），然后准备就绪。 加载图案，设置X射线源/仪器配置文件，输入化学系统（例如 `Fe-As-S`）或添加本地CIF，然后单击 **运行相位搜索**。 --- ## 构建可分发版本 ```bash pip install pyinstaller pyinstaller QuickPhaseAnalysis.spec ``` 输出进入 `dist/` （`AutoPhaseAnalysis.app` 在macOS上，其他平台为单目录捆绑包）。 BGMN二进制文件在运行时会被捆绑并复制到可写入的每个用户目录，因此打包的应用程序即使安装在只读位置也可用。 --- ## 无头/MCP服务器 `mcp_server.py` 通过Model Context Protocol（stdio）公开所有功能：相位搜索、精细化、批量分析、作业进度/取消、解决方案数据、导出和CIF缓存。 ```bash python mcp_server.py ``` 参见 [`MCP_SERVER.md`](MCP_SERVER.md) 获取工具列表和使用方法。 --- ## 数据位置 | 位置 | 目录 | |------|-------| | BGMN二进制文件 | `~/.autophaseanalysis/bgmn` | | 工作目录（临时下载） | `~/.autophaseanalysis/work` | | 每个化学系统的CIF缓存 | 操作系统应用程序数据目录 → `AutoPhaseAnalysis/cifs/<system>/` | | 预设/最近文件/会话 | `QSettings` （操作系统原生存储） | 从 **工具 → 刷新COD缓存** 清除化学系统的CIF缓存。 --- ## 致谢与许可 - 相位搜索和精细化由 [`dara`](https://github.com/CederGroupHub/dara) （CederGroupHub）和 [**BGMN**](http://www.bgmn.de/) Rietveld引擎提供支持。 如果您使用此应用程序获得的结果，请引用两者： > Fei, Y., McDermott, M. J., Rom, C. L., Wang, S. & Ceder, G. (2026). Dara: Automated multiple-hypothesis phase identification and refinement from powder X-ray diffraction. *Chemistry of Materials*, 38(3), 1364–1376. [doi:10.1021/acs.chemmater.5c02820](https://doi.org/10.1021/acs.chemmater.5c02820) > Bergmann, J., Friedel, P. & Kleeberg, R. (1998). BGMN — a new fundamental parameters based Rietveld program for laboratory X-ray sources, its use in quantitative analysis and structure investigations. *CPD Newsletter, Commission of Powder Diffraction, International Union of Crystallography*, No. 20, 5–8. - BGMN是第三方组件，遵循GNU通用公共许可证版本2或更高版本（GPL-2.0-or-later），根据已发布的BGMN/Profex许可证信息。 在重新分发捆绑BGMN二进制文件的打包应用程序之前，请遵守BGMN的GPL条款。 - 参考结构来自 [晶体学开放数据库（COD）](https://www.crystallography.net/)。 本项目自己的代码在 [MIT许可证](LICENSE) 下发布。