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
.xinDBlayout 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
- 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 incore/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-Inorglibrary, any other.xinDBlibrary can be mounted from any folder (Settings → Reference Database…, orxinmatch 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 aphasestable. See docs/ACCEPTANCE-3COD-20261020.md §6. - Reference libraries are built in the sibling repo, not here.
XinMatch-DataBasebuilds all six libraries (COD/PCOD/TCOD×Inorg/Full); the CIF sources live one level up in../sync-COD(override withXRD_DATA_ROOT), and the built.xinDBfiles default toXinMatch-DataBase/data/. See that repo's Build and acceptance manual for the build/validate/acceptance commands.
- Clean-room: no disassembly or decompilation of proprietary software. Specifications come from official documentation + published algorithms + black-box file-format observation for interoperability.
- Kernel / GUI decoupled: everything in
xinmatch/core/is pure computation (numpy arrays + dataclasses), unit-testable without a display. The GUI inxinmatch/ui/is a thin layer on top. - Open data first: the reference database is built from the COD (CC0) public dump.
- Small, verifiable steps: every task ships with pytest acceptance criteria so an AI agent can build, test, and debug independently.
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)
# (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.ps1The reference libraries (
*.xinDB, ~110 MB–1.7 GB) are not in the repository; the source checkout resolves them from../XinMatch-DataBase/data(XINMATCH_XINDB_DIRoverrides). Tests that need them skip themselves.
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 librariesThe 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.
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).
This software is distributed under a dual license (Academic + Commercial), consistent with the upstream PolyXRD project.
- English: LICENSE
- Chinese (Simplified): LICENSE-CN
Academic use is free under the Academic License; any commercial use requires a separate written Commercial License from the copyright holder (see license text).