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

[balbasty]

Changes (fastfields-cuda-lib)

Structural mirror of fastfields-cpu-lib#50 — that repo is the correctness
gate (no GPU in CI), and this layer is verified by compile+link only.

• _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-#53 symbols {field,flow}_matvec_{add,sub} ->
  ..._{add_,sub_} (see Naming below).

Stream plumbing (_reg_stream) and the Lamé matrix-stencil nbatch handling
(ntrail = 2 when shears/div are active) are carried through unchanged.

Verification status — please let CI be the gate here

Honest status at time of opening: the local nvcc build had compiled the new
code for ~32 min at the Makefile default -O3 and a further ~10 min at CI's
-O1 with zero compile errors, but had not yet reached the link step —
distance.o done, reg_field.o still in cicc. nvcc on these heavily
templated TUs is simply slow here (this repo's own notes put pushpull at ~40 min
on its own). The earlier EXIT=2 in my logs was nvcc: Terminated — my own
pkill when switching to CI's flags — not a compile failure.

What is established:

• The new instantiations were observed compiling (they appear by name in
  nvcc's diagnostic traces, e.g.
  _field_kernel<ndim,op,scalar_t,offset_t,BOUND...> at reg_field.cpp(1007)),
  with no diagnostics beyond the pre-existing
  warning #186-D: pointless comparison of unsigned integer with zero.
• The declarations are consistent with their consumers: fastfields-lib
  compiles and links against these headers with FF_CUDA:: dispatch, and its
  make all is EXIT=0 with all 12 symbols exported.
• The logic is identical to the CPU implementation, which is green
  (make test: 11 binaries, 0 failures — reg_field 7426 checks, reg_flow
  11415, reg_op 186).

CI here runs make -C . CXX=clang++ CXXFLAGS="-std=c++14 -O1", which is the
real gate for this repo. I'll post a follow-up comment with the local link
result once it completes.

Background (shared by this PR series)

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 —
field_matvec_add does out = inp.clone() then calls the same C function
with 'add'.

Scope check:grep -rl "char op" over all of jitfields/csrc matches
onlyreg_field / reg_flow (and their regularisers/*/utils.h), so
field+flow × matvec/kernel/diag is complete parity.

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(...)

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

In-place only, so the name says so — matching ff::'s existing marker for
accumulate-into-out (sym_addmatvec_, sym_submatvec_) and the
field_precond / field_precond_ pairing. This renames the four task-#53
symbols; the project is unreleased, and it removes a real collision, since
fastfields.{numpy,torch,cupy}.field_matvec_add is the out-of-place spelling.

The one deliberate deviation from "mirror #53 exactly" — a one-line sed to
revert if you'd rather keep the un-suffixed spelling.

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.

PR series

1. fastfields-cpu-libreg: restore the in-place diag/kernel accumulate primitives (lost from jitfields) fastfields-cpu-lib#50 — the correctness gate (all CPU tests green)
2. fastfields-cuda-lib — this PR
3. fastfields-libreg: expose the 12 in-place accumulate entry points at the hub + bump pins fastfields-lib#47 — the 12 hub entry points
4. fastfields-dlpackreg: bind the 12 in-place accumulate primitives + bump lib pin fastfields-dlpack#20 — nanobind + dlpack re-exports
5. fastfields-numpyreg: route accumulate wrappers through the fused in-place primitive fastfields-numpy#19 / fastfields-torchreg: implement the accumulate ops as autograd-safe in-place Functions (supersedes #19) fastfields-torch#21 (supersedes refactor(posdef,splinc): teeny dispatch + stream; add to MODULES #19) / fastfields-cupyreg: route accumulate wrappers through the fused in-place primitive fastfields-cupy#14
6. fastfieldscontract: replace the blanket torch in-place ban with a per-op rule (supersedes #21) fastfields#22 — API_CONTRACT + conformance (supersedes reg_flow: add flow_kernel dispatch (forwards CUDA stream) #21)

fastfields#20 is re-pointed at this series.

🤖 Generated with Claude Code

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code