IRAxis construction is unreliable at small beta*wmax: LinAlgError crash, or silently wrong transform matrices

[k-yoshimi]

Summary

IRAxis construction (src/hwave/solver/ir_axis.py) becomes numerically unreliable at very small beta*wmax, in two distinct ways (both reproduced at wmax=5, eps=1e-8):

• beta = 0.02: construction crashes with a LinAlgError from the pinv-based transform-matrix build.
• beta <= 0.001: construction succeeds but the resulting transform matrices are silently wrong — roundtrip checks are off by roughly 4x, with no exception raised.

The second mode is the dangerous one: a FLEX run configured with an unusually low ir_wmax at high temperature (small beta) would produce plausible-looking but wrong susceptibilities with no warning.

How this was found

While building an independent Lehmann-sum oracle for the IR bond bubble, fixture selection at wmax=5, eps=1e-8 showed that beta <~ 0.03-0.04 hits this conditioning boundary. The oracle work moved its fixture to beta=0.1 (cross-checked against an nmat=65536 dense ladder, rel diff ~6e-6), so no shipped test depends on the fragile region — but nothing guards production against entering it either.

Suggested direction

• Detect the ill-conditioned regime at IRAxis construction time (e.g. a conditioning/roundtrip self-check on the fitted matrices) and raise a clear error naming beta, wmax, and eps, instead of crashing deep in pinv or silently degrading.
• A regression test at the two reproduced points (expect: clean error, never silent wrongness).

Found during the bubble-kernel unification work (#152); out of that PR's scope since it predates it and lives in IRAxis construction.

[k-yoshimi]

Additional finding from PR #152's CI: the ill-conditioning boundary is platform-(BLAS-)dependent. A fixture at beta=0.1, wmax=5, eps=1e-8 (beta*wmax = 0.5) produced silently wrong transform matrices on the GitHub Actions runners' BLAS while the same versions of sparse-ir/pylibsparseir gave correct results on two other stacks (macOS/Accelerate and a Linux A100 host). So the safe-parameter region cannot be stated once and reused across machines — which strengthens the case for a construction-time conditioning self-check rather than documented parameter bounds.

[k-yoshimi]

Closed by #175 (merged): IRAxis construction now runs a coefficient-space roundtrip-residual self-check on every design matrix (threshold 1e-11, calibrated with 160x/10x margins) and raises a contextual ValueError naming beta/wmax/eps/residual/remedy — both reported failure modes (the LinAlgError crash and the silent ~4x-wrong transforms) are eliminated; the healthy path is bit-identical, pinned by a test. The campaign also surfaced that the regime boundary is sparse-ir-version dependent (1.1.7 vs 2.1.1 invert BOTH ways), so the guard tests assert the contract environment-adaptively, and a shipped small-Lambda fixture that had been silently exercising meaningless transforms on 1.1.7 was repaired. Basis-truncation error at well-conditioned small Lambda is out of a conditioning guard's reach — tracked separately as #179.