Added pybind11 example that uses dpctl.SyclQueue to indicate offload

Author: oleksandr-pavlyk

examples/pybind11/use_dpctl_syclqueue/README.md

@@ -0,0 +1,25 @@
+# Usage of dpctl entities in Pybind11
+
+This extension demonstrates how dpctl Python types,
+such as dpctl.SyclQueue could be used in Pybind11
+extensions.
+
+
+# Building extension
+
+```
+source /opt/intel/oneapi/compiler/latest/env/vars.sh
+CXX=dpcpp CC=dpcpp python setup.py build_ext --inplace
+python example.py
+```
+
+# Sample output
+
+```
+(idp) [17:25:27 ansatnuc04 use_dpctl_syclqueue]$ python example.py
+EU count returned by Pybind11 extension 24
+EU count computed by dpctl 24
+
+Computing modular reduction using SYCL on a NumPy array
+Offloaded result agrees with reference one computed by NumPy
+```

examples/pybind11/use_dpctl_syclqueue/example.py

@@ -0,0 +1,48 @@
+#                      Data Parallel Control (dpctl)
+#
+# Copyright 2020-2021 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# coding: utf-8
+
+import numpy as np
+import pybind11_example as eg
+
+import dpctl
+
+q = dpctl.SyclQueue()
+
+# Pass dpctl.SyclQueue to Pybind11 extension
+eu_count = eg.get_max_compute_units(q)
+
+print(f"EU count returned by Pybind11 extension {eu_count}")
+print("EU count computed by dpctl {}".format(q.sycl_device.max_compute_units))
+
+print("")
+print("Computing modular reduction using SYCL on a NumPy array")
+
+X = np.random.randint(low=1, high=2 ** 16 - 1, size=10 ** 6, dtype=np.longlong)
+modulus_p = 347
+
+Y = eg.offloaded_array_mod(
+    q, X, modulus_p
+)  # Y is a regular array with host memory underneath it
+Ynp = X % modulus_p
+
+check = np.array_equal(Y, Ynp)
+
+if check:
+    print("Offloaded result agrees with reference one computed by NumPy")
+else:
+    print("Offloaded array differs from reference result computed by NumPy")

examples/pybind11/use_dpctl_syclqueue/pybind11_example.cpp

@@ -0,0 +1,92 @@
+#include <CL/sycl.hpp>
+#include <cstdint>
+#include <pybind11/numpy.h>
+#include <pybind11/pybind11.h>
+
+#include "../_sycl_queue.h"
+#include "../_sycl_queue_api.h"
+#include "dpctl_sycl_types.h"
+
+namespace py = pybind11;
+
+size_t get_max_compute_units(py::object queue)
+{
+    PyObject *queue_ptr = queue.ptr();
+    if (PyObject_TypeCheck(queue_ptr, &PySyclQueueType)) {
+        DPCTLSyclQueueRef QRef =
+            get_queue_ref(reinterpret_cast<PySyclQueueObject *>(queue_ptr));
+        sycl::queue *q = reinterpret_cast<sycl::queue *>(QRef);
+
+        return q->get_device()
+            .get_info<sycl::info::device::max_compute_units>();
+    }
+    else {
+        throw std::runtime_error("expected dpctl.SyclQueue as argument");
+    }
+}
+
+py::array_t<int64_t>
+offloaded_array_mod(py::object queue,
+                    py::array_t<int64_t, py::array::c_style> array,
+                    int64_t mod)
+{
+    sycl::queue *q_ptr;
+
+    PyObject *queue_pycapi = queue.ptr();
+    if (PyObject_TypeCheck(queue_pycapi, &PySyclQueueType)) {
+        DPCTLSyclQueueRef QRef =
+            get_queue_ref(reinterpret_cast<PySyclQueueObject *>(queue_pycapi));
+        q_ptr = reinterpret_cast<sycl::queue *>(QRef);
+    }
+    else {
+        throw std::runtime_error("expected dpctl.SyclQueue as argument");
+    }
+
+    py::buffer_info arg_pybuf = array.request();
+    if (arg_pybuf.ndim != 1) {
+        throw std::runtime_error("Expecting a vector");
+    }
+    if (mod <= 0) {
+        throw std::runtime_error("Modulus must be non-negative");
+    }
+
+    size_t n = arg_pybuf.size;
+
+    auto res = py::array_t<int64_t>(n);
+    py::buffer_info res_pybuf = res.request();
+
+    int64_t *a = static_cast<int64_t *>(arg_pybuf.ptr);
+    int64_t *r = static_cast<int64_t *>(res_pybuf.ptr);
+
+    {
+        const sycl::property_list props = {
+            sycl::property::buffer::use_host_ptr()};
+        sycl::buffer<int64_t, 1> a_buf(a, sycl::range<1>(n), props);
+        sycl::buffer<int64_t, 1> r_buf(r, sycl::range<1>(n), props);
+
+        q_ptr
+            ->submit([&](sycl::handler &cgh) {
+                sycl::accessor a_acc(a_buf, cgh, sycl::read_only);
+                sycl::accessor r_acc(r_buf, cgh, sycl::write_only,
+                                     sycl::noinit);
+
+                cgh.parallel_for(sycl::range<1>(n), [=](sycl::id<1> idx) {
+                    r_acc[idx] = a_acc[idx] % mod;
+                });
+            })
+            .wait_and_throw();
+    }
+
+    return res;
+}
+
+PYBIND11_MODULE(pybind11_example, m)
+{
+    // Import the dpctl._sycl_queue extension
+    import_dpctl___sycl_queue();
+    m.def("get_max_compute_units", &get_max_compute_units,
+          "Computes max_compute_units property of the device underlying given "
+          "dpctl.SyclQueue");
+    m.def("offloaded_array_mod", &offloaded_array_mod,
+          "Compute offloaded modular reduction of integer-valued NumPy array");
+}

examples/pybind11/use_dpctl_syclqueue/setup.py

@@ -0,0 +1,33 @@
+#                      Data Parallel Control (dpctl)
+#
+# Copyright 2020-2021 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pybind11.setup_helpers import Pybind11Extension
+from setuptools import setup
+
+import dpctl
+
+exts = [
+    Pybind11Extension(
+        "pybind11_example",
+        ["./pybind11_example.cpp"],
+        include_dirs=[dpctl.get_include()],
+        extra_compile_args=["-fPIC"],
+        extra_link_args=["-fPIC"],
+        language="c++",
+    ),
+]
+
+setup(name="pybind11_example", ext_modules=exts)