PeakMatch

Open-source powder X-ray diffraction (PXRD) analysis tool. PeakMatch detects and fits peaks, identifies phases against open crystal-structure databases (no ICDD licence required), estimates crystallite size and microstrain, and runs whole-pattern Rietveld refinement. It runs locally and opens in your web browser.

The precomputed databases (MC3D, COD, MP, OQMD) for peak-matching will be added soon.

Status — testing/development. PeakMatch is under active development and should be treated as a preview: results have not been fully validated and behaviour may change between versions. Please double-check anything you rely on.

---

What you can do

• Load a pattern — drag in a two-column .xy file (2θ vs intensity), or click Load sample to try it immediately.
• Detect & fit peaks — automatic peak finding (prominence, second-derivative, or wavelet methods) with a profile fit (Gaussian / Lorentzian / Pseudo-Voigt) on every peak for accurate positions, widths, and areas. Add or remove peaks by clicking on the plot.
• Identify phases (search-match) — rank candidate phases from open databases (Materials Project, MC3D, OQMD, COD, or your own) against your peaks. Filter by chemistry with element constraints. The bundled reference data is a small demonstration set; the full databases will be made available later.
• Multi-phase analysis — accept a phase, subtract its peaks, and re-search the leftovers to find additional phases. Accepted phases are overlaid on the plot.
• Structural analysis (Williamson–Hall) — estimate crystallite size and microstrain from peak broadening, with optional instrumental-broadening correction from an uploaded line-standard file (auto-fitted Caglioti curve).
• Rietveld refinement (beta) — whole-pattern refinement of scale, background, unit cell, zero-shift, and peak-shape parameters, with R-factors (Rwp, Rp, Rexp) and goodness-of-fit. This feature is in beta and will be made fully available later.
• Export — save the peak table as CSV.

---

Installation

PeakMatch runs on Windows, macOS, and Linux. Setup is three steps: install two free tools, download the code, and run one script.

Step 1 — Install the prerequisites

You need Rust and Node.js (version 18 or newer). Both are free.

• Rust (provides the cargo build tool) — install from https://rustup.rs, or on macOS/Linux run:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

  Important: the installer adds cargo to your PATH, but only for new terminals. After it finishes, either close and reopen your terminal, or load it into the current one:

  source "$HOME/.cargo/env"

  (On Windows, close and reopen the terminal instead.) Without this you'll get cargo: command not found even though Rust is installed.
• Node.js 18+ — download from https://nodejs.org (the "LTS" version), or use your package manager (brew install node, sudo apt install nodejs npm, …).

Check they're installed (open a fresh terminal first):

cargo --version     # should print e.g. cargo 1.80+
node --version      # should print v18 or higher

cargo: command not found? Rust was installed but its folder isn't on your PATH yet in this terminal. Run source "$HOME/.cargo/env" (macOS/Linux) or open a new terminal window, then try again. If it still fails, re-run the rustup installer above.

Step 2 — Download PeakMatch

git clone https://github.com/bracerino/peak-match.git

Step 3 — Enter the folder

cd peak-match

Step 4 — Start it

./run.sh

The first run builds everything (it downloads dependencies and compiles the app — this takes a few minutes the first time only; later runs start in seconds). When it finishes you'll see:

▶ serving on http://localhost:8000

Step 5 — Open it in your browser

Go to http://localhost:8000. That's it — PeakMatch is running.

To stop the app, press Ctrl+C in the terminal. To start it again later, just cd peak-match and run ./run.sh again.

Windows note: run the commands in Git Bash or WSL (Windows Subsystem for Linux) so the ./run.sh script works.

---

Using your own structure databases (optional)

PeakMatch ships with a few example phases in Databases/. To search against your own crystal structures, you can turn a folder of .cif / POSCAR files into a searchable database. This step needs Python (3.9+).

# 1. create and activate a Python environment
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# 2. install the builder's dependencies
pip install -r scripts/requirements.txt

# 3. build a database from a folder of structures
python scripts/build_database.py \
    --input  Structures \
    --output Databases/my_phases.json \
    --name   my_phases

Drop the resulting .json into the Databases/ folder and restart the app (Ctrl+C, then ./run.sh) — it's picked up automatically and appears in the database selector. Point --input at any folder of structure files.

Diffraction patterns are computed with xrd-rust, a Rust-accelerated version of pymatgen's XRDCalculator.

---

How it works (for the curious)

• Peak fitting — each detected peak is refined with a Levenberg–Marquardt fit over a local window (baseline removed) to a Gaussian, Lorentzian, or Pseudo-Voigt profile, so the reported centre is the true sub-step position, not just the tallest data channel.
• Search-match — reference phases are stored as d-spacings + relative intensities (wavelength-independent). At search time the engine regenerates 2θ positions for your chosen radiation and scores each phase by peak overlap and intensity agreement (or full-profile cosine similarity).
• Rietveld — a standard whole-pattern model (y = background + Σ scale · Σ intensity · profile) refines scale, Chebyshev background, unit cell (via the reciprocal metric tensor), zero-shift, Caglioti peak widths, and Pseudo-Voigt mixing by least squares.

Everything computational runs in a compiled Rust core, so it's fast even on large databases.

---

License

See LICENSE.