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