Kronecker preconditioners: StiffnessPreconditioner, refactor of the mass preconditioners; bump feectools

[spossann]

Summary

Points the feectools submodule to the branch of struphy-hub/feectools#100, so that the struphy test suite runs against it before that PR is merged.

struphy-hub/feectools#100 changes KroneckerStencilMatrix and KroneckerLinearSolver:

• factors on groups of axes (e.g. 2d x 1d);
• A @ B returns a new ComposedKroneckerStencilMatrix (operands in multiplicands, exact Kronecker factors of the product in mats);
• ComposedLinearOperator.multiplicants → multiplicands, with a deprecated alias;
• KroneckerSumSolver, the exact inverse of sums of Kronecker products by fast diagonalization;
• factor_ndims in KroneckerLinearSolver;
• docstrings and type annotations; feectools 0.7.0.

Existing calls are unchanged, so struphy needs no code changes. struphy builds these objects in feec/preconditioner.py (MassMatrixPreconditioner) and feec/projectors.py.

multiplicants → multiplicands

• All struphy uses (preconditioner, projectors, multigrid coarsening) now use multiplicands.
• linop_nbytes in feec/memory.py adds up all child attributes, so a ComposedKroneckerStencilMatrix counts both its operands and the factors of the product.

Refactor of MassMatrixPreconditioner

• The construction of the Kronecker approximation is split into module-level helpers in feec/preconditioner.py. They cover the boundary conditions, gathering array weights over MPI, the 1d weight, the 1d mass matrix and its BCs, the 1d solver, the process-local 1d factor, the block-diagonal assembly and the operator to invert.
• MassMatrixDiagonalPreconditioner now calls these helpers instead of repeating the same ~200 lines.
• Values and the order of MPI calls are unchanged. The copy into the process-local 1d stencil matrix is now vectorized, and the block-diagonal operators are no longer hard-coded to 3 components.
• Docstrings, comments and type annotations.

MassMatrixPreconditioner: new option and fixes

• New option weight_reduction="midpoint" | "average" sets how the weight is reduced to 1d in the directions other than dim_reduce. The default "midpoint" gives the same results as before, verified for M0, M1, M2, Mv, M1n and array weights, serially and on 2 ranks. "average" uses the mean over those directions: Gauss quadrature of the Derham for array weights, 16-point Gauss–Legendre for callables.
• Array weights are reduced with a single Allreduce, instead of a subcommunicator plus Bcast.
• The mass matrix is located in the composed operator by identity, and the approximate inverse is applied exactly there. Both preconditioners share this code (_apply_composed). Before, a mass matrix in the left-most position was applied instead of inverted.
• FFTSolver copies its column, which was a view of the dense matrix also used for the stencil factor. It now stabilises a singular matrix once, at construction. is_circulant is vectorized.

PCG iterations (tolerance 1e-8) on HollowTorus, grid 12×16×6, degree (2,3,2), as a reference for choosing weight_reduction:

	M0	M1	M2	M3	Mv	M1n	M2n	Mvn
midpoint	13	22	22	13	31	673	600	1000 (not converged)
average	13	15	15	13	30	798	727	1000 (not converged)

On HollowCylinder both need 2 iterations for every matrix.

Kronecker preconditioners: base class, stiffness preconditioner

KroneckerPreconditioner is a new base class for preconditioners of the form P = B E · S Ã⁻¹ S · Eᵀ Bᵀ:

• Ã (matrix) approximates the core operator, and its exact inverse is solver. Subclasses build the approximation.
• S is an optional diagonal scaling D̂^{1/2} D^{-1/2} (Loli–Sangalli–Tani), with D the diagonal of the core operator and D̂ that of the approximation.
• The base class holds the common interface (solve, dot, the composition with B E, the properties).

Mass preconditioners

• MassMatrixPreconditioner is a subclass. It gets the options diagonal_scaling (default False) and dim_reduce=None (unit weights in all directions), and the method update_mass_operator. With diagonal_scaling=True, the PCG iterations for M1 on a HollowTorus drop from 20 to 8.
• MassMatrixDiagonalPreconditioner is now MassMatrixPreconditioner(dim_reduce=None, diagonal_scaling=True), kept for its name in the solver options. It no longer assembles a separate 3d logical mass matrix; D̂ comes from the Kronecker approximation. Results are unchanged up to rounding (1e-13), checked on HollowTorus and IGAPolarCylinder, including update_mass_operator, serially and on 2 ranks.

StiffnessPreconditioner (new) preconditions the stabilized stiffness operators Gᵀ M1 G + σ M0, Cᵀ M2 C + σ M1 and Dᵀ M3 D + σ M2:

• With Kronecker mass matrices, each diagonal block is a sum of Kronecker products of 1d stiffness and mass matrices. It is inverted exactly with KroneckerSumSolver, one solver per component (the components have different spline types, e.g. DNN/NDN/NND for M1). For grad, this is exact on the logical cube.
• curl and div neglect the off-diagonal blocks (block Jacobi). Block Jacobi alone overestimates the operator on the kernel of the derivative, so a kernel correction σ⁻¹ d₋ P₋ d₋ᵀ is added (default, needs σ > 0): with d₋ = G and the grad preconditioner for curl, and d₋ = C and the curl block Jacobi for div.
• Weights: weights="average" (default) approximates the mass-matrix weights by one common separable shape per direction plus a mean per term, which keeps the fast diagonalization exact. weights="unit" uses the logical cube. Diagonal scaling (default on) adds the geometry pointwise; for it, the diagonal of the stiffness operator is computed by probing.
• Polar splines are not supported yet.

PCG iterations (tolerance 1e-8), HollowTorus, grid 12×16×6, degree (2,3,2):

	no preconditioner	mass preconditioner	StiffnessPreconditioner (defaults)
grad, σ = 0	187	–	41
curl, σ = 1	> 3000	716	46
div, σ = 1	> 3000	636	48

On a stretched cuboid (constant, anisotropic weights), grad needs 2 iterations. For large σ (1e4), the mass preconditioner is as good or slightly better (about 13 vs 25 iterations).

Tests

Run locally with the submodule branch: all preconditioner tests (test_preconditioner_transpose.py, the new test_stiffness_preconditioner.py, test_mass_matrices.py::test_mass_preconditioner*, test_reduced_weight_1d) pass serially and on 2 ranks (52 passed each). The new stiffness tests cover the approximation against the operator on the unit cube, PCG iteration counts for grad/curl/div, the kernel correction, weights="average", and independence of the MPI decomposition. The rest is left to CI.

Don't raise the feectools pin in pyproject.toml until 0.7.0 is on PyPI. Before merging, the submodule pointer should move to the merged devel-tiny commit.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The code requires feectools 0.6 APIs while the package metadata still restricts installations to feectools 0.5.0.

1 open finding

• Import requires unavailable feectools 0.6.0 APIs · New

What changed in this PR

Adds reusable Kronecker-based mass and stiffness preconditioners and adopts feectools 0.6 APIs.

Changes:

• Refactors mass preconditioners and adds weight reduction and diagonal scaling.
• Adds StiffnessPreconditioner with MPI-aware tests.
• Migrates composed operators to multiplicands.

File	Description
feectools	Points to the paired feectools development commit.
src/​struphy/​feec/​preconditioner.py	Implements Kronecker preconditioners and helpers.
src/​struphy/​feec/​memory.py	Counts all composite operator children.
src/​struphy/​feec/​projectors.py	Uses the renamed composition API.
src/​struphy/​linear_algebra/​multigrid/​coarsen.py	Updates composition coarsening.
src/​struphy/​propagators/​variational_viscosity.py	Updates a commented attribute reference.
src/​struphy/​propagators/​variational_resistivity.py	Updates a commented attribute reference.
src/​struphy/​feec/​tests/​test_stiffness_preconditioner.py	Tests stiffness preconditioning behavior.
src/​struphy/​feec/​tests/​test_preconditioner_transpose.py	Expands mass-preconditioner tests.
src/​struphy/​feec/​tests/​test_mass_matrices.py	Tests weight reduction and MPI consistency.

🧠 Review effort: Balanced

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

[spossann]

@max-models this is ready now!