Skip to content
Snippets Groups Projects
Commit 3d44a19e authored by Frederik Hennig's avatar Frederik Hennig
Browse files

Update docs, installation + contrib guide

parent d5de4047
No related branches found
No related tags found
1 merge request!458HIP Target and Platform
Pipeline #76061 passed
...@@ -2,23 +2,19 @@ ...@@ -2,23 +2,19 @@
The code generation infrastructure for Nvidia and AMD GPUs using CUDA and HIP comprises the following components: 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 - The platforms {any}`CudaPlatform` and {any}`HipPlatform` at `backend.platforms`
space by mapping GPU block and thread indices to iteration space points. To perform this task, which perform materialization of a kernel's iteration space
it depends on a {any}`ThreadMapping` instance which defines the nature of that mapping. 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. 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. - 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 It provides both the {any}`ThreadMapping` for the codegen backend, as well as the launch configuration
for the runtime system. 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 CUDA Platform and Thread Mappings
```{eval-rst} ```{eval-rst}
.. module:: pystencils.backend.platforms.cuda .. module:: pystencils.backend.platforms.generic_gpu
.. autosummary:: .. autosummary::
:toctree: generated :toctree: generated
......
...@@ -26,7 +26,6 @@ targets in the future. ...@@ -26,7 +26,6 @@ targets in the future.
Platform Platform
GenericCpu GenericCpu
GenericVectorCpu GenericVectorCpu
GenericGpu
``` ```
## CPU Platforms ## CPU Platforms
...@@ -49,6 +48,18 @@ targets in the future. ...@@ -49,6 +48,18 @@ targets in the future.
:nosignatures: :nosignatures:
:template: autosummary/entire_class.rst :template: autosummary/entire_class.rst
GenericGpu
CudaPlatform CudaPlatform
SyclPlatform HipPlatform
``` ```
## Experimental Platforms
```{eval-rst}
.. autosummary::
:toctree: generated
:nosignatures:
:template: autosummary/entire_class.rst
SyclPlatform
```
\ No newline at end of file
...@@ -48,16 +48,22 @@ git pull --set-upstream upstream master ...@@ -48,16 +48,22 @@ git pull --set-upstream upstream master
## Set Up the Python Environment ## Set Up the Python Environment
### Prerequesites
To develop pystencils, you will need at least the following software installed on your machine: To develop pystencils, you will need at least the following software installed on your machine:
- Python 3.10 or later: Since pystencils minimal supported version is Python 3.10, we recommend that you work with Python 3.10 directly. - Python 3.10 or later: Since pystencils minimal supported version is Python 3.10, we recommend that you work with Python 3.10 directly.
- An up-to-date C++ compiler, used by pystencils to JIT-compile generated code - An up-to-date C++ compiler, used by pystencils to JIT-compile generated code
- [Nox](https://nox.thea.codes/en/stable/), which we use for test automation. - [Nox](https://nox.thea.codes/en/stable/), which we use for test automation.
Nox will be used extensively in the instructions on testing below. Nox will be used extensively in the instructions on testing below.
- Optionally [CUDA](https://developer.nvidia.com/cuda-toolkit), - Optionally, for GPU development:
if you have an Nvidia or AMD GPU and plan to develop on pystencils' GPU capabilities - At least CUDA 11 for Nvidia GPUs, or
- At least ROCm/HIP 6.1 for AMD GPUs.
### Virtual Environment Setup
Once you have these, set up a [virtual environment](https://docs.python.org/3/library/venv.html) for development. Once you have all the prerequesites,
set up a [virtual environment](https://docs.python.org/3/library/venv.html) for development.
This ensures that your system's installation of Python is kept clean, and isolates your development environment This ensures that your system's installation of Python is kept clean, and isolates your development environment
from outside influence. from outside influence.
Use the following commands to create a virtual environment at `.venv` and perform an editable install of pystencils into it: Use the following commands to create a virtual environment at `.venv` and perform an editable install of pystencils into it:
...@@ -74,7 +80,39 @@ Setting `PIP_REQUIRE_VIRTUALENV` ensures that pip refuses to install packages gl ...@@ -74,7 +80,39 @@ Setting `PIP_REQUIRE_VIRTUALENV` ensures that pip refuses to install packages gl
Consider setting this variable globally in your shell's configuration file. Consider setting this variable globally in your shell's configuration file.
::: :::
You are now ready to go! Create a new git branch to work on, open up an IDE, and start coding. :::{admonition} Feature Groups
The above installation instructions assume that you will be running all code checking
and test tasks through `nox`.
If you need or want to run them manually, you will need to add one or more
of these feature groups to your installation:
- `doc`, which contains all dependencies required to build this documentation;
- `dev`, which adds `flake8` for code style checking,
`mypy` for static type checking,
and the `black` formatter;
- `testsuite`, which adds `pytest` plus plugins and some more dependencies required
for running the test suite.
Depending on your development focus, you might also need to add some of the user feature
groups listed in [the installation guide](#installation_guide).
:::
### Cupy for CUDA and HIP
When developing for NVidia or AMD GPUs, you will likely need an installation of [cupy](https://cupy.dev/).
Since cupy has to be built specifically against the libraries of a given CUDA or ROCm version,
it cannot be installed directly via dependency resolution from pystencils.
For instructions on how to install Cupy, refer to their [installation manual](https://docs.cupy.dev/en/stable/install.html).
### Test Your Setup
To check if your setup is complete, a good check is to invoke the pystencils test suite:
```bash
nox -s "testsuite(cpu)"
```
If this finishes without errors, you are ready to go! Create a new git branch to work on, open up an IDE, and start coding.
Make sure your IDE recognizes the virtual environment you created, though. Make sure your IDE recognizes the virtual environment you created, though.
## Static Code Analysis ## Static Code Analysis
......
(_installation)= (installation_guide)=
# Setup and Installation # Setup and Installation
## Install pystencils ## Install pystencils
...@@ -17,7 +17,7 @@ git clone -b v2.0-dev https://i10git.cs.fau.de/pycodegen/pystencils.git ...@@ -17,7 +17,7 @@ git clone -b v2.0-dev https://i10git.cs.fau.de/pycodegen/pystencils.git
pip install -e pystencils pip install -e pystencils
``` ```
### Feature Groups ## Feature Groups
In both cases, you can add a set of optional features to your installation by listing them In both cases, you can add a set of optional features to your installation by listing them
in square brackets (e.g. `pip install -e pystencils[feature1, feature2]`). in square brackets (e.g. `pip install -e pystencils[feature1, feature2]`).
...@@ -33,22 +33,7 @@ The following feature sets are available: ...@@ -33,22 +33,7 @@ The following feature sets are available:
- `use_cython`: Install [Cython](https://cython.org/), which is used internally by pystencils - `use_cython`: Install [Cython](https://cython.org/), which is used internally by pystencils
to accelerate the setup of boundary conditions. to accelerate the setup of boundary conditions.
:::{dropdown} For Developers ## For GPUs
If you are developing pystencils, we recommend you perform an editable install of your
local clone of the repository, with all optional features:
```bash
pip install -e pystencils[alltrafos,interactive,use_cython,doc,testsuite]
```
This includes the additional feature groups `doc`, which contains all dependencies required
to build this documentation, and `tests`, which adds `flake8` for code style checking,
`mypy` for static type checking, and `pytest` plus plugins for running the test suite.
For more information on developing pystencils, see the [](#contribution_guide).
:::
### For GPUs
If you have an Nvidia graphics processor and CUDA installed, you can use pystencils to directly compile If you have an Nvidia graphics processor and CUDA installed, you can use pystencils to directly compile
and execute kernels running on your GPU. and execute kernels running on your GPU.
......
...@@ -55,8 +55,8 @@ automatically select one or the other, depending on the current runtime environm ...@@ -55,8 +55,8 @@ automatically select one or the other, depending on the current runtime environm
:::{note} :::{note}
If `cupy` is not installed, `create_kernel` will raise an exception when using `Target.CurrentGPU`. If `cupy` is not installed, `create_kernel` will raise an exception when using `Target.CurrentGPU`.
When exporting kernels to be compiled externally in an environment where cupy is not available, You can still generate kernels for CUDA or HIP directly even without Cupy;
the GPU target must therefore be set explicitly. you just won't be able to just-in-time compile and run them.
::: :::
Here is a snippet creating a kernel for the locally available GPU target: Here is a snippet creating a kernel for the locally available GPU target:
...@@ -218,7 +218,7 @@ assignments = [ ...@@ -218,7 +218,7 @@ assignments = [
```{code-cell} ipython3 ```{code-cell} ipython3
y = ps.DEFAULTS.spatial_counters[0] y = ps.DEFAULTS.spatial_counters[0]
cfg = ps.CreateKernelConfig() cfg = ps.CreateKernelConfig()
cfg.target= ps.Target.CUDA cfg.target= ps.Target.CurrentGPU
cfg.iteration_slice = ps.make_slice[:, y:] cfg.iteration_slice = ps.make_slice[:, y:]
``` ```
......
...@@ -29,7 +29,6 @@ classifiers = [ ...@@ -29,7 +29,6 @@ classifiers = [
"Source Code" = "https://i10git.cs.fau.de/pycodegen/pystencils" "Source Code" = "https://i10git.cs.fau.de/pycodegen/pystencils"
[project.optional-dependencies] [project.optional-dependencies]
gpu = ['cupy']
alltrafos = ['islpy', 'py-cpuinfo'] alltrafos = ['islpy', 'py-cpuinfo']
bench_db = ['blitzdb', 'pymongo', 'pandas'] bench_db = ['blitzdb', 'pymongo', 'pandas']
interactive = [ interactive = [
...@@ -76,7 +75,7 @@ testsuite = [ ...@@ -76,7 +75,7 @@ testsuite = [
'matplotlib', 'matplotlib',
'py-cpuinfo', 'py-cpuinfo',
'randomgen>=1.18', 'randomgen>=1.18',
'scipy' 'scipy',
] ]
[build-system] [build-system]
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment