Repository navigation
XinMatch v3.2.0 — Phase-level identity: candidate folding + dual prescreen quota + new logo
Download:
XinMatch-Setup-3.2.0.exe(release installer, with registration mechanism) orXinMatch-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; useSHA256SUMS.txtto 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…" orXinMatch.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:
- 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, seedocs/基准报告-物相检索-v3.md§3, §10). - 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)
- Cell preferred over stoichiometry as criterion — occupancy-refined variants (
Al1.499 Be3 Si6 O18vsAl2 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). - 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".
- Folding only changes display, not scoring — folding happens at the render layer and doesn't touch
rank_candidates. The fact that insynth_10, 15 spinel cards pushed metallic Fe out of Top-1 is unchanged (seedocs/基准报告-物相检索-v3.md§5, §6) — folding just displays it as one row, so you must not read "folded list looks nice" as "recall fixed". Calcite insynth_02truly returned to the top thanks to the §3.5 prescreen change, not folding. - 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. Usevisible_results()for export and reports, otherwise row counts won't match the UI. - Carve 20% of prescreen slots for "reflection count" —
prescreenoriginally 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_hitscores nothing, so it's pushed past 800th by the major phase and its sibling cards (candidate_limit=8000only 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.pyusingassets/splash_backdrop.pngas base, logo plate bottom-right + vignette bottom-left + version number), version number read at runtime fromxinmatch.__version__.
5. Compatibility
- No new dependencies, no schema change,
.xinDBlibraries work as-is. CandidateListTable.set_candidates()gains keyword argmerge(defaultNone= 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 tovisible_results(). - Default parameter change:
DEFAULT_RANK_LIMIT/DEFAULT_CANDIDATE_LIMITchanged from 800 to 1000, prescreen gains adiversify_slotskeyword arg (defaultNone= 20% oflimit; 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__prioritizespyproject.tomlin the source tree (previously shadowed by a stalexinmatch.egg-info/PKG-INFOversion).
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:
- Download
*.xinDB.zipfrom the Release above → extract to get a single*.xinDB. Keep the filename as<kind>-<YYYYMMDD>.xinDB(the verifier reconciles against the library's internalmeta; renaming fails the check). You can verify the zip with the Release'sSHA256SUMS.txt. - Place in any directory (local disk, NAS read-only share both fine; the library uses
journal_mode=DELETE, no-wal/-shmsidecars). - 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 toolsall pass;mypy121 filesSuccess: no issues found. - Regression: full
pytest(addoptsdefaults to excludingslow) 1477 items: 1472 passed / 4 skipped / 1 xfailed / 0 failed (13m27s, withtests/ui258 +tests/search310 +tests/db139 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=0reproduces old behavior),tests/db/test_reader_v3_fetch.py(2 items: param cap batching, over-cap connection proxy). The oracle intests/db/test_reader_v3_perf.pyis 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_processfull 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. Sample5-3best 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
/SILENTin 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.