Docs for Ufuncs

docs/dppy/device-functions.rst

@@ -1,3 +1,5 @@
+.. _device-functions:
+
 Writing Device Functions
 ========================
 

docs/dppy/index.rst

@@ -4,6 +4,8 @@ Numba for DPPY GPUs
 ===================
 
 .. toctree::
+   :maxdepth: 2
 
    device-functions.rst
    reduction.rst
+   ufunc.rst

docs/dppy/reduction.rst

@@ -1,7 +1,7 @@
 GPU Reduction
 =============
 
-DPPY does not provide specific features for implementing reductions on GPU.
+DPPY does not provide specific decorators for implementing reductions on GPU.
 Examples contain different approaches for calculating reductions using both
 device and host.
 
@@ -37,7 +37,8 @@ Full example can be found at ``numba_dppy/examples/sum_reduction_ocl.py``.
 Example 3
 ~~~~~~~~~
 
-Full example can be found at ``numba_dppy/examples/sum_reduction_recursive_ocl.py``
+Full example can be found at
+``numba_dppy/examples/sum_reduction_recursive_ocl.py``.
 
 .. literalinclude:: ../../numba_dppy/examples/sum_reduction_recursive_ocl.py
    :pyobject: sum_reduction_kernel

docs/dppy/ufunc.rst

@@ -0,0 +1,65 @@
+DPPY Universal functions
+========================
+
+See `Creating NumPy universal functions`_ in Numba for more information about
+``@vectorize`` and ``@guvectorize``.
+
+DPPY supports ``@vectorize`` and does not support ``@guvectorize`` yet.
+
+DPPY ``@vectorize`` returns a ufunc-like object which is a close analog
+but not fully compatible with a regular NumPy ufunc.
+
+DPPY ufunc kernels don't have the ability to call other DPPY device functions yet.
+See :ref:`device-functions`.
+
+Example: Basic Example
+----------------------
+
+Full example can be found at ``numba_dppy/examples/vectorize.py``.
+
+.. literalinclude:: ../../numba_dppy/examples/vectorize.py
+   :pyobject: ufunc_kernel
+
+.. literalinclude:: ../../numba_dppy/examples/vectorize.py
+   :pyobject: test_ufunc
+
+Example: Calling Functions from ``math``
+----------------------------------------
+
+Full example can be found at ``numba_dppy/examples/blacksholes_njit.py``.
+
+.. literalinclude:: ../../numba_dppy/examples/blacksholes_njit.py
+   :pyobject: cndf2
+
+Transition from Numba CUDA
+--------------------------
+
+Numba CUDA requires ``target='cuda'`` parameter for ``@vectorize`` and
+``@guvectorize``.
+DPPY does not require ``target`` parameter for ``@vectorize``. Just use
+``dpctl.device_context`` for running universal function on DPPY devices.
+
+Limitations
+-----------
+
+Running universal functions on DPPY devices requires `Intel Python Numba`_.
+Without `Intel Python Numba`_ ``dpctl.device_context`` will have no effect.
+
+.. _`Intel Python Numba`: https://github.com/IntelPython/numba
+
+
+See also:
+---------
+
+Examples:
+
+- ``numba_dppy/examples/vectorize.py``
+- ``numba_dppy/examples/blacksholes_njit.py``
+
+Theory:
+
+- `Universal functions (ufunc)`_ in NumPy
+- `Creating NumPy universal functions`_ in Numba
+
+.. _`Universal functions (ufunc)`: http://docs.scipy.org/doc/numpy/reference/ufuncs.html
+.. _`Creating NumPy universal functions`: https://numba.pydata.org/numba-doc/latest/user/vectorize.html

numba_dppy/examples/vectorize.py

@@ -0,0 +1,35 @@
+import numpy as np
+from numba import vectorize
+import dpctl
+
+
+@vectorize(nopython=True)
+def ufunc_kernel(x, y):
+    return x + y
+
+
+def get_context():
+    if dpctl.has_gpu_queues():
+        return "opencl:gpu"
+    elif dpctl.has_cpu_queues():
+        return "opencl:cpu"
+    else:
+        raise RuntimeError("No device found")
+
+
+def test_ufunc():
+    N = 10
+    dtype = np.float64
+
+    A = np.arange(N, dtype=dtype)
+    B = np.arange(N, dtype=dtype) * 10
+
+    context = get_context()
+    with dpctl.device_context(context):
+        C = ufunc_kernel(A, B)
+
+    print(C)
+
+
+if __name__ == "__main__":
+    test_ufunc()