Skip to content

XinMatch v3.2.0 — Phase-level identity: candidate folding + dual prescreen quota + new logo

Choose a tag to compare

@PolyXRD PolyXRD released this 04 Nov 10:06
· 168 commits to master since this release

Download: XinMatch-Setup-3.2.0.exe (release installer, with registration mechanism) or XinMatch-Internal-3.2.0.zip (no-install internal evaluation build). Both bundle the COD-Inorg reference library (78,035 phases); install or extract and you can search immediately; use SHA256SUMS.txt to verify integrity.

Need a larger reference library? Go to the sibling repo PolyXRD/XinMatch-DataBase Releases to download *.xinDB.zip (PCOD / TCOD / Full / Materials Project), extract, then "Settings → Reference database…" or XinMatch.exe libraries --add <path> to mount — multiple libraries can coexist. This Release does not bundle GB-scale large libraries. Detailed steps in §6 below. This version's binaries passed 5 rounds of robustness acceptance (hash / portable / frozen GUI / silent install / post-install search), see §8.

XinMatch v3.2.0 — Phase-level identity: candidate list folds same-phase variants + dual-track baseline

Baseline v3.1.0 | this is a minor release (new feature + two default-behavior changes): reference library format, FoM weights, commands and config are all unchanged; old projects and old libraries work as before. The search engine changed in only one place — the prescreen quota allocation (§3.5), candidate cap 800 → 1000.

1. Problem to solve

The reference library has dozens of cards for the same phase. In COD, BaTiO₃ has 96-210-0858 / 96-210-0859, TiO₂ anatase has 96-500-0223 / 96-900-8214; in a top_n=40 measurement, synth_01's Top-40 has 18 cards belonging to the Al₂O₃ family, synth_02 has 12 belonging to the beryl family (18 before the prescreen quota fix). This creates two independent problems:

  1. The candidate list is flooded by near-duplicate cards. The user flipping through 40 rows is really seeing the same phase. In synth_02, calcite's FoM was only 0.0017 below the top, yet because beryl cards occupied slots it was once ranked outside the Top-40 (it's now the top, see docs/基准报告-物相检索-v3.md §3, §10).
  2. The baseline metric records "found the right phase" as a failure. Judging hits strictly by entry_id, falling onto a sibling card counts as a miss — same library, same engine, entry-level Top-1 is 7/13, phase-level is 11/13.

2. Core capabilities

Capability Description
Phase-level identity same_phase(a, b) Same element set + cell axes within ±1% / angles ±1.5° + same space group; falls back to stoichiometry comparison (tolerance 0.25) only when cell is missing
Candidate folding group_same_phase() slices the sorted candidates into phase families (family rep = highest-ranked within the family); the table shows one row per family by default
"Variants" column In folded state shows N cards; hovering lists each card's entry_id + six cell parameters in the family, ▶ marks the family rep
Expand / collapse Right-click "Expand same-phase variants (N cards)" → one row per card, that column becomes rank-in-family/total-in-family (1/3, 2/3…); right-click again "Collapse same-phase variants" to retract
Dual-track baseline tools/bench_pattern_set.py outputs both entry-level (strict id) and phase-level (same-phase different-card counts as hit) summaries
Synthetic-pattern ruler swap tools/generate_synthetic_patterns.py --peak-source v3 --library <xinDB>: d/I taken directly from the same entry in the library, eliminating the intensity mismatch of "pattern generated by v2 cards, searched with v3 library"
Dual-track prescreen quota prescreen() keeps the original "main-peak hit → intensity-weighted hit → hit count" ranking for 80% of slots, and takes the other 20% by "intensity-weighted hit → hit count" so minor phases enter by reflection count; default candidate cap 800 → 1000

3. Key design decisions (and why)

  1. Cell preferred over stoichiometry as criterion — occupancy-refined variants (Al1.499 Be3 Si6 O18 vs Al2 Be3 Si6 O18) have nearly identical cells but different formulas; polymorphs (anatase / rutile) have the same formula but different cells. Using stoichiometry as the main criterion would split the former into two phases and merge the latter into one — both directions wrong. So with a cell, the cell rules, and stoichiometry only kicks in when the cell is missing (the only available evidence).
  2. Greedy grouping, order-preserving — walk in ranking order; each candidate merges into the first family it's same-phase with. This makes the family rep naturally the strongest card in the family, and the family order unchanged — the 1st folded row is still the original #1 phase, so the user doesn't have to re-understand the ordering. The cost is theoretical non-transitivity (A≈B, B≈C doesn't guarantee A≈C), which is a non-issue under the one-dimensional approximation of "same-phase different-card".
  3. Folding only changes display, not scoring — folding happens at the render layer and doesn't touch rank_candidates. The fact that in synth_10, 15 spinel cards pushed metallic Fe out of Top-1 is unchanged (see docs/基准报告-物相检索-v3.md §5, §6) — folding just displays it as one row, so you must not read "folded list looks nice" as "recall fixed". Calcite in synth_02 truly returned to the top thanks to the §3.5 prescreen change, not folding.
  4. Row numbers are no longer candidate indices — in folded state the 2nd row may correspond to the 4th candidate. Every path from UI back to data must go through a mapping: CandidateListTable.selected_results() / result_at(row) / family_results_at(row) all pass through the folded table; MainWindow._selected_candidate_results() (entry to the refinement wizard and batch operations) has switched to the former. Use visible_results() for export and reports, otherwise row counts won't match the UI.
  5. Carve 20% of prescreen slots for "reflection count" — prescreen originally took the top N by a three-level sort (main-peak hit, intensity-weighted hit, hit count). This criterion implicitly assumes "the true phase's strongest line is also strong in the measured pattern" — false for minor phases: Al₂O₃ in the 3-1 measured pattern only has weaker lines left, main_hit scores nothing, so it's pushed past 800th by the major phase and its sibling cards (candidate_limit=8000 only surfaces it at rank 197). Changing to 80% old criterion + 20% by reflection count lets phases that "have a corresponding measured peak at many d positions" enter by coverage. No FoM change, no change to anything beyond the candidate pool — just splitting the slot allocation from a single criterion into two complementary ones.

4. UI and branding

  • The candidate list gains an 11th column "Variants"; the right-click menu gains a fold toggle (shows "No same-phase variants" and is greyed out when none).
  • family_mode_changed(bool) signal: emitted when fold state changes, for status-bar / export hints to sync.
  • New logo from v3.2.0: window icon, app icon, installer icon, and splash unified to assets/icons/logo*.png / logo.ico; splash recomposed (tools/compose_brand_assets.py using assets/splash_backdrop.png as base, logo plate bottom-right + vignette bottom-left + version number), version number read at runtime from xinmatch.__version__.

5. Compatibility

  • No new dependencies, no schema change, .xinDB libraries work as-is.
  • CandidateListTable.set_candidates() gains keyword arg merge (default None = follow current fold state, first time folded). Positional signature unchanged.
  • Default behavior change: the candidate table folds same-phase variants by default; visible row count = number of phase families, not number of candidates. External scripts relying on rowCount() == len(candidates) must switch to visible_results().
  • Default parameter change: DEFAULT_RANK_LIMIT / DEFAULT_CANDIDATE_LIMIT changed from 800 to 1000, prescreen gains a diversify_slots keyword arg (default None = 20% of limit; pass 0 to fully restore old behavior). The cost is increased search time: COD-Inorg (78k phases) 0.37 → 0.41 s (+11%), PCOD-Inorg (1.06M phases) 1.50 → 1.89 s (+26%).
  • xinmatch.__version__ prioritizes pyproject.toml in the source tree (previously shadowed by a stale xinmatch.egg-info/PKG-INFO version).

6. Reference database: bundled default library + mount external libraries

Out of the box: both binaries bundle COD-Inorg-20261020.xinDB (rebuild, 78,035 phases / 113.1 MiB) under <program dir>\data\. After install or extraction no config is needed to search; the library in that directory can be replaced directly, or you can mount others.

Extended libraries released in the sibling repo: PolyXRD/XinMatch-DataBase Releases provide .xinDB split by source; this Release does not duplicate them (a single PCOD library is 1.7 GB, no point stuffing it into the installer):

Release Libraries provided Purpose
20261020-rebuild COD-Inorg (same as above), TCOD-Inorg 47k phases, PCOD-Inorg 1.06M phases, TCOD-Full 360k phases, COD-Full 530k phases Use predicted/theoretical libraries as fallback when the experimental library finds nothing; Full libraries contain all archives
20261031-mp MP-20261031.xinDB (Materials Project) First-principles structure supplement

Mount in three steps:

  1. Download *.xinDB.zip from the Release above → extract to get a single *.xinDB. Keep the filename as <kind>-<YYYYMMDD>.xinDB (the verifier reconciles against the library's internal meta; renaming fails the check). You can verify the zip with the Release's SHA256SUMS.txt.
  2. Place in any directory (local disk, NAS read-only share both fine; the library uses journal_mode=DELETE, no -wal/-shm sidecars).
  3. GUI: "Settings → Reference database…" to add and select; or command line:
XinMatch.exe libraries --add "D:\XRD-DB\PCOD-Inorg-20261020.xinDB" --label "PCOD predicted library"
XinMatch.exe libraries --json

--add only registers the path, does not modify or copy the library file; unmount with libraries --remove <id>. The registry is written to user dir ~/.xinmatch/libraries.json and survives upgrades.

Multiple libraries coexist, with a cost: you can mount several libraries at once and pick the active one at search time. Larger libraries are slower — in this version, the same 208-peak pattern measured: COD-Inorg (78k phases) 0.41 s, PCOD-Inorg (1.06M phases) 1.89 s, because the prescreen does boolean ops over the whole top_d matrix and candidate location must decode more chunks. Recommended: use COD-Inorg daily, mount PCOD/TCOD only when you can't find something. The old v2 .db / .sqlite reference libraries were removed in v3.0.0 and mounting them is explicitly rejected.

7. Acceptance

  • Static gate: ruff check xinmatch tests tools all pass; mypy 121 files Success: no issues found.
  • Regression: full pytest (addopts defaults to excluding slow) 1477 items: 1472 passed / 4 skipped / 1 xfailed / 0 failed (13m27s, with tests/ui 258 + tests/search 310 + tests/db 139 as the main coverage for this change).
  • New tests: tests/search/test_phase_key.py (14 items: formula parsing, same-phase different-card, occupancy variants, polymorphs not merged, different elements, space-group conflict, missing cell not used as negative evidence, missing cell compares ratios not counts, family order and rep), tests/ui/test_tables.py +6 items (fold, expand/retract, selection mapping, menu toggle), tests/db/test_prescreen_diversity.py (4 items: default share, out-of-bounds clamp, minor phase entering from the hit-count half, diversify_slots=0 reproduces old behavior), tests/db/test_reader_v3_fetch.py (2 items: param cap batching, over-cap connection proxy). The oracle in tests/db/test_reader_v3_perf.py is synced to the new quota strategy.
  • Baseline (COD-Inorg 78,035 phases, 13 synthetic-pattern sets, new patterns = v3 library intensities):
Metric Top-1 Top-5 Sequential full recovery Phase recall
Entry-level (strict id) 7/13 11/13 2/13 9/24
Phase-level (same-phase different-card counts as hit) 11/13 12/13 10/13 19/24
Old patterns / phase-level 9/13 10/13 7/13 15/24

The only true misses left are 2: synth_07 (sparse pattern lacking discriminative power, whole-pattern T1/T5 both zero), synth_10 (metallic Fe and spinel-type oxide in the same family, top spot taken by 96-900-6921, T5 hit). synth_02 is fixed this round (beryl flood, sequential 2/2 fully recovered).

  • Baseline (second set, 13 real measured-pattern sets, auto_process full pipeline, 12 evaluable): whole-pattern Top-1 10/12, Top-5 12/12; phase recall Top-20 card-level 24/43 / folded family-level 27/43; sequential full recovery 5/12. Sample 5-3 best shows folding's real effect: card-level 1/5 → family-level 5/5.

Details and data in docs/基准报告-物相检索-v3.md; failure localization process in docs/检索基准-v3-诊断-20261104.md.

8. Binary robustness acceptance (5 rounds, all verified end-to-end)

Ran 5 rounds against the actually released artifacts (not the source tree); reproducible tool tools/verify_binary.py (python -m tools.verify_binary --setup … --zip … --workdir …), raw results .scratch/binary_verify_320.json:

# Check Method and measured result
1 SHA-256 consistency Each artifact hashed → written to SHA256SUMS.txt → read back the manifest and re-hash to compare, consistent ✅
2 Portable-mode launch 7-Zip unpack (3556 files / 785 MiB) → variant.txt=internal, bundled COD-Inorg-20261020.xinDB 118,640,640 B, bundled logo_256.png byte-identical to source; frozen CLI libraries --json and import --help both exit 0, registry internal default library entries=78035 / available=true ✅
3 Frozen GUI smoke offscreen self-test hooks triple: REG → variant=internal, registration_enabled=false, internal evaluation build; LIBS → export 10 library records; ABOUT → render About dialog PNG (9,117 B, new logo visible). Also 3 consecutive cold starts all exit 0, no leftover locks ✅ (Chinese renders as boxes under offscreen due to missing CJK fonts in the session, not an artifact issue)
4 Silent install XinMatch-Setup-3.2.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /CURRENTUSER /DIR=… /LOG=… → exit 0, log Installation process succeeded, 3558 files landed, XinMatch.exe + data\COD-Inorg-20261020.xinDB, variant.txt=release ✅
5 Post-install launch Install-dir frozen CLI: libraries --json exit 0; real-pattern end-to-end search search 5-1.txt --db <install-dir bundled library> --top-n 5 --json → 118 peaks / 5 candidates / top 96-210-0189 (calcite, consistent with baseline); release GUI hook variant=release, registration_enabled=true, unregistered; installer and main app version resource ProductVersion=3.2.0 ✅

Earlier versions hung under /SILENT in non-interactive sessions, and the release variant was blocked by the registration popup; this round both pass after adding /CURRENTUSER. Manual double-click acceptance is still recommended once by the user before release (automation only covers the offscreen path).

9. Release artifacts

Attachment Bytes SHA-256
XinMatch-Setup-3.2.0.exe 254,143,458 350b24cfe0ffb669a1792216a5246a20ecd6c1d9461dd18843e6ead525a93590
XinMatch-Internal-3.2.0.zip 353,721,811 96e818ee29cbe5453178b7d6d793f1d408e97fc1dedcca7062a4d73016d47756
SHA256SUMS.txt 185 manifest of the two hashes above

Both binaries bundle COD-Inorg-20261020.xinDB (rebuild, 78,035 phases); extended libraries per §6 go to the XinMatch-DataBase repo to mount, this Release does not bundle GB-scale large libraries.