KroneckerSumSolver: stiffness coefficients and additional Kronecker terms

[spossann]

Summary

Generalizes KroneckerSumSolver (fast diagonalization of sums of Kronecker products), needed by struphy's StiffnessPreconditioner for operators like the adiabatic gyrokinetic Poisson equation:

$$A = \sum_d a_d , M_1 \otimes \dots \otimes S_d \otimes \dots \otimes M_n + \sigma , M_1 \otimes \dots \otimes M_n + \sum_t c_t , F_{t,1} \otimes \dots \otimes F_{t,n}$$

• stiffness_coeffs: coefficients $a_d$ of the stiffness terms (default 1). $S_d$ defines the eigenbasis also for $a_d = 0$, e.g. a direction in which a perpendicular diffusion has no stiffness.
• mass_terms: additional terms $c_t , F_{t,1} \otimes \dots \otimes F_{t,n}$ (None for $M_d$), used through their diagonal $\mathrm{diag}(U_d^T F_{t,d} U_d)$ in the eigenbasis. This is exact when the $U_d$ diagonalize the $F_{t,d}$, e.g. for $F = c,c^T/(\mathbb 1^T c)$ with $c = M_d \mathbb 1$ in a direction with $S_d \mathbb 1 = 0$ (removing the mean in a periodic direction: $U_d^T F U_d = e_0 e_0^T$); otherwise it is an approximation.
• Default arguments give exactly the previous behavior (including the pseudo-inverse threshold).
• Version 0.7.0 → 0.8.0.

Tests

test_kron_sum_solver_terms_{ser,par}: stiffness coefficients (one of them zero) and a term removing the mean in the two periodic directions; exact (pseudo-)inverse, relative residual < 1e-12. test_kron_stencil_matrix.py: 25 passed serially, 45 on 2 ranks.

Paired struphy PR: struphy-hub/struphy#740

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Signed terms can cause cancellation that makes the pseudo-inverse threshold incorrectly discard nonzero eigenvalues.

2 open findings

• Use assembled spectrum maximum for pseudo-inverse cutoff · New
• Normalize mean-removal projection factor · New

What changed in this PR

Generalizes KroneckerSumSolver for stiffness preconditioning with weighted stiffness terms and additional Kronecker mass terms.

Changes:

• Adds stiffness coefficients and additional mass terms.
• Adds serial and MPI tests for the generalized solver.
• Bumps the package version to 0.8.0.

File	Description
pyproject.toml	Updates the package version.
feectools/​linalg/​kron.py	Implements and documents generalized Kronecker terms.
feectools/​linalg/​tests/​test_kron_stencil_matrix.py	Tests weighted stiffness and mean-removal terms.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.