cunumpy 0.6.1__tar.gz → 0.6.3__tar.gz

cunumpy-0.6.3/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Max Lindqvist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -1,8 +1,30 @@
 Metadata-Version: 2.4
 Name: cunumpy
-Version: 0.6.1
+Version: 0.6.3
 Summary: Simple wrapper for numpy and cupy. Replace `import numpy as np` with `import cunumpy as xp`.
 Author: Max
+License: MIT License
+        
+        Copyright (c) 2025 Max Lindqvist
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
 Project-URL: Source, https://github.com/max-models/cunumpy
 Keywords: python
 Classifier: Development Status :: 3 - Alpha
@@ -14,6 +36,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+License-File: LICENSE.txt
 Requires-Dist: array-api-compat
 Requires-Dist: maybempi>=0.1.2
 Requires-Dist: numpy
@@ -25,11 +48,14 @@ Requires-Dist: ipykernel; extra == "docs"
 Requires-Dist: myst-parser; extra == "docs"
 Requires-Dist: nbconvert; extra == "docs"
 Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
 Requires-Dist: jupyterlab; extra == "docs"
 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"
@@ -37,6 +63,7 @@ Requires-Dist: scipy; extra == "test"
 Provides-Extra: test-compiled
 Requires-Dist: cunumpy[test]; extra == "test-compiled"
 Requires-Dist: pyccel; extra == "test-compiled"
+Dynamic: license-file
 
 # CuNumpy
 
@@ -64,7 +91,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 +103,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
 
@@ -337,8 +366,9 @@ positional argument 0 is written, avoiding unnecessary copy-back for
 read-only inputs. For a keyword call, declare the keyword name, such as
 `outputs=("out",)`. A wrong declaration can leave GPU output values stale.
 The wrapper can also traverse arrays nested in lists, tuples, dictionaries,
-and selected application objects; see the full [API reference](docs/source/api.md)
-for `object_modules`, `is_array`, aliasing, and output declarations.
+and selected application objects; see [Host kernels with GPU
+data](docs/source/kernels/pyccel-kernel.md) for `object_modules`, `is_array`,
+aliasing, and output declarations.
 
 ## Write CUDA kernels next to host kernels
 
@@ -473,8 +503,9 @@ Launches can be 1D to 3D (`n_threads=(nx, ny)`, `block_size=(16, 16)`) or use
 an explicit `grid`, with dynamic shared memory (`shared_mem`) and a `stream`.
 C++ function templates are instantiated with `template_args`, and
 `CudaKernelVariants` caches kernels whose source is generated per variant
-(e.g. per dimension and dtype). See the [API reference](docs/source/api.md) for
-details.
+(e.g. per dimension and dtype). See [Writing CUDA
+kernels](docs/source/kernels/cuda-kernel.md) and [CUDA
+headers](docs/source/kernels/cuda-headers.md) for details.
 
 Kernels run asynchronously, so a CUDA error (an illegal memory access, say)
 normally surfaces at a later `.get()` or MPI call, far from the kernel that
@@ -561,8 +592,9 @@ published at <https://max-models.github.io/cunumpy/>:
 * [Worked examples](docs/source/examples/index.md),
   [best practices](docs/source/best-practices.md),
   [troubleshooting](docs/source/troubleshooting.md),
-  [Pyodide](docs/source/pyodide.md) and the
-  [API reference](docs/source/api.md).
+  [Pyodide](docs/source/pyodide.md), the
+  [API overview](docs/source/api.md) and the
+  [API reference](docs/source/reference/index.md).
 
 ### For AI coding assistants
 

{cunumpy-0.6.1 → cunumpy-0.6.3}/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
 
@@ -297,8 +299,9 @@ positional argument 0 is written, avoiding unnecessary copy-back for
 read-only inputs. For a keyword call, declare the keyword name, such as
 `outputs=("out",)`. A wrong declaration can leave GPU output values stale.
 The wrapper can also traverse arrays nested in lists, tuples, dictionaries,
-and selected application objects; see the full [API reference](docs/source/api.md)
-for `object_modules`, `is_array`, aliasing, and output declarations.
+and selected application objects; see [Host kernels with GPU
+data](docs/source/kernels/pyccel-kernel.md) for `object_modules`, `is_array`,
+aliasing, and output declarations.
 
 ## Write CUDA kernels next to host kernels
 
@@ -433,8 +436,9 @@ Launches can be 1D to 3D (`n_threads=(nx, ny)`, `block_size=(16, 16)`) or use
 an explicit `grid`, with dynamic shared memory (`shared_mem`) and a `stream`.
 C++ function templates are instantiated with `template_args`, and
 `CudaKernelVariants` caches kernels whose source is generated per variant
-(e.g. per dimension and dtype). See the [API reference](docs/source/api.md) for
-details.
+(e.g. per dimension and dtype). See [Writing CUDA
+kernels](docs/source/kernels/cuda-kernel.md) and [CUDA
+headers](docs/source/kernels/cuda-headers.md) for details.
 
 Kernels run asynchronously, so a CUDA error (an illegal memory access, say)
 normally surfaces at a later `.get()` or MPI call, far from the kernel that
@@ -521,8 +525,9 @@ published at <https://max-models.github.io/cunumpy/>:
 * [Worked examples](docs/source/examples/index.md),
   [best practices](docs/source/best-practices.md),
   [troubleshooting](docs/source/troubleshooting.md),
-  [Pyodide](docs/source/pyodide.md) and the
-  [API reference](docs/source/api.md).
+  [Pyodide](docs/source/pyodide.md), the
+  [API overview](docs/source/api.md) and the
+  [API reference](docs/source/reference/index.md).
 
 ### For AI coding assistants
 

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

@@ -5,7 +5,7 @@ requires = [ "setuptools", "wheel" ]
 
 [project]
 name = "cunumpy"
-version = "0.6.1"
+version = "0.6.3"
 description = "Simple wrapper for numpy and cupy. Replace `import numpy as np` with `import cunumpy as xp`."
 readme = "README.md"
 keywords = [ "python" ]
@@ -37,12 +37,14 @@ optional-dependencies.docs = [
   "myst-parser",
   "nbconvert",
   "nbsphinx",
+  "numpydoc",
   "jupyterlab",
   "pre-commit",
   "pyproject-fmt",
   "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"
@@ -57,8 +59,33 @@ cunumpy = [ "py.typed", "*.pyi", "LLM_GUIDE.md", "cuda/include/cunumpy/*.cuh" ]
 # agent worktrees and scratch scripts are local copies, not part of the project
 extend-exclude = [ ".claude" ]
 # formatting: `ruff format`; import sorting: the isort rules of `ruff check`
-lint.extend-select = [ "I", "TID252" ]
+lint.extend-select = [ "D", "I", "TID252" ]
+# D105/D107: magic methods and __init__ (constructor parameters go in the class docstring)
+lint.extend-ignore = [ "D105", "D107" ]
 lint.isort.known-first-party = [ "cunumpy" ]
+lint.per-file-ignores."_fake_cupy*.py" = [ "D" ]
+lint.per-file-ignores."conftest.py" = [ "D" ]
+lint.per-file-ignores."docs/**" = [ "D" ]
+lint.per-file-ignores."tests/**" = [ "D" ]
+lint.pydocstyle.convention = "numpy"
 
 [tool.ruff.lint.flake8-tidy-imports]
 ban-relative-imports = "all"
+
+# `python -m numpydoc lint src/cunumpy/*.py`: the public API (names re-exported by a public
+# module) has full numpydoc sections; private helpers only need a one-line summary.
+[tool.numpydoc_validation]
+checks = [
+  "all",
+  "ES01", # extended summary is optional (docstrings are kept short)
+  "EX01", # examples are required for public functions and classes, not every method
+  "SA01", # See Also is optional
+  "GL08", # undocumented objects are caught by ruff's D rules instead
+]
+# one-line docstrings (properties, trivial methods) need no Returns section
+override_RT01 = [ '\A[^\n]*\Z' ]
+exclude = [
+  '\._[A-Za-z]\w*$',  # private functions, classes and methods
+  '\.__\w+__$',    # dunder methods
+  '_fake_cupy',
+]

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

@@ -72,26 +72,37 @@ 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)`; component-major `(ncomp, N)`: `axis=-1` |
+| run CUDA kernel launches on the CPU in a test (fake CuPy) | `with kernel_testing.emulated_launches(): ...` (also makes `kernel.compile()`/`compile_all()` build the emulation instead of CUDA); `with kernel_testing.fake_cupy_session(): ...` adds the CuPy backend; `kernel_testing.host_buffer(a)` reads a fake array; struct arguments are read through their fields |
+| run a test on the fake CuPy from a NumPy test process | `kernel_testing.run_in_fake_cupy_subprocess(code)` (serial child, rank 0 only under MPI); `@kernel_testing.requires_device_backend` = a GPU or the fake CuPy |
+| 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` |
 | host arrays reach kernels while CuPy is active | `Kernel(..., dispatch="arrays")` / `from_package(..., dispatch="arrays")`: CUDA only for device arguments |
 | one kernel folder declares its kernel in its own `__init__.py` | `kernel = xp.kernels.Kernel.from_folder(__name__, host_suffix="_pyccel", compile_host=..., dispatch="arrays")`; `<name>_numba.py`, `<name>_numpy.py` in the folder are further host implementations |
-| bring a `dispatch="arrays"` kernel's arguments to the side of the main array | `xp.kernels.as_kernel_array(a, like=grid, dtype=float)`; outputs: `with xp.kernels.kernel_output(out, like=grid, dtype=float) as buf:` |
+| bring a `dispatch="arrays"` kernel's arguments to the side of the main array | `xp.kernels.as_kernel_array(a, like=grid, dtype=float)`; outputs: `with xp.kernels.kernel_output(out, like=grid, dtype=float) as buf:`; `strided=True` passes NumPy views in C order with gaps (`a[:, :n]`) to Pyccel hosts without a copy |
 | choose the host implementation (pyccel/numba/numpy/python) | `xp.kernels.set_host_kernel_implementation("numpy")`, `with xp.kernels.use_host_kernel_implementation(...)`, `CUNUMPY_HOST_KERNEL_IMPLEMENTATION=numpy`; default: first available of pyccel, numba, numpy; `kernel.selected()` |
 | require CUDA for device kernel dispatch | `xp.kernels.set_device_kernel_implementation("cuda")`, `get_device_kernel_implementation()`, `with xp.kernels.use_device_kernel_implementation(...)`, `CUNUMPY_DEVICE_KERNEL_IMPLEMENTATION=cuda`; default `None` preserves `missing_cuda` policy; explicit CUDA rejects host fallback |
 | check host and CUDA kernels take the same parameters | `catalog.check_signatures()` (in a unit test) |
-| test a CUDA kernel's arithmetic without a GPU | `cunumpy.kernel_testing.emulate_cuda_kernel(kernel, *numpy_args, n_threads=n)` (C++ compiler; shared memory and __syncthreads ok, no warp ops; `shared_mem=` for extern shared) |
+| test a CUDA kernel's arithmetic without a GPU | `cunumpy.kernel_testing.emulate_cuda_kernel(kernel, *numpy_args, n_threads=n)` (C++ compiler; shared memory and __syncthreads ok, no warp ops; inline asm traps; compiled once per kernel and cached; `shared_mem=` for extern shared) |
 | shared-memory budget of a block | `xp.cuda.max_shared_memory_per_block()` (48 KiB without a GPU) |
 | random numbers inside a kernel, equal on the host | `#include <cunumpy/random.cuh>`: `cunumpy_uniform(seed, particle_id, step)`; host: `xp.rng.philox_uniform(seed, ids, step)` |
 | sort points along a Z-curve / quadtree or octree nodes as contiguous ranges | `keys = xp.algorithms.morton_keys(pos, lower, upper, levels)`, `keys, order, pos = xp.algorithms.sort_by_key(keys, pos)`; in a kernel `#include <cunumpy/morton.cuh>`: `cunumpy_morton_key2(x, y, x0, y0, sx, sy, levels)` with `xp.algorithms.morton_scales(...)` |
 | one thread per marker without passing n_threads | default: `CudaKernel(...)` uses the first array's row count for 1D launches |
 | copy device arrays to the host for output without stalling | `xp.memory.HostStaging(shape, dtype)`: `c = staging.copy(a)` ... `c.result()` |
+| read a device scalar without a sync (e.g. a convergence test one iteration late) | `h = xp.to_host_async(x)`; `h.ready()` never waits, `h.result()` |
 | PIC recipes (compaction, sort by cell, MPI exchange, graphs) | docs guide "Particle codes" |
 | reproducible random numbers per MPI rank | `xp.rng.random_streams.seed(seed, rank=rank)`, then `xp.rng.random_streams.normal(...)` / `.generator()` |
 | group arrays/scalars into one kernel argument | `xp.arguments.CudaArguments` (flattened), `xp.arguments.CudaStruct` (C struct), `xp.arguments.CudaStructArguments` (C struct as a class); host kernels take their own argument objects, the caller picks one per backend |
 | CUDA struct from a Pyccel argument class | `xp.arguments.CudaStruct.from_signature(Cls.__init__, "Name")`, `xp.arguments.write_cuda_header(...)` |
 | SciPy (sparse, sparse.linalg, fft, special, ndimage, ...) on either backend | `xp.scipy.<subpackage>.<name>` (SciPy or `cupyx.scipy`); `xp.scipy.special.available(name)` |
+| splines on the device | `xp.scipy.interpolate.UnivariateSpline`, `make_interp_spline`, `NdBSpline` (no `RectBivariateSpline`: `make_interp_spline` per axis + `NdBSpline`) |
+| circulant solve (FFT preconditioner) on the device | `xp.scipy.linalg.solve_circulant(c, b)` (cunumpy fill-in on CuPy, SciPy's arguments) |
+| one root/minimization/integral/ODE at setup with an `xp` callback using device data | `xp.optimize.fsolve`/`root`/`minimize`, `xp.integrate.quad`/`odeint` (SciPy on the host, callback args and results on `x0`'s backend) |
+| many independent scalar root problems (one per ray, per marker) | `xp.optimize.newton(func, x0_array, fprime=None)` (SciPy's array Newton/secant, on the device) |
 | chain of elementwise operations as one GPU kernel | `@xp.kernels.fuse` (`cupy.fuse` for CuPy arrays, plain call otherwise) |
 | PETSc solve on device arrays without copies | `xp.petsc.petsc_vec(array)` (CUDA/HIP petsc4py for CuPy arrays); `xp.synchronize()` around PETSc calls |
 | reduction inside a CUDA kernel (energy, max velocity) | `<cunumpy/reduce.cuh>`: `cunumpy_block_sum_to(out, v)`, `cunumpy_block_min/max`, `cunumpy_warp_sum` |
@@ -101,6 +112,7 @@ https://max-models.github.io/cunumpy/ and in `docs/source/` of the repository.
 | timing GPU code | `with xp.profiling.timed_region("name") as t:` → `t.elapsed` |
 | profiler markers | `xp.profiling.nvtx_range("name")` (context manager or decorator) |
 | find transfers | `with xp.profiling.count_transfers() as c: ...; print(c.report())` |
+| check transfers per phase of a time loop | `b = xp.profiling.TransferBudget()`; `b.count("step")(fn)` or `with b.phase("output"):`; `b.require("step", allow={"to_host": {"max_nbytes": 8}})`; `b.check()` |
 | debug an illegal memory access | `CUNUMPY_CUDA_DEBUG=1`, then `compute-sanitizer` |
 | test on both backends | `cunumpy.kernel_testing.BACKENDS`, `backend` fixture, `requires_cupy` |
 | test CUDA vs host kernel | `cunumpy.kernel_testing.assert_kernels_agree(kernel, make_args, n_threads=...)` |
@@ -137,6 +149,9 @@ xp.as_device_array(value, dtype=None, ndim=None, *, name=None)
 with xp.profiling.count_transfers() as c: ...   # c.total, c.to_host, c.to_device,
                                       # c.kernel_conversions, c.fallbacks, c.events, c.report()
 with xp.profiling.assert_no_transfers(): ...    # rejects host/device copies and host fallback
+h = xp.to_host_async(a)  # non-blocking copy of a device scalar: h.ready(), h.result()
+budget = xp.profiling.TransferBudget()          # per-phase counts: budget.phase(name),
+                                      # budget.count(name)(fn), budget.require(...), budget.check()
 ```
 
 Mirror refreshes, MPI/output staging, argument conversion and kernel output
@@ -160,6 +175,9 @@ with xp.mpi.mpi_buffer(a) as buf:
 with xp.mpi.mpi_buffer(a, send=False, recv=True) as buf:
     ...  # array, or pinned staging copy
 xp.mpi.set_mpi_cuda_aware(True | False | None), xp.mpi.get_mpi_cuda_aware()
+xp.mpi.exchange(
+    comm, sends=[(send, dest, tag)], receives=[(recv, source, tag)]
+)  # waits for all transfers and GPU copy-back; MPI posting/wait errors abort comm
 xp.algorithms.segment_sum(
     values, keys, n_segments
 )  # out[k] = sum(values[keys == k]); keys < 0 dropped
@@ -300,8 +318,10 @@ xp.cuda.cuda_include_dir()
 * Default `n_threads_from="auto"` infers from the first array, including arrays
   in supported argument objects: 1D block -> shape[0], 2D -> shape[:2], 3D ->
   shape[:3] (x, y, z). Per-call block overrides apply. Explicit n_threads/grid
-  wins; use a callback for flattened `.size`, reversed axes or another work
-  count, or None to require explicit sizes. Missing arrays/axes raise.
+  wins; `"last_axis"` uses the first array's last axis (component-major
+  `(ncomp, N)` marker arrays); use a callback for flattened `.size`, reversed
+  axes or another work count, or None to require explicit sizes. Missing
+  arrays/axes raise.
 
 Shipped CUDA headers (always on the include path):
 

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

@@ -1,3 +1,16 @@
+"""NumPy and CuPy behind one namespace.
+
+``import cunumpy as xp`` gives the functions of the active backend's
+``array-api-compat`` module (``xp.zeros``, ``xp.linalg``, ...), replaced when
+the backend changes, plus backend selection, array inspection and conversion,
+host execution helpers (:func:`host_call`), and :data:`scipy`. Everything else
+is in a submodule (:mod:`cunumpy.kernels`, :mod:`cunumpy.cuda`, ...). See
+:doc:`/api` for the module layout and :doc:`/guides/backends`.
+
+``xp.numpy_backend`` and ``xp.cupy_backend`` are booleans telling whether the
+active backend is NumPy or CuPy (prefer :func:`get_backend` for the name).
+"""
+
 # cunumpy/__init__.py
 import re as _re
 from importlib.metadata import PackageNotFoundError, version
@@ -6,20 +19,26 @@ from cunumpy import (
     algorithms,
     arguments,
     cuda,
+    integrate,
     kernels,
     memory,
     mpi,
+    optimize,
     petsc,
     profiling,
     rng,
     xp,
 )
+from cunumpy._host import evaluate_on_host, host_call, setup_on_host
 from cunumpy._scipy_backend import scipy
+from cunumpy._staging import to_host_async
 from cunumpy.xp import (
+    MIN_CUPY_VERSION,
     as_device_array,
     assert_same_backend,
     backend_info,
     cupy_available,
+    cupy_version_supported,
     default_float_dtype,
     get_array_backend,
     get_array_module,
@@ -36,6 +55,7 @@ from cunumpy.xp import (
 )
 
 try:
+    #: The installed version of cunumpy; ``"0.0.0+unknown"`` without package metadata.
     __version__ = version("cunumpy")
 except PackageNotFoundError:
     __version__ = "0.0.0+unknown"
@@ -46,18 +66,27 @@ def _version_key(text: str) -> tuple[int, ...]:
 
 
 def require_version(minimum: str) -> None:
-    """Raise ``ImportError`` if this cunumpy is older than `minimum`.
-
-    For projects that depend on a feature of a given release, as a clearer
-    error than an ``AttributeError`` later::
-
-        import cunumpy as xp
-
-        xp.require_version("0.4.0")
-
-    Only the numeric part of the versions is compared (``0.4.0`` and
-    ``0.4.0.dev1`` compare equal). Nothing is checked when the installed
-    version is unknown (cunumpy not installed as a package).
+    """Raise ``ImportError`` if the installed cunumpy is older than `minimum`.
+
+    A clearer error than a later ``AttributeError`` for code that needs a
+    feature of a given release. Only the numeric part is compared (``0.4.0``
+    and ``0.4.0.dev1`` are equal); nothing is checked when the installed
+    version is unknown (cunumpy not installed as a package, ``xp.__version__``
+    is then ``"0.0.0+unknown"``).
+
+    Parameters
+    ----------
+    minimum : str
+        The oldest acceptable version, e.g. ``"0.4.0"``.
+
+    Raises
+    ------
+    ImportError
+        If the installed version is older than `minimum`.
+
+    Examples
+    --------
+    >>> xp.require_version("0.4.0")
     """
     if __version__.startswith("0.0.0+unknown"):
         return
@@ -69,6 +98,7 @@ def require_version(minimum: str) -> None:
 
 
 __all__ = [
+    "MIN_CUPY_VERSION",
     "__version__",
     "algorithms",
     "arguments",
@@ -78,16 +108,21 @@ __all__ = [
     "cuda",
     "cupy_available",
     "cupy_backend",
+    "cupy_version_supported",
     "default_float_dtype",
+    "evaluate_on_host",
     "get_array_backend",
     "get_array_module",
     "get_backend",
+    "host_call",
+    "integrate",
     "is_cpu",
     "is_gpu",
     "kernels",
     "memory",
     "mpi",
     "numpy_backend",
+    "optimize",
     "petsc",
     "profiling",
     "require_version",
@@ -95,9 +130,11 @@ __all__ = [
     "same_backend",
     "scipy",
     "set_backend",
+    "setup_on_host",
     "synchronize",
     "to_cunumpy",
     "to_cupy",
+    "to_host_async",
     "to_numpy",
     "use_backend",
     "xp",
@@ -105,12 +142,7 @@ __all__ = [
 
 
 def __getattr__(name: str):
-    """Resolve names that are not in the namespace: cunumpy.<name> -> cunumpy.xp.<name>.
-
-    The public names of the active backend are copied into this namespace (see
-    `_sync_backend_namespace`), so this only runs for names missing from the
-    backend's ``__all__`` and for ``numpy_backend``/``cupy_backend``.
-    """
+    """Resolve ``numpy_backend``, ``cupy_backend`` and backend names not copied here."""
     if name == "numpy_backend":
         return xp.numpy_backend
     if name == "cupy_backend":

{cunumpy-0.6.1 → cunumpy-0.6.3}/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
 
@@ -11,19 +11,27 @@ from numpy import *
 from cunumpy import algorithms as algorithms
 from cunumpy import arguments as arguments
 from cunumpy import cuda as cuda
+from cunumpy import integrate as integrate
 from cunumpy import kernels as kernels
 from cunumpy import memory as memory
 from cunumpy import mpi as mpi
+from cunumpy import optimize as optimize
 from cunumpy import petsc as petsc
 from cunumpy import profiling as profiling
 from cunumpy import rng as rng
 from cunumpy import xp as xp
 from cunumpy._scipy_backend import scipy as scipy
+from cunumpy._staging import HostCopy
 
 def to_numpy(array: Any) -> np.ndarray: ...
 def to_cupy(array: Any) -> Any: ...
 def to_cunumpy(array: Any) -> Any: ...
+def to_host_async(array: Any) -> HostCopy: ...
 def cupy_available() -> bool: ...
+def cupy_version_supported(cupy_version: str) -> bool: ...
+
+MIN_CUPY_VERSION: str
+
 def backend_info() -> dict[str, Any]: ...
 def get_array_module(array: Any) -> Any: ...
 def get_backend() -> str: ...
@@ -38,6 +46,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: ...