Two issues in the wall-velocity solver: (1) `findWallVelocityDetonation` unpacks 5 values from a 7-tuple + (2) hybrid-regime singular Boltzmann matrix

[tasicarl]

WallGo version: 1.1.1 (pip) · Python: 3.10.19 · OS: Linux

Thanks for WallGo! I'm using it to compute out-of-equilibrium wall velocities for a 2HDM Type-I scan (driven from TransitionListener, feeding WallGo the phases + percolation temperature). Across a 100-point strong-PT panel I hit two distinct solver problems. The first is a clear bug with a one-line fix; the second is a robustness/usability issue around the documented sonic-point singularity.

---

Issue 1 — findWallVelocityDetonation unpacks 5 values from the 7-tuple returned by wallPressure (every detonation solve raises ValueError)

EOM.wallPressure returns a 7-tuple:

# equationOfMotion.py
def wallPressure(...) -> tuple[
    float, WallParams, BoltzmannResults, BoltzmannBackground,
    HydroResults, float, float,   # <- emViolationT30, emViolationT33
]:

But the two call sites inside findWallVelocityDetonation unpack only 5:

# equationOfMotion.py, in findWallVelocityDetonation (v1.1.1)
# line ~280:
pressure2, wallParams, boltzmannResults, _, _ = wallPressureResults2
# line ~331:
pressure3, wallParams2, _, _, _ = wallPressureResults2

so every call to manager.solveWallDetonation(...) raises:

ValueError: too many values to unpack (expected 5)

(The other unpack sites in the same file, e.g. lines ~472–478 and ~513–519, correctly take 7 values — these two were evidently missed when wallPressure grew the two emViolation return values.)

Why it bit hard

For strong transitions the physical wall is a detonation (the deflagration branch correctly returns "maximum pressure on wall is negative" → no root for v_w < v_J). With the detonation branch crashing, all such points come back with no solution, indistinguishable from a genuine runaway.

Fix (one line each)

pressure2, wallParams, boltzmannResults, _, _, _, _ = wallPressureResults2
pressure3, wallParams2, _, _, _, _, _ = wallPressureResults2

After this, solveWallDetonation runs its grid scan correctly. Happy to open a PR.

---

Issue 2 — hybrid-regime (c_s < v_w < v_J) deflagration solve hits LinAlgError('Singular matrix'), forceImproveConvergence does not cure it, and it cannot be toggled by the user

After fixing Issue 1, a subset of our strongest points (high latent heat / thin wall) fail at the first deflagration trial, which the solver places just below the Jouguet velocity:

------------- Trying wallVelocity=0.784794 -------------   # v_J = 0.7847942
solveWall (deflagration) failed: LinAlgError('Singular matrix')
------------- Trying wallVelocity=0.785794 -------------   # v_J + 1e-3 (detonation)
solveWallDetonation failed: LinAlgError('Singular matrix')

The failing velocity sits in the hybrid band c_s ≈ 0.577 < v_w < v_J = 0.785, i.e. exactly the supersonic-deflagration regime where the paper (arXiv:2411.04970) notes the kinetic matrix of the Boltzmann system develops a vanishing eigenvalue at v_w = c_s and the background perturbations diverge. The singular solve is the
np.linalg.solve(operator, source) in boltzmann.py (solveBoltzmannEquations, ~line 283).

What I tried

1. wallThicknessGuess ∈ {0.75, 1.5, 3.0, 5.0} (1/T units) — all still singular. (Note: with the default meanFreePathScale = 50, the grid tailLength = max(meanFreePathScale, 0.5·L_w·…) is dominated by meanFreePathScale, so wallThicknessGuess barely changes the grid — perhaps worth documenting.)
2. forceImproveConvergence = True (the robust "cautious" nonlinear-background scheme). The deflagration cautious flag is self.forceImproveConvergence, auto-forced True only for v_w > v_J (equationOfMotion.py ~845–847). I enabled it for the deflagration branch too — still singular at the same v_w. It looks like the singular np.linalg.solve happens before the cautious iteration can stabilize the background.

Two requests

1. Expose forceImproveConvergence through WallSolverSettings. Right now WallGoManager.buildEOM hardcodes forceImproveConvergence=False (manager.py ~746), so a user cannot enable the robust scheme for deflagrations without editing site-packages. A field on WallSolverSettings (alongside bIncludeOffEquilibrium, meanFreePathScale, wallThicknessGuess) would make the documented sonic-point workaround reachable.
2. Guidance / hardening for the hybrid regime. Is there a recommended setting (grid N/M, errTol, starting-velocity offset from v_J) that avoids the singular kinetic matrix for hybrid walls? In our scan ~half of the strong-PT points fail here even with forceImproveConvergence, so any robustness improvement (e.g. catching the singular solve and retrying with a perturbed v_w / regularized operator) would help a lot.

Minimal reproducer (model-independent symptom)

The crash in Issue 1 reproduces on any model that reaches solveWallDetonation. For Issue 2, our failing point (2HDM Type-I, on-shell-matched Veff) is:

alpha = 0.118,  beta/H = 490,  T_perc = 56.68 GeV
lambda1..5 = [0.3458, 0.2650, 6.1506, -2.1103, -2.1306]
m12^2 = 3612 GeV^2,  tan(beta) = 14.15
v_J = 0.7847942,  c_s ≈ 0.577  (so the first deflagration trial at 0.784794 is hybrid)

I can share a self-contained script + the collision files if useful.

---

Thanks again — Issue 1 in particular is a quick win that unblocks all detonation solving.

[og113]

Hi Carlo, thanks a lot for bringing this to our attention.

Issue 1

This was a very clear bug, so thanks for picking it up. We realised that there were no tests for detonations, so that a recent breaking change was missed. The fix is in PR #371, plus we also aim to add a basic test for detonations so this doesn't happen again (though not implemented yet).

Issue 2

Thanks again for your suggestions. We've exposed forceImproveConvergence in PR #371. As for how to solve these singular-matrix issues in the hybrid regime, this is not something we met in our testing, so we'd be very interested to understand more. We had expected the collision operator to be rather generically non-singular, if all the relevant interactions are taken into account, but perhaps we missed something. Could you please share your code and collision files?