cunumpy 0.6.2__tar.gz → 0.7.0__tar.gz

cunumpy-0.7.0/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.2 → cunumpy-0.7.0}/PKG-INFO

@@ -1,8 +1,30 @@
 Metadata-Version: 2.4
 Name: cunumpy
-Version: 0.6.2
+Version: 0.7.0
 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,22 +36,18 @@ 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
 Provides-Extra: dev
-Requires-Dist: ruff; extra == "dev"
 Requires-Dist: cunumpy[docs,test-compiled]; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pyproject-fmt; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
 Provides-Extra: docs
+Requires-Dist: griffe; extra == "docs"
 Requires-Dist: ipykernel; extra == "docs"
-Requires-Dist: myst-parser; extra == "docs"
-Requires-Dist: nbconvert; extra == "docs"
-Requires-Dist: nbsphinx; 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
@@ -39,6 +57,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
 
@@ -79,7 +98,7 @@ never hide a NumPy name:
 
 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)).
+`pip install 'cunumpy[metal]'`, see [the guide](https://max-models.github.io/cunumpy/kernels/metal-kernel/)).
 
 ## Install
 
@@ -95,7 +114,7 @@ installation instructions for your system. CuNumpy does not install CUDA.
 `array-api-compat` supplies NumPy and CuPy compatibility modules with more
 consistent behavior for shared array operations. CuNumpy uses them internally;
 your arrays remain ordinary NumPy or CuPy arrays. See [why CuNumpy uses
-`array-api-compat`](docs/source/array-api-compat.md) for a plain-language
+`array-api-compat`](https://max-models.github.io/cunumpy/guides/array-api-compat/) for a plain-language
 explanation and examples.
 
 ## Choose a backend
@@ -121,7 +140,7 @@ Use `xp.set_backend("cupy", strict=True)` to raise when CUDA is unavailable,
 preserving the previous backend. `xp.backend_info()` returns structured backend,
 dependency, and CUDA diagnostics. Reusable streams/events, MPI staging, cell
 ranges, and prepared reductions are described in the
-[execution helpers guide](docs/source/guides/execution-helpers.md).
+[execution helpers guide](https://max-models.github.io/cunumpy/guides/execution-helpers/).
 
 Use `use_backend()` for a temporary selection. It restores the previous
 selection when the block exits, including when an exception is raised:
@@ -341,8 +360,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](https://max-models.github.io/cunumpy/kernels/pyccel-kernel/) for `object_modules`, `is_array`,
+aliasing, and output declarations.
 
 ## Write CUDA kernels next to host kernels
 
@@ -477,8 +497,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](https://max-models.github.io/cunumpy/kernels/cuda-kernel/) and [CUDA
+headers](https://max-models.github.io/cunumpy/kernels/cuda-headers/) 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
@@ -538,35 +559,36 @@ mirror.to_host()  # vector._data holds the result on both backends
 
 CuNumpy supports the NumPy backend in Pyodide. It does not provide CuPy/CUDA
 there. Ordinary Python callables can be wrapped with `PyccelKernel` without
-compilation. See the [Pyodide guide](docs/source/pyodide.md) for a complete
+compilation. See the [Pyodide guide](https://max-models.github.io/cunumpy/pyodide/) for a complete
 installation example and compatibility notes.
 
 ## Documentation
 
-The full documentation lives in [`docs/source`](docs/source/index.md) and is
+The full documentation lives in [`docs/`](docs/) (Astro + Starlight, `make docs-build`) and is
 published at <https://max-models.github.io/cunumpy/>:
 
-* Getting started: [installation](docs/source/installation.md) and a
-  [quickstart](docs/source/quickstart.md) with a map of which guide covers what.
-* User guide: [choosing a backend](docs/source/guides/backends.md),
-  [backend-agnostic code](docs/source/guides/portable-code.md),
-  [data movement](docs/source/guides/data-movement.md),
-  [devices, memory and streams](docs/source/guides/gpu-devices.md),
-  [MPI with one rank per GPU](docs/source/guides/mpi.md),
-  [timing and profiling](docs/source/guides/profiling.md).
-* Porting kernels: [overview](docs/source/kernels/overview.md),
-  [`PyccelKernel`](docs/source/kernels/pyccel-kernel.md),
-  [`CudaKernel`](docs/source/kernels/cuda-kernel.md),
-  [`Kernel` and `KernelCatalog`](docs/source/kernels/dispatch.md),
-  [argument objects and structs](docs/source/kernels/arguments.md),
-  [accumulation kernels](docs/source/kernels/accumulation.md),
-  [debugging](docs/source/kernels/debugging.md),
-  [testing](docs/source/kernels/testing.md).
-* [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).
+* Getting started: [installation](https://max-models.github.io/cunumpy/getting-started/installation/) and a
+  [quickstart](https://max-models.github.io/cunumpy/getting-started/quickstart/) with a map of which guide covers what.
+* User guide: [choosing a backend](https://max-models.github.io/cunumpy/guides/backends/),
+  [backend-agnostic code](https://max-models.github.io/cunumpy/guides/portable-code/),
+  [data movement](https://max-models.github.io/cunumpy/guides/data-movement/),
+  [devices, memory and streams](https://max-models.github.io/cunumpy/guides/gpu-devices/),
+  [MPI with one rank per GPU](https://max-models.github.io/cunumpy/guides/mpi/),
+  [timing and profiling](https://max-models.github.io/cunumpy/guides/profiling/).
+* Porting kernels: [overview](https://max-models.github.io/cunumpy/kernels/overview/),
+  [`PyccelKernel`](https://max-models.github.io/cunumpy/kernels/pyccel-kernel/),
+  [`CudaKernel`](https://max-models.github.io/cunumpy/kernels/cuda-kernel/),
+  [`Kernel` and `KernelCatalog`](https://max-models.github.io/cunumpy/kernels/dispatch/),
+  [argument objects and structs](https://max-models.github.io/cunumpy/kernels/arguments/),
+  [accumulation kernels](https://max-models.github.io/cunumpy/kernels/accumulation/),
+  [debugging](https://max-models.github.io/cunumpy/kernels/debugging/),
+  [testing](https://max-models.github.io/cunumpy/kernels/testing/).
+* [Worked examples](https://max-models.github.io/cunumpy/examples/),
+  [best practices](https://max-models.github.io/cunumpy/best-practices/),
+  [troubleshooting](https://max-models.github.io/cunumpy/troubleshooting/),
+  [Pyodide](https://max-models.github.io/cunumpy/pyodide/), the
+  [API overview](https://max-models.github.io/cunumpy/reference/overview/) and the
+  [API reference](https://max-models.github.io/cunumpy/reference/).
 
 ### For AI coding assistants
 

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

@@ -37,7 +37,7 @@ never hide a NumPy name:
 
 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)).
+`pip install 'cunumpy[metal]'`, see [the guide](https://max-models.github.io/cunumpy/kernels/metal-kernel/)).
 
 ## Install
 
@@ -53,7 +53,7 @@ installation instructions for your system. CuNumpy does not install CUDA.
 `array-api-compat` supplies NumPy and CuPy compatibility modules with more
 consistent behavior for shared array operations. CuNumpy uses them internally;
 your arrays remain ordinary NumPy or CuPy arrays. See [why CuNumpy uses
-`array-api-compat`](docs/source/array-api-compat.md) for a plain-language
+`array-api-compat`](https://max-models.github.io/cunumpy/guides/array-api-compat/) for a plain-language
 explanation and examples.
 
 ## Choose a backend
@@ -79,7 +79,7 @@ Use `xp.set_backend("cupy", strict=True)` to raise when CUDA is unavailable,
 preserving the previous backend. `xp.backend_info()` returns structured backend,
 dependency, and CUDA diagnostics. Reusable streams/events, MPI staging, cell
 ranges, and prepared reductions are described in the
-[execution helpers guide](docs/source/guides/execution-helpers.md).
+[execution helpers guide](https://max-models.github.io/cunumpy/guides/execution-helpers/).
 
 Use `use_backend()` for a temporary selection. It restores the previous
 selection when the block exits, including when an exception is raised:
@@ -299,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](https://max-models.github.io/cunumpy/kernels/pyccel-kernel/) for `object_modules`, `is_array`,
+aliasing, and output declarations.
 
 ## Write CUDA kernels next to host kernels
 
@@ -435,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](https://max-models.github.io/cunumpy/kernels/cuda-kernel/) and [CUDA
+headers](https://max-models.github.io/cunumpy/kernels/cuda-headers/) 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
@@ -496,35 +498,36 @@ mirror.to_host()  # vector._data holds the result on both backends
 
 CuNumpy supports the NumPy backend in Pyodide. It does not provide CuPy/CUDA
 there. Ordinary Python callables can be wrapped with `PyccelKernel` without
-compilation. See the [Pyodide guide](docs/source/pyodide.md) for a complete
+compilation. See the [Pyodide guide](https://max-models.github.io/cunumpy/pyodide/) for a complete
 installation example and compatibility notes.
 
 ## Documentation
 
-The full documentation lives in [`docs/source`](docs/source/index.md) and is
+The full documentation lives in [`docs/`](docs/) (Astro + Starlight, `make docs-build`) and is
 published at <https://max-models.github.io/cunumpy/>:
 
-* Getting started: [installation](docs/source/installation.md) and a
-  [quickstart](docs/source/quickstart.md) with a map of which guide covers what.
-* User guide: [choosing a backend](docs/source/guides/backends.md),
-  [backend-agnostic code](docs/source/guides/portable-code.md),
-  [data movement](docs/source/guides/data-movement.md),
-  [devices, memory and streams](docs/source/guides/gpu-devices.md),
-  [MPI with one rank per GPU](docs/source/guides/mpi.md),
-  [timing and profiling](docs/source/guides/profiling.md).
-* Porting kernels: [overview](docs/source/kernels/overview.md),
-  [`PyccelKernel`](docs/source/kernels/pyccel-kernel.md),
-  [`CudaKernel`](docs/source/kernels/cuda-kernel.md),
-  [`Kernel` and `KernelCatalog`](docs/source/kernels/dispatch.md),
-  [argument objects and structs](docs/source/kernels/arguments.md),
-  [accumulation kernels](docs/source/kernels/accumulation.md),
-  [debugging](docs/source/kernels/debugging.md),
-  [testing](docs/source/kernels/testing.md).
-* [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).
+* Getting started: [installation](https://max-models.github.io/cunumpy/getting-started/installation/) and a
+  [quickstart](https://max-models.github.io/cunumpy/getting-started/quickstart/) with a map of which guide covers what.
+* User guide: [choosing a backend](https://max-models.github.io/cunumpy/guides/backends/),
+  [backend-agnostic code](https://max-models.github.io/cunumpy/guides/portable-code/),
+  [data movement](https://max-models.github.io/cunumpy/guides/data-movement/),
+  [devices, memory and streams](https://max-models.github.io/cunumpy/guides/gpu-devices/),
+  [MPI with one rank per GPU](https://max-models.github.io/cunumpy/guides/mpi/),
+  [timing and profiling](https://max-models.github.io/cunumpy/guides/profiling/).
+* Porting kernels: [overview](https://max-models.github.io/cunumpy/kernels/overview/),
+  [`PyccelKernel`](https://max-models.github.io/cunumpy/kernels/pyccel-kernel/),
+  [`CudaKernel`](https://max-models.github.io/cunumpy/kernels/cuda-kernel/),
+  [`Kernel` and `KernelCatalog`](https://max-models.github.io/cunumpy/kernels/dispatch/),
+  [argument objects and structs](https://max-models.github.io/cunumpy/kernels/arguments/),
+  [accumulation kernels](https://max-models.github.io/cunumpy/kernels/accumulation/),
+  [debugging](https://max-models.github.io/cunumpy/kernels/debugging/),
+  [testing](https://max-models.github.io/cunumpy/kernels/testing/).
+* [Worked examples](https://max-models.github.io/cunumpy/examples/),
+  [best practices](https://max-models.github.io/cunumpy/best-practices/),
+  [troubleshooting](https://max-models.github.io/cunumpy/troubleshooting/),
+  [Pyodide](https://max-models.github.io/cunumpy/pyodide/), the
+  [API overview](https://max-models.github.io/cunumpy/reference/overview/) and the
+  [API reference](https://max-models.github.io/cunumpy/reference/).
 
 ### For AI coding assistants
 

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

@@ -5,7 +5,7 @@ requires = [ "setuptools", "wheel" ]
 
 [project]
 name = "cunumpy"
-version = "0.6.2"
+version = "0.7.0"
 description = "Simple wrapper for numpy and cupy. Replace `import numpy as np` with `import cunumpy as xp`."
 readme = "README.md"
 keywords = [ "python" ]
@@ -28,21 +28,14 @@ dependencies = [
 ]
 
 optional-dependencies.dev = [
-  "ruff",
   "cunumpy[test-compiled,docs]",
-]
-# https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594
-optional-dependencies.docs = [
-  "ipykernel",
-  "myst-parser",
-  "nbconvert",
-  "nbsphinx",
-  "jupyterlab",
   "pre-commit",
   "pyproject-fmt",
-  "sphinx",
-  "sphinx-book-theme",
+  "ruff",
 ]
+# the API reference of the docs site (docs/, Astro + Starlight) reads the docstrings with griffe;
+# the shared docs workflow registers an ipykernel even without notebooks
+optional-dependencies.docs = [ "griffe", "ipykernel" ]
 optional-dependencies.metal = [ "mlx; sys_platform == 'darwin' and platform_machine == 'arm64'" ]
 optional-dependencies.test = [ "coverage", "pytest", "scipy" ]
 optional-dependencies.test-compiled = [ "cunumpy[test]", "pyccel" ]
@@ -58,8 +51,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.2 → cunumpy-0.7.0}/src/cunumpy/LLM_GUIDE.md

@@ -5,7 +5,7 @@ correct code with `cunumpy`. It ships inside the installed package
 (`<site-packages>/cunumpy/LLM_GUIDE.md`; locate it with
 `python -c "import cunumpy, pathlib; print(pathlib.Path(cunumpy.__file__).parent / 'LLM_GUIDE.md')"`).
 It is self-contained. The full documentation is at
-https://max-models.github.io/cunumpy/ and in `docs/source/` of the repository.
+https://max-models.github.io/cunumpy/ and in `docs/` of the repository.
 
 ## What cunumpy is
 
@@ -74,29 +74,35 @@ https://max-models.github.io/cunumpy/ and in `docs/source/` of the repository.
 | 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 |
+| 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:` (several: `with xp.kernels.kernel_outputs(a, b, like=grid, dtype=float) as (buf_a, buf_b):`); `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` |
@@ -106,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=...)` |
@@ -142,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
@@ -165,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
@@ -305,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.2 → cunumpy-0.7.0}/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,9 +19,11 @@ from cunumpy import (
     algorithms,
     arguments,
     cuda,
+    integrate,
     kernels,
     memory,
     mpi,
+    optimize,
     petsc,
     profiling,
     rng,
@@ -16,11 +31,14 @@ from cunumpy import (
 )
 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,
@@ -38,6 +56,7 @@ from cunumpy.xp import (
 
 try:
     __version__ = version("cunumpy")
+    """The installed version of cunumpy; ``"0.0.0+unknown"`` without package metadata."""
 except PackageNotFoundError:
     __version__ = "0.0.0+unknown"
 
@@ -47,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
@@ -70,6 +98,7 @@ def require_version(minimum: str) -> None:
 
 
 __all__ = [
+    "MIN_CUPY_VERSION",
     "__version__",
     "algorithms",
     "arguments",
@@ -79,18 +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",
@@ -102,6 +134,7 @@ __all__ = [
     "synchronize",
     "to_cunumpy",
     "to_cupy",
+    "to_host_async",
     "to_numpy",
     "use_backend",
     "xp",
@@ -109,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":