Skip to content

XinMatch v2.0.0 — Reference database mounts from any location

Choose a tag to compare

@PolyXRD PolyXRD released this 20 Oct 15:30
· 168 commits to master since this release

XinMatch 2.0.0 — Reference database mounts from any location

The changes in this version focus on one thing: the reference library no longer needs to be copied into the install directory. Together with PolyXRD's full switch to .sqlite, the two programs can now directly share the same set of database files.

Main changes

Mount a database from any location
Settings → Reference database → Add external library…, or the command line:

XinMatch.exe libraries --add "D:\XRD-Data\PolyXRD\COD_inorganics.sqlite"
XinMatch.exe libraries --list --json
XinMatch.exe libraries --build <id> --force

Mount info is recorded in <user data>\libraries.json (default %USERPROFILE%\.xinmatch\); the source file is not moved and is not modified.

PolyXRD databases usable directly

  • phases libraries (peaks_d/peaks_i) are converted once into an index cache in XinMatch's native schema, stored under <user data>\indexes\external\, auto-invalidated and rebuilt by source mtime+size, conversion is cancellable;
  • libraries with an entries+peaks+elements structure (e.g. the 3COD series) mount with zero conversion;
  • structure-only dumps (cod_index.sqlite / cod_entries) are explicitly rejected with a reason, rather than mounting an empty library.

CLI / GUI in sync
search, run both go through the new open path; the GUI gained "Add external library / Remove mount / Build·rebuild index", and opening a library without an index auto-builds it behind the busy overlay, then retries.

3 packaging defects found and fixed before release

All three only appeared when "frozen into exe + going through the packaging pipeline"; running from source was fine:

  1. The frozen libraries command couldn't actually open libraries — the binary dispatcher hard-coded 6 subcommands and missed libraries (and earlier batch, instrument). XinMatch.exe libraries --add … was treated as an unknown command and launched the GUI directly, without erroring or mounting. In other words, 2.0.0's headline feature was broken in the release build. Now fixed by deriving the subcommand set at runtime from the CLI parser, plus 12 regression tests.
  2. Building the internal variant deleted the already-built release variant — the variant was passed only via env var; in nested invocations it never reached the child process, so the internal build computed the release output dir name and PyInstaller deleted dist\xinmatch-2.0.0\ before writing. Now fixed by passing via a file (build/variant.request) and asserting before the build.
  3. build_exe.ps1 lacked a UTF-8 BOM — Chinese comments were decoded as ANSI under PowerShell 5.1, and when certain bytes fell on a line-ending backslash they merged the next line of code into the comment, manifesting as $LASTEXITCODE being empty, paths becoming $null, and other puzzling behavior. Now stored as UTF-8 with BOM.

Validation

  • ruff: All checks passed; mypy: 114 files, 0 errors
  • Default test suite: 1351 items / 1344 passed / 0 failed / 7 skipped (742.7 s, excluding slow)
  • Both frozen variants were verified end-to-end: import --help, libraries --json, libraries --add (78,747 entries, needs_index=false), search (Al₂O₃ pattern, Top-1 FoM 0.802, ground truth COD 2300448 ranked 2nd), registration self-check (release: unregistered / internal: internal evaluation build)

Install

Method 1: Installer (recommended)

  1. Run XinMatch-Setup-2.0.0.exe, install location selectable;
  2. Download xinmatch-cod-db-2.0.0.zip, extract its data\cod_inorganics.db into the install directory (i.e. <install dir>\data\cod_inorganics.db);
  3. Launch XinMatch. To use another library, simply "Add external library" pointing to a .sqlite anywhere.

Method 2: No-install internal evaluation build

Extract XinMatch-Internal-2.0.0.zip and put data\cod_inorganics.db inside its data\ folder. The internal build has no registration mechanism; the status bar shows "internal evaluation build" fixed.

Known limitations

  • GSAS-II not bundled: Rietveld / quantitative refinement only enable if GSAS-II is separately installed on the machine; all other features are unaffected.
  • Reference library not bundled: neither the installer nor the zip contains the database (.db ~745 MB); it must be placed separately per step 2 above.
  • Large-library search cost: million-scale predicted libraries like PCOD cost ~11 min/pattern at default params; recommended with element constraints or offline batch processing. The experimental COD sub-library (79k entries, 0.89 GiB) is usable interactively.
  • The slow-marked test suite (GSAS-II real refinement, L3 acceptance, etc.) was not run this time.

Checksums

File Bytes
XinMatch-Setup-2.0.0.exe 180,974,864
XinMatch-Internal-2.0.0.zip 265,471,156
xinmatch-cod-db-2.0.0.zip 204,614,240

Full acceptance record in repo docs/ACCEPTANCE-v2.0.0-20261020.md.