reg: restore the in-place diag/kernel accumulate primitives (lost from jitfields)

[balbasty]

Changes (fastfields-cpu-lib)

• _field_diag / _field_kernel / _flow_diag / _flow_kernel are now
  templated on char op (they hardcoded '='); the impl layer already took the
  op, so this only threads it through.
• New ADD_DG_DT / SUB_DG_DT / ADD_KN_DT / SUB_KN_DT dispatch macros,
  mirroring the existing ADD_MV_DT / SUB_MV_DT.
• New public entry points: {field,flow}_{diag,kernel}_{add_,sub_} (8).
• Renamed the four task-test(reg): cover the diag_bending/diag_all corner cross-term bug #53 symbols {field,flow}_matvec_{add,sub} ->
  ..._{add_,sub_} (see Naming below), including the internal
  field_forward / flow_forward call sites.
• Tests: run_2d_diag_kernel_addsub in tests/test_reg_{field,flow}.cpp,
  same oracle style as the existing run_2d_matvec_addsub — the '=' path
  computes the reference, then add_/sub_ must reproduce base +/- ref
  against a nonzero pre-existing buffer (which is what catches an op that
  silently overwrites). Covers absolute/membrane/bending, the flow Lamé
  (matrix-stencil) shape, three boundary conditions, and float+double.

Note tests/test_reg_op.cpp already covered impl-level op dispatch for
matvec and diag; the kernel op path had no coverage until now.

Verification

make test CXX=clang++ — all 11 test binaries pass, 0 failures:

test_reg_field checks: 7426, failures: 0 PASSED
test_reg_flow checks: 11415, failures: 0 PASSED
test_reg_op checks: 186, failures: 0 PASSED
(+ distance, distance_mesh, distance_spline, posdef, pushpull,
resize, restrict, splinc — all PASSED)

Background (shared by this PR series)

The regulariser accumulate ops ({field,flow}_{matvec,kernel,diag} with
op = set / add / sub) were in-place-only at the C level in jitfields, and
that primitive was lost partway up the fastfields port. An earlier PR pair
(fastfields-torch#19, fastfields#21) diagnosed the symptom correctly — the
torch *_add_ ops really were mutating their input — but drew the wrong
conclusion and deleted the Python feature. The right fix is to restore the
missing C primitive. Those two PRs are superseded and closed.

What jitfields actually does (verified, not assumed)

jitfields/csrc/lib/regularisers/{field,flow}/utils.h:

template <char op, typenamescalar_t, typenamereduce_t = scalar_t>
structOp { staticconstexpr FuncType f = set; };
template <...> structOp<'+', ...> { staticconstexpr FuncType f = iadd; };
template <...> structOp<'-', ...> { staticconstexpr FuncType f = isub; };

Every matvec_* / kernel_* / diag_* entry point takes that char op and
writes through out, so '+'/'-' are read-modify-write on the caller's
buffer. There is no separate "return a fresh tensor" C entry point.

In jitfields' Python layer the two spellings share that one kernel:

deffield_matvec_add(...): # out-of-placeout=inp.clone() # <- the ONLY differencefn(out, vec, ..., 'add')
deffield_matvec_add_(...): # in-placefn(inp, vec, ..., 'add')

What was actually missing in fastfields

layer	state before
kernels	Op<op> intact
cpu-impl / cuda-impl	char op on matvec/kernel/diag — intact
cpu-lib / cuda-lib	only {field,flow}_matvec_{add,sub} (task #53); _field_diag/_field_kernel hardcoded '='
lib (hub)	nothing — no accumulate entry point at all
bind-py / dlpack	nothing
numpy / torch / cupy	faked it in Python: inp + field_matvec(...) (two kernels + a temporary)

So the earlier claim "no accumulate-into-out kernel exists below" was observing
a real gap — but the gap was a missing surface, not a missing capability.

Naming: trailing underscore

The restored entry points are {field,flow}_{matvec,diag,kernel}_{add_,sub_} —
with a trailing underscore, because they are in-place only. This matches the
existing ff:: convention for accumulate-into-out (sym_addmatvec_,
sym_submatvec_) and the out-of-place/in-place pairing field_precond /
field_precond_.

This renames the four symbols added by task #53
({field,flow}_matvec_{add,sub} -> ..._{add_,sub_}). The project is
unreleased (0.1+dev), and the rename removes a real Python-level collision:
fastfields.{numpy,torch,cupy}.field_matvec_add is the out-of-place spelling,
so leaving the in-place C primitive under the same name meant one name with
opposite meanings in two importable modules.

This is the one deliberate deviation from "mirror #53 exactly". If you'd
rather keep the un-suffixed spelling, it is a one-line sed to revert.

Python surface (unchanged, and identical to jitfields)

field_matvec_add out-of-place, field_matvec_add_ in-place — on numpy, torch
and cupy alike. Both route through the single in-place C primitive; the
out-of-place form clones first. No behaviour change for existing callers, but
the accumulate is now one fused kernel instead of a matvec plus a temporary.

Divergence from jitfields (deliberate)

jitfields.field_kernel_add calls impl.flow_kernel — an upstream copy-paste
bug (its docstring even reads "See flow_kernel"). fastfields routes
field_kernel_add_ to the field kernel. Not reproduced.

🤖 Generated with Claude Code

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code