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)     A desktop GUI for **automated X-ray diffraction (XRD) phase identification and Rietveld refinement**. Load a diffraction pattern, name a chemical system (or supply your own CIF files), and hit run — a **tree search** (via [`dara`](https://github.com/CederGroupHub/dara)) automatically explores candidate phase combinations, runs a full Rietveld refinement on each with the **BGMN / eflech** engines, and returns ranked solutions with interactive plots, phase weight fractions, lattice parameters, fit metrics (Rwp/Rp/GOF), and exportable refinement files. **No manual peak matching. No hand-built refinement models.** Pattern in, ranked refined phase compositions out — typically in minutes. 📚 **Documentation:** [jojusmathew.github.io/AutoPhaseAnalysis](https://jojusmathew.github.io/AutoPhaseAnalysis/) --- ## Features **Analysis** - **Automated phase matching + Rietveld refinement** — dara's tree search assembles candidate phase combinations and Rietveld-refines every one of them; you never pick peaks or build a refinement model by hand. - Load `.xy`, `.xye`, `.xrdml`, `.raw`, `.rasx`, `.scn`, `.txt` patterns. - **Batch analysis queue** — load many patterns and they are analysed sequentially with the same settings: live per-file queue, results per file with a switcher, and one failed file never kills the rest of the batch. - Search the [Crystallography Open Database (COD)](https://www.crystallography.net/) by chemical system, and/or supply local CIF files — scales to systems with **1000+ candidate structures** via throttled parallel refinement. - Pin phases you know are present (e.g. an internal standard). - Overlay expected phase reflections on the raw pattern before searching. - Quick and Advanced refinement modes (zero-point, sample height, asymmetry, size broadening, preferred orientation, background subtraction). - **Re-refinement** — edit a solution's phase list and run a direct single refinement (no search) to test "what if I drop this phase?". **Robustness** - **Search budget with best-so-far recovery** — huge searches are capped (30 min / 5000 combinations); instead of hanging forever, the app stops and returns the best matches found so far, with a clear warning. - **Resilient COD fetching** — automatic mirror fallback (`crystallography.net` → `qiserver.ugr.es`) and a **self-healing CIF cache**: a download interrupted mid-fetch is detected and repaired on the next run instead of silently searching a degraded candidate pool. **Results & workflow** - Ranked solutions with interactive Plotly charts, phase tables, lattice parameters, and raw `.lst` output. - Export plot data, interactive HTML, text reports, and an **Origin-style publication figure** (300-dpi PNG or vector PDF/SVG). - **Parameter presets** shared between the GUI and the MCP server, plus session restore and a recent-files list. - Optional headless **MCP server** for driving the whole pipeline from an AI agent. --- ## Requirements - **Python 3.13** (developed and tested against 3.13.5). - **macOS, Linux, or Windows.** - **Internet access** on first run (to fetch BGMN binaries) and whenever you search a new chemical system against COD. Once a chemical system's CIFs are cached and BGMN is installed, repeated runs work offline. BGMN binaries are downloaded/installed automatically to a per-user directory (`~/.autophaseanalysis/bgmn`) on first use — no manual setup required. --- ## Installation ### Option 1 — Download the app (macOS) No Python required. Grab the packaged app from the [**Releases page**](https://github.com/jomat733-ops/AutoPhaseAnalysis/releases): 1. Download `AutoPhaseAnalysis-0.1.0-macos-arm64.zip` (Apple Silicon). 2. Unzip and drag `AutoPhaseAnalysis.app` into **Applications**. 3. On first launch macOS will warn that the app is from an unidentified developer — right-click the app → **Open** (or allow it under **System Settings → Privacy & Security**). The app is ad-hoc signed, not notarized. > **Windows:** a packaged Windows version of the app will be released soon. > Until then, Windows (and Linux) users can run from source below. ### Option 2 — Run from source ```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 ``` > The `dara` dependency is pinned to a specific commit that the app's > compatibility patches (`app/patches.py`) were written against. Do not > un-pin it without re-verifying those patches. --- ## Running Installed the packaged app? Just launch **AutoPhaseAnalysis** from Applications. From source: ```bash python main.py ``` On first launch the app will download the BGMN engine (a few seconds) and is then ready. Load a pattern, set the X-ray source / instrument profile, enter a chemical system (e.g. `Fe-As-S`) or add local CIFs, and click **Run Phase Search**. --- ## Building a distributable ```bash pip install pyinstaller pyinstaller QuickPhaseAnalysis.spec ``` Output goes to `dist/` (`AutoPhaseAnalysis.app` on macOS, a one-dir bundle elsewhere). The BGMN binaries are bundled and copied to the writable per-user dir at runtime, so the packaged app works even when installed to a read-only location. --- ## Headless / MCP server `mcp_server.py` exposes every feature over the Model Context Protocol (stdio): phase search, refinement, batch analysis, job progress/cancellation, solution data, exports, and the CIF cache. ```bash python mcp_server.py ``` See [`MCP_SERVER.md`](MCP_SERVER.md) for the tool list and usage. --- ## Data locations | What | Where | |------|-------| | BGMN binaries | `~/.autophaseanalysis/bgmn` | | Working dir (transient downloads) | `~/.autophaseanalysis/work` | | Per-chemical-system CIF cache | OS app-data dir → `AutoPhaseAnalysis/cifs/<system>/` | | Presets / recent files / session | `QSettings` (OS-native store) | Clear a chemical system's CIF cache from **Tools → Refresh COD cache**. --- ## Acknowledgements & licensing - Phase search and refinement are powered by [`dara`](https://github.com/CederGroupHub/dara) (CederGroupHub) and the [**BGMN**](http://www.bgmn.de/) Rietveld engine. If you publish results obtained with this app, please cite both: > 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 is a third-party component licensed under the GNU General Public License version 2 or later (GPL-2.0-or-later), according to published BGMN/Profex license information. Please comply with BGMN's GPL terms before redistributing a packaged app that bundles BGMN binaries. - Reference structures come from the [Crystallography Open Database (COD)](https://www.crystallography.net/). This project's own code is released under the [MIT License](LICENSE).