HIP Target and Platform

Introduce HIP as a dedicated code generation platform.

pystencils.codegen

• Add Target.HIP
• Change Target.GPU to alias Target.CurrentGPU
• Auto-detect Target.CUDA or Target.HIP on GPU systems when using Target.CurrentGPU

pystencils.backend

• Move all common functionality of CUDA and HIP to GenericGpu platform class
• Introduce HipPlatform to inherit from GenericGpu

pystencils.jit

• Adapt the CupyJit to only compile CUDA kernels on NVidia platforms, and only HIP kernels on ROCm platforms
  • While HIP can technically act as a shallow wrapper around CUDA on NVidia systems, this does not make sense here, since a) we're gaining portability through code generation anyway, b) hipcc will just call nvcc on Nvidia systems anyway, and c) cupy needs to be built against the entire ROCm software stack to use HIP.

Code Adaptations

• Use Target.CurrentGPU throughout the test suite where it is required
• Use Target.is_gpu() to detect GPU targets in all places where previously targets were checked only against Target.CUDA

Documentation

• Adapt installation guide and GPU codegen guide to reflect the new target
• Adapt backend GPU codegen docs
• Extend contrib guide with info on GPU development

On CI Testing

Since cupy only supports the combinations NVidia+CUDA and ROCm+HIP, we cannot currently test HIP code generation in the CI since we don't have GitLab runners with AMD GPUs.

Rationale

Separate modelling of CUDA and HIP in the code generator will be necessary to capture architectural differences in !438 (merged). Also, it turns out to be very important for the new waLBerla code generator (see https://i10git.cs.fau.de/da15siwa/sfg-walberla); using the target is the easiest way to distinguish between CUDA and HIP for GPU codegen.

docs/source/backend/gpu_codegen.md

@@ -2,23 +2,19 @@
 
 The code generation infrastructure for Nvidia and AMD GPUs using CUDA and HIP comprises the following components:
 
- - The {any}`CudaPlatform` at `backend.platforms` which performs materialization of a kernel's iteration
-   space by mapping GPU block and thread indices to iteration space points. To perform this task,
-   it depends on a {any}`ThreadMapping` instance which defines the nature of that mapping.
+ - The platforms {any}`CudaPlatform` and {any}`HipPlatform` at `backend.platforms`
+   which perform materialization of a kernel's iteration space
+   by mapping GPU block and thread indices to iteration space points.
+   To perform this task, it depends on a {any}`ThreadMapping` instance which defines the nature of that mapping.
    The platform also takes care of lowering mathematical functions to their CUDA runtime library implementation.
  - In the code generation driver, the strings are drawn by the `GpuIndexing` helper class.
    It provides both the {any}`ThreadMapping` for the codegen backend, as well as the launch configuration
    for the runtime system.
 
-:::{attention}
-
-Code generation for HIP through the `CudaPlatform` is experimental and not tested at the moment.
-:::
-
-## The CUDA Platform and Thread Mappings
+## The GPU Platform and Thread Mappings
 
 ```{eval-rst}
-.. module:: pystencils.backend.platforms.cuda
+.. module:: pystencils.backend.platforms.generic_gpu
 
 .. autosummary::
     :toctree: generated