Added an example showing filter string usage. (#725)

- Use try..except in examples to make sure we do not
    crash on a system where needed drivers are not installed.

Author: Diptorup Deb

examples/python/device_selection.py

@@ -54,11 +54,13 @@ def create_gpu_device():
     SYCL_DEVICE_FILTER, which determines SYCL devices seen by the
     SYCL runtime.
     """
-    d1 = dpctl.SyclDevice("gpu")
-    d2 = dpctl.select_gpu_device()
-    assert d1 == d2
-    print_device(d1)
-    return d1
+    try:
+        d1 = dpctl.SyclDevice("gpu")
+        d2 = dpctl.select_gpu_device()
+        assert d1 == d2
+        print_device(d1)
+    except ValueError:
+        print("A GPU device is not available on the system")
 
 
 def create_gpu_device_if_present():

examples/python/filter_selection.py

@@ -0,0 +1,64 @@
+#                      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.
+
+"""Examples illustrating SYCL device selection using filter strings.
+"""
+
+import dpctl
+
+
+def print_device(d):
+    "Display information about given device argument."
+    if type(d) is not dpctl.SyclDevice:
+        raise ValueError
+    print("Name: ", d.name)
+    print("Vendor: ", d.vendor)
+    print("Driver version: ", d.driver_version)
+    print("Backend: ", d.backend)
+    print("Max EU: ", d.max_compute_units)
+
+
+def select_using_filter():
+    """
+    Demonstrate the usage of a filter string to create a SyclDevice.
+
+    """
+    try:
+        d1 = dpctl.SyclDevice("cpu")
+        print_device(d1)
+    except ValueError:
+        print("A CPU type device is not available on the system")
+
+    try:
+        d1 = dpctl.SyclDevice("opencl:cpu:0")
+        print_device(d1)
+    except ValueError:
+        print("An OpenCL CPU driver needs to be installed on the system")
+
+    d1 = dpctl.SyclDevice("0")
+    print_device(d1)
+
+    try:
+        d1 = dpctl.SyclDevice("gpu")
+        print_device(d1)
+    except ValueError:
+        print("A GPU type device is not available on the system")
+
+
+if __name__ == "__main__":
+    import _runner as runner
+
+    runner.run_examples("Filter selection examples for dpctl.", globals())