Fix field_kernel_* dispatching to flow_kernel, and kernel_sub silently adding

[balbasty]

Two independent bugs in the *_kernel_add / *_kernel_sub wrappers, found
while porting these kernels to fastfields.
Both are verified against the current main (dc74377); a regression test that
fails before and passes after is included.

1. field_kernel_add/_ dispatch to impl.flow_kernel

field_kernel_add and field_kernel_add_ call impl.flow_kernel instead of
impl.field_kernel. This is a hard failure, not a silent one: the backend
signature is

flow_kernel(out, bound, voxel_size, absolute, membrane, bending, shears, div, op='')

— 8 required positional parameters — and the call site passes 7, so all four
public entry points raise immediately:

>>> field_kernel_add(2, inp, 0.3, 1.0, 0.2, voxel_size=[1.5, 1.0])
TypeError: flow_kernel() missing 1 required positional argument: 'div'

bindings/cuda's flow_kernel declares the identical 8-positional signature,
so the CUDA path fails the same way (unverified at runtime — no GPU here). The
stale See `flow_kernel` docstrings on the two _add variants (every
sibling says See `field_kernel` ) are corrected too — they look like the
origin of the slip.

Worth noting for the test: field_kernel and flow_kernel produce
bit-identical channel-0 kernels under the default isotropic voxel size,
and only diverge once voxel_size is anisotropic. So even a version of this
call that had the right arity would still have gone unnoticed under a
default-argument test.

2. field_kernel_sub/_ and flow_kernel_sub/_ silently add

All four forward to their _add sibling without the trailing _sub=True flag,
so op is computed as 'add' and they add the kernel instead of subtracting
it. On current main (flow variants are reachable today; the field ones are
blocked by bug 1):

>>> torch.equal(flow_kernel_add(inp, ...), flow_kernel_sub(inp, ...))
True # should be False
>>> torch.allclose(flow_kernel_sub(zeros, ...), -flow_kernel(...))
False # returns +kernel

Every other _sub wrapper in these two modules — field_matvec_sub,
field_matvec_sub_, field_diag_sub, field_diag_sub_, and the four flow
equivalents — does pass True. These four are the only omissions.

Changes

• _regularisers_fields.py: impl.flow_kernel → impl.field_kernel in
  field_kernel_add and field_kernel_add_; fix their docstrings; forward
  True from field_kernel_sub / field_kernel_sub_.
• _regularisers_flows.py: forward True from flow_kernel_sub /
  flow_kernel_sub_.
• tests/test_reg_field.py, tests/test_reg_flow.py: new
  test_kernel_add_sub, asserting kernel_add(inp) == inp + kernel and
  kernel_sub(inp) == inp - kernel for the out-of-place and in-place variants.
  The voxel size is deliberately anisotropic ([1.5, 1., 2.5][:dim]) so
  that a field-vs-flow cross-wiring cannot hide behind the isotropic
  coincidence described above.

Verified locally (CPU backend, bindings/cpp):

# on main, the two new tests only
12 failed # field: TypeError above; flow: the `sub` assertion
# with this change, both reg modules
36 passed

One thing I did not touch

My first draft of the flow test also covered shears/div. I dropped it
because it runs into what looks like a separate, pre-existing problem:
flow_kernel with shears/div on a spatial shape larger than the minimal
one does not seem to produce a centred stencil. On current main:

>>> flow_kernel([5], shears=0.5, div=0.7, voxel_size=[1.5]) # shape (5,1,1)
[-1.7, -1.7, -1.7, -1.7, 3.4]

I would have expected a centred 3-tap stencil zero-padded to length 5, and the
voxel_size scaling also appears to be absent (2*shears + div == 1.7, with no
1/1.5²). The existing test_kernel only exercises shears/div at the
minimal [3]*dim shape, so this regime is untested. I have not diagnosed
this properly and it is unrelated to the two bugs fixed here — flagging it only
so it is not lost. (Instantiating the kernel_lame'+'/'-' templates also
crashed cppyy in my environment, which may or may not be related.)

---

Found while porting jitfields to https://github.com/fastfields. I have opened a
companion issue listing the other jitfields-inherited defects turned up by that
port. Left unmerged for your review, as requested.

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code

[balbasty]

Two independent bugs in the *_kernel_add / *_kernel_sub wrappers, found
while porting these kernels to fastfields.
Both are verified against the current main (dc74377); a regression test that
fails before and passes after is included.

1. field_kernel_add/_ dispatch to impl.flow_kernel

field_kernel_add and field_kernel_add_ call impl.flow_kernel instead of
impl.field_kernel. This is a hard failure, not a silent one: the backend
signature is

flow_kernel(out, bound, voxel_size, absolute, membrane, bending, shears, div, op='')

— 8 required positional parameters — and the call site passes 7, so all four
public entry points raise immediately:

>>> field_kernel_add(2, inp, 0.3, 1.0, 0.2, voxel_size=[1.5, 1.0])
TypeError: flow_kernel() missing 1 required positional argument: 'div'

bindings/cuda's flow_kernel declares the identical 8-positional signature,
so the CUDA path fails the same way (unverified at runtime — no GPU here). The
stale See `flow_kernel` docstrings on the two _add variants (every
sibling says See `field_kernel` ) are corrected too — they look like the
origin of the slip.

Worth noting for the test: field_kernel and flow_kernel produce
bit-identical channel-0 kernels under the default isotropic voxel size,
and only diverge once voxel_size is anisotropic. So even a version of this
call that had the right arity would still have gone unnoticed under a
default-argument test.

2. field_kernel_sub/_ and flow_kernel_sub/_ silently add

All four forward to their _add sibling without the trailing _sub=True flag,
so op is computed as 'add' and they add the kernel instead of subtracting
it. On current main (flow variants are reachable today; the field ones are
blocked by bug 1):

>>> torch.equal(flow_kernel_add(inp, ...), flow_kernel_sub(inp, ...))
True # should be False
>>> torch.allclose(flow_kernel_sub(zeros, ...), -flow_kernel(...))
False # returns +kernel

Every other _sub wrapper in these two modules — field_matvec_sub,
field_matvec_sub_, field_diag_sub, field_diag_sub_, and the four flow
equivalents — does pass True. These four are the only omissions.

Changes

• _regularisers_fields.py: impl.flow_kernel → impl.field_kernel in
  field_kernel_add and field_kernel_add_; fix their docstrings; forward
  True from field_kernel_sub / field_kernel_sub_.
• _regularisers_flows.py: forward True from flow_kernel_sub /
  flow_kernel_sub_.
• tests/test_reg_field.py, tests/test_reg_flow.py: new
  test_kernel_add_sub, asserting kernel_add(inp) == inp + kernel and
  kernel_sub(inp) == inp - kernel for the out-of-place and in-place variants.
  The voxel size is deliberately anisotropic ([1.5, 1., 2.5][:dim]) so
  that a field-vs-flow cross-wiring cannot hide behind the isotropic
  coincidence described above.

Verified locally (CPU backend, bindings/cpp):

# on main, the two new tests only
12 failed # field: TypeError above; flow: the `sub` assertion
# with this change, both reg modules
36 passed

One thing I did not touch

My first draft of the flow test also covered shears/div. I dropped it
because it runs into what looks like a separate, pre-existing problem:
flow_kernel with shears/div on a spatial shape larger than the minimal
one does not seem to produce a centred stencil. On current main:

>>> flow_kernel([5], shears=0.5, div=0.7, voxel_size=[1.5]) # shape (5,1,1)
[-1.7, -1.7, -1.7, -1.7, 3.4]

I would have expected a centred 3-tap stencil zero-padded to length 5, and the
voxel_size scaling also appears to be absent (2*shears + div == 1.7, with no
1/1.5²). The existing test_kernel only exercises shears/div at the
minimal [3]*dim shape, so this regime is untested. I have not diagnosed
this properly and it is unrelated to the two bugs fixed here — flagging it only
so it is not lost. (Instantiating the kernel_lame'+'/'-' templates also
crashed cppyy in my environment, which may or may not be related.)

---

Found while porting jitfields to https://github.com/fastfields. I have opened a
companion issue listing the other jitfields-inherited defects turned up by that
port. Left unmerged for your review, as requested.

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code

[balbasty]

Two independent bugs in the *_kernel_add / *_kernel_sub wrappers, found
while porting these kernels to fastfields.
Both are verified against the current main (dc74377); a regression test that
fails before and passes after is included.

1. field_kernel_add/_ dispatch to impl.flow_kernel

field_kernel_add and field_kernel_add_ call impl.flow_kernel instead of
impl.field_kernel. This is a hard failure, not a silent one: the backend
signature is

flow_kernel(out, bound, voxel_size, absolute, membrane, bending, shears, div, op='')

— 8 required positional parameters — and the call site passes 7, so all four
public entry points raise immediately:

>>> field_kernel_add(2, inp, 0.3, 1.0, 0.2, voxel_size=[1.5, 1.0])
TypeError: flow_kernel() missing 1 required positional argument: 'div'

bindings/cuda's flow_kernel declares the identical 8-positional signature,
so the CUDA path fails the same way (unverified at runtime — no GPU here). The
stale See `flow_kernel` docstrings on the two _add variants (every
sibling says See `field_kernel` ) are corrected too — they look like the
origin of the slip.

Worth noting for the test: field_kernel and flow_kernel produce
bit-identical channel-0 kernels under the default isotropic voxel size,
and only diverge once voxel_size is anisotropic. So even a version of this
call that had the right arity would still have gone unnoticed under a
default-argument test.

2. field_kernel_sub/_ and flow_kernel_sub/_ silently add

All four forward to their _add sibling without the trailing _sub=True flag,
so op is computed as 'add' and they add the kernel instead of subtracting
it. On current main (flow variants are reachable today; the field ones are
blocked by bug 1):

>>> torch.equal(flow_kernel_add(inp, ...), flow_kernel_sub(inp, ...))
True # should be False
>>> torch.allclose(flow_kernel_sub(zeros, ...), -flow_kernel(...))
False # returns +kernel

Every other _sub wrapper in these two modules — field_matvec_sub,
field_matvec_sub_, field_diag_sub, field_diag_sub_, and the four flow
equivalents — does pass True. These four are the only omissions.

Changes

• _regularisers_fields.py: impl.flow_kernel → impl.field_kernel in
  field_kernel_add and field_kernel_add_; fix their docstrings; forward
  True from field_kernel_sub / field_kernel_sub_.
• _regularisers_flows.py: forward True from flow_kernel_sub /
  flow_kernel_sub_.
• tests/test_reg_field.py, tests/test_reg_flow.py: new
  test_kernel_add_sub, asserting kernel_add(inp) == inp + kernel and
  kernel_sub(inp) == inp - kernel for the out-of-place and in-place variants.
  The voxel size is deliberately anisotropic ([1.5, 1., 2.5][:dim]) so
  that a field-vs-flow cross-wiring cannot hide behind the isotropic
  coincidence described above.

Verified locally (CPU backend, bindings/cpp):

# on main, the two new tests only
12 failed # field: TypeError above; flow: the `sub` assertion
# with this change, both reg modules
36 passed

One thing I did not touch

My first draft of the flow test also covered shears/div. I dropped it
because it runs into what looks like a separate, pre-existing problem:
flow_kernel with shears/div on a spatial shape larger than the minimal
one does not seem to produce a centred stencil. On current main:

>>> flow_kernel([5], shears=0.5, div=0.7, voxel_size=[1.5]) # shape (5,1,1)
[-1.7, -1.7, -1.7, -1.7, 3.4]

I would have expected a centred 3-tap stencil zero-padded to length 5, and the
voxel_size scaling also appears to be absent (2*shears + div == 1.7, with no
1/1.5²). The existing test_kernel only exercises shears/div at the
minimal [3]*dim shape, so this regime is untested. I have not diagnosed
this properly and it is unrelated to the two bugs fixed here — flagging it only
so it is not lost. (Instantiating the kernel_lame'+'/'-' templates also
crashed cppyy in my environment, which may or may not be related.)

---

Found while porting jitfields to https://github.com/fastfields. I have opened a
companion issue listing the other jitfields-inherited defects turned up by that
port. Left unmerged for your review, as requested.

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code

[balbasty]

Two independent bugs in the *_kernel_add / *_kernel_sub wrappers, found
while porting these kernels to fastfields.
Both are verified against the current main (dc74377); a regression test that
fails before and passes after is included.

1. field_kernel_add/_ dispatch to impl.flow_kernel

field_kernel_add and field_kernel_add_ call impl.flow_kernel instead of
impl.field_kernel. This is a hard failure, not a silent one: the backend
signature is

flow_kernel(out, bound, voxel_size, absolute, membrane, bending, shears, div, op='')

— 8 required positional parameters — and the call site passes 7, so all four
public entry points raise immediately:

>>> field_kernel_add(2, inp, 0.3, 1.0, 0.2, voxel_size=[1.5, 1.0])
TypeError: flow_kernel() missing 1 required positional argument: 'div'

bindings/cuda's flow_kernel declares the identical 8-positional signature,
so the CUDA path fails the same way (unverified at runtime — no GPU here). The
stale See `flow_kernel` docstrings on the two _add variants (every
sibling says See `field_kernel` ) are corrected too — they look like the
origin of the slip.

Worth noting for the test: field_kernel and flow_kernel produce
bit-identical channel-0 kernels under the default isotropic voxel size,
and only diverge once voxel_size is anisotropic. So even a version of this
call that had the right arity would still have gone unnoticed under a
default-argument test.

2. field_kernel_sub/_ and flow_kernel_sub/_ silently add

All four forward to their _add sibling without the trailing _sub=True flag,
so op is computed as 'add' and they add the kernel instead of subtracting
it. On current main (flow variants are reachable today; the field ones are
blocked by bug 1):

>>> torch.equal(flow_kernel_add(inp, ...), flow_kernel_sub(inp, ...))
True # should be False
>>> torch.allclose(flow_kernel_sub(zeros, ...), -flow_kernel(...))
False # returns +kernel

Every other _sub wrapper in these two modules — field_matvec_sub,
field_matvec_sub_, field_diag_sub, field_diag_sub_, and the four flow
equivalents — does pass True. These four are the only omissions.

Changes

• _regularisers_fields.py: impl.flow_kernel → impl.field_kernel in
  field_kernel_add and field_kernel_add_; fix their docstrings; forward
  True from field_kernel_sub / field_kernel_sub_.
• _regularisers_flows.py: forward True from flow_kernel_sub /
  flow_kernel_sub_.
• tests/test_reg_field.py, tests/test_reg_flow.py: new
  test_kernel_add_sub, asserting kernel_add(inp) == inp + kernel and
  kernel_sub(inp) == inp - kernel for the out-of-place and in-place variants.
  The voxel size is deliberately anisotropic ([1.5, 1., 2.5][:dim]) so
  that a field-vs-flow cross-wiring cannot hide behind the isotropic
  coincidence described above.

Verified locally (CPU backend, bindings/cpp):

# on main, the two new tests only
12 failed # field: TypeError above; flow: the `sub` assertion
# with this change, both reg modules
36 passed

One thing I did not touch

My first draft of the flow test also covered shears/div. I dropped it
because it runs into what looks like a separate, pre-existing problem:
flow_kernel with shears/div on a spatial shape larger than the minimal
one does not seem to produce a centred stencil. On current main:

>>> flow_kernel([5], shears=0.5, div=0.7, voxel_size=[1.5]) # shape (5,1,1)
[-1.7, -1.7, -1.7, -1.7, 3.4]

I would have expected a centred 3-tap stencil zero-padded to length 5, and the
voxel_size scaling also appears to be absent (2*shears + div == 1.7, with no
1/1.5²). The existing test_kernel only exercises shears/div at the
minimal [3]*dim shape, so this regime is untested. I have not diagnosed
this properly and it is unrelated to the two bugs fixed here — flagging it only
so it is not lost. (Instantiating the kernel_lame'+'/'-' templates also
crashed cppyy in my environment, which may or may not be related.)

---

Found while porting jitfields to https://github.com/fastfields. I have opened a
companion issue listing the other jitfields-inherited defects turned up by that
port. Left unmerged for your review, as requested.

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code

[balbasty]

Two independent bugs in the *_kernel_add / *_kernel_sub wrappers, found
while porting these kernels to fastfields.
Both are verified against the current main (dc74377); a regression test that
fails before and passes after is included.

1. field_kernel_add/_ dispatch to impl.flow_kernel

field_kernel_add and field_kernel_add_ call impl.flow_kernel instead of
impl.field_kernel. This is a hard failure, not a silent one: the backend
signature is

flow_kernel(out, bound, voxel_size, absolute, membrane, bending, shears, div, op='')

— 8 required positional parameters — and the call site passes 7, so all four
public entry points raise immediately:

>>> field_kernel_add(2, inp, 0.3, 1.0, 0.2, voxel_size=[1.5, 1.0])
TypeError: flow_kernel() missing 1 required positional argument: 'div'

bindings/cuda's flow_kernel declares the identical 8-positional signature,
so the CUDA path fails the same way (unverified at runtime — no GPU here). The
stale See `flow_kernel` docstrings on the two _add variants (every
sibling says See `field_kernel` ) are corrected too — they look like the
origin of the slip.

Worth noting for the test: field_kernel and flow_kernel produce
bit-identical channel-0 kernels under the default isotropic voxel size,
and only diverge once voxel_size is anisotropic. So even a version of this
call that had the right arity would still have gone unnoticed under a
default-argument test.

2. field_kernel_sub/_ and flow_kernel_sub/_ silently add

All four forward to their _add sibling without the trailing _sub=True flag,
so op is computed as 'add' and they add the kernel instead of subtracting
it. On current main (flow variants are reachable today; the field ones are
blocked by bug 1):

>>> torch.equal(flow_kernel_add(inp, ...), flow_kernel_sub(inp, ...))
True # should be False
>>> torch.allclose(flow_kernel_sub(zeros, ...), -flow_kernel(...))
False # returns +kernel

Every other _sub wrapper in these two modules — field_matvec_sub,
field_matvec_sub_, field_diag_sub, field_diag_sub_, and the four flow
equivalents — does pass True. These four are the only omissions.

Changes

• _regularisers_fields.py: impl.flow_kernel → impl.field_kernel in
  field_kernel_add and field_kernel_add_; fix their docstrings; forward
  True from field_kernel_sub / field_kernel_sub_.
• _regularisers_flows.py: forward True from flow_kernel_sub /
  flow_kernel_sub_.
• tests/test_reg_field.py, tests/test_reg_flow.py: new
  test_kernel_add_sub, asserting kernel_add(inp) == inp + kernel and
  kernel_sub(inp) == inp - kernel for the out-of-place and in-place variants.
  The voxel size is deliberately anisotropic ([1.5, 1., 2.5][:dim]) so
  that a field-vs-flow cross-wiring cannot hide behind the isotropic
  coincidence described above.

Verified locally (CPU backend, bindings/cpp):

# on main, the two new tests only
12 failed # field: TypeError above; flow: the `sub` assertion
# with this change, both reg modules
36 passed

One thing I did not touch

My first draft of the flow test also covered shears/div. I dropped it
because it runs into what looks like a separate, pre-existing problem:
flow_kernel with shears/div on a spatial shape larger than the minimal
one does not seem to produce a centred stencil. On current main:

>>> flow_kernel([5], shears=0.5, div=0.7, voxel_size=[1.5]) # shape (5,1,1)
[-1.7, -1.7, -1.7, -1.7, 3.4]

I would have expected a centred 3-tap stencil zero-padded to length 5, and the
voxel_size scaling also appears to be absent (2*shears + div == 1.7, with no
1/1.5²). The existing test_kernel only exercises shears/div at the
minimal [3]*dim shape, so this regime is untested. I have not diagnosed
this properly and it is unrelated to the two bugs fixed here — flagging it only
so it is not lost. (Instantiating the kernel_lame'+'/'-' templates also
crashed cppyy in my environment, which may or may not be related.)

---

Found while porting jitfields to https://github.com/fastfields. I have opened a
companion issue listing the other jitfields-inherited defects turned up by that
port. Left unmerged for your review, as requested.

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code

[balbasty]

Two independent bugs in the *_kernel_add / *_kernel_sub wrappers, found
while porting these kernels to fastfields.
Both are verified against the current main (dc74377); a regression test that
fails before and passes after is included.

1. field_kernel_add/_ dispatch to impl.flow_kernel

field_kernel_add and field_kernel_add_ call impl.flow_kernel instead of
impl.field_kernel. This is a hard failure, not a silent one: the backend
signature is

flow_kernel(out, bound, voxel_size, absolute, membrane, bending, shears, div, op='')

— 8 required positional parameters — and the call site passes 7, so all four
public entry points raise immediately:

>>> field_kernel_add(2, inp, 0.3, 1.0, 0.2, voxel_size=[1.5, 1.0])
TypeError: flow_kernel() missing 1 required positional argument: 'div'

bindings/cuda's flow_kernel declares the identical 8-positional signature,
so the CUDA path fails the same way (unverified at runtime — no GPU here). The
stale See `flow_kernel` docstrings on the two _add variants (every
sibling says See `field_kernel` ) are corrected too — they look like the
origin of the slip.

Worth noting for the test: field_kernel and flow_kernel produce
bit-identical channel-0 kernels under the default isotropic voxel size,
and only diverge once voxel_size is anisotropic. So even a version of this
call that had the right arity would still have gone unnoticed under a
default-argument test.

2. field_kernel_sub/_ and flow_kernel_sub/_ silently add

All four forward to their _add sibling without the trailing _sub=True flag,
so op is computed as 'add' and they add the kernel instead of subtracting
it. On current main (flow variants are reachable today; the field ones are
blocked by bug 1):

>>> torch.equal(flow_kernel_add(inp, ...), flow_kernel_sub(inp, ...))
True # should be False
>>> torch.allclose(flow_kernel_sub(zeros, ...), -flow_kernel(...))
False # returns +kernel

Every other _sub wrapper in these two modules — field_matvec_sub,
field_matvec_sub_, field_diag_sub, field_diag_sub_, and the four flow
equivalents — does pass True. These four are the only omissions.

Changes

• _regularisers_fields.py: impl.flow_kernel → impl.field_kernel in
  field_kernel_add and field_kernel_add_; fix their docstrings; forward
  True from field_kernel_sub / field_kernel_sub_.
• _regularisers_flows.py: forward True from flow_kernel_sub /
  flow_kernel_sub_.
• tests/test_reg_field.py, tests/test_reg_flow.py: new
  test_kernel_add_sub, asserting kernel_add(inp) == inp + kernel and
  kernel_sub(inp) == inp - kernel for the out-of-place and in-place variants.
  The voxel size is deliberately anisotropic ([1.5, 1., 2.5][:dim]) so
  that a field-vs-flow cross-wiring cannot hide behind the isotropic
  coincidence described above.

Verified locally (CPU backend, bindings/cpp):

# on main, the two new tests only
12 failed # field: TypeError above; flow: the `sub` assertion
# with this change, both reg modules
36 passed

One thing I did not touch

My first draft of the flow test also covered shears/div. I dropped it
because it runs into what looks like a separate, pre-existing problem:
flow_kernel with shears/div on a spatial shape larger than the minimal
one does not seem to produce a centred stencil. On current main:

>>> flow_kernel([5], shears=0.5, div=0.7, voxel_size=[1.5]) # shape (5,1,1)
[-1.7, -1.7, -1.7, -1.7, 3.4]

I would have expected a centred 3-tap stencil zero-padded to length 5, and the
voxel_size scaling also appears to be absent (2*shears + div == 1.7, with no
1/1.5²). The existing test_kernel only exercises shears/div at the
minimal [3]*dim shape, so this regime is untested. I have not diagnosed
this properly and it is unrelated to the two bugs fixed here — flagging it only
so it is not lost. (Instantiating the kernel_lame'+'/'-' templates also
crashed cppyy in my environment, which may or may not be related.)

---

Found while porting jitfields to https://github.com/fastfields. I have opened a
companion issue listing the other jitfields-inherited defects turned up by that
port. Left unmerged for your review, as requested.

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code

[balbasty]

Two independent bugs in the *_kernel_add / *_kernel_sub wrappers, found
while porting these kernels to fastfields.
Both are verified against the current main (dc74377); a regression test that
fails before and passes after is included.

1. field_kernel_add/_ dispatch to impl.flow_kernel

field_kernel_add and field_kernel_add_ call impl.flow_kernel instead of
impl.field_kernel. This is a hard failure, not a silent one: the backend
signature is

flow_kernel(out, bound, voxel_size, absolute, membrane, bending, shears, div, op='')

— 8 required positional parameters — and the call site passes 7, so all four
public entry points raise immediately:

>>> field_kernel_add(2, inp, 0.3, 1.0, 0.2, voxel_size=[1.5, 1.0])
TypeError: flow_kernel() missing 1 required positional argument: 'div'

bindings/cuda's flow_kernel declares the identical 8-positional signature,
so the CUDA path fails the same way (unverified at runtime — no GPU here). The
stale See `flow_kernel` docstrings on the two _add variants (every
sibling says See `field_kernel` ) are corrected too — they look like the
origin of the slip.

Worth noting for the test: field_kernel and flow_kernel produce
bit-identical channel-0 kernels under the default isotropic voxel size,
and only diverge once voxel_size is anisotropic. So even a version of this
call that had the right arity would still have gone unnoticed under a
default-argument test.

2. field_kernel_sub/_ and flow_kernel_sub/_ silently add

All four forward to their _add sibling without the trailing _sub=True flag,
so op is computed as 'add' and they add the kernel instead of subtracting
it. On current main (flow variants are reachable today; the field ones are
blocked by bug 1):

>>> torch.equal(flow_kernel_add(inp, ...), flow_kernel_sub(inp, ...))
True # should be False
>>> torch.allclose(flow_kernel_sub(zeros, ...), -flow_kernel(...))
False # returns +kernel

Every other _sub wrapper in these two modules — field_matvec_sub,
field_matvec_sub_, field_diag_sub, field_diag_sub_, and the four flow
equivalents — does pass True. These four are the only omissions.

Changes

• _regularisers_fields.py: impl.flow_kernel → impl.field_kernel in
  field_kernel_add and field_kernel_add_; fix their docstrings; forward
  True from field_kernel_sub / field_kernel_sub_.
• _regularisers_flows.py: forward True from flow_kernel_sub /
  flow_kernel_sub_.
• tests/test_reg_field.py, tests/test_reg_flow.py: new
  test_kernel_add_sub, asserting kernel_add(inp) == inp + kernel and
  kernel_sub(inp) == inp - kernel for the out-of-place and in-place variants.
  The voxel size is deliberately anisotropic ([1.5, 1., 2.5][:dim]) so
  that a field-vs-flow cross-wiring cannot hide behind the isotropic
  coincidence described above.

Verified locally (CPU backend, bindings/cpp):

# on main, the two new tests only
12 failed # field: TypeError above; flow: the `sub` assertion
# with this change, both reg modules
36 passed

One thing I did not touch

My first draft of the flow test also covered shears/div. I dropped it
because it runs into what looks like a separate, pre-existing problem:
flow_kernel with shears/div on a spatial shape larger than the minimal
one does not seem to produce a centred stencil. On current main:

>>> flow_kernel([5], shears=0.5, div=0.7, voxel_size=[1.5]) # shape (5,1,1)
[-1.7, -1.7, -1.7, -1.7, 3.4]

I would have expected a centred 3-tap stencil zero-padded to length 5, and the
voxel_size scaling also appears to be absent (2*shears + div == 1.7, with no
1/1.5²). The existing test_kernel only exercises shears/div at the
minimal [3]*dim shape, so this regime is untested. I have not diagnosed
this properly and it is unrelated to the two bugs fixed here — flagging it only
so it is not lost. (Instantiating the kernel_lame'+'/'-' templates also
crashed cppyy in my environment, which may or may not be related.)

---

Found while porting jitfields to https://github.com/fastfields. I have opened a
companion issue listing the other jitfields-inherited defects turned up by that
port. Left unmerged for your review, as requested.

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code

[balbasty]

Two independent bugs in the *_kernel_add / *_kernel_sub wrappers, found
while porting these kernels to fastfields.
Both are verified against the current main (dc74377); a regression test that
fails before and passes after is included.

1. field_kernel_add/_ dispatch to impl.flow_kernel

field_kernel_add and field_kernel_add_ call impl.flow_kernel instead of
impl.field_kernel. This is a hard failure, not a silent one: the backend
signature is

flow_kernel(out, bound, voxel_size, absolute, membrane, bending, shears, div, op='')

— 8 required positional parameters — and the call site passes 7, so all four
public entry points raise immediately:

>>> field_kernel_add(2, inp, 0.3, 1.0, 0.2, voxel_size=[1.5, 1.0])
TypeError: flow_kernel() missing 1 required positional argument: 'div'

bindings/cuda's flow_kernel declares the identical 8-positional signature,
so the CUDA path fails the same way (unverified at runtime — no GPU here). The
stale See `flow_kernel` docstrings on the two _add variants (every
sibling says See `field_kernel` ) are corrected too — they look like the
origin of the slip.

Worth noting for the test: field_kernel and flow_kernel produce
bit-identical channel-0 kernels under the default isotropic voxel size,
and only diverge once voxel_size is anisotropic. So even a version of this
call that had the right arity would still have gone unnoticed under a
default-argument test.

2. field_kernel_sub/_ and flow_kernel_sub/_ silently add

All four forward to their _add sibling without the trailing _sub=True flag,
so op is computed as 'add' and they add the kernel instead of subtracting
it. On current main (flow variants are reachable today; the field ones are
blocked by bug 1):

>>> torch.equal(flow_kernel_add(inp, ...), flow_kernel_sub(inp, ...))
True # should be False
>>> torch.allclose(flow_kernel_sub(zeros, ...), -flow_kernel(...))
False # returns +kernel

Every other _sub wrapper in these two modules — field_matvec_sub,
field_matvec_sub_, field_diag_sub, field_diag_sub_, and the four flow
equivalents — does pass True. These four are the only omissions.

Changes

• _regularisers_fields.py: impl.flow_kernel → impl.field_kernel in
  field_kernel_add and field_kernel_add_; fix their docstrings; forward
  True from field_kernel_sub / field_kernel_sub_.
• _regularisers_flows.py: forward True from flow_kernel_sub /
  flow_kernel_sub_.
• tests/test_reg_field.py, tests/test_reg_flow.py: new
  test_kernel_add_sub, asserting kernel_add(inp) == inp + kernel and
  kernel_sub(inp) == inp - kernel for the out-of-place and in-place variants.
  The voxel size is deliberately anisotropic ([1.5, 1., 2.5][:dim]) so
  that a field-vs-flow cross-wiring cannot hide behind the isotropic
  coincidence described above.

Verified locally (CPU backend, bindings/cpp):

# on main, the two new tests only
12 failed # field: TypeError above; flow: the `sub` assertion
# with this change, both reg modules
36 passed

One thing I did not touch

My first draft of the flow test also covered shears/div. I dropped it
because it runs into what looks like a separate, pre-existing problem:
flow_kernel with shears/div on a spatial shape larger than the minimal
one does not seem to produce a centred stencil. On current main:

>>> flow_kernel([5], shears=0.5, div=0.7, voxel_size=[1.5]) # shape (5,1,1)
[-1.7, -1.7, -1.7, -1.7, 3.4]

I would have expected a centred 3-tap stencil zero-padded to length 5, and the
voxel_size scaling also appears to be absent (2*shears + div == 1.7, with no
1/1.5²). The existing test_kernel only exercises shears/div at the
minimal [3]*dim shape, so this regime is untested. I have not diagnosed
this properly and it is unrelated to the two bugs fixed here — flagging it only
so it is not lost. (Instantiating the kernel_lame'+'/'-' templates also
crashed cppyy in my environment, which may or may not be related.)

---

Found while porting jitfields to https://github.com/fastfields. I have opened a
companion issue listing the other jitfields-inherited defects turned up by that
port. Left unmerged for your review, as requested.

Workstream: claude-jitfields-to-fastfields

---

Generated by Claude Code