Repository navigation
Releases
XinMatch v3.6.3 — Element constraints four-state + closed-loop · FPFM full-profile fitting as default
XinMatch v3.6.3 — Element constraints four-state + closed-loop · FPFM full-profile fitting as default
This Release cumulates the four never-separately-released versions v3.6.0 / v3.6.1 / v3.6.2 / v3.6.3. The previous public release was v3.5.0. The reference library format (
.xinDBv3), FoM weights, command-line interface and.xinmarchive format are all unchanged; old archives open as usual.
Highlights of this release (v3.6.3)
① Element constraints four-state + closed-loop (criteria aligned with sibling project PolyXRD)
Previously there were only three states "must-contain / exclude / no-constraint", with two real shortcomings: to express "the sample is the MgO or CaO or CaCO3 family" you could only mark all 4 elements must-contain (AND semantics, leaving only dolomite); to express "only allow these detected elements" you'd have to click 113 of the 118 buttons. Now:
| State | Predicate | Meaning |
|---|---|---|
| Must have | P ⊆ S |
each must appear (AND) |
| May contain | S ∩ H ≠ ∅ |
contains at least one (OR) |
| Possible | no forced condition | only relaxes the closed-loop allowed pool |
| Must not have | S ∩ E = ∅ |
contains any → eliminated |
Click order: no-constraint → may-contain → possible → must-not-have → must-have (the harshest filter placed last). New closed-loop switch "restrict to selected elements": unmarked elements are all treated as "must-not-have"; the panel adds "add light elements" to mark O/C/H/N/S as "may-contain" in one click. The four-state conversion is consolidated into a single element_constraint_sets(), shared by prescreen / direct SQL query / baseline scripts.
② Phase identification now defaults to FPFM full-profile fitting (no peak finding)
The toolbar dropdown can still switch back to "peak-list FoM (peak finding)" with one click.
⚠️ Element constraints only take effect in "peak-list FoM" mode — the FPFM search chain has norestraintsparameter. To use element constraints as chemical priors, switch back to peak-finding mode first; the toolbar "sample elements" button, when constraints are set + FPFM, persistently shows the "|not effective under FPFM" hint.
③ Compatibility: closed_world defaults off, and the new states aren't used by old archives, so behavior is bit-identical to v3.5.0 when only must-have/must-not-have are set; baseline numbers (real-pattern phases 30/43, etc.) are unchanged.
Cumulated v3.6.0 ~ v3.6.2
| Version | Contents |
|---|---|
| v3.6.0 | All 11 placeholder GUI menu actions wired up (Profile Fit / Quantify / Microstructure / Indexing / Export); peak-position refinement switched to LM optimization (35 s → 0.35 s); candidate list 50-row display budget; periodic table redesigned (font-metric-driven sizing, fixes clipped symbols) |
| v3.6.1 | Three field-reported bug fixes: each curve shown twice in the pattern legend / Rietveld refinement wizard full-window white-screen freeze / match-list "crystal system" column labeling hexagonal phases as monoclinic |
| v3.6.2 | Pattern-area interaction rework: reference-line zones below the pattern (candidate-phase preview + all confirmed-phase columns, to spot unmatched peaks); top axis control bar hidden, switched to click-axis-to-toggle; pattern shortcut icon row (reset / box-select by axis / pan / step zoom / crosshair) |
Deliverables
Only XinMatch-Setup-3.6.3.exe (Windows installer). Bundles the COD-Inorg default reference library, search works out of the box with no separate database download. The portable zip is for internal-evaluation use and is not released with the Release.
Validation
ruff check ./mypy xinmatch/coreall pass; version consistency 5/5- Full regression 1867 = 1862 passed / 4 skipped / 1 xfailed / 0 F / 0 E (
--collect-onlysum reconciled exactly to 1867) - Binary robustness 5-round automated acceptance (hash / portable launch / frozen GUI / silent install / post-install real search)
Detailed release notes in repo docs/RELEASE-NOTES-v3.6.0.md ~ docs/RELEASE-NOTES-v3.6.3.md, roadmap and acceptance checklist in docs/STATUS.md and docs/HANDOVER-20261106.md.
XinMatch v3.5.0
XinMatch v3.5.0 — "Must-not-contain" element constraint enabled, single source of truth for version
Baseline v3.4.0. This is a defect-closure + engineering-governance release: reference library format, FoM weights, P-value definitions, and the command-line interface are all unchanged; search default behavior is unchanged item-by-item (synthetic baseline 11/13·12/13·10/13·19/24 re-verified).
Core capabilities
| Capability | Description |
|---|---|
| "Must-not-contain" element constraint | Red periodic-table elements now actually participate in search: the prescreen layer uses the element_inv inverted index to drop phases containing that element, intersected with "must-contain" (green) |
| Three entry points consistent | GUI (Constraints panel), search_match(restraints=...), search_match_v3(elements_excluded=...) all go through the same path |
| Opposite semantics for unknown elements | A misspelled symbol empties results on the "must-contain" side, but on the "must-not-contain" side excludes nothing |
| FPFM mode made explicit | The full-profile fitting chain has no restraints parameter; selecting elements then switching to FPFM shows a status-bar hint instead of silently failing |
| Single source of truth for version | pyproject.toml is the only one; the spec derives from it, and the iss keeps just one default value overridden by the build script |
| Version-consistency tests | 5 checks; any drift fails the test (added for XinMatch) |
Validation
| Item | Result |
|---|---|
pytest / ruff / mypy |
all pass, no issues |
| Synthetic baseline (default metric) | Phase-level Top-1 11/13, Top-5 12/13, sequential 10/13, phase recall 19/24 — identical item-by-item to 3.4.x |
| Element constraint (real 13 sets, ideal XRF settings) | Top-1 10/12 → 12/12; per-phase rank changes 21 up / 17 flat / 4 down / 1 pushed out |
| Binary acceptance (5 rounds) | version, library registration, frozen search, new-feature penetration, install/launch/portable all pass |
Release artifacts
| File | Size | SHA-256 |
|---|---|---|
XinMatch-Setup-3.5.0.exe |
242.3 MiB | e81ab39f97ec9322db8bf68de18831bb02ce14b3f77e6b8eb23d460d159f9ba7 |
XinMatch-Internal-3.5.0.zip (portable, not distributed with the Release) |
337.4 MiB | 41ac3005ea17af5f4af2538ea285a5bbc69932ae9c456985cd5e63cce295b40b |
Upgrade notes
- Default behavior unchanged: users not using the "Constraints" panel get search results bit-identical to 3.4.x.
- To make red elements take effect, tick elements in the "Constraints" tab and set their state to red, then run Search-Match (peak-list FoM mode only; FPFM will warn it doesn't participate).
- The installer filename changes to
XinMatch-Setup-3.5.0.exe; olddata\*.xinDBreference libraries can be carried over directly.
XinMatch v3.4.0 — Export phase analysis (.xinm): one-click results into refinement (incl. v3.3.0 few-line-phase marker)
XinMatch v3.4.0 — Export phase-analysis state (.xinm): one-click from search conclusions into refinement
Baseline
v3.2.0| this release also includes the never-separately-released v3.3.0 content (few-line-phase ★ strong-line anchor marker), merged into one release. Reference library format, FoM weights, ranking criteria, and command line are all unchanged.
1. New in this release: export phase analysis (.xinm)
Problem to solve
Once search is done, the conclusions live only inside XinMatch. To run full-profile fitting in a refinement program you have to do three things by hand: re-import the pattern, retrieve the CIFs of each identified phase one by one, and remember the wavelength.
The second is the killer. The COD archive spreads 520k files across id-based directories (COD/9/00/82/9008220.cif); the library only stores the ref_id 96-900-8220, not the path or contents. Users either flip through directories from memory or download them one by one from the website — both ways you can attach the wrong phase, and a refinement with the wrong phase still converges, just with a uselessly high Rwp and wasted quantification.
Capabilities
| Capability | Description |
|---|---|
| Export phase analysis (.xinm) | New entry in the File menu; packs the anchor pattern + CIFs of selected phases + peak table + metadata in one go |
| Container format | zip: manifest.json + pattern/pattern.csv + cifs/*.cif; format:"xinm" / version:1, fields only added never removed |
| Pattern normalization | Two-column CSV (two_theta,intensity), %.10g — float64 round-trip relative error ≤1e-9, ~2 MB for 100k points |
| CIF retrieval bridge | 96-900-8220 → COD id 9008220 → {id[0]}/{id[1:3]}/{id[3:5]}/{id:07d}.cif; probes roots in order "env var → current archive root → historical root" |
| Degrade without blocking | If a phase's CIF retrieval fails → that phase structural=false + a readable reason, export still completes; downstream lists it as "reference only", CIF can be added manually |
| Copyright boundary | Does not bundle any ICDD/PDF2 derived data files; PDF2-type entries only write id and peak-table metadata |
| Candidate summary | The top 20 unselected candidates carry only name / entry_id / source, no embedded CIF |
Companion version: XinRefinement 1.1.0 (File → Import XinMatch phase analysis…, one-click loads pattern + CIF + wavelength and goes straight into recipe refinement). Format contract in docs/JOINT_PLAN_xinm_xinr.md.
Key design decisions
- zip container, not a single JSON — a 100k-point pattern as a float list in JSON is ~4 MB+ and slow to parse, while CSV is ~2 MB and streamable; CIFs are fetched directly as zip members, saving 33% vs base64 and not polluting the manifest.
- Reuse
core/refine/cif_store.pyrather than build a new bridge module — that module already has the full ref_id → COD id → archive-path chain (used by structure viewing); building another layer risks the two drifting in layout. This change only adds multi-root probing to it. %.10ginstead of%.6g—%.6gcan't round-trip float64; the pattern participates in baseline subtraction and residual computation, so a few extra significant digits are worth it.- Only judge "can we get the CIF", not "should we give it" — export only answers "is this entry's CIF in the local archive", leaving structural-validity checks to the refinement-side import.
- Multi-root archive probing —
DEFAULT_COD_ROOTwas hardcoded toPolyXRD\cod\cif; after a machine migration that dir no longer exists (archive now lives atsync-COD\COD). Hardcoding made "all CIF retrievals fail" look like "the database is broken". - Normalize scan range/step on the export side — pattern meta often lacks
tmin/tmax, andstepcarries float tails like0.019999999999999574; now it backfills the real first/last 2θ (6 decimals) andround(step, 6).
Two defects fixed along the way
- Frozen version number polluted by dist-info (present since v3.3.0): the frozen package has no
pyproject.toml, but the dev machine'ssite-packagesstill hadxinmatch-1.7.1.dist-info, whichimportlib.metadatatreated as the real version → both the About dialog and the.xinm'sapp.versionwere written as 1.7.1. Now the frozen state returns__init__._FALLBACK_VERSIONdirectly, andxinmatch.specasserts at build time that it equalsAPP_VERSION(build fails if out of sync). XinMatch.exe --versionopened the GUI:CLI_FLAGSonly had-h/--help. Added--version/-V.
2. Merged v3.3.0: few-line-phase ★ strong-line anchor marker
The FoM's P(npeaks) counts by number of lines — an intermetallic with 40~150 reflections can "hit" many weak residual peaks by chance, while the genuinely recognizable few-line phases (metallic Fe 6 lines, NaCl 17 lines, KCl ~9 lines) only explain two or three peaks, so they're always ranked last.
v3.3.0 added a criterion that only marks, doesn't re-rank: strongest reference line hit ≥0.30×strongest residual peak + P(2θ)≥0.98 + matched pairs≥2 + P(ncorr)≥0.50 + reference reflections≤20 (the line-count guard directly drops the dense 40~150-line cards). Candidates passing the criterion show ★ in the first column, hover gives the criterion explanation, and the status bar reports "★ N strongest lines hit strong residual peaks".
| Item | Description |
|---|---|
AnchorPolicy / _anchor_ok() |
The five-condition criterion above |
ResidualSearchResult.anchored_ids |
For UI and export use |
| Optional re-rank (default off) | search_residual(..., promote_anchored=True), for offline experiments |
Why not re-rank by default: on the real 12-pattern set, re-ranking lost 3-2 — anchoring pushed Bi1.284O2.988Y0.684 to the top, whose P(2θ) 0.984 is more accurate than the true CaF₂'s 0.928; after mis-confirmation the residual was polluted and CaF₂ couldn't be recovered in 5 rounds (sequential full recovery 5/12 → 4/12). The root cause is the synthetic ruler rebuilding with the same batch of reference intensities, systematically overestimating this rule. So this release downgrades it to a marker; ranking is identical item-by-item to v3.2.0 (real-pattern Top-1 10/12, Top-5 12/12, sequential 5/12, card recall 24/43, family-level 27/43), and the user decides whether to look at that 7th-place ★.
See docs/基准报告-物相检索-v3.md §11.5, docs/RELEASE-NOTES-v3.3.0.md for details.
3. Release artifacts
| Attachment | Bytes | SHA-256 |
|---|---|---|
XinMatch-Setup-3.4.0.exe |
254,139,154 | 4962defa7d0e4cf702db200c0b3366243b7ea09f95fafe4d7a39fab7ef0c7f19 |
XinMatch-Internal-3.4.0.zip |
368,486,794 | fb82ce897bf4227aa79420fce3359772001809ee274be64f356ace9aa7ff3a08 |
SHA256SUMS.txt |
— | manifest of the two hashes above |
Both binaries bundle COD-Inorg-20261020.xinDB (113 MiB / 78,035 phases); extract or install and you can search immediately; larger extended libraries (PCOD / TCOD / Full / MP) are distributed in the sibling repo XinMatch-DataBase Releases — download *.xinDB.zip → extract → "Settings → Reference database…" or XinMatch.exe libraries --add <path> to mount.
| Build | Artifact | Registration | Far-right status bar |
|---|---|---|---|
| Release | XinMatch-Setup-<v>.exe |
Yes: checks registration status on every launch | Registered: <org/dept name> / Unregistered |
| Internal evaluation | XinMatch-Internal-<v>.zip (no install) |
No | Red bold internal evaluation build |
4. Acceptance
Binary robustness 5 rounds all passed (tools/verify_binary.py, run against the actual released artifacts):
| # | Check | Measured |
|---|---|---|
| 1 | SHA-256 consistency | hash → write manifest → parse back and re-hash to compare, consistent |
| 2 | Portable mode | unpack exit 0; variant.txt=internal; bundled library 118,640,640 B / 78,035 phases; bundled logo byte-identical to source; libraries --json, import --help both exit 0 |
| 3 | Frozen GUI smoke | REG → internal evaluation build; LIBS → 10 library records; ABOUT → renders dialog PNG |
| 4 | Silent install | /VERYSILENT /CURRENTUSER exit 0, lands XinMatch.exe + bundled library, variant.txt=release |
| 5 | Post-install launch | frozen CLI normal; real-pattern end-to-end search 5-1.txt → 118 peaks / 5 candidates / top 96-210-0189 (calcite, bit-identical to v3.3.0); release GUI hook variant=release, registration_enabled=true, unregistered |
- Unit/integration: 1494 items, 1489 passed / 5 skipped / 0 failed.
- Real-sample round-trip:
5-1.txt+ COD96-210-0189→ export 5751 points / 1 CIF / 23.3 KB → XinRefinementread_xinmreads back 5751 points, CIF 3,580 B,app.version=3.4.0.
Not code-signed: on first run Windows SmartScreen may warn "Unknown publisher"; choose "Run anyway".
5. Compatibility
| Item | Status |
|---|---|
Reference library format (.xinDB schema v3) |
unchanged, v3.3.0 / v3.2.0 libraries usable directly |
| FoM weights / ranking / P-value definitions | unchanged, search results identical item-by-item to v3.3.0 |
| Command line / config files | unchanged (added --version / -V) |
| Registration mechanism / dual variants | unchanged |
| New artifact | .xinm, standalone file, doesn't affect existing projects and reports; also backfills v3.3.0's ★ marker |
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 librar...
XinMatch v3.1.0 — Sequential phase identification
XinMatch v3.1.0 — Sequential phase identification: confirm one phase → re-search residual peaks → confirm again
Baseline
v3.0.0| this is a minor release (new feature, no breaking changes): reference library format, search engine, FoM weights, commands and config are all unchanged; old projects/old libraries work as before.
1. Problem to solve
A single search-match gives only one ranking. In multi-phase samples, the major phase's strong lines keep dominating the FoM: after confirming the major phase and re-searching, the top of the ranking is still filled with the major phase's sibling cards, and the minor phases are pushed beyond the top 20; the user can only manually "exclude explained peaks" in the peak list, and that exclusion is guesswork that cannot be tied to specific candidate cards.
v3.1.0 turns "confirm phase by phase" into a closed loop: every confirmation re-searches using the remaining unexplained peaks, so the ranking answers "what's left".
2. Core capabilities
| Capability | Description |
|---|---|
| Confirm = search | Double-click / Enter / right-click "Confirm as matched phase" / bottom "Confirm this phase" button — four equivalent entry points |
| Residual peaks = measured peaks − confirmed-phase contributions | Each phase determines a count-domain scale factor scale (counts / unit relative intensity) by least squares against its reference intensity table and the measured intensities, then subtracts peak by peak |
| Three-state peak status | Explained (residual ≤ 5% of the peak's own intensity), Unexplained (significant but still unexplained), Low-intensity ignored (< 1% of the strongest peak in the whole pattern, not used in search) |
| Residual-peak search | search_residual() runs the same FoM engine on the residual peaks (not a separate scoring scheme), and automatically drops confirmed entries |
| Rollbackable | Undo last phase / double-click a match-list row / remove a specified phase / clear the match list → residuals recomputed wholesale |
| Visual cross-check | The pattern area overlays reference lines per phase (height = the counts that phase claims to contribute), so whether the lines match the measured peaks is obvious at a glance; the peak list "Linked" column is checked in sync |
3. Key design decisions (and why)
- Full rebuild, not incremental update —
SequentialIdentifierrecomputes every layer from the original peak list on each change: correlation → scale factor → residual → mask. Reason: phase B's scale factor is fitted after phase A is subtracted, so removing A must allow B's values to change. Incremental updates would accumulate float drift, leave stale correlated peaks, and make the undo path unclean. The cost is one correlation pass per phase (µs-scale), bought in exchange for the invariant "state = f(original peaks, phase sequence)". - Scale factor fitted in the count domain, not reusing FoM's
i_scale—CandidateResult.i_scaleis the LSQ shape factor after each side is normalized to 100 (ideal ≈ 1.0), and cannot be used to subtract counts from measured peaks. The sequential module fits its ownscale = Σ(I_residual·r)/Σ(r²)(r = I_ref/I_ref,max) in the count domain, so the result carries the "counts / unit relative intensity" dimension. - Low-intensity peaks get their own bucket, not forced into "Explained" — hard lesson (synth_02, see acceptance doc): after both phases confirmed, 32/51 peaks were still "unexplained" while intensity-explained was 92% — what remained was a small noise bump; the third search round then matched the noise to junk candidates like
Fe0.75V0.25. Marking <1% peaks as "ignored" (neither explained nor residual) is both honest and makes the third round return an empty list. - "Partially explained" peaks keep their residual intensity — overlapping peaks (major phase + unconfirmed phase): after subtracting the major phase's contribution the residual is positive, so they stay in the residual set with intensity lowered by the difference; they are not swallowed by "position hit = explained". This is critical when a minor phase's lines fall on the major phase's strong-line positions in multi-phase samples.
4. UI
- The candidate-list panel gains a new action bar:
Confirm this phase (add to match list)/Undo last phase/Clear match list+ a residual readout (N phases confirmed | X/Y peaks residual | Z% intensity explained | K low-intensity peaks ignored). - The Match List is filled by confirm actions; double-click rolls back that phase.
- Peak-list "Linked" column: peaks positionally related to confirmed phases get a ✓.
- Pattern area: per phase, a set of reference lines overlaid, colored in the same order as the candidate row swatches.
- FPFM mode has no peak list: on first confirmation it lazily runs peak detection once on the current pattern, then enters the sequential flow (status-bar hint).
- Every full-pattern search (including peak detection, FPFM search) resets the sequential context — a new search means a new analysis round.
5. Compatibility
- No new dependencies;
.xinDB/ old SQLite libraries both work (via the existingsearch_matchdispatch). - No change to any numerical behavior of
search_match/rank_candidates/ FoM: the sequence just "swaps in a different peak set and recomputes". - The
CandidateTableright-click menu item "Select/Deselect" becomes "Confirm as matched phase (add to match list)"; thetoggle_selectionsignal is retained (external scripts unaffected). Phase.scale_factor/Phase.correlationsare written back with real values in the sequential flow, so the downstream fields read by the refinement wizard / report / CIF export stay self-consistent.
6. Acceptance
- Full regression (local final state): 1452 passed / 5 skipped / 0 failed, 849 s (14m09s), EXIT=0.
- New tests:
tests/search/test_sequential.py(18 items, purely synthetic, hand-checkable),tests/ui/test_sequential_ui.py(17 items, offscreen UI closed-loop). - Real-library multi-phase samples (default COD inorganic library, 71k): two-phase samples 3/3 fully recovered (synth_02 / 04 / 12, both phases locked within two rounds); three-phase sample synth_01 recovered 2/3 (ZnO not recalled, a base recall limitation).
Details and data in docs/序贯物相鉴定-v3.1.0.md.
XinMatch v3.0.0 — .xinDB single-format consolidation · COD-Inorg bundled default library · internal build red-text badge
XinMatch v3.0.0 — .xinDB single-format consolidation · COD-Inorg bundled default library · internal build red-text badge
Baseline
v2.0.0| full regression 1570 passed / 4 skipped / 1 xfail (pytest tests, 12m14s, EXIT=0)
1. Default library switched to COD-Inorg (*.xinDB), and bundled into the portable package
| Item | v2.0.0 | v3.0.0 |
|---|---|---|
| Default library | data/cod_inorganics.db (v2 SQLite, 712 MB) |
COD-Inorg-20261020.xinDB (v3 columnar, 113 MB) |
| Portable package usable for search directly | No (must download the 512 MB library package separately and mount it) | Yes (<exe>/data/ is bundled) |
| Library source resolution | Hardcoded | XINMATCH_XINDB_DIR → <exe>/data → <exe>/_internal/data → ../XinMatch-DataBase/data (source-tree mode) |
- Library registry
core/db/multi_db.pyfully rewritten to v3-only:KIND_XINDB+ four built-in ids (xindb_cod_inorgdefault /xindb_cod_full/xindb_pcod_inorg/xindb_tcod_inorg), picking the latest snapshot by<Prefix>-<YYYYMMDD>.xinDB;open_library()/open_search_database()return a read-onlyXinDBReader. xinmatch.specadds_find_bundled_xindb()to pull the default library intodata/;tools/build_exe.ps1moves the library from PyInstaller 6's_internal/datato<exe>/data(user can replace it directly).
2. Old-format runtime code deleted (not deprecated)
- Removed
core/db/polyxrd.py(PolyXRDphasesdump conversion layer) andcore/db/pdf2_index.py(PDF-2 conversion layer). ui/dialogs/library_dialog.py720 → ~300 lines: now only list / mount / unmount / refresh, with the build-thread and index-thread fully removed; thePDF-2 source directoryconfig item is removed.- CLI
librariesonly keeps--add/--remove(--build/--force/--no-buildremoved). core/batch.pyand the top-level APIsidentify_phase/full_analysismoved from rawsqlite3.connecttoopen_search_database()— otherwise they would fall through to the deleted v2 row-table path.- Removed 10 v2-specific test files; added
tests/xindb_support.py(write_xindbbuilds a real.xinDB).
3. Internal evaluation build: status bar red bold "internal evaluation build"
_build_statusbar()uses a widget-level stylesheet:color: #d32f2f; font-weight: bold; padding: 0 6px;,objectName = internalBuildLabel,addPermanentWidget(label, 1)pins it to the far right of the status bar.- Why a widget instead of global QSS: the status bar is repainted with the theme, and a widget-level rule has higher priority, so the color survives theme switches.
4. Attachments
| Attachment | Contents |
|---|---|
XinMatch-Setup-3.0.0.exe |
Release installer (with registration mechanism, status bar shows Registered: <org> / Unregistered), bundles the COD-Inorg library |
XinMatch-Internal-3.0.0.zip |
Portable package = internal evaluation build (no install, no registration mechanism, status bar in red "internal evaluation build"), bundles the COD-Inorg library |
XinMatch-Databases-COD-Inorg-3.0.0.zip |
Standalone COD inorganic library package (*.xinDB, for swapping/supplementing the library on an existing install) |
SHA256SUMS.txt |
SHA-256 of the above attachments |
5. Upgrade notes
- Upgrading from v2.0.0: old
.db/.sqlitereference libraries are no longer usable (mounting is explicitly rejected with a notice that the format was removed). UseCOD-Inorg-*.xinDBinstead (bundled in this release; PCOD / TCOD are distributed via XinMatch-DataBase Releases). - Other
*.xinDBlibraries can still be mounted from any folder:Settings → Reference database…orxinmatch libraries --add <path>.
XinMatch v2.0.0 — Reference database mounts from any location
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> --forceMount 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
phaseslibraries (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 sourcemtime+size, conversion is cancellable;- libraries with an
entries+peaks+elementsstructure (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:
- The frozen
librariescommand couldn't actually open libraries — the binary dispatcher hard-coded 6 subcommands and missedlibraries(and earlierbatch,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. - 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. build_exe.ps1lacked 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$LASTEXITCODEbeing 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)
- Run
XinMatch-Setup-2.0.0.exe, install location selectable; - Download
xinmatch-cod-db-2.0.0.zip, extract itsdata\cod_inorganics.dbinto the install directory (i.e.<install dir>\data\cod_inorganics.db); - Launch XinMatch. To use another library, simply "Add external library" pointing to a
.sqliteanywhere.
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.
XinMatch v1.7.1 — Code review follow-up
v1.7.1 — Code review remediation (maintenance release)
Version 1.7.0 → 1.7.1, no API breakage, no data migration. Full acceptance see docs/ACCEPTANCE-v1.7.1-20261018.md, item-by-item review and implementation plan see docs/CODE_REVIEW-20261018.md.
Defect fixes
- GUI search connection leak: every SQLite connection opened per search is now closed in
finally; when re-entering the busy window is rejected, the caller closes it as well. Long sessions no longer accumulate handles or hold the reference DB, which previously caused "rebuild/replace library" to fail. - High-angle peaks crashing search: when
d ≤ λ/2(backscatter limit, e.g. Mo/Ag-target data paired with Cu wavelength)math.asingoes out of range; now the peak is skipped and logged, and both 2θ window bounds are clamped. recall_max_candidatesfailed in restraints mode: broad constraints (e.g. "must contain O") scored tens of thousands of candidates in full; now it truncates consistently with other recall modes (intersected with d-value recall, then best selected).- Package unusable after
pip install: the wheel previously lackedschema.sqland the 3D-view resources (3dmol), failing at import; package data is now declared and read viaimportlib.resources, and CI added a packaging assertion. - Import failure with no dist metadata:
__version__gained a fallback constant. - Stale curve records after clearing pattern:
PatternView.clear()was shadowed by pyqtgraph's same-named instance attribute (a real bug), now fixed —patterns()no longer returns deleted curves.
Performance
- Candidate fetch N+1 → batched chunks: SQL round-trips for 3000 candidates dropped from 3000 to 7.
- Hanawalt top-K intensity cache now keyed by library fingerprint (mtime/size + lock + LRU(2)): rebuilding or replacing the reference DB no longer hits stale rankings.
- Result assembly normalized: added
fpfm.to_candidates(), GUI / batch / CLI now share the sameraw → CandidateResultmapping.
UX
- Opening large data files (
.raw/.brml/ large ASCII) no longer freezes the UI. - Long tasks are cancellable: FPFM full-profile fitting and similar operations show a "Cancel" button (cooperative interrupt, threads not force-killed).
- 5 placeholder toolbar actions are now functional: background subtraction / smoothing / Kα2 stripping / reset raw data / peak detection.
Engineering
- Added GitHub Actions CI (ubuntu + windows × Python 3.10/3.12: ruff + mypy + default tests + wheel resource assertions), with a local equivalent entry
tools/ci.ps1. slowmarkers completed and excluded by default:pytestnow runs directly; full numerical cases viapytest -m slow.- Removed the hardcoded
D:\Project\...default library path; SQLite URI and LIKE wildcard escaping; GSAS-II gpx backfill exceptions now logged, withGSAS2_HOMEoverride support. - Docs index
docs/README.md; data-backup cleanup scripttools/clean_data_backups.ps1(dry-run by default).
Acceptance numbers
ruff: All checks passed;mypy: 113 source files, 0 errors.- Default regression suite: 1297 items / 0 failures / 7 skipped (13.2 min, excluding slow).
- Frozen binary:
XinMatch.exe import --helpexit 0; internal variant registration self-check JSON correct.
Install
- Download
XinMatch-Setup-1.7.1.exeand install (install location selectable). - Download
xinmatch-cod-db-1.7.1.zip, extract into the install directory so the reference DB is atdata/cod_inorganics.db(the installer does not bundle the database, ~700 MB). - The internal evaluation build (no registration) is
XinMatch-Internal-1.7.1.zip, extract-and-use.
Known limitations
- The
slowsuite (turn-on least squares, GSAS-II real refinement, L3 acceptance) was not run this time; re-run separately withpytest -m slow. - The release variant's GUI self-check is blocked by the startup registration dialog in non-interactive sessions (same environment limitation as the v1.7.0 acceptance record), confirmed covered via variant markers + unit tests.
- Registration codes remain an HMAC "obfuscation-level" scheme (security boundary in
docs/PACKAGING.md); upgrading to asymmetric signing requires re-issuing codes.
XinMatch v1.7.0 — Registration mechanism + release/internal build variants
XinMatch 1.7.0 release.
Highlights
- Registration mechanism (reuses the PolyXRD-family scheme from
PolyXRD-Reg, byte-identical algorithm):- Unregistered → every launch shows: "This software is unregistered. All rights reserved. Commercial use is prohibited. To register, contact sshztx@outlook.com"; clicking OK closes the notice and the software works normally; clicking Enter registration code completes registration.
- Help menu now includes Enter registration code (&R)…; once registered, the status bar (bottom row, right-aligned) shows Registered: <organization/department name>.
- Codes are issued by the developer per organization name (
tools/make_reg_code.py, or the familyPolyXRD-RegTool.exe); offline HMAC-SHA256 verification, no machine binding.
- Two build variants:
- Release build — this Setup installer: registration check at startup.
- Internal evaluation build —
XinMatch-Internal-1.7.0.zip(no-install, self-use): no registration mechanism; status bar shows internal evaluation build.
- Static checks all green (ruff + mypy 112 files 0 errors); core 1112 tests + UI/CLI 247 tests, 0 failures.
Assets
| Asset | What it is |
|---|---|
XinMatch-Setup-1.7.0.exe |
Single-file installer (DB not bundled; install location selectable during setup) |
xinmatch-cod-db-1.7.0.zip |
COD reference DB — extract into the install folder (creates data\cod_inorganics.db) |
XinMatch-Internal-1.7.0.zip |
Internal evaluation build (no registration, status bar shows internal evaluation build). Internal repo, so included here |
Install
- Run the Setup exe (choose install location).
- Download + extract the DB zip into the install directory.
- Launch XinMatch — unregistered builds show the notice each launch until a registration code is entered (Help → Enter registration code).
XinMatch v1.6.1 — SMPF renamed to FPFM (Full Pattern Fitting Match)
XinMatch 1.6.1 release.
Highlights
- Rename: SMPF → FPFM (Full Pattern Fitting Match) — module
core/search/smpf.py→fpfm.py, all classes/functions/constants/UI text renamed. No algorithm or behavior change. - Full backward compatibility (3 layers, covered by dedicated regression tests):
- CLI
--mode smpfstill accepted (silently normalized tofpfm); - Batch YAML
mode: smpfnormalized in place; - Persisted config keys
smpf_kalpha*auto-migrated tofpfm_*on load (legacy user settings still win over new defaults).
- CLI
- Includes the March-Dollase preferred-orientation refinement merged since v1.6.0, plus the PolyXRD dual-license (Academic/Commercial) switch and README refresh.
- Static checks all green (ruff + mypy 109 files 0 errors); core 1091 tests + UI/CLI 237 tests, 0 failures.
Assets
| Asset | What it is |
|---|---|
XinMatch-Setup-1.6.1.exe |
Single-file installer (DB not bundled) |
xinmatch-cod-db-1.6.1.zip |
COD reference DB — extract into the install folder (creates data\cod_inorganics.db) |
A portable (zip, no-install) build is kept locally and is not uploaded here.
Install
- Run the Setup exe.
- Download + extract the DB zip into the install directory.
- Launch XinMatch (CLI
XinMatch.exe search/quantify/...or double-click for GUI).