Declare kernel outputs for PyccelKernels

CUDA_STRATEGY.md

@@ -631,6 +631,16 @@ Fail fast: on CuPy, if a listed kernel has no CUDA version, `compile_cuda_kernel
 that pushes with `push_bxu_Hdiv`). On NumPy it does nothing. A test runs a model for one step on NumPy and checks that every
 `Kernel` called in the time loop is listed.
 
+**Declared kernel outputs (#342).** Each kernel folder's `__init__.py` declares the arguments its kernel writes
+to, by position, as `OUTPUTS` and passes them to cunumpy (`Kernel.from_folder(..., host_options={"outputs":
+OUTPUTS})`), the 16 FEEC assembly kernel folders of #411 (`feec/kernels/kernel_*`, `surface_kernel_3d_*`,
+`assemble_dofs_for_weighted_basisfuns_*d`) included. Scratch arrays inside argument objects (`DerhamArguments.bn1`,
+...) are not outputs. On the CuPy fallback only the outputs are copied back to the device; the GPU parity test
+(`assert_kernels_agree`) compares only the outputs; `test_declared_outputs` checks on the NumPy backend that a kernel
+changes its outputs and no other argument, and the CPU emulation test checks the same for the CUDA kernel.
+`KernelCatalog.from_package` does not see the folders' `OUTPUTS`, so `test_cuda_parity` takes the kernels from the
+folders (`DECLARED`). A new kernel folder declares `OUTPUTS` (`test_kernels_declare_outputs`).
+
 ## PR 18 implementation notes
 
 Geometry evaluation runs on the GPU for every analytic mapping (`kind_map` 10–12, 20–22, 30–32).

src/struphy/bsplines/kernels/eval_spline_mpi_markers/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-eval_spline_mpi_markers = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: values
+OUTPUTS = (3,)
+
+eval_spline_mpi_markers = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/bsplines/kernels/eval_spline_mpi_matrix/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-eval_spline_mpi_matrix = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: values
+OUTPUTS = (5,)
+
+eval_spline_mpi_matrix = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/bsplines/kernels/eval_spline_mpi_sparse_meshgrid/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-eval_spline_mpi_sparse_meshgrid = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: values
+OUTPUTS = (5,)
+
+eval_spline_mpi_sparse_meshgrid = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/bsplines/kernels/eval_spline_mpi_tensor_product_fixed/__init__.py

@@ -4,4 +4,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-eval_spline_mpi_tensor_product_fixed = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: values
+OUTPUTS = (10,)
+
+eval_spline_mpi_tensor_product_fixed = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/assemble_dofs_for_weighted_basisfuns_1d/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-assemble_dofs_for_weighted_basisfuns_1d = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: mat
+OUTPUTS = (0,)
+
+assemble_dofs_for_weighted_basisfuns_1d = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/assemble_dofs_for_weighted_basisfuns_2d/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-assemble_dofs_for_weighted_basisfuns_2d = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: mat
+OUTPUTS = (0,)
+
+assemble_dofs_for_weighted_basisfuns_2d = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/assemble_dofs_for_weighted_basisfuns_3d/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-assemble_dofs_for_weighted_basisfuns_3d = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: mat
+OUTPUTS = (0,)
+
+assemble_dofs_for_weighted_basisfuns_3d = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/hybrid_weight/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-hybrid_weight = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: data1, data2, data3
+OUTPUTS = (15, 16, 17)
+
+hybrid_weight = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/feec/kernels/kernel_1d_eval/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_1d_eval = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: values
+OUTPUTS = (6,)
+
+kernel_1d_eval = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_1d_mat/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_1d_mat = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (9,)
+
+kernel_1d_mat = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_1d_vec/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_1d_vec = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (7,)
+
+kernel_1d_vec = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_2d_eval/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_2d_eval = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: values
+OUTPUTS = (11,)
+
+kernel_2d_eval = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_2d_mat/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_2d_mat = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (17,)
+
+kernel_2d_mat = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_2d_vec/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_2d_vec = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (13,)
+
+kernel_2d_vec = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_3d_diag/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_3d_diag = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (19,)
+
+kernel_3d_diag = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_3d_eval/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_3d_eval = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: values
+OUTPUTS = (16,)
+
+kernel_3d_eval = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_3d_mat/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_3d_mat = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (25,)
+
+kernel_3d_mat = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_3d_matrixfree/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_3d_matrixfree = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data_out
+OUTPUTS = (34,)
+
+kernel_3d_matrixfree = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/kernel_3d_vec/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_3d_vec = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (19,)
+
+kernel_3d_vec = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/surface_kernel_3d_mat/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-surface_kernel_3d_mat = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (23,)
+
+surface_kernel_3d_mat = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/kernels/surface_kernel_3d_vec/__init__.py

@@ -8,4 +8,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-surface_kernel_3d_vec = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, missing_cuda="fallback")
+# the arguments the kernel writes to, by position: data
+OUTPUTS = (17,)
+
+surface_kernel_3d_vec = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, missing_cuda="fallback", host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/local_projectors/kernels/get_dofs_local_1_form_ec_component/__init__.py

@@ -4,4 +4,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-get_dofs_local_1_form_ec_component = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: f_eval_aux
+OUTPUTS = (2,)
+
+get_dofs_local_1_form_ec_component = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/local_projectors/kernels/get_dofs_local_1_form_ec_component_weighted/__init__.py

@@ -4,4 +4,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-get_dofs_local_1_form_ec_component_weighted = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: f_eval_aux
+OUTPUTS = (6,)
+
+get_dofs_local_1_form_ec_component_weighted = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/local_projectors/kernels/get_dofs_local_2_form_ec_component/__init__.py

@@ -4,4 +4,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-get_dofs_local_2_form_ec_component = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: f_eval_aux
+OUTPUTS = (2,)
+
+get_dofs_local_2_form_ec_component = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/local_projectors/kernels/get_dofs_local_2_form_ec_component_weighted/__init__.py

@@ -4,4 +4,9 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-get_dofs_local_2_form_ec_component_weighted = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: f_eval_aux
+OUTPUTS = (7,)
+
+get_dofs_local_2_form_ec_component_weighted = Kernel.from_folder(
+    __name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS}
+)

src/struphy/feec/local_projectors/kernels/get_dofs_local_3_form/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-get_dofs_local_3_form = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: f_eval
+OUTPUTS = (2,)
+
+get_dofs_local_3_form = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/feec/local_projectors/kernels/get_dofs_local_3_form_weighted/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-get_dofs_local_3_form_weighted = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: f_eval
+OUTPUTS = (8,)
+
+get_dofs_local_3_form_weighted = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/feec/local_projectors/kernels/solve_local_main_loop/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-solve_local_main_loop = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: out
+OUTPUTS = (2,)
+
+solve_local_main_loop = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/feec/local_projectors/kernels/solve_local_main_loop_weighted/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-solve_local_main_loop_weighted = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: out
+OUTPUTS = (8,)
+
+solve_local_main_loop_weighted = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/geometry/kernels/kernel_evaluate/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_evaluate = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: mat_f
+OUTPUTS = (5,)
+
+kernel_evaluate = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/geometry/kernels/kernel_evaluate_pic/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_evaluate_pic = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: mat_f
+OUTPUTS = (3,)
+
+kernel_evaluate_pic = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/geometry/kernels/kernel_pullpush/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_pullpush = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: out
+OUTPUTS = (8,)
+
+kernel_pullpush = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/geometry/kernels/kernel_pullpush_pic/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-kernel_pullpush_pic = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: out
+OUTPUTS = (5,)
+
+kernel_pullpush_pic = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/pic/accumulation/kernels/cc_lin_mhd_5d_D/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-cc_lin_mhd_5d_D = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: mat12, mat13, mat23
+OUTPUTS = (3, 4, 5)
+
+cc_lin_mhd_5d_D = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/pic/accumulation/kernels/cc_lin_mhd_5d_M/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-cc_lin_mhd_5d_M = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: vec1, vec2, vec3
+OUTPUTS = (9, 10, 11)
+
+cc_lin_mhd_5d_M = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/pic/accumulation/kernels/cc_lin_mhd_5d_curlb/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-cc_lin_mhd_5d_curlb = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: mat11 to vec3
+OUTPUTS = tuple(range(3, 12))
+
+cc_lin_mhd_5d_curlb = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})

src/struphy/pic/accumulation/kernels/cc_lin_mhd_5d_gradB/__init__.py

@@ -4,4 +4,7 @@
 
 from struphy.utils.cuda_arguments import CUDA_STRUCTS
 
-cc_lin_mhd_5d_gradB = Kernel.from_folder(__name__, structs=CUDA_STRUCTS)
+# the arguments the kernel writes to, by position: vec1, vec2, vec3
+OUTPUTS = (9, 10, 11)
+
+cc_lin_mhd_5d_gradB = Kernel.from_folder(__name__, structs=CUDA_STRUCTS, host_options={"outputs": OUTPUTS})