Declare kernel outputs for PyccelKernels

[max-models]

Stack: part 13 of 14, based on #725 (merge that first), next: #722. Full order: #709 → #708 → #711 → #712 → #705 → #713 → #714 → #718 → #720 → #721 → #724 → #725 → #723 → #722.

Stack fixes: added OUTPUTS to the 16 FEEC assembly folders of #725, using the same arguments as the former PyccelKernel(..., outputs=...) wraps in mass.py/boundary_mass.py/basis_projection_ops.py, plus kernel_*d_vec and surface_kernel_3d_vec. Also added OUTPUTS for eval_spline_mpi_tensor_product_fixed (#724). The indices of eval_spline_mpi_{markers,matrix,sparse_meshgrid} were moved to the SplineArguments signatures of #721 (3, 5, 5). argument_arrays now knows CudaSplineArguments. The test_cuda_emulation.py merge keeps the tests added below (test_emulated_v1_symm_filler). Local re-run on the stacked branch: test_cuda_parity.py, test_kernel_backends.py, test_evaluation_cuda.py (59 passed, 336 skipped), test_cuda_emulation.py (74 passed).

---

Solves the following issue(s):

Solves #342, part of the CUDA work tracked in #650. Struphy's PyccelKernels now declare which arguments they write to (outputs=), which cunumpy 0.6.1 already supports (PyccelKernel(..., outputs=...), Kernel.from_folder(..., host_options={"outputs": ...}), and assert_kernels_agree uses kernel.host_kernel.outputs by default). Before this PR, no struphy kernel declared outputs. Without a declaration, the CuPy fallback copies every converted array back to the device after each call, and the parity tests compare every array.

Core changes:

• Kernel folders (all 90): each <package>/kernels/<name>/__init__.py declares

  # the arguments the kernel writes to, by position: args_markers
  OUTPUTS = (2,)
  
  push_eta_stage = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

  The declarations come from a static analysis of the pyccel sources, which follows writes through aliases (markers = args_markers.markers) and through called kernel helpers. I reviewed the results by hand. The breakdown:

  • 41 pushers write only args_markers (only its markers field).
  • The accumulation kernels write their mat*/vec* arrays.
  • The diagnostics write markers or res.
  • Evaluation, geometry, SPH and local-projector kernels write their out/values/mat_f/f_eval* argument.

  The scratch arrays bn1 … bd3 of DerhamArguments are written by some kernels but are not outputs. They are not in the CUDA struct either.

• Other PyccelKernel(...) wraps pass outputs= too:

  • WeightedMassOperator assembly (kernel_{1,2,3}d_mat, -1), eval_quad (kernel_*d_eval, -1), the matrix-free dot (kernel_3d_matrixfree, -2, which writes out._data; the last argument is v._data) and diagonal (kernel_3d_diag, -1), in feec/mass.py
  • BoundaryMassOperator (surface_kernel_3d_mat, -1), in feec/boundary_mass.py
  • BasisProjectionOperator (assemble_dofs_for_weighted_basisfuns_*d, 0), in feec/basis_projection_ops.py

  Negative indices keep one declaration valid for every dimension. The test-only wraps in test_mat_vec_filler.py and test_kernel_setup.py are unchanged.

• Parity tests use the declarations:

  • test_cuda_parity.py: KernelCatalog.from_package builds its own Kernels and does not see the folders' OUTPUTS. The test therefore takes the kernels from the folder modules (DECLARED), and the GPU test_parity (assert_kernels_agree) now compares only the declared outputs. A side effect, found by reading the code but not run on a GPU: before, assert_kernels_agree also collected the host DerhamArguments scratch arrays (argument i.bn1, …). The CUDA struct has no such fields, so the host and CUDA key sets could not match for kernels taking args_derham.
  • New test_kernels_declare_outputs (no GPU needed): every kernel folder declares non-empty, in-range OUTPUTS.
  • New test_declared_outputs (NumPy backend, every parity case): the pyccel kernel changes at least one declared output and no other argument array. Argument objects are compared through their CUDA struct fields, so scratch is ignored. The helper argument_arrays lives in cuda_parity_cases.py.
  • test_cuda_emulation.test_emulated_parity now compares only the outputs with the pyccel kernel, and also asserts that the emulated CUDA kernel leaves every non-output array unchanged. I checked both new checks by mutation: declaring push_eta_stage with OUTPUTS = (4,) makes both tests fail.

• CUDA_STRATEGY.md: short note on OUTPUTS.

Model-specific changes:

None. Behaviour on the NumPy backend is unchanged, because PyccelKernel uses outputs only when it converts CuPy arrays.

Documentation changes:

A short note in CUDA_STRATEGY.md.

Local tests run (macOS, no GPU; GitHub CI covers the rest):

• pic/tests/test_cuda_parity.py: 18 passed, 213 skipped (the GPU tests)
• pic/tests/test_cuda_emulation.py -k emulated_parity: all 15 kernels passed. This ran as two invocations: the first hit my 5-minute limit after 13 kernels, and the remaining two (kernel_pullpush_pic, kernel_pullpush) passed separately in 80 s.
• pic/tests/test_kernel_backends.py and test_kernel_setup.py: 89 passed, 22 skipped
• feec/tests/test_boundary_integrals.py and test_mass_reassembly.py: 25 passed

GPU tests were not run. On the GPU, test_parity now compares only the declared outputs. The outputs= of the FEEC mass/projection wraps only take effect on the CuPy fallback path. No local test exercises them, neither on a GPU nor with the fake CuPy.

🤖 Generated with Claude Code