XRD Diffraction Matching Guide

Overview

XRD (X-ray diffraction) phase identification is a core technique in materials characterization. Based on pymatgen, this platform pre-computes diffraction peaks from the CIF crystal structures of the full material collection, building an XRD library that spans the HEA / TRA / ELA datasets. You only need to paste a list of experimentally measured diffraction peak 2θ (°) values, and the system returns the closest crystal structures by peak-position and intensity similarity, assisting rapid phase identification.

• Input: a 2θ list (optionally with intensities, 2θ:intensity), separated by commas / spaces / newlines.
• Output: candidate materials (MP-ID, dataset, F1, recall, matched peaks and hkl), with the full diffraction pattern available on expand.
• Multi-target: common targets such as Cu / Mo / Co / Cr / Ag are supported; diffraction peak positions shift with wavelength.

Target Selection

Different targets have different wavelengths, so the absolute positions of the diffraction peaks change accordingly; the choice should account for the sample's absorption coefficient, ferromagnetism and resolution requirements.

Matching Principles

The search adopts a “three-strongest-peaks-first” strategy: each material's three strongest peaks (by intensity, peak 1 ≥ peak 2 ≥ peak 3) are pre-stored in the database. The three highest-intensity peaks of your experimental pattern serve as the search keys, recalling candidates first from the main library's three-strongest index, then matching the remaining peaks against each candidate's full pattern, ranked by F1 and recall.

• Three strongest peaks: it is recommended to provide the three strongest peaks (the 3 highest-intensity ones) directly; at least 3 peaks are required to search.
• Strong hits: the number of query key peaks matched among the candidate material's three strongest peaks (0–3), the primary ranking criterion.
• Recall: the fraction of your experimental peaks that are explained; higher is more reliable.
• F1: the harmonic mean of precision and recall, balancing hits and conciseness.
• Peak tolerance: default 0.7°, controlling the allowed deviation in peak-position matching.
• hkl notation: 4-index Miller-Bravais for hexagonal/trigonal systems, 3-index otherwise.
• Ranking prioritizes “strong hits → F1 → recall”.

API Endpoints

XRD diffraction matching is served through one unified endpoint that switches between three modes automatically based on the parameters passed: matching mode (pass peaks to search for similar materials by experimental peaks), pattern mode (pass mp_id to return that material's full diffraction pattern), and browse mode (pass neither, to return the default list of the first N records). Parameter priority is peaks > mp_id > browse. Matching and browse results are deduplicated by mp_id across datasets: when the same material has records in multiple datasets (HEA / TRA / ELA) only the highest-priority one is kept (HEA → TRA → ELA). Rate limits and error responses follow the platform-wide policy; see the API Endpoints documentation for details.

Query Parameters

Matching Mode: match materials by diffraction peaks

curl "https://heas.labs.gt.ac.cn/api/v1/xrd?peaks=21.2,44.5,64.8:80&tolerance=0.7&limit=50&target=CuKa"

{
  "success": true,
  "query": {
    "peaks": [{"t":21.2,"i":80},{"t":44.5,"i":50},{"t":64.8,"i":30}],
    "tolerance": 0.7
  },
  "count": 1,
  "results": [
    {
      "mp_id": "mp-16496",
      "type": "HEA",
      "formula": "AlFe3",
      "score": 0.912,
      "strong_hits": 3,
      "recall": 1.0,
      "matched": 3,
      "query_peaks": 3,
      "matched_peaks": [
        {"query_t":21.2,"match_t":21.18,"match_hkl":"(111)","delta":0.02},
        {"query_t":44.5,"match_t":44.52,"match_hkl":"(200)","delta":0.02},
        {"query_t":64.8,"match_t":64.79,"match_hkl":"(220)","delta":0.01}
      ],
      "three_strong": [21.18, 44.52, 64.79]
    }
  ]
}

Matching results[] fields

Pattern Mode: fetch a material's diffraction pattern

curl "https://heas.labs.gt.ac.cn/api/v1/xrd?mp_id=mp-16496&target=CuKa"

{
  "success": true,
  "data": {
    "mp_id": "mp-16496",
    "type": "HEA",
    "n_peaks": 28,
    "radiation": "Cu Kα",
    "wavelength": 1.5418,
    "three_strong": [21.18, 44.52, 64.79],
    "three_strong_by_target": {"CuKa": [21.18, 44.52, 64.79]},
    "peaks": [
      {"t":21.18,"i":100,"hkl":"(111)"},
      {"t":44.52,"i":55,"hkl":"(200)"},
      {"t":64.79,"i":35,"hkl":"(220)"}
    ]
  }
}

# XRD pattern
mp_id: mp-16496
type: HEA
radiation: Cu Kα
wavelength: 1.5418 A
# generated using pymatgen
2theta(deg)	intensity(%)	hkl
21.1800	100.00	(111)
44.5200	55.00	(200)
64.7900	35.00	(220)

Browse Mode: default diffraction pattern list

Without peaks / mp_id, the database preview list is returned (catalog information only, without full patterns). Paging is supported via page + limit; the response carries total / page / total_pages for client-side pagination. The same material may exist in multiple datasets (HEA / TRA / ELA); the browse list is deduplicated across datasets by HEA → TRA → ELA priority, keeping only the highest-priority entry (e.g. if an mp_id has records in both HEA and TRA, only the HEA version is returned), avoiding duplicate listings.

curl "https://heas.labs.gt.ac.cn/api/v1/xrd?limit=10&page=2&target=CuKa"

{
  "success": true,
  "query": {"mode":"browse","target":"CuKa","page":2,"per_page":10},
  "count": 10,
  "total": 170157,
  "page": 2,
  "total_pages": 17016,
  "results": [
    {
      "mp_id": "mp-10001",
      "type": "TRA",
      "element": "W",
      "n_peaks": 18,
      "three_strong": [30.45, 40.12, 65.33],
      "formula": "W"
    }
  ]
}

FAQ

Why do different targets give different results?

Diffraction peak positions are determined by the wavelength: the 2θ peak positions of the same material differ under different targets, so matching must use the target library consistent with your experiment.

Can a small number of main peaks be matched?

Yes. Hitting the main peaks (the first few strongest peaks) can yield high recall; the system preferentially returns the materials that explain the most experimental peaks.

Why are there 4 numbers in the hkl?

Hexagonal / trigonal systems use the 4-index Miller-Bravais notation (h,k,i,l), while the other systems use the 3-index notation (h,k,l); both are standard representations.

How does browse mode page?

Browse mode (without peaks / mp_id) supports paging via limit (records per page, 1–100) and page (page number, starting from 1); the response contains total / page / total_pages for client-side pagination, and the web preview also provides Previous / Next navigation.

Why does the same material appear only once?

The data spans multiple datasets (HEA / TRA / ELA), so the same material could appear repeatedly. The browse list is deduplicated across datasets by HEA → TRA → ELA priority, keeping only the highest-priority entry; the detail endpoint locates records precisely by mp_id + dataset and is unaffected by deduplication.