fix(regularisers): correct diag_bending/diag_all corner cross-term sign error

[balbasty]

Agent: claude-fastfields-to-teeny

Closes#48

The bug

The boundary-corrected diagonal in diag_bending (field) and diag_bending / diag_all (flow) computed each corner weight as

w * (fx0*fy0 + fx1*fy0 + fx1*fy0 + fx1*fy1)

fx1*fy0 is counted twice and fx0*fy1 is dropped. The correct expansion of (fx0+fx1)*(fy0+fy1) is

w * (fx0*fy0 + fx1*fy0 + fx0*fy1 + fx1*fy1)

which is exactly what matvec_bending / matvec_all already compute a few lines up in the same files, e.g. regularisers/field/2d.h:

+ w11 * (get(x0+y0, fx0*fy0) + get(x1+y0, fx1*fy0) +
get(x0+y1, fx0*fy1) + get(x1+y1, fx1*fy1))

The error cancels at fully-symmetric corners (both axes flipping the same way) and only shows up where the two axes' one-sided boundary signs differ — which is why the existing interior-only diag tests never saw it. It corrupts the shipped field_diag / flow_diag public output at boundary voxels under sign-flipping bounds (Zero / DST1 / DST2) whenever bending is active, and hence also the Jacobi preconditioner built from that diagonal.

Sites fixed — 12 terms, matching the issue exactly

file	function	terms
regularisers/field/2d.h	diag_bending	1 (w11 xy)
regularisers/field/3d.h	diag_bending	3 (w110 xy, w101 xz, w011 yz)
regularisers/flow/2d.h	diag_bending, diag_all	1 + 1
regularisers/flow/3d.h	diag_bending, diag_all	3 + 3

Total 12 wrong terms across 6 functions — the exact count the issue predicted, and the exact same per-file line counts as the already-verified fix on claude/fastfields-teeny-refactor-js42id (5ed785a, ex-PR #32). Confirmed by grep that no remaining doubled-term expression exists anywhere under regularisers/.

This is a re-application, not a cherry-pick: main has since converted these from static methods using Impl:: qualification to instance methods on a bound::dyn<B>-holding object (bound_utils_x.sign(...)), per kernels #42 / the bound::type::Dynamic work. The corrected expressions are textually identical to the verified fix; only their surroundings differ.

Verification

Built fastfields-cpu-lib @ origin/main (6aaa159) against this branch via the dev-tree symlinks (cpu-lib/impl -> cpu-impl@b6eae48 -> kernels@this), make test CXX=clang++:

	result
before fix (main kernels)	all 12 suites PASS — test_reg_field 4610 checks / 0 fail, test_reg_flow 5859 / 0
after fix	all 12 suites PASS — identical check counts, 0 failures

No existing test changes value, i.e. nothing on main currently covers the buggy boundary corners.

Regression test — fastfields/fastfields-cpu-lib#53

Since fastfields-kernels has no test suite of its own, the regression test for this fix lives downstream: fastfields/fastfields-cpu-lib#53 carries the three boundary-symmetry tests (test-only, no production code). Verified revert/restore cycle against that branch:

kernels commit	test_reg_field	test_reg_flow
15295c2 — pre-fix	4 failures	16 failures
9b6517f — this PR's head	0 failures	0 failures

All 20 pre-fix failures show a uniform ~8.0 discrepancy against a 1e-5 tolerance, so it is a decisive detector. The invariant needs no reference implementation: on a square domain with the same boundary condition on every axis (DST2, bending active), the operator's diagonal must be symmetric under axis swap, so diag(0,j,c) == diag(j,0,c) — and for diag_all with shears == div, diag(0,j,c) == diag(j,0,1-c) under simultaneous axis + channel swap.

Merge this PR first. cpu-lib#53 stays red until this lands and the cpu-impl -> kernels / cpu-lib -> impl pins are bumped; that ordering is spelled out in its body.

[balbasty]

Closing this — not because the analysis was wrong. It wasn't: I re-derived the defect independently and this PR's diagnosis is correct in every particular.

Why it's being closed

This PR comes from the claude-fastfields-to-teeny workstream, whose PRs must always target the teeny branch. This one targets main, so it was mis-filed. That's the sole reason for closing.

The analysis was sound — credit where it's due

Verified independently rather than taken on trust:

• The corner weight really was expanded as w*(fx0*fy0 + fx1*fy0 + fx1*fy0 + fx1*fy1) — fx1*fy0 twice, fx0*fy1 dropped.
• The correct form really is what matvec_bending/matvec_all already accumulate over their four corner neighbours a few lines above in each same file (e.g. regularisers/field/2d.h:383-384, field/3d.h:418-423), term-for-term.
• The site count was exactly right: 12 terms across 6 functions in 4 files — field/2d.h ×1, field/3d.h ×3, flow/2d.h ×2, flow/3d.h ×6.
• The cancellation argument was right too: with fx0==fx1 and fy0==fy1 both forms come to 4*fx0*fy0, so the error is invisible except where the two axes' one-sided boundary signs differ — which is why interior-only diagonal tests never saw it.

Where the fix actually landed

The equivalent fix is now on main via #81 (merged, 1df9fd3), which closed #48. It is textually the same 12-term correction — there is only one right answer here — but re-derived and re-verified against current main from scratch.

The pin chain has been cascaded so the fix is live on both backends:

cpu-lib -> cpu-impl 5e2c78e -> kernels 1df9fd3

Regression coverage

The teeny branch already carries the equivalent fix (5ed785a) and, in 8afcab4, the matching regression tests — both still present at teeny HEAD. So nothing from this PR is stranded and no follow-up issue is needed on that account.

On main, the regression test landed as fastfields-cpu-lib#89, which is deliberately broader than the 2D-only version: it covers 3D as well (where 9 of the 12 fixed terms live), sweeps the whole domain, and runs under Zero/DCT2/DST2 with DCT2 as a non-sign-flipping control. Measured: it fails with 328 (test_reg_field) + 1696 (test_reg_flow) failures against the pre-fix kernels and passes at 1df9fd3, with identical check counts both ways.

Nothing here has been dropped on the floor. This PR's branch has not been modified.

---

Generated by Claude Code