Skip to content
XinProfPublic

About

XinMatch — open-source powder XRD phase-analysis platform: search-match, sequential multi-phase identification and Rietveld quantification, with a PySide6 GUI, CLI and Python library API.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

XinMatch logo

XinMatch

Chinese (Simplified) · English

Open-source powder X-ray diffraction (XRPD) phase analysis platform — a clean-room implementation guided by publicly documented XRD phase-analysis workflows, published algorithms and open reference data (COD).

✅ v3.8.0. Core computation kernel + full GUI + dual-mode search-match (peak-list FoM / FPFM full-profile fitting, formerly SMPF) + sequential multi-phase identification + true March-Dollase preferred-orientation modelling + GSAS-II refinement pipeline + quantitative Rietveld (main-phase wt% < 3 on certified samples). Reference data is the single v3 columnar .xinDB layout with the COD-Inorg library bundled as the built-in default — works out of the box, still mountable from any folder.

This release (v3.8.0) — search-match benchmarking and diagnostics, with no change to default search results: a fourth ruler built on seven measured multi-phase patterns (33 crystalline phases, 13 metrics), a configurable prescreen pool cap, a default-off adaptive pool, and an element-restraint upper bound that is the first one-directional improvement across all four rulers. The frozen CLI dispatcher now recognises userdb. All external documentation is published in English.

Reissued 2026-11-16 (same version and tag): the installer now bundles the production registration key for legacy-generator compatibility; default search results are unchanged.

Download v3.8.0 · Changelog · This release · Status · Roadmap

What XinMatch does

  • Qualitative phase analysis (search-match): identify crystalline phases from an experimental powder diffraction pattern against a reference database.
  • Sequential multi-phase identification (v3.1.0): confirm the best phase, subtract what it explains, and re-search the remaining unexplained peaks for the next phase — repeat until no significant peak is left. Each confirmation is reversible, and the residual status (peaks explained / left over / too weak to use) is shown next to the candidate list.
  • Phase-level candidate list (v3.2.0): a reference library holds dozens of cards per phase, so near-identical entries used to flood the Top-N. Cards now fold into one row per phase (identical unit cell / element set / space group, see core/search/phase_key.py); the "Variants" column shows how many cards were folded, its tooltip lists each card with its cell, and the context menu expands them again.
  • Sparse-phase marks (v3.3.0): the residual search flags candidates whose strongest reference line sits on a strong leftover peak (★ in the first column, rule in core/search/sequential.py). The FoM counts how many peaks a candidate explains, so a correct 6-line metal never outvotes a 150-reflection card; the mark makes it visible without changing the order.
  • Quantitative phase analysis (RIR, internal standard, Rietveld).
  • Raw data preprocessing: smoothing, background subtraction, Kα₂ stripping, zero-point / displacement correction.
  • Profile fitting & peak search.
  • Rietveld / Le Bail refinement (delegated to GSAS-II).
  • Powder indexing (Treor / Dicvol).
  • Microstructure: crystallite size (Scherrer), microstrain, crystallinity.
  • Reports & export, GUI (PySide6), CLI / batch scripting.
  • Reference-database mounting: besides the bundled COD-Inorg library, any other .xinDB library can be mounted from any folder (Settings → Reference Database…, or xinmatch libraries --add <path>). v3 libraries are self-contained columnar files, so nothing is copied or converted.
  • 3COD libraries are split by provenance (tools/split_3cod.py): COD-Inorg (experimental, 79 k), PCOD-Inorg (predicted, 1.06 M), TCOD-Inorg (theoretical, 47 k). Mount all three side by side in XinMatch; PolyXRD only ever picks up the experimental one, because the other two ship without a phases table. See docs/ACCEPTANCE-3COD-20261020.md §6.
  • Reference libraries are built in the sibling repo, not here. XinMatch-DataBase builds all six libraries (COD / PCOD / TCOD × Inorg / Full); the CIF sources live one level up in ../sync-COD (override with XRD_DATA_ROOT), and the built .xinDB files default to XinMatch-DataBase/data/. See that repo's Build and acceptance manual for the build/validate/acceptance commands.

Design principles

  1. Clean-room: no disassembly or decompilation of proprietary software. Specifications come from official documentation + published algorithms + black-box file-format observation for interoperability.
  2. Kernel / GUI decoupled: everything in xinmatch/core/ is pure computation (numpy arrays + dataclasses), unit-testable without a display. The GUI in xinmatch/ui/ is a thin layer on top.
  3. Open data first: the reference database is built from the COD (CC0) public dump.
  4. Small, verifiable steps: every task ships with pytest acceptance criteria so an AI agent can build, test, and debug independently.

Project layout

xinmatch/
├── core/            # pure computation kernel (no GUI)
│   ├── model/       # Pattern, Peak, Entry, Phase, Restraints, Project
│   ├── io/          # 33 diffraction formats + CIF + exporters
│   ├── preprocess/  # smoothing, background, Kα2, zero point, ...
│   ├── peak/        # peak search, profile fitting, shapes
│   ├── db/          # SQLite reference database (COD) + user DB
│   ├── search/      # FoM search-match, PFSM, restraints
│   ├── index/       # Treor / Dicvol indexing
│   ├── refine/      # Le Bail / Rietveld (delegated to GSAS-II)
│   ├── quant/       # RIR, internal standard, Rietveld quant
│   ├── micro/       # crystallite size, microstrain, DOC
│   └── report/      # report data model + rendering
├── ui/              # PySide6 GUI
├── cli/             # command-line / batch interface
├── utils/           # registration + build variant (stdlib only, no Qt)
tests/               # pytest suite + fixtures + reference baseline
docs/                # analysis docs (reference help retained externally)
tools/               # helper scripts (doc extraction, baseline building)

Getting started

# (optional) create a virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1

# install in editable mode with dev + gui extras
pip install -e ".[dev,gui]"

# run the test suite (fast subset; the ``slow`` marker is excluded by default)
pytest

# include the numerically heavy suite (turn-on least squares, GSAS-II
# subprocesses, L3 acceptance curve_fit) — tens of minutes
pytest -m slow

# full local CI (ruff + mypy + tests), mirrors .github/workflows/ci.yml
powershell -File tools/ci.ps1

The reference libraries (*.xinDB, ~110 MB–1.7 GB) are not in the repository; the source checkout resolves them from ../XinMatch-DataBase/data (XINMATCH_XINDB_DIR overrides). Tests that need them skip themselves.

Run the working tree without building

run_dev.bat starts the code in the working tree in place — no PyInstaller build and no install step, so what you see is always the latest source. Without arguments it opens the GUI; any other arguments are forwarded to the CLI (python -m xinmatch.cli.main):

run_dev.bat                                  :: GUI
run_dev.bat search pat.txt --db ..\XinMatch-DataBase\data\COD-Inorg-20261020.xinDB --top-n 5 --json
run_dev.bat libraries --json                 :: list available .xinDB libraries

The interpreter is resolved in this order and echoed on startup: %XINMATCH_DEV_PYTHON% → .venv\Scripts\python.exe → venv\Scripts\python.exe → D:\Project\XRD\python310\python.exe → python on PATH. Because the batch file cds to the repository root, python -m loads the local xinmatch/ package even when a different copy is installed in site-packages.

Builds & registration

Since v1.7.0 two binaries are produced. Since v3.0.0 both builds bundle the default library COD-Inorg-<snapshot>.xinDB (unzip/install and you can search-match; located at <install-dir>\data\, replaceable, or mount other .xinDB libraries):

Build Artifact Registration mechanism Right end of the status bar
Release build (release) XinMatch-Setup-<v>.exe (install location selectable at install time) Yes: registration status checked on every launch Registered: <organization/department name> / Unregistered
Internal evaluation build (internal) XinMatch-Internal-<v>.zip (no installation, for internal use) None bold red internal evaluation version

Current release: v3.8.0 — XinMatch-Setup-3.8.0.exe. Per-version sizes, hashes and acceptance results live in CHANGELOG.md and docs/RELEASE-NOTES-v3.8.0.md.

The reference database is unchanged in this release; both binaries bundle COD-Inorg-20261020.xinDB (78,035 phases). .xinm export must be paired with XinRefinement 1.1.0. Larger external libraries (PCOD / TCOD / Full / Materials Project) are distributed in the sister repository XinMatch-DataBase Releases: Download *.xinDB.zip → unzip → "Settings → Reference Database…" or XinMatch.exe libraries --add <path> to mount; multiple libraries can coexist; see docs/RELEASE-NOTES-v3.4.0.md §7.

When the release build is unregistered, a prompt pops up on every launch:

This software is not registered — all rights reserved, commercial use prohibited. For registration, please contact sshztx@outlook.com

Click "OK" to dismiss the prompt and keep using the software (the prompt returns at the next launch); click "Enter registration code" to paste the code, and once it validates, registration is complete and the prompt no longer appears. You can also register any time via Help → Enter registration code (&R)….

Registration codes are generated by the developer from the "organization/department name" supplied by the user: PXRD1-XXXX-XXXX-… (Base32 payload UTF8(org name) + HMAC-SHA256[:8]); the software re-verifies it and can recover the organization name for display in the status bar; no network connection or machine code is needed, and the same organization can use it on multiple machines. The algorithm is shared with the PolyXRD family (reusing D:\Project\XRD\PolyXRD-Reg, with a copy in this repo at xinmatch/utils/registration.py).

License

This software is distributed under a dual license (Academic + Commercial), consistent with the upstream PolyXRD project.

Academic use is free under the Academic License; any commercial use requires a separate written Commercial License from the copyright holder (see license text).

About

XinMatch — open-source powder XRD phase-analysis platform: search-match, sequential multi-phase identification and Rietveld quantification, with a PySide6 GUI, CLI and Python library API.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages