Repository navigation
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 |