Skip to content

Phase Search Workflow

This page describes the end-to-end automated analysis pipeline — what happens between clicking Run Phase Search and seeing ranked solutions. Everything in between is hands-off: the app identifies the phases and refines them for you. The same pipeline backs both the GUI and the MCP server.

Overview

flowchart TD
    A[Load pattern] --> B{CIFs cached?}
    B -- yes --> D[Isolate pattern to temp dir]
    B -- no --> C[Download CIFs from COD]
    C --> D
    D --> E[Tree search: refine every candidate phase combination]
    E --> F[Rank solutions by fit]
    F --> G[Package top 10 solutions]
    G --> H[Display / export]

Steps in detail

1. Input isolation

The chosen pattern is copied to a fresh temporary directory as pattern.xy. This avoids read-only-file issues and legacy filename-length limits, and keeps the original untouched.

2. CIF acquisition

The app checks a persistent, per-chemical-system cache. If CIFs for the system already exist locally, the COD download is skipped entirely. Otherwise structures are downloaded concurrently from COD (with mirror fallback and failure resilience) and stored in the cache for next time.

3. Tree search and refinement

The core search_phases() call runs dara's tree search — the automation at the heart of the app. Each node in the tree is a candidate phase combination: the search starts from single-phase candidates, runs a real BGMN Rietveld refinement on every node, and expands the best-fitting branches with additional phases. By the time a solution is ranked, it has already been fully refined — there is no manual peak matching or model building at any point.

Large phase spaces (1000+ CIFs) are throttled with a sliding window so the underlying Ray cluster is not overwhelmed, and runaway searches are bounded by the search budget.

4. Packaging

The top solutions are packaged for display, each carrying:

  • Fit metrics — Rwp, Rp, Rexp, GoF, and the Durbin–Watson statistic.
  • Phase weight fractions (with ESD).
  • A profile table (2θ / Observed / Calculated / Background / Difference).
  • A peaks table (Bragg reflections per phase).
  • The raw .lst refinement output.
  • Structural data — lattice parameters, cell volume, and space group.

Reading the fit metrics

Metric Meaning Rule of thumb
Rwp Weighted profile residual Lower is better
Rp Profile residual Lower is better
Rexp Expected residual (statistical floor) Rwp approaching Rexp is good
GoF Goodness of fit = Rwp / Rexp Closer to 1 is better
Durbin–Watson Serial correlation of residuals Values near 2 indicate little correlation

Metrics are not the whole story

A low Rwp does not guarantee the right phases — always sanity-check the difference curve and whether the identified phases are chemically plausible for your sample.

  • Pick a promising rank and inspect its lattice parameters and difference curve.
  • Export the plot data, interactive HTML, or text report.
  • Optionally edit the phase list and re-run a single refinement (the GUI's Refine Phases, or start_refinement over MCP) with the exact CIFs from a chosen solution.
  • For the final fit, switch the Refine panel to Advanced and re-refine the chosen solution — search in Quick mode first, polish in Advanced mode after.