cunumpy 0.6.1__tar.gz → 0.6.2__tar.gz

{cunumpy-0.6.1 → cunumpy-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cunumpy
-Version: 0.6.1
+Version: 0.6.2
 Summary: Simple wrapper for numpy and cupy. Replace `import numpy as np` with `import cunumpy as xp`.
 Author: Max
 Project-URL: Source, https://github.com/max-models/cunumpy
@@ -30,6 +30,8 @@ Requires-Dist: pre-commit; extra == "docs"
 Requires-Dist: pyproject-fmt; extra == "docs"
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: sphinx-book-theme; extra == "docs"
+Provides-Extra: metal
+Requires-Dist: mlx; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "metal"
 Provides-Extra: test
 Requires-Dist: coverage; extra == "test"
 Requires-Dist: pytest; extra == "test"
@@ -64,7 +66,7 @@ never hide a NumPy name:
 
 | Submodule | Contents |
 |---|---|
-| `xp.kernels` | `Kernel`, `KernelCatalog`, `PyccelKernel`, `CudaKernel`, host implementations, `fuse` |
+| `xp.kernels` | `Kernel`, `KernelCatalog`, `PyccelKernel`, `CudaKernel`, `MetalKernel`, host implementations, `fuse` |
 | `xp.arguments` | CUDA only: `CudaStruct`, `CudaStructArguments`, `CudaArguments` |
 | `xp.cuda` | CUDA only: devices, streams, debug mode, CUDA headers |
 | `xp.rng` | `random_streams`, `get_rng`, `philox_*` |
@@ -76,6 +78,8 @@ never hide a NumPy name:
 | `cunumpy.kernel_testing` | pytest helpers for host/CUDA kernel pairs |
 
 Everything except `xp.cuda`, `xp.arguments` and `CudaKernel` works on both backends.
+`MetalKernel` runs Metal kernels on the GPU of an Apple silicon Mac (MLX, float32, NumPy arrays;
+`pip install 'cunumpy[metal]'`, see [the guide](docs/source/kernels/metal-kernel.md)).
 
 ## Install
 

{cunumpy-0.6.1 → cunumpy-0.6.2}/README.md

@@ -24,7 +24,7 @@ never hide a NumPy name:
 
 | Submodule | Contents |
 |---|---|
-| `xp.kernels` | `Kernel`, `KernelCatalog`, `PyccelKernel`, `CudaKernel`, host implementations, `fuse` |
+| `xp.kernels` | `Kernel`, `KernelCatalog`, `PyccelKernel`, `CudaKernel`, `MetalKernel`, host implementations, `fuse` |
 | `xp.arguments` | CUDA only: `CudaStruct`, `CudaStructArguments`, `CudaArguments` |
 | `xp.cuda` | CUDA only: devices, streams, debug mode, CUDA headers |
 | `xp.rng` | `random_streams`, `get_rng`, `philox_*` |
@@ -36,6 +36,8 @@ never hide a NumPy name:
 | `cunumpy.kernel_testing` | pytest helpers for host/CUDA kernel pairs |
 
 Everything except `xp.cuda`, `xp.arguments` and `CudaKernel` works on both backends.
+`MetalKernel` runs Metal kernels on the GPU of an Apple silicon Mac (MLX, float32, NumPy arrays;
+`pip install 'cunumpy[metal]'`, see [the guide](docs/source/kernels/metal-kernel.md)).
 
 ## Install
 

{cunumpy-0.6.1 → cunumpy-0.6.2}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [ "setuptools", "wheel" ]
 
 [project]
 name = "cunumpy"
-version = "0.6.1"
+version = "0.6.2"
 description = "Simple wrapper for numpy and cupy. Replace `import numpy as np` with `import cunumpy as xp`."
 readme = "README.md"
 keywords = [ "python" ]
@@ -43,6 +43,7 @@ optional-dependencies.docs = [
   "sphinx",
   "sphinx-book-theme",
 ]
+optional-dependencies.metal = [ "mlx; sys_platform == 'darwin' and platform_machine == 'arm64'" ]
 optional-dependencies.test = [ "coverage", "pytest", "scipy" ]
 optional-dependencies.test-compiled = [ "cunumpy[test]", "pyccel" ]
 urls."Source" = "https://github.com/max-models/cunumpy"

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/LLM_GUIDE.md

@@ -72,6 +72,11 @@ https://max-models.github.io/cunumpy/ and in `docs/source/` of the repository.
 | hand data to SciPy/matplotlib/h5py | `xp.to_numpy(a)` |
 | call an existing NumPy-only kernel with GPU arrays (slow, correct) | `xp.kernels.PyccelKernel(fn, outputs=(...))` |
 | launch a hand-written CUDA C kernel | `xp.kernels.CudaKernel(source, "name")` / `CudaKernel.from_file(path)` |
+| run a Metal (MSL) kernel on an Apple silicon GPU, NumPy float32 in and out (float64 raises; `float64="cast"` computes in float32); not part of `Kernel` dispatch | `xp.kernels.MetalKernel(body, inputs=[...], outputs=[...])(*args, out=arrays, n_threads=n)`; check `xp.kernels.metal_available()` |
+| call host-only code (SciPy, file readers) with arguments of either backend | `xp.host_call(fun, *args)`; `@xp.evaluate_on_host` on a method; `@xp.setup_on_host` on `__init__` |
+| keep the live rows of particle arrays at the front | `n = xp.algorithms.compact_by_mask(alive, markers, weights)` |
+| run CUDA kernel launches on the CPU in a test (fake CuPy) | `with kernel_testing.emulated_launches(): ...`; `kernel_testing.host_buffer(a)` reads a fake array; struct arguments are read through their fields |
+| find the arguments a host kernel writes (copy only those back) | `PyccelKernel(fn, outputs=("out",))` (names work positionally); `xp.kernels.outputs_from_annotations(fn)`; `Kernel.from_folder(..., outputs="annotations")` |
 | host kernel + CUDA port, chosen by backend | `xp.kernels.Kernel(host_fn, cuda_kernel_or_None)` |
 | many kernels in a package, ported incrementally | `xp.kernels.KernelCatalog.from_package(__name__, missing_cuda="fallback")` |
 | host kernels compiled at first call (your compile function), NumPy fallback | `from_package(..., host_suffix="_pyccel", compile_host=my_compile, host_fallback={...})` -> `xp.kernels.CompiledHostKernel` |

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/__init__.py

@@ -14,6 +14,7 @@ from cunumpy import (
     rng,
     xp,
 )
+from cunumpy._host import evaluate_on_host, host_call, setup_on_host
 from cunumpy._scipy_backend import scipy
 from cunumpy.xp import (
     as_device_array,
@@ -79,9 +80,11 @@ __all__ = [
     "cupy_available",
     "cupy_backend",
     "default_float_dtype",
+    "evaluate_on_host",
     "get_array_backend",
     "get_array_module",
     "get_backend",
+    "host_call",
     "is_cpu",
     "is_gpu",
     "kernels",
@@ -95,6 +98,7 @@ __all__ = [
     "same_backend",
     "scipy",
     "set_backend",
+    "setup_on_host",
     "synchronize",
     "to_cunumpy",
     "to_cupy",

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/__init__.pyi

@@ -1,7 +1,7 @@
 # Stub file for Pylance/mypy: exposes all numpy symbols so that
 # `import cunumpy as xp` followed by `xp.<Tab>` shows numpy completions.
 # At runtime the real __init__.py dispatches to numpy or cupy via __getattr__.
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from contextlib import contextmanager
 from typing import Any
 
@@ -38,6 +38,9 @@ def set_backend(backend: str, *, strict: bool = ...) -> None: ...
 def require_version(minimum: str) -> None: ...
 def default_float_dtype() -> Any: ...
 def synchronize() -> None: ...
+def host_call(fun: Callable[..., Any], *args: Any, **kwargs: Any) -> Any: ...
+def evaluate_on_host(method: Callable[..., Any]) -> Callable[..., Any]: ...
+def setup_on_host(init: Callable[..., None]) -> Callable[..., None]: ...
 def as_device_array(
     value: Any, dtype: Any = ..., ndim: int | None = ..., *, name: str | None = ...
 ) -> Any: ...

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/_algorithms.py

@@ -251,3 +251,49 @@ def sort_by_key(keys: Any, *arrays: Any) -> tuple[Any, ...]:
             )
     order = xpm.argsort(keys, kind="stable").astype(xpm.int64, copy=False)
     return (keys[order], order, *(array[order] for array in arrays))
+
+
+def compact_by_mask(mask: Any, *arrays: Any) -> int:
+    """Move the rows where `mask` is True to the front of every array, in place.
+
+    The usual step after particles left the domain or were absorbed: keep the
+    live ones at the front of the marker array (and of the arrays that go with
+    it) and continue with ``markers[:n]``. The order of the kept rows is
+    preserved, so the result is reproducible::
+
+        n = xp.algorithms.compact_by_mask(alive, markers, weights)
+        markers, weights = markers[:n], weights[:n]
+
+    Parameters
+    ----------
+    mask : array of bool, shape (n,)
+        True for the rows to keep.
+    *arrays : arrays
+        Arrays with ``n`` rows (any further axes), on the backend of `mask`.
+        Rows ``[:count]`` hold the kept rows afterwards; the rows after them
+        are unspecified, so ignore them (or overwrite them).
+
+    Returns
+    -------
+    int
+        The number of kept rows. Its value is needed on the host, so on CuPy
+        the call synchronizes once per call (counted by
+        :func:`~cunumpy.profiling.count_transfers` where it can be seen).
+    """
+    assert_same_backend(mask, *arrays)
+    xpm = get_array_module(mask)
+    mask = xpm.asarray(mask)
+    if mask.ndim != 1 or mask.dtype != np.bool_:
+        raise TypeError(
+            f"mask must be a 1D boolean array, got dtype {mask.dtype}, {mask.ndim}D",
+        )
+    for i, array in enumerate(arrays):
+        if array.ndim < 1 or array.shape[0] != mask.shape[0]:
+            raise ValueError(
+                f"array {i} has shape {array.shape}, expected {mask.shape[0]} rows",
+            )
+    rows = xpm.nonzero(mask)[0]
+    n_kept = int(rows.size)
+    for array in arrays:
+        array[:n_kept] = array[rows]  # the right side is a copy: no overlap problem
+    return n_kept

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/_cuda_kernel.py

@@ -66,6 +66,9 @@ from typing import Any, NamedTuple
 
 import numpy as np
 
+from cunumpy._transfers import _ACTIVE as _COUNTERS
+from cunumpy._transfers import _record_sync
+
 __all__ = [
     "DEBUG_OPTIONS",
     "CudaArguments",
@@ -2421,6 +2424,10 @@ class CudaKernel:
         if shared_mem < 0:
             raise ValueError(f"shared_mem must be non-negative, got {shared_mem}")
         values = self.prepare_args(*args)
+        # RawKernel accepts size-one NumPy arrays for structs passed by value,
+        # but not structured NumPy scalars (np.void). Keep their packed bytes
+        # and alignment intact, including array-view pointers and strides.
+        values = tuple(np.asarray(v) if isinstance(v, np.void) else v for v in values)
         if 0 in grid_shape:
             return
 
@@ -2528,6 +2535,8 @@ class CudaKernel:
             stream = cp.cuda.get_current_stream()
         if _is_capturing(stream):
             return
+        if _COUNTERS:
+            _record_sync(f"debug synchronization after kernel {self.expression!r}")
         try:
             stream.synchronize()
         except Exception as error:

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/_dispatch.py

@@ -40,6 +40,7 @@ from cunumpy._kernel import (
     HostImplementations,
     PyccelKernel,
     get_device_kernel_implementation,
+    outputs_from_annotations,
 )
 from cunumpy._transfers import _ACTIVE as _COUNTERS
 from cunumpy._transfers import _record
@@ -219,6 +220,10 @@ class Kernel:
                 "host_options are for wrapping a plain callable; configure the "
                 "given PyccelKernel directly",
             )
+        if host_kernel._parameters is None:
+            # compiled kernels have no Python signature: name the parameters
+            # from the host function, so that outputs may be given by name
+            host_kernel._parameters = self.host_parameters
         self._host_kernel = host_kernel
         self._cuda_kernel = cuda_kernel
         self._name = name if name is not None else host_kernel.name
@@ -239,6 +244,7 @@ class Kernel:
         check_name_length: bool = True,
         missing_cuda: str = "raise",
         host_options: Mapping[str, Any] | None = None,
+        outputs: Sequence[int | str] | str | None = None,
         include_dirs: Sequence[str | Path] | None = None,
         dispatch: str = "backend",
         compile_host: Callable[[Any], Any] | None = None,
@@ -285,6 +291,14 @@ class Kernel:
             As for :meth:`KernelCatalog.from_package`.
         missing_cuda, host_options, dispatch
             Passed on to :class:`Kernel`.
+        outputs : Sequence[int | str] | "annotations" | None
+            The arguments the host kernel writes to (names or indices, see
+            :class:`~cunumpy.kernels.PyccelKernel`), so that only those arrays are
+            copied back to the device on the fallback path. ``"annotations"``
+            reads them from the annotations of the host function: every
+            parameter that is not ``Final`` or a scalar is an output (see
+            :func:`~cunumpy.kernels.outputs_from_annotations`). A value in
+            `host_options` takes precedence.
         include_dirs : Sequence[str | Path] | None
             Include directories of the CUDA kernel, in addition to the folder
             itself; by default the source root of the top-level package (the
@@ -334,6 +348,19 @@ class Kernel:
             test_args = f"{package}.{name}{test_args_suffix}"
         module = importlib.import_module(f"{package}.{name}{host_suffix}")
         python = getattr(module, name)
+        if outputs is not None and "outputs" not in (host_options or {}):
+            declared = (
+                outputs_from_annotations(python)
+                if isinstance(outputs, str) and outputs == "annotations"
+                else outputs
+            )
+            if isinstance(outputs, str) and outputs != "annotations":
+                raise ValueError(
+                    f"outputs must be a sequence of names/indices or 'annotations', "
+                    f"got {outputs!r}",
+                )
+            if declared is not None:
+                host_options = {**(host_options or {}), "outputs": declared}
         loaders: dict[str, Callable[[], Callable[..., Any]]] = {
             "python": lambda: python,
             "pyccel": (
@@ -669,6 +696,12 @@ class KernelCatalog(Mapping):
         host_options: (
             Mapping[str, Any] | Callable[[str], Mapping[str, Any]] | None
         ) = None,
+        outputs: (
+            Sequence[int | str]
+            | str
+            | Callable[[str], Sequence[int | str] | str | None]
+            | None
+        ) = None,
         include_dirs: Sequence[str | Path] | None = None,
         dispatch: str = "backend",
         compile_host: Callable[[Any], Any] | None = None,
@@ -713,6 +746,10 @@ class KernelCatalog(Mapping):
             Keyword arguments for the :class:`~cunumpy.kernels.PyccelKernel` wrapping each
             host kernel (see :class:`Kernel`): the same for all kernels, or a
             function of the kernel name, e.g. to declare per-kernel ``outputs``.
+        outputs : Sequence[int | str] | "annotations" | Callable | None
+            The arguments every host kernel writes to, or ``"annotations"`` to
+            read them from the annotations of each host function, or a function
+            of the kernel name returning either (see :meth:`Kernel.from_folder`).
         include_dirs : Sequence[str | Path] | None
             Include directories of the CUDA kernels, in addition to each
             kernel's own folder. By default the source root of the top-level
@@ -757,6 +794,7 @@ class KernelCatalog(Mapping):
                 host_options=(
                     host_options(name) if callable(host_options) else host_options
                 ),
+                outputs=outputs(name) if callable(outputs) else outputs,
                 include_dirs=include_dirs,
                 dispatch=dispatch,
                 compile_host=compile_host,

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/_emulation.py

@@ -28,11 +28,22 @@ thread runs to its next barrier before any thread continues past it, as on a
 GPU. Per-block deposits, shared-memory reductions and tiled kernels therefore
 work.
 
+Struct parameters take, for each struct, a mapping from field name to value, a
+:class:`~cunumpy.arguments.CudaStructValue`, or any object with an attribute
+per field (e.g. a :class:`~cunumpy.arguments.CudaStructArguments` or a host
+argument class); the arrays of the fields are updated in place like the others.
+
+:func:`emulated_launches` makes every :class:`~cunumpy.kernels.CudaKernel` launch
+in a block run through the emulation, on the arrays of the fake CuPy
+(:mod:`cunumpy._fake_cupy`), so that code that launches kernels (a
+:class:`~cunumpy.kernels.Kernel` on the CuPy backend, a propagator) can be
+tested without a GPU.
+
 What it does not emulate: concurrency between the barriers (threads run one
 after another, so atomics are plain additions and races never show), warp
 intrinsics (``__shfl_*``, ``__syncwarp``, ``__ballot_sync``, ...; a kernel or an
-included header using them is refused), structs and ``CudaArguments`` objects
-(not supported), and ``<cupy/complex.cuh>``. Use a GPU for those.
+included header using them is refused), and ``<cupy/complex.cuh>``. Use a GPU
+for those.
 
 Floating point: like NVRTC (``--fmad=true`` by default) the C++ compiler may
 fuse ``a * b + c`` into one fused multiply-add, so results can differ from
@@ -49,21 +60,25 @@ import re
 import shutil
 import subprocess
 import tempfile
-from collections.abc import Sequence
+from collections.abc import Generator, Mapping, Sequence
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
 import numpy as np
 
+from cunumpy import _fake_cupy
 from cunumpy._cuda_kernel import (
     CudaKernel,
     CudaParameter,
+    CudaStructArguments,
+    CudaStructValue,
     _scalar_checker,
     _strip_comments,
     cuda_include_dir,
 )
 
-__all__ = ["emulate_cuda_kernel", "emulation_compiler"]
+__all__ = ["emulate_cuda_kernel", "emulated_launches", "emulation_compiler"]
 
 # CUDA constructs that serial emulation would get wrong
 _UNSUPPORTED = {
@@ -258,6 +273,76 @@ def _check_supported(kernel: CudaKernel) -> None:
             )
 
 
+def _host(value: Any) -> Any:
+    """The NumPy buffer of a fake CuPy array; anything else as it is."""
+    if _fake_cupy.is_active():
+        try:
+            return _fake_cupy.host_buffer(value)
+        except TypeError:
+            pass
+    return value
+
+
+def _field_value(struct_name: str, value: Any, field: CudaParameter) -> Any:
+    """The value of the struct field `field` in the struct argument `value`."""
+    try:
+        if isinstance(value, (CudaStructValue, Mapping)):
+            return value[field.name]
+        return getattr(value, field.name)
+    except (KeyError, AttributeError):
+        raise TypeError(
+            f"struct argument {struct_name!r} has no value for the field "
+            f"{field.name!r} ({type(value).__name__})",
+        ) from None
+
+
+def _declaration(param: CudaParameter, name: str) -> str:
+    if param.view_ndim is not None:
+        return f"{param.ctype} {name}"
+    return f"{param.ctype}{'*' if param.pointer else ''} {name}"
+
+
+def _flatten_structs(
+    kernel: CudaKernel,
+    args: Sequence[Any],
+) -> tuple[CudaKernel, list[Any]]:
+    """A kernel that takes every struct field as a parameter, and its arguments.
+
+    The wrapper kernel (the source of `kernel` plus a ``__global__`` function with
+    one parameter per field) rebuilds the structs and calls `kernel`, so that the
+    emulation only has to deal with arrays and scalars.
+    """
+    params, builds, call, flat = [], [], [], []
+    for p, value in zip(kernel.signature, args):
+        if p.struct is None:
+            params.append(_declaration(p, p.name))
+            call.append(p.name)
+            flat.append(value)
+            continue
+        names = [f"{p.name}__{f.name}" for f in p.struct.fields]
+        params += [_declaration(f, n) for f, n in zip(p.struct.fields, names)]
+        builds.append(f"    {p.struct.name} {p.name}_struct{{{', '.join(names)}}};")
+        call.append(f"{p.name}_struct")
+        flat += [_field_value(p.name, value, f) for f in p.struct.fields]
+    name = f"emulated_{kernel.name}"
+    source = (
+        kernel.source
+        + f'\nextern "C" __global__ void {name}({", ".join(params)}) {{\n'
+        + "\n".join(builds)
+        + f"\n    {kernel.expression}({', '.join(call)});\n}}\n"
+    )
+    wrapper = CudaKernel(
+        source,
+        name,
+        block_size=kernel.block_size,
+        options=[o for o in kernel.options if not o.startswith("-I")],
+        include_dirs=kernel.include_dirs,
+        source_dir=kernel.source_dir,
+        n_threads_from=kernel.n_threads_from,
+    )
+    return wrapper, flat
+
+
 def emulate_cuda_kernel(
     kernel: CudaKernel,
     *args: Any,
@@ -275,8 +360,11 @@ def emulate_cuda_kernel(
     kernel : CudaKernel
         The kernel; its signature must be parsed (the default).
     *args
-        The kernel arguments with NumPy arrays in place of CuPy arrays. Arrays
-        are updated in place with what the kernel wrote.
+        The kernel arguments with NumPy arrays in place of CuPy arrays (arrays of
+        the fake CuPy are used through their host buffer). Arrays are updated in
+        place with what the kernel wrote. A struct parameter takes a mapping of
+        field names to values, a :class:`~cunumpy.arguments.CudaStructValue`, or
+        an object with an attribute per field.
     n_threads, grid, block
         Launch shape, as for :meth:`CudaKernel.__call__`.
     compiler : str | None
@@ -291,8 +379,8 @@ def emulate_cuda_kernel(
     Raises
     ------
     NotImplementedError
-        If the kernel (or a header it includes) uses warp intrinsics, or the
-        kernel has struct parameters or complex scalars.
+        If the kernel (or a header it includes) uses warp intrinsics, or has
+        complex scalars.
     TypeError
         If an argument does not match its parameter (dtype, dimensions, a
         scalar that does not fit).
@@ -309,6 +397,19 @@ def emulate_cuda_kernel(
         raise TypeError(
             f"kernel {kernel.name!r} takes {len(params)} arguments, got {len(args)}",
         )
+    if any(p.struct is not None for p in params):
+        wrapper, flat = _flatten_structs(kernel, args)
+        return emulate_cuda_kernel(
+            wrapper,
+            *flat,
+            n_threads=n_threads,
+            grid=grid,
+            block=block,
+            compiler=compiler,
+            options=options,
+            shared_mem=shared_mem,
+        )
+    args = tuple(_host(a) for a in args)
     compiler = compiler or emulation_compiler()
     if compiler is None:
         raise RuntimeError("emulation needs a C++ compiler (set CXX or install c++)")
@@ -323,10 +424,6 @@ def emulate_cuda_kernel(
         globals_, inits, call_args, writes, arrays = [], [], [], [], []
         for i, (param, value) in enumerate(zip(params, args)):
             name = f"cunumpy_arg{i}"
-            if param.struct is not None:
-                raise NotImplementedError(
-                    "emulation does not support struct parameters",
-                )
             if param.pointer or param.view_ndim is not None:
                 if not isinstance(value, np.ndarray):
                     raise TypeError(
@@ -444,3 +541,74 @@ def emulate_cuda_kernel(
         for value, buffer, out in arrays:
             result = np.fromfile(out, dtype=buffer.dtype).reshape(buffer.shape)
             value[...] = result
+
+
+@contextmanager
+def emulated_launches(
+    *,
+    compiler: str | None = None,
+    options: Sequence[str] = (),
+) -> Generator[None, None, None]:
+    """Run every :class:`~cunumpy.kernels.CudaKernel` launch in the block on the CPU.
+
+    With the fake CuPy (:func:`cunumpy.kernel_testing.install_fake_cupy`)
+    CUDA kernels cannot run. Inside this block a launch is emulated instead
+    (:func:`emulate_cuda_kernel`), on the host buffers of the fake CuPy arrays
+    it is given, so code that launches kernels runs on a machine without a GPU
+    and its device arrays hold the results afterwards::
+
+        with emulated_launches():
+            propagator(dt)  # CuPy backend: the CUDA kernels run on the CPU
+
+    The launch arguments are those of :meth:`CudaKernel.__call__`
+    (`stream` is ignored). Argument objects are flattened like in a launch;
+    struct values and :class:`~cunumpy.arguments.CudaStructArguments` objects
+    stay one argument and are read through their fields. Arrays must be arrays
+    of the fake CuPy or NumPy arrays.
+
+    Launches are serial and slow (each one compiles the kernel as C++), so use it
+    on small problems. The limits of :func:`emulate_cuda_kernel` apply.
+
+    Parameters
+    ----------
+    compiler : str | None
+        C++ compiler; by default :func:`emulation_compiler`.
+    options : Sequence[str]
+        Additional compiler options for every launch, e.g.
+        ``("-ffp-contract=off",)``.
+    """
+    original = CudaKernel.__call__
+
+    def launch(
+        self: CudaKernel,
+        *args: Any,
+        n_threads: int | Sequence[int] | None = None,
+        grid: int | Sequence[int] | None = None,
+        block: int | Sequence[int] | None = None,
+        shared_mem: int = 0,
+        stream: Any = None,
+    ) -> None:
+        flat: list[Any] = []
+        for arg in args:
+            if isinstance(arg, (CudaStructValue, CudaStructArguments)):
+                flat.append(arg)
+            elif hasattr(arg, "__cuda_args__"):
+                flat.extend(arg.__cuda_args__())
+            else:
+                flat.append(arg)
+        emulate_cuda_kernel(
+            self,
+            *flat,
+            n_threads=n_threads,
+            grid=grid,
+            block=block,
+            compiler=compiler,
+            options=options,
+            shared_mem=shared_mem,
+        )
+
+    CudaKernel.__call__ = launch  # type: ignore[method-assign]
+    try:
+        yield
+    finally:
+        CudaKernel.__call__ = original  # type: ignore[method-assign]

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/_fake_cupy.py

@@ -17,7 +17,9 @@ matters for finding host/device bugs:
   :class:`~cunumpy.kernels.CudaKernel` work;
 * CUDA kernels cannot run: ``RawKernel`` and friends raise
   ``NotImplementedError`` when called, and :func:`cunumpy.kernel_testing.requires_cupy`
-  skips tests while the fake is active.
+  skips tests while the fake is active. Inside
+  :func:`cunumpy.kernel_testing.emulated_launches` a ``CudaKernel`` launch runs
+  on the CPU instead, on the host buffers of the arrays (:func:`host_buffer`).
 
 Activate it before CuPy or cunumpy's backend is first used, either with the
 environment variable ``CUNUMPY_FAKE_CUPY=1`` (read when cunumpy is imported)
@@ -35,7 +37,7 @@ import sys
 import types
 from pathlib import Path
 
-__all__ = ["install", "is_active", "uninstall"]
+__all__ = ["host_buffer", "install", "is_active", "uninstall"]
 
 _IMPLEMENTATION = Path(__file__).with_name("_fake_cupy_impl.py")
 _SUBMODULES = ("cupy.cuda", "cupy.cuda.device", "cupy.cuda.runtime", "cupy.linalg")
@@ -47,6 +49,28 @@ def is_active() -> bool:
     return bool(getattr(module, "__cunumpy_fake__", False))
 
 
+def host_buffer(array: object) -> object:
+    """The NumPy array that holds the data of a fake ``cupy.ndarray``.
+
+    Not a copy: writing to the buffer changes the fake device array, so a
+    kernel emulation (:func:`cunumpy.kernel_testing.emulated_launches`) can
+    update the array in place. A test can also read results with it without a
+    ``.get()``, which is the point of a "device" array being visible in tests.
+
+    Raises
+    ------
+    TypeError
+        If `array` is not an array of the fake CuPy (including when the fake
+        is not active).
+    """
+    module = sys.modules.get("cupy")
+    if is_active() and isinstance(array, module.ndarray):
+        return array._a
+    raise TypeError(
+        f"host_buffer needs an array of the fake CuPy, got {type(array).__name__}",
+    )
+
+
 def install() -> types.ModuleType:
     """Install the fake ``cupy`` package into ``sys.modules`` and return it.
 

{cunumpy-0.6.1 → cunumpy-0.6.2}/src/cunumpy/_fake_cupy_impl.py

@@ -15,6 +15,14 @@ __cunumpy_fake__ = True
 _HOST = _np.ndarray
 
 
+def _sync(what):
+    """Count a scalar read of a device array (an implicit sync of the real CuPy)."""
+    from cunumpy._transfers import _ACTIVE, _record_sync
+
+    if _ACTIVE:
+        _record_sync(what)
+
+
 def _err(obj, where=""):
     return TypeError(
         f"Unsupported type {type(obj)}{where} (fake CuPy: host arrays/lists are "
@@ -75,6 +83,8 @@ class ndarray:
         # no __array_interface__ etc.: NumPy must not see the host buffer
         if name.startswith("__"):
             raise AttributeError(name)
+        if name in ("item", "tolist"):
+            _sync(f"ndarray.{name}()")
         attr = getattr(self._a, name)
         if callable(attr):
             return _wrap_callable(attr, strict=True, name=f"ndarray.{name}")
@@ -101,18 +111,23 @@ class ndarray:
         return format(self._a.item() if self._a.ndim == 0 else self._a, spec)
 
     def __bool__(self):
+        _sync("bool(device array)")
         return bool(self._a)
 
     def __int__(self):
+        _sync("int(device array)")
         return int(self._a)
 
     def __float__(self):
+        _sync("float(device array)")
         return float(self._a)
 
     def __complex__(self):
+        _sync("complex(device array)")
         return complex(self._a)
 
     def __index__(self):
+        _sync("index of a device array")
         return operator.index(self._a.item() if self._a.ndim == 0 else self._a)
 
     __hash__ = None