Merge branch 'main' into gold/2021

.gitattributes

@@ -0,0 +1 @@
+numba_dppy/_version.py export-subst

.gitignore

@@ -0,0 +1,27 @@
+*.pyc
+*.o
+*.so
+*.dylib
+*.pyd
+*.pdb
+*.egg-info
+*.sw[po]
+*.out
+*.ll
+.coverage
+.nfs*
+tags
+MANIFEST
+
+build/
+docs/_build/
+docs/gh-pages/
+dist/
+htmlcov/
+.idea/
+.vscode/
+.mypy_cache/
+.ipynb_checkpoints/
+__pycache__/
+
+docs/source/developer/autogen*

CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.12.0] - 2020-12-17
+### Added
+- numba-dppy is a standalone package now. Added setup.py and conda recipe.
+- Offload diagnostics.
+- Controllable fallback.
+- Add flags to generate debug symbols.
+- Implementation of `np.linalg.eig`, `np.ndarray.sum`, `np.ndarray.max`, `np.ndarray.min`, `np.ndarray.mean`.
+- Two new re-write passes to convert NumPy calls into a pseudo `numba_dppy` call site to allow target-specific
+  overload of NumPy functions. The rewrite passes is a temporary fix till Numba gains support for target-specific overlaods.
+- Updated to dpCtl 0.5.* and dpNP 0.4.*
+
+### Changed
+- The `dpnp` interface now uses Numba's `@overload` functionality as opposed to the previous `@lower_builtin` method.
+- Rename `DPPL` to `DPPY`.
+- Cleaned test code.
+- `DPPLTestCase` replaced with `unittest.TestCase`.
+- All tests and examples use `with device_context`.
+- Config environment variables starts with `NUMBA_DPPY_`
+(i.e. NUMBA_DPPY_SAVE_IR_FILES and NUMBA_DPPY_SPIRV_VAL)
+- Remove nested folder `dppl` in `tests`.
+- No dependency on `cffi`.
+
+### Removed
+- The old backup file.
+
+## NUMBA Version 0.48.0 + DPPY Version 0.3.0 (June 29, 2020)
+
+This release includes:
+- Caching of dppy.kernels which will improve performance.
+- Addition of support for Intel Advisor which will help in profiling applications.

DEBUGGING.md

@@ -0,0 +1,31 @@
+## Debugging with GDB
+
+Setting the debug environment variable `NUMBA_DPPY_DEBUG` (e.g. `export NUMBA_DPPY_DEBUG=True`) enables 
+the emission of debug info to the llvm and spirv IR.
+To disable debugging set this variable to None: (e.g. `export NUMBA_DPPY_DEBUG= `).  
+Currently, the following debug info is available:
+- Source location (filename and line number) is available. 
+- Setting break points by the line number.
+- Stepping over break points.
+
+### Requirements
+
+Intel® Distribution for GDB installed to the system.  
+Documentation for this debugger can be found in the 
+[Intel® Distribution for GDB documentation](https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/distribution-for-gdb.html).
+
+### Example debug usage
+
+```bash
+$ export NUMBA_DPPY_DEBUG=True
+$ gdb-oneapi -q python  
+(gdb) break numba_dppy/examples/sum.py:14     # Assumes the kernel is in file sum.py, at line 14  
+(gdb) run sum.py
+```
+
+### Limitations
+
+Currently, Numba-dppy provides only initial support of debugging GPU kernels.  
+The following functionality is **not supported** :
+- Printing kernel local variables (e.g. ```info locals```).
+- Stepping over several off-loaded functions.

HowTo.rst

@@ -7,7 +7,7 @@ are listed below with the help of sample code snippets. In this release we have
 the implementation of the OAK approach described in MS138 in section 4.3.2. The
 new decorator is described below.
 
-To access the features driver module have to be imported from numba_dppy.dppl_driver
+To access the features driver module have to be imported from numba_dppy.dppy_driver
 
 New Decorator
 =============
@@ -61,7 +61,7 @@ Primitive types are passed by value to the kernel, currently supported are int,
 Math Kernels
 ============
 
-This release has support for math kernels. See numba_dppy/tests/dppl/test_math_functions.py
+This release has support for math kernels. See numba_dppy/tests/dppy/test_math_functions.py
 for more details.
 
 
@@ -170,6 +170,6 @@ Testing
 
 All examples can be found in numba_dppy/examples/
 
-All tests can be found in numba_dppy/tests/dppl and can be triggered by the following command:
+All tests can be found in numba_dppy/tests/dppy and can be triggered by the following command:
 
 ``python -m numba.runtests numba_dppy.tests``

MANIFEST.in

@@ -3,3 +3,5 @@ include README.md setup.py LICENSE
 
 recursive-include numba_dppy *.cl
 
+include versioneer.py
+include numba_dppy/_version.py

README.md

@@ -20,11 +20,12 @@ https://intelpython.github.io/dpnp/
 ## Dependencies
 
 * numba >=0.51 (IntelPython/numba)
-* dpCtl >=0.3.8
-* dpNP >=0.3 (optional)
+* dpCtl 0.5.*
+* dpNP 0.4.* (optional)
 * llvm-spirv (SPIRV generation from LLVM IR)
 * llvmdev (LLVM IR generation)
 * spirv-tools
+* scipy (for testing)
 
 ## dpPy
 
@@ -43,7 +44,7 @@ See folder `numba_dppy/tests`.
 
 Run tests:
 ```bash
-python -m numba.runtests numba_dppy.tests
+python -m unittest numba_dppy.tests
 ```
 
 ## Examples
@@ -57,9 +58,17 @@ python numba_dppy/examples/sum.py
 
 ## How Tos
 
-Refer the HowTo.rst guide for an overview of the programming semantics,
+Refer the [HowTo.rst](HowTo.rst) guide for an overview of the programming semantics,
 examples, supported functionalities, and known issues.
 
+## Debugging
+
+Please follow instructions in the [DEBUGGING.md](DEBUGGING.md)
+
 ## Reporting issues
 
 Please use https://github.com/IntelPython/numba-dppy/issues to report issues and bugs.
+
+## Features
+
+Read this guide for additional features [INDEX.md](docs/INDEX.md)

conda-recipe/meta.yaml

@@ -17,17 +17,21 @@ requirements:
         - python
         - setuptools
         - cython
-        - llvm-spirv
         - numba
-        - dpctl
-        - dpnp
+        - dpctl 0.5.*
+        - dpnp 0.4.*  # [linux]
     run:
         - python
         - numba >=0.51
-        - dpctl
+        - dpctl 0.5.*
         - spirv-tools
         - llvm-spirv
-        - dpnp
+        - llvmdev
+        - dpnp 0.4.*  # [linux]
+
+test:
+  requires:
+    - scipy  # [linux]
 
 about:
     home: https://github.com/IntelPython/numba-dppy

conda-recipe/run_test.bat

@@ -1,3 +1,8 @@
+REM For activating OpenCL CPU
+call "%ONEAPI_ROOT%\compiler\latest\env\vars.bat"
+
+@echo on
+
 python -m numba.runtests -b -v -m -- numba_dppy.tests
 IF %ERRORLEVEL% NEQ 0 exit /B 1
 

conda-recipe/run_test.sh

@@ -1,6 +1,12 @@
 #!/bin/bash
 
-set -ex
+set -e
+
+# For activating OpenCL CPU
+source ${ONEAPI_ROOT}/compiler/latest/env/vars.sh
+source ${ONEAPI_ROOT}/tbb/latest/env/vars.sh
+
+set -x
 
 python -m numba.runtests -b -v -m -- numba_dppy.tests
 

docs/INDEX.md

@@ -0,0 +1,18 @@
+# numba-dppy
+
+Below is the functionality that is implemented in numba-dppy. You can follow the detailed descriptions of some of the features.
+
+## Offload Diagnostics
+
+Setting the debug environment variable `NUMBA_DPPY_OFFLOAD_DIAGNOSTICS `
+(e.g. `export NUMBA_DPPY_OFFLOAD_DIAGNOSTICS=1`) enables the parallel and offload diagnostics information.
+
+If set to an integer value between 1 and 4 (inclusive) diagnostic information about parallel transforms undertaken by Numba will be written to STDOUT. The higher the value set the more detailed the information produced.
+In the "Auto-offloading" section there is the information on which device (device name) this parfor or kernel was offloaded.
+
+## Controllable Fallback
+
+With the default behavior of numba-dppy, if a section of code cannot be offloaded on the GPU, then it is automatically executed on the CPU and printed a warning. This behavior only applies to njit functions and auto-offloading of numpy functions, array expressions, and prange loops.
+
+Setting the debug environment variable `NUMBA_DPPY_FALLBACK_OPTION `
+(e.g. `export NUMBA_DPPY_FALLBACK_OPTION=0`) enables the code is not automatically offload to the CPU, and an error occurs. This is necessary in order to understand at an early stage which parts of the code do not work on the GPU, and not to wait for the program to execute on the CPU if you don't need it.