1. Overview

XMatcher has a three-stage recommended workflow. The fastest path is to download the prebuilt MP500_xrd_database.pkl from GitHub Releases. If you need custom build parameters, download MP500.db and build the peak database yourself.

The retrieval stage reads only MP500_xrd_database.pkl. Do not pass the raw MP500.db directly to XRDRetriever.

3. Install The Environment

Use Python 3.9 or newer and create an isolated environment.

git clone https://github.com/Bin-Cao/XMatcher.git
cd XMatcher

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -e .

For notebooks, tests, and lint tooling:

pip install -r requirements-dev.txt
pytest

4. Download Databases From Releases

Open the project's GitHub Releases page. There are now two download paths:

• MP500_xrd_database.pkl: recommended. This is the prebuilt XMatcher theoretical peak database and can be used directly for retrieval.
• MP500.db: the raw ASE crystal structure database. Download it only if you want to rebuild the peak database yourself or change build parameters such as peak count or 2θ range.

If you download MP500_xrd_database.pkl directly, place it in the project root:

XMatcher/
  MP500_xrd_database.pkl
  exp_data/
  XMatcher/

5. Build The XMatcher Theoretical Peak Database

build_database_parallel.py reads crystal structures from MP500.db, uses pymatgen to calculate theoretical XRD patterns, extracts the strongest peaks, and saves the searchable feature database used by XMatcher.

Small Test Build

python build_database_parallel.py \
  --db-path MP500.db \
  --output MP500_xrd_database.pkl \
  --workers 4 \
  --max-entries 500 \
  --batch-size 200 \
  --n-peaks 30 \
  --two-theta-min 10 \
  --two-theta-max 90

Full Build

python build_database_parallel.py \
  --db-path MP500.db \
  --output MP500_xrd_database.pkl \
  --workers 8 \
  --batch-size 1000 \
  --save-interval 1000 \
  --n-peaks 30 \
  --two-theta-min 10 \
  --two-theta-max 90

After the build finishes, MP500_xrd_database.pkl will appear in the project directory. Retrieval must read this output file:

retriever = XRDRetriever(database_path="MP500_xrd_database.pkl")

6. Run The First Search

The script below reads an example experimental pattern, detects peaks, and retrieves the closest structures from the built MP500_xrd_database.pkl.

from XMatcher import XRDRetriever

retriever = XRDRetriever(
    database_path="MP500_xrd_database.pkl",
    n_peaks=20,
    position_tolerance=0.2,
    scoring_method="hybrid",
)

results = retriever.retrieve_from_file(
    "exp_data/BTc.csv",
    elements=["B", "Tc"],
    element_filter_mode="exact",
    top_n=10,
)

retriever.print_results(results)

best = results[0]
print(best["formula"], best["score"], best["estimated_shift"])
print(best["peak_matches"][:3])

Save it as quick_start.py and run:

python quick_start.py

7. Jupyter API Guide

For a step-by-step notebook workflow covering experimental XRD import, peak-detection tuning, full-database retrieval, and peak-match inspection, open the API example in the project root:

XMatcher_Jupyter_API_Guide_CN_EN.ipynb

The notebook uses MP500_xrd_database.pkl by default and sets QUERY_ELEMENTS = None for full-database retrieval. You can edit the experimental data path, peak-detection parameters, and matching parameters directly.

1. Experimental XRD Input Format

The file needs at least two columns: 2θ in the first column and intensity in the second. Comma, tab, whitespace, and semicolon delimiters are supported.

two_theta,intensity
10.00,5.2
10.02,5.5
10.04,5.1

The reader sorts values, removes invalid rows, merges duplicate 2θ points, and filters negative intensities.

2. Parameter Suggestions

• elements: provide known elements whenever possible to reduce false positives.
• element_filter_mode="exact": use when candidates must contain exactly the given elements.
• element_filter_mode="contains": use when dopants, impurities, or extra elements are possible.
• position_tolerance=0.2: a good starting point; try 0.3 to 0.5 for noisier calibration.
• n_peaks=20: usually enough; increase to 30 for complex or noisy patterns.
• intensity_weight=0.15: keeps the score position-focused when experimental intensities are less reliable.

3. Troubleshooting

MP500.db cannot be found

Make sure the file was downloaded from Releases and build_database_parallel.py --db-path points to the correct location. Relative paths are resolved from the directory where you run the command.

MP500_xrd_database.pkl cannot be found

The build has not finished, or the output file is not in the current directory. Run the build command first, then point XRDRetriever(database_path=...) to the built .pkl file.

No matches returned

Try element_filter_mode="contains" or increase position_tolerance. Also verify the 2θ unit and range in the experimental file.

The App Shows API Not Connected

Make sure python xmatcher_local_api.py --database MP500_xrd_database.pkl is running in the project root and the terminal has no error. If you changed the API URL, confirm it matches http://127.0.0.1:8765 or the actual service address.

No Candidate After Running Identification

Reduce Peak count first. A larger peak count requires more experimental strong peaks to be explained simultaneously; noisy, multiphase, or weak-peak patterns can become too strict. Also check whether Min height and Min prominence missed important peaks.

PDF Module Reports Unknown Endpoint

This usually means an older local API is still running and does not expose /api/cif-xrd. Stop the old terminal and restart the latest xmatcher_local_api.py, or reopen the packaged App.

PDF Calculation Fails

Check that each CIF is valid, then confirm the local environment includes pymatgen. Invalid 2θ ranges, such as a minimum larger than the maximum, can also fail.

The PDF Plot Looks Different From The Main Plot

The main plot is for fast identification and selected candidate overlay; the PDF module is for full validation with background-removed experiment, bottom markers for all theoretical peaks, and multiphase mixture profiles. Use the PDF full-peak comparison for final confirmation.

Database building is slow

Theoretical XRD calculation is computationally heavy. Start with --max-entries, then tune --workers and --batch-size for your machine.

Pickle security warning

This safety boundary applies to the built .pkl feature database. Only load outputs built by yourself or trusted prebuilt feature databases.