Skip to content

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
· 168 commits to master since this release

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