Skip to content

Releases

XinMatch v3.6.3 — Element constraints four-state + closed-loop · FPFM full-profile fitting as default

Choose a tag to compare

@PolyXRD PolyXRD released this 09 Nov 14:19

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 (.xinDB v3), FoM weights, command-line interface and .xinm archive 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 no restraints parameter. 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/core all pass; version consistency 5/5
  • Full regression 1867 = 1862 passed / 4 skipped / 1 xfailed / 0 F / 0 E (--collect-only sum 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

Choose a tag to compare

@PolyXRD PolyXRD released this 06 Nov 06:40

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; old data\*.xinDB reference 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)

Choose a tag to compare

@PolyXRD PolyXRD released this 05 Nov 03:31

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

  1. 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.
  2. Reuse core/refine/cif_store.py rather 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.
  3. %.10g instead of %.6g — %.6g can't round-trip float64; the pattern participates in baseline subtraction and residual computation, so a few extra significant digits are worth it.
  4. 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.
  5. Multi-root archive probing — DEFAULT_COD_ROOT was hardcoded to PolyXRD\cod\cif; after a machine migration that dir no longer exists (archive now lives at sync-COD\COD). Hardcoding made "all CIF retrievals fail" look like "the database is broken".
  6. Normalize scan range/step on the export side — pattern meta often lacks tmin/tmax, and step carries float tails like 0.019999999999999574; now it backfills the real first/last 2θ (6 decimals) and round(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's site-packages still had xinmatch-1.7.1.dist-info, which importlib.metadata treated as the real version → both the About dialog and the .xinm's app.version were written as 1.7.1. Now the frozen state returns __init__._FALLBACK_VERSION directly, and xinmatch.spec asserts at build time that it equals APP_VERSION (build fails if out of sync).
  • XinMatch.exe --version opened the GUI: CLI_FLAGS only 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 + COD 96-210-0189 → export 5751 points / 1 CIF / 23.3 KB → XinRefinement read_xinm reads 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

Choose a tag to compare

@PolyXRD PolyXRD released this 04 Nov 10:06

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 librar...
Read more

XinMatch v3.1.0 — Sequential phase identification

Choose a tag to compare

@PolyXRD PolyXRD released this 31 Oct 13:20

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)

  1. Full rebuild, not incremental update — SequentialIdentifier recomputes 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)".
  2. Scale factor fitted in the count domain, not reusing FoM's i_scale — CandidateResult.i_scale is 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 own scale = Σ(I_residual·r)/Σ(r²) (r = I_ref/I_ref,max) in the count domain, so the result carries the "counts / unit relative intensity" dimension.
  3. 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.
  4. "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 existing search_match dispatch).
  • No change to any numerical behavior of search_match / rank_candidates / FoM: the sequence just "swaps in a different peak set and recomputes".
  • The CandidateTable right-click menu item "Select/Deselect" becomes "Confirm as matched phase (add to match list)"; the toggle_selection signal is retained (external scripts unaffected).
  • Phase.scale_factor / Phase.correlations are 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

Choose a tag to compare

@PolyXRD PolyXRD released this 23 Oct 16:07

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.py fully rewritten to v3-only: KIND_XINDB + four built-in ids (xindb_cod_inorg default / 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-only XinDBReader.
  • xinmatch.spec adds _find_bundled_xindb() to pull the default library into data/; tools/build_exe.ps1 moves the library from PyInstaller 6's _internal/data to <exe>/data (user can replace it directly).

2. Old-format runtime code deleted (not deprecated)

  • Removed core/db/polyxrd.py (PolyXRD phases dump conversion layer) and core/db/pdf2_index.py (PDF-2 conversion layer).
  • ui/dialogs/library_dialog.py 720 → ~300 lines: now only list / mount / unmount / refresh, with the build-thread and index-thread fully removed; the PDF-2 source directory config item is removed.
  • CLI libraries only keeps --add / --remove (--build / --force / --no-build removed).
  • core/batch.py and the top-level APIs identify_phase / full_analysis moved from raw sqlite3.connect to open_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_xindb builds 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 / .sqlite reference libraries are no longer usable (mounting is explicitly rejected with a notice that the format was removed). Use COD-Inorg-*.xinDB instead (bundled in this release; PCOD / TCOD are distributed via XinMatch-DataBase Releases).
  • Other *.xinDB libraries can still be mounted from any folder: Settings → Reference database… or xinmatch libraries --add <path>.

XinMatch v2.0.0 — Reference database mounts from any location

Choose a tag to compare

@PolyXRD PolyXRD released this 20 Oct 15:30

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.

XinMatch v1.7.1 — Code review follow-up

Choose a tag to compare

@PolyXRD PolyXRD released this 18 Oct 11:21

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.asin goes out of range; now the peak is skipped and logged, and both 2θ window bounds are clamped.
  • recall_max_candidates failed 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 lacked schema.sql and the 3D-view resources (3dmol), failing at import; package data is now declared and read via importlib.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 same raw → CandidateResult mapping.

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.
  • slow markers completed and excluded by default: pytest now runs directly; full numerical cases via pytest -m slow.
  • Removed the hardcoded D:\Project\... default library path; SQLite URI and LIKE wildcard escaping; GSAS-II gpx backfill exceptions now logged, with GSAS2_HOME override support.
  • Docs index docs/README.md; data-backup cleanup script tools/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 --help exit 0; internal variant registration self-check JSON correct.

Install

  1. Download XinMatch-Setup-1.7.1.exe and install (install location selectable).
  2. Download xinmatch-cod-db-1.7.1.zip, extract into the install directory so the reference DB is at data/cod_inorganics.db (the installer does not bundle the database, ~700 MB).
  3. The internal evaluation build (no registration) is XinMatch-Internal-1.7.1.zip, extract-and-use.

Known limitations

  • The slow suite (turn-on least squares, GSAS-II real refinement, L3 acceptance) was not run this time; re-run separately with pytest -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

Choose a tag to compare

@PolyXRD PolyXRD released this 16 Oct 23:32

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 family PolyXRD-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

  1. Run the Setup exe (choose install location).
  2. Download + extract the DB zip into the install directory.
  3. 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)

Choose a tag to compare

@PolyXRD PolyXRD released this 16 Oct 07:04

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 smpf still accepted (silently normalized to fpfm);
    • Batch YAML mode: smpf normalized in place;
    • Persisted config keys smpf_kalpha* auto-migrated to fpfm_* on load (legacy user settings still win over new defaults).
  • 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

  1. Run the Setup exe.
  2. Download + extract the DB zip into the install directory.
  3. Launch XinMatch (CLI XinMatch.exe search/quantify/... or double-click for GUI).