kernel-tuner 0.4.2__tar.gz → 1.0__tar.gz

kernel_tuner-1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.1
+Name: kernel_tuner
+Version: 1.0
+Summary: An easy to use CUDA/OpenCL kernel tuner in Python
+Home-page: https://KernelTuner.github.io/kernel_tuner/
+License: Apache-2.0
+Keywords: auto-tuning,gpu,computing,pycuda,cuda,pyopencl,opencl
+Author: Ben van Werkhoven
+Author-email: b.vanwerkhoven@esciencecenter.nl
+Requires-Python: >=3.8,<3.12
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: GPU
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Distributed Computing
+Provides-Extra: cuda
+Provides-Extra: cuda-opencl
+Provides-Extra: hip
+Provides-Extra: opencl
+Provides-Extra: tutorial
+Requires-Dist: jsonschema
+Requires-Dist: jupyter (>=1.0.0,<2.0.0) ; extra == "tutorial"
+Requires-Dist: matplotlib (>=3.5.0,<4.0.0) ; extra == "tutorial"
+Requires-Dist: numpy (>=1.22.2,<2.0.0)
+Requires-Dist: nvidia-ml-py (>=12.535.108,<13.0.0) ; extra == "cuda" or extra == "tutorial"
+Requires-Dist: packaging
+Requires-Dist: pandas (>=2.0.0,<3.0.0)
+Requires-Dist: pycuda (>=2024.1,<2025.0) ; extra == "cuda" or extra == "cuda-opencl"
+Requires-Dist: pyhip-interface ; extra == "hip"
+Requires-Dist: pynvml (>=11.4.1,<12.0.0) ; extra == "cuda"
+Requires-Dist: pyopencl ; extra == "opencl" or extra == "cuda-opencl"
+Requires-Dist: python-constraint2 (>=2.0.0b5,<3.0.0)
+Requires-Dist: scikit-learn (>=1.0.2,<2.0.0)
+Requires-Dist: scipy (>=1.10.1,<2.0.0)
+Requires-Dist: xmltodict
+Project-URL: Documentation, https://KernelTuner.github.io/kernel_tuner/
+Project-URL: Repository, https://github.com/KernelTuner/kernel_tuner
+Project-URL: Tracker, https://github.com/KernelTuner/kernel_tuner/issues
+Description-Content-Type: text/markdown
+
+
+
+<div align="center">
+  <img width="500px" src="doc/images/KernelTuner-logo.png"/>
+</div>
+
+---
+[![Build Status](https://github.com/KernelTuner/kernel_tuner/actions/workflows/build-test-python-package.yml/badge.svg)](https://github.com/KernelTuner/kernel_tuner/actions/workflows/build-test-python-package.yml)
+[![CodeCov Badge](https://codecov.io/gh/KernelTuner/kernel_tuner/branch/master/graph/badge.svg)](https://codecov.io/gh/KernelTuner/kernel_tuner)
+[![PyPi Badge](https://img.shields.io/pypi/v/kernel_tuner.svg?colorB=blue)](https://pypi.python.org/pypi/kernel_tuner/)
+[![Zenodo Badge](https://zenodo.org/badge/54894320.svg)](https://zenodo.org/badge/latestdoi/54894320)
+[![SonarCloud Badge](https://sonarcloud.io/api/project_badges/measure?project=KernelTuner_kernel_tuner&metric=alert_status)](https://sonarcloud.io/dashboard?id=KernelTuner_kernel_tuner)
+[![OpenSSF Badge](https://bestpractices.coreinfrastructure.org/projects/6573/badge)](https://bestpractices.coreinfrastructure.org/projects/6573)
+[![FairSoftware Badge](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green)](https://fair-software.eu)
+---
+
+
+Create optimized GPU applications in any mainstream GPU 
+programming language (CUDA, HIP, OpenCL, OpenACC).
+
+What Kernel Tuner does:
+
+- Works as an external tool to benchmark and optimize GPU kernels in isolation
+- Can be used directly on existing kernel code without extensive changes 
+- Can be used with applications in any host programming language
+- Blazing fast search space construction
+- More than 20 [optimization algorithms](https://kerneltuner.github.io/kernel_tuner/stable/optimization.html) to speedup tuning
+- Energy measurements and optimizations [(power capping, clock frequency tuning)](https://arxiv.org/abs/2211.07260)
+- ... and much more! For example, [caching](https://kerneltuner.github.io/kernel_tuner/stable/cache_files.html), [output verification](https://kerneltuner.github.io/kernel_tuner/stable/correctness.html), [tuning host and device code](https://kerneltuner.github.io/kernel_tuner/stable/hostcode.html), [user defined metrics](https://kerneltuner.github.io/kernel_tuner/stable/metrics.html), see [the full documentation](https://kerneltuner.github.io/kernel_tuner/stable/index.html).
+
+
+
+## Installation
+
+- First, make sure you have your [CUDA](https://kerneltuner.github.io/kernel_tuner/stable/install.html#cuda-and-pycuda), [OpenCL](https://kerneltuner.github.io/kernel_tuner/stable/install.html#opencl-and-pyopencl), or [HIP](https://kerneltuner.github.io/kernel_tuner/stable/install.html#hip-and-pyhipl) compiler installed
+- Then type: `pip install kernel_tuner[cuda]`, `pip install kernel_tuner[opencl]`, or `pip install kernel_tuner[hip]`
+- or why not all of them: `pip install kernel_tuner[cuda,opencl,hip]`
+
+More information on installation, also for other languages, in the [installation guide](http://kerneltuner.github.io/kernel_tuner/stable/install.html).
+
+## Example
+
+```python
+import numpy as np
+from kernel_tuner import tune_kernel
+
+kernel_string = """
+__global__ void vector_add(float *c, float *a, float *b, int n) {
+    int i = blockIdx.x * block_size_x + threadIdx.x;
+    if (i<n) {
+        c[i] = a[i] + b[i];
+    }
+}
+"""
+
+n = np.int32(10000000)
+
+a = np.random.randn(n).astype(np.float32)
+b = np.random.randn(n).astype(np.float32)
+c = np.zeros_like(a)
+
+args = [c, a, b, n]
+
+tune_params = {"block_size_x": [32, 64, 128, 256, 512]}
+
+tune_kernel("vector_add", kernel_string, n, args, tune_params)
+```
+
+More [examples here](https://kerneltuner.github.io/kernel_tuner/stable/examples.html).
+
+## Resources
+
+- [Full documentation](https://kerneltuner.github.io/kernel_tuner/stable/)
+- Guides:
+  - [Getting Started](https://kerneltuner.github.io/kernel_tuner/stable/quickstart.html)
+  - [Convolution](https://kerneltuner.github.io/kernel_tuner/stable/convolution.html)
+  - [Diffusion](https://kerneltuner.github.io/kernel_tuner/stable/diffusion.html)
+  - [Matrix Multiplication](https://kerneltuner.github.io/kernel_tuner/stable/matrix_multiplication.html)
+- Features & Use cases:
+  - [Full list of examples](https://kerneltuner.github.io/kernel_tuner/stable/examples.html)
+  - [Output verification](https://kerneltuner.github.io/kernel_tuner/stable/correctness.html)
+  - [Test GPU code from Python](https://github.com/KernelTuner/kernel_tuner/blob/master/examples/cuda/test_vector_add.py)
+  - [Tune code in both host and device code](https://kerneltuner.github.io/kernel_tuner/stable/hostcode.html)
+  - [Optimization algorithms](https://kerneltuner.github.io/kernel_tuner/stable/optimization.html)
+  - [Mixed-precision & Accuracy tuning](https://github.com/KernelTuner/kernel_tuner/blob/master/examples/cuda/accuracy.py)
+  - [Custom metrics & tuning objectives](https://kerneltuner.github.io/kernel_tuner/stable/metrics.html)
+- **Kernel Tuner Tutorial** slides [[PDF]](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/slides/2022_SURF/SURF22-Kernel-Tuner-Tutorial.pdf), hands-on:
+  - Vector add example [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/00_Kernel_Tuner_Introduction.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/00_Kernel_Tuner_Introduction.ipynb)
+  - Tuning thread block dimensions [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/01_Kernel_Tuner_Getting_Started.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/01_Kernel_Tuner_Getting_Started.ipynb)
+  - Search space restrictions & output verification [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/02_Kernel_Tuner_Intermediate.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/02_Kernel_Tuner_Intermediate.ipynb)
+  - Visualization & search space optimization [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/03_Kernel_Tuner_Advanced.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/03_Kernel_Tuner_Advanced.ipynb)
+- **Energy Efficient GPU Computing** tutorial slides [[PDF]](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/slides/2023_Supercomputing/SC23.pdf), hands-on:
+  - Kernel Tuner for GPU energy measurements [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/energy/00_Kernel_Tuner_Introduction.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/energy/00_Kernel_Tuner_Introduction.ipynb)
+  - Code optimizations for energy [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/energy/01_Code_Optimizations_for_Energy.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/energy/01_Code_Optimizations_for_Energy.ipynb)
+  - Mixed precision and accuracy tuning [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/energy/02_Mixed_precision_programming.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/energy/02_Mixed_precision_programming.ipynb)
+  - Optimzing for time vs for energy [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/energy/03_energy_efficient_computing.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/energy/03_energy_efficient_computing.ipynb)
+
+
+## Kernel Tuner ecosystem
+
+<img width="250px" src="doc/images/kernel_launcher.png"/><br />C++ magic to integrate auto-tuned kernels into C++ applications 
+
+<img width="250px" src="doc/images/kernel_float.png"/><br />C++ data types for mixed-precision CUDA kernel programming
+
+<img width="275px" src="doc/images/kernel_dashboard.png"/><br />Monitor, analyze, and visualize auto-tuning runs
+
+
+## Communication & Contribution
+
+- GitHub [Issues](https://github.com/KernelTuner/kernel_tuner/issues): Bug reports, install issues, feature requests, work in progress
+- GitHub [Discussion group](https://github.com/orgs/KernelTuner/discussions): General questions, Q&A, thoughts
+
+Contributions are welcome! For feature requests, bug reports, or usage problems, please feel free to create an issue.
+For more extensive contributions, check the [contribution guide](http://kerneltuner.github.io/kernel_tuner/stable/contributing.html).
+
+## Citation
+
+If you use Kernel Tuner in research or research software, please cite the most relevant among the [publications on Kernel 
+Tuner](https://kerneltuner.github.io/kernel_tuner/stable/#citation). To refer to the project as a whole, please cite:
+
+```latex
+@article{kerneltuner,
+  author  = {Ben van Werkhoven},
+  title   = {Kernel Tuner: A search-optimizing GPU code auto-tuner},
+  journal = {Future Generation Computer Systems},
+  year = {2019},
+  volume  = {90},
+  pages = {347-358},
+  url = {https://www.sciencedirect.com/science/article/pii/S0167739X18313359},
+  doi = {https://doi.org/10.1016/j.future.2018.08.004}
+}
+```
+
+

kernel_tuner-1.0/README.md

@@ -0,0 +1,133 @@
+
+
+<div align="center">
+  <img width="500px" src="doc/images/KernelTuner-logo.png"/>
+</div>
+
+---
+[![Build Status](https://github.com/KernelTuner/kernel_tuner/actions/workflows/build-test-python-package.yml/badge.svg)](https://github.com/KernelTuner/kernel_tuner/actions/workflows/build-test-python-package.yml)
+[![CodeCov Badge](https://codecov.io/gh/KernelTuner/kernel_tuner/branch/master/graph/badge.svg)](https://codecov.io/gh/KernelTuner/kernel_tuner)
+[![PyPi Badge](https://img.shields.io/pypi/v/kernel_tuner.svg?colorB=blue)](https://pypi.python.org/pypi/kernel_tuner/)
+[![Zenodo Badge](https://zenodo.org/badge/54894320.svg)](https://zenodo.org/badge/latestdoi/54894320)
+[![SonarCloud Badge](https://sonarcloud.io/api/project_badges/measure?project=KernelTuner_kernel_tuner&metric=alert_status)](https://sonarcloud.io/dashboard?id=KernelTuner_kernel_tuner)
+[![OpenSSF Badge](https://bestpractices.coreinfrastructure.org/projects/6573/badge)](https://bestpractices.coreinfrastructure.org/projects/6573)
+[![FairSoftware Badge](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green)](https://fair-software.eu)
+---
+
+
+Create optimized GPU applications in any mainstream GPU 
+programming language (CUDA, HIP, OpenCL, OpenACC).
+
+What Kernel Tuner does:
+
+- Works as an external tool to benchmark and optimize GPU kernels in isolation
+- Can be used directly on existing kernel code without extensive changes 
+- Can be used with applications in any host programming language
+- Blazing fast search space construction
+- More than 20 [optimization algorithms](https://kerneltuner.github.io/kernel_tuner/stable/optimization.html) to speedup tuning
+- Energy measurements and optimizations [(power capping, clock frequency tuning)](https://arxiv.org/abs/2211.07260)
+- ... and much more! For example, [caching](https://kerneltuner.github.io/kernel_tuner/stable/cache_files.html), [output verification](https://kerneltuner.github.io/kernel_tuner/stable/correctness.html), [tuning host and device code](https://kerneltuner.github.io/kernel_tuner/stable/hostcode.html), [user defined metrics](https://kerneltuner.github.io/kernel_tuner/stable/metrics.html), see [the full documentation](https://kerneltuner.github.io/kernel_tuner/stable/index.html).
+
+
+
+## Installation
+
+- First, make sure you have your [CUDA](https://kerneltuner.github.io/kernel_tuner/stable/install.html#cuda-and-pycuda), [OpenCL](https://kerneltuner.github.io/kernel_tuner/stable/install.html#opencl-and-pyopencl), or [HIP](https://kerneltuner.github.io/kernel_tuner/stable/install.html#hip-and-pyhipl) compiler installed
+- Then type: `pip install kernel_tuner[cuda]`, `pip install kernel_tuner[opencl]`, or `pip install kernel_tuner[hip]`
+- or why not all of them: `pip install kernel_tuner[cuda,opencl,hip]`
+
+More information on installation, also for other languages, in the [installation guide](http://kerneltuner.github.io/kernel_tuner/stable/install.html).
+
+## Example
+
+```python
+import numpy as np
+from kernel_tuner import tune_kernel
+
+kernel_string = """
+__global__ void vector_add(float *c, float *a, float *b, int n) {
+    int i = blockIdx.x * block_size_x + threadIdx.x;
+    if (i<n) {
+        c[i] = a[i] + b[i];
+    }
+}
+"""
+
+n = np.int32(10000000)
+
+a = np.random.randn(n).astype(np.float32)
+b = np.random.randn(n).astype(np.float32)
+c = np.zeros_like(a)
+
+args = [c, a, b, n]
+
+tune_params = {"block_size_x": [32, 64, 128, 256, 512]}
+
+tune_kernel("vector_add", kernel_string, n, args, tune_params)
+```
+
+More [examples here](https://kerneltuner.github.io/kernel_tuner/stable/examples.html).
+
+## Resources
+
+- [Full documentation](https://kerneltuner.github.io/kernel_tuner/stable/)
+- Guides:
+  - [Getting Started](https://kerneltuner.github.io/kernel_tuner/stable/quickstart.html)
+  - [Convolution](https://kerneltuner.github.io/kernel_tuner/stable/convolution.html)
+  - [Diffusion](https://kerneltuner.github.io/kernel_tuner/stable/diffusion.html)
+  - [Matrix Multiplication](https://kerneltuner.github.io/kernel_tuner/stable/matrix_multiplication.html)
+- Features & Use cases:
+  - [Full list of examples](https://kerneltuner.github.io/kernel_tuner/stable/examples.html)
+  - [Output verification](https://kerneltuner.github.io/kernel_tuner/stable/correctness.html)
+  - [Test GPU code from Python](https://github.com/KernelTuner/kernel_tuner/blob/master/examples/cuda/test_vector_add.py)
+  - [Tune code in both host and device code](https://kerneltuner.github.io/kernel_tuner/stable/hostcode.html)
+  - [Optimization algorithms](https://kerneltuner.github.io/kernel_tuner/stable/optimization.html)
+  - [Mixed-precision & Accuracy tuning](https://github.com/KernelTuner/kernel_tuner/blob/master/examples/cuda/accuracy.py)
+  - [Custom metrics & tuning objectives](https://kerneltuner.github.io/kernel_tuner/stable/metrics.html)
+- **Kernel Tuner Tutorial** slides [[PDF]](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/slides/2022_SURF/SURF22-Kernel-Tuner-Tutorial.pdf), hands-on:
+  - Vector add example [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/00_Kernel_Tuner_Introduction.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/00_Kernel_Tuner_Introduction.ipynb)
+  - Tuning thread block dimensions [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/01_Kernel_Tuner_Getting_Started.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/01_Kernel_Tuner_Getting_Started.ipynb)
+  - Search space restrictions & output verification [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/02_Kernel_Tuner_Intermediate.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/02_Kernel_Tuner_Intermediate.ipynb)
+  - Visualization & search space optimization [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/03_Kernel_Tuner_Advanced.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/hands-on/cuda/03_Kernel_Tuner_Advanced.ipynb)
+- **Energy Efficient GPU Computing** tutorial slides [[PDF]](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/slides/2023_Supercomputing/SC23.pdf), hands-on:
+  - Kernel Tuner for GPU energy measurements [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/energy/00_Kernel_Tuner_Introduction.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/energy/00_Kernel_Tuner_Introduction.ipynb)
+  - Code optimizations for energy [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/energy/01_Code_Optimizations_for_Energy.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/energy/01_Code_Optimizations_for_Energy.ipynb)
+  - Mixed precision and accuracy tuning [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/energy/02_Mixed_precision_programming.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/energy/02_Mixed_precision_programming.ipynb)
+  - Optimzing for time vs for energy [[.ipynb](https://github.com/KernelTuner/kernel_tuner_tutorial/blob/master/energy/03_energy_efficient_computing.ipynb)] [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KernelTuner/kernel_tuner_tutorial/blob/master/energy/03_energy_efficient_computing.ipynb)
+
+
+## Kernel Tuner ecosystem
+
+<img width="250px" src="doc/images/kernel_launcher.png"/><br />C++ magic to integrate auto-tuned kernels into C++ applications 
+
+<img width="250px" src="doc/images/kernel_float.png"/><br />C++ data types for mixed-precision CUDA kernel programming
+
+<img width="275px" src="doc/images/kernel_dashboard.png"/><br />Monitor, analyze, and visualize auto-tuning runs
+
+
+## Communication & Contribution
+
+- GitHub [Issues](https://github.com/KernelTuner/kernel_tuner/issues): Bug reports, install issues, feature requests, work in progress
+- GitHub [Discussion group](https://github.com/orgs/KernelTuner/discussions): General questions, Q&A, thoughts
+
+Contributions are welcome! For feature requests, bug reports, or usage problems, please feel free to create an issue.
+For more extensive contributions, check the [contribution guide](http://kerneltuner.github.io/kernel_tuner/stable/contributing.html).
+
+## Citation
+
+If you use Kernel Tuner in research or research software, please cite the most relevant among the [publications on Kernel 
+Tuner](https://kerneltuner.github.io/kernel_tuner/stable/#citation). To refer to the project as a whole, please cite:
+
+```latex
+@article{kerneltuner,
+  author  = {Ben van Werkhoven},
+  title   = {Kernel Tuner: A search-optimizing GPU code auto-tuner},
+  journal = {Future Generation Computer Systems},
+  year = {2019},
+  volume  = {90},
+  pages = {347-358},
+  url = {https://www.sciencedirect.com/science/article/pii/S0167739X18313359},
+  doi = {https://doi.org/10.1016/j.future.2018.08.004}
+}
+```
+

{kernel_tuner-0.4.2 → kernel_tuner-1.0}/kernel_tuner/__init__.py

@@ -1,5 +1,6 @@
-
 from kernel_tuner.integration import store_results, create_device_targets
-
 from kernel_tuner.interface import tune_kernel, run_kernel
 
+from importlib.metadata import version
+
+__version__ = version(__package__)

kernel_tuner-1.0/kernel_tuner/accuracy.py

@@ -0,0 +1,308 @@
+from collections import UserDict
+from typing import Dict
+import numpy as np
+import logging
+import re
+
+from kernel_tuner.observers import OutputObserver
+
+
+class Tunable(UserDict):
+    def __init__(self, param_key: str, arrays: Dict):
+        """The ``Tunable`` object can be used as an input argument when tuning
+        kernels. It is a container that holds several arrays internally and
+        selects one array during benchmarking based on the value of a tunable parameter.
+
+        Example
+        -------
+        Consider this example::
+
+            arg = Tunable("matrix_layout", dict("c"=matrix, "f"=matrix.transpose()))
+
+        In this example, we create a Tunable object that selects either matrix
+        or matrix.transpose() for benchmarking, depending on the value of the
+        tunable parameter "matrix_layout". The first argument is the name of the tunable
+        paramater. The second argument is a dictionary that maps the tunable parameter
+        values "c" and "f" to the arrays ``matrix`` and ``matrix.transpose()``, respectively.
+        During benchmarking, the Tunable object selects the array passed to the kernel based
+        on the value of "matrix_layout".
+
+        :param param_key: : The tunable parameter used to select the array for benchmarking.
+        :param arrays: A dictionary that maps the value of that tunable parameter to options.
+        """
+        if isinstance(arrays, (tuple, list)):
+            arrays = dict(enumerate(arrays))
+
+        super().__init__(arrays)
+        self.param_key = param_key
+
+    def select_for_configuration(self, params):
+        if callable(self.param_key):
+            option = self.param_key(params)
+        elif self.param_key in params:
+            option = params[self.param_key]
+        else:
+            option = eval(self.param_key, params, params)
+
+        if option not in self.data:
+            list = ", ".join(map(str, self.data.keys()))
+            raise KeyError(
+                f"'{option}' is not a valid parameter value, should be one of: {list}"
+            )
+
+        return self.data[option]
+
+    def __call__(self, params):
+        return self.select_for_configuration(params)
+
+
+def _find_bfloat16_if_available():
+    # Try to get bfloat16 if available.
+    try:
+        from bfloat16 import bfloat16
+        return bfloat16
+    except ImportError:
+        pass
+
+    try:
+        from tensorflow import bfloat16
+        return bfloat16.as_numpy_dtype
+    except ImportError:
+        pass
+
+    logging.warning(
+        "could not find `bfloat16` data type for numpy, "
+        + "please install either the package `bfloat16` or `tensorflow`"
+    )
+
+    return None
+
+
+def _to_float_dtype(x: str) -> np.dtype:
+    """Convert a string to a numpy data type (``dtype``). This function recognizes
+    common names (such as ``f16`` or ``kfloat``), and uses ``np.dtype(x)`` as a
+    fallback.
+    """
+    if isinstance(x, str):
+        x = x.lower()
+
+    if x in ("bfloat16", "bf16", "kbfloat16", "__nv_bfloat16"):
+        result = _find_bfloat16_if_available()
+        if result is not None:
+            return result
+
+    if x in ("half", "f16", "float16", "__half", "khalf", 16):
+        return np.half
+    if x in ("float", "single", "f32", "float32", "kfloat", 32):
+        return np.float32
+    if x in ("double", "f64", "float64", "kdouble", 64):
+        return np.float64
+
+    return np.dtype(x)
+
+
+class TunablePrecision(Tunable):
+    def __init__(
+        self, param_key: str, array: np.ndarray, dtypes: Dict[str, np.dtype] = None
+    ):
+        """The ``Tunable`` object can be used as an input argument when tuning
+        kernels. It is a container that internally holds several arrays
+        containing the same data, but stored in using different levels of
+        precision. During benchamrking, one array is selected based on the value
+        of the tunable parameter called ``param_key``.
+
+        Example
+        -------
+        Consider this example::
+
+            arg = TunablePrecision("matrix_type", matrix)
+
+        This creates a ``TunablePrecision`` argument that selects the required
+        floating-point precision for ``matrix`` based on the tunable parameter
+        ``"matrix_type"``.
+
+        :param param_key: The tunable parameter used to select the level of precision.
+        :param array: The input array. It will automatically be converted to
+                      all data types given by ``dtypes``.
+        :param dtypes: Dictionary that maps names to numpy data types. The default
+                       types are ``double``, ``float``, and ``half``.
+        """
+        # If no dtypes are given, generate a default list
+        if not dtypes:
+            dtypes = dict(half=np.half, float=np.single, double=np.double)
+
+            bfloat16 = _find_bfloat16_if_available()
+            if bfloat16 is not None:
+                dtypes["bfloat16"] = bfloat16
+
+
+        # If dtype is a list, convert it to a dictionary
+        if isinstance(dtypes, (list, tuple)):
+            dtypes = dict((name, _to_float_dtype(name)) for name in dtypes)
+
+        arrays = dict()
+        for precision, dtype in dtypes.items():
+            # We convert the array into a `np.ndarray` by using `np.array`.
+            # However, if the value is a numpy scalar, then we do not want to
+            # convert it into an array but instead keep the original value
+            if not isinstance(array, np.generic):
+                array = np.array(array)
+
+            arrays[precision] = array.astype(dtype)
+
+        super().__init__(param_key, arrays)
+
+
+def error_metric_from_name(user_key, EPS=1e-8):
+    """Find the error metric function for the given name.
+
+    Returns an function that takes two parameters (the ground-truth and the
+    estimated values) as numpy arrays and returns the error between the two
+    according to the given error metric.
+
+    Valid values for the ``key`` are:
+
+    * MSE (mean square error)
+    * RSME (Root mean square error)
+    * NRMSE (normalized root mean square error)
+    * RMSRE (root mean square relative error)
+    * RMSLE (root mean square log error)
+    * MAE (mean absolute error)
+    * MRE (mean relative error)
+    * MALE (mean absolute log error)
+    * max (maximum absolute error)
+    * max rel (maximum relative error)
+
+    The value of `EPS` is used for relative errors to prevent division by zero.
+    ``
+    """
+
+    # Prepocess the provided name:
+    # - convert to lowercase
+    # - remove the word "error"
+    # - remove underscores and dashes
+    # - strip whitespaces
+    # - replace common abreviations
+    key = user_key.lower()
+    key = re.sub(r"\berror\b", " ", key)
+    key = re.sub(r"[\s_-]+", " ", key)
+    key = key.strip()
+
+    replacements = {
+        "average": "mean",
+        "avg": "mean",
+        "square": "squared",
+        "sq": "squared",
+        "max": "maximum",
+        "rel": "relative",
+        "abs": "absolute",
+        "log": "logarithmic",
+    }
+
+    for pattern, replacement in replacements.items():
+        key = re.sub(rf"\b{pattern}\b", replacement, key)
+
+    # Select the right metric
+    if key in ("mse", "mean squared"):
+
+        def metric(a, b):
+            return np.average(np.square(a - b))
+
+    elif key in ("rmse", "root mean squared"):
+
+        def metric(a, b):
+            return np.sqrt(np.average(np.square(a - b)))
+
+    elif key in ("nrmse", "normalized root mean squared"):
+
+        def metric(a, b):
+            return np.sqrt(np.average(np.square(a - b)) / np.average(np.square(a)))
+
+    elif key in ("mae", "absolute", "mean absolute"):
+
+        def metric(a, b):
+            return np.average(np.abs(a - b))
+
+    elif key in ("mre", "relative", "mean relative"):
+
+        def metric(a, b):
+            return np.average(np.abs(a - b) / np.maximum(np.abs(a), EPS))
+
+    elif key in ("rmsre", "root mean squared relative"):
+
+        def metric(a, b):
+            return np.sqrt(np.average(np.square(a - b) / np.square(np.maximum(a, EPS))))
+
+    elif key in ("male", "mean absolute logarithmic"):
+
+        def metric(a, b):
+            return np.average(np.abs(np.log10(a + EPS) - np.log10(b + EPS)))
+
+    elif key in ("rmsle", "root mean squared logarithmic"):
+
+        def metric(a, b):
+            return np.sqrt(np.average(np.square(np.log10(a + EPS) - np.log10(b + EPS))))
+
+    elif key in ("maximum absolute", "maximum"):
+
+        def metric(a, b):
+            return np.amax(np.abs(a - b))
+
+    elif key in ("maximum relative",):
+
+        def metric(a, b):
+            return np.amax(np.abs(a - b) / np.maximum(np.abs(a), EPS))
+
+    else:
+        raise ValueError(f"invalid error metric provided: {user_key}")
+
+    # cast both arguments to f64 before passing them to the metric
+    return lambda a, b: metric(
+        a.astype(np.float64, copy=False), b.astype(np.float64, copy=False)
+    )
+
+
+class AccuracyObserver(OutputObserver):
+    """``AccuracyObserver`` measures the error on the output produced by a kernel
+    by comparing the output against a reference output.
+
+    By default, it uses the root mean-squared error (RMSE) and uses the
+    metric name ``"error"``.
+    """
+
+    def __init__(self, metric=None, key="error", *, atol=1e-8):
+        """Create a new ``AccuracyObserver``.
+
+        :param metric: The error metric. This should be a string that is
+                       accepted by ``error_metric_from_name`` such as ``"absolute error"``
+                       or ``"relative error"``. Alternatively, it can be a
+                       function that accepts two numpy arrays as arguments
+                       (the reference output and the kernel output)
+        :param key: The name of this metric in the results.
+        :param atol: The tolerance used in relative metrics to prevent
+                     division by zero. It is ignored by absolute error metrics.
+        """
+
+        # Default metric is RMSE
+        if not metric:
+            metric = "rmse"
+
+        # If it is a string, convert it to a function
+        if isinstance(metric, str):
+            metric = error_metric_from_name(metric, atol)
+
+        self.key = key
+        self.metric = metric
+        self.result = None
+
+    def process_output(self, answers, outputs):
+        errors = []
+
+        for answer, output in zip(answers, outputs):
+            if answer is not None:
+                errors.append(self.metric(answer, output))
+
+        self.result = max(errors)
+
+    def get_results(self):
+        return dict([(self.key, self.result)])