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) 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

---

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) 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:

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

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:

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

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.

python mcp_server.py

See 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 (CederGroupHub) and the BGMN 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

  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).

This project's own code is released under the MIT License.