dpctl.SyclDevice.get_filter_string method added

dpctl.SyclDevice.filter_string property gives fully specified
filter selector, which includes backend, device_type and relative id.

get_filter_string(include_backend, include_device_type) allows one
to construct filter strings which would omit either backend or device_type
or both, guaranteeing that dpctl.SyclDevice(obtained_selector_string)
will give back the same device.

```
In [1]: import dpctl

In [2]: default_dev = dpctl.SyclDevice()

In [3]: default_dev.get_filter_string(include_backend=False)
Out[3]: 'gpu:1'

In [4]: default_dev.get_filter_string(include_device_type=False)
Out[4]: 'level_zero:0'

In [5]: default_dev.get_filter_string(include_device_type=False, include_backend=False)
Out[5]: '4'
```

Author: oleksandr-pavlyk

dpctl/_backend.pxd

@@ -208,6 +208,9 @@ cdef extern from "dpctl_sycl_device_manager.h":
         DPCTLDeviceVectorRef DVRef,
         size_t index)
     cdef DPCTLDeviceVectorRef DPCTLDeviceMgr_GetDevices(int device_identifier)
+    cdef int DPCTLDeviceMgr_GetPositionInDevices(
+        const DPCTLSyclDeviceRef DRef,
+        int device_identifier)
     cdef size_t DPCTLDeviceMgr_GetNumDevices(int device_identifier)
     cdef void DPCTLDeviceMgr_PrintDeviceInfo(const DPCTLSyclDeviceRef DRef)
     cdef DPCTLSyclContextRef DPCTLDeviceMgr_GetCachedContext(

dpctl/_sycl_device.pxd

@@ -51,3 +51,7 @@ cdef public class SyclDevice(_SyclDevice) [object PySyclDeviceObject, type PySyc
     cdef list create_sub_devices_by_counts(self, object counts)
     cdef list create_sub_devices_by_affinity(self, _partition_affinity_domain_type domain)
     cdef cpp_bool equals(self, SyclDevice q)
+    cdef int get_device_type_ordinal(self)
+    cdef int get_overall_ordinal(self)
+    cdef int get_backend_ordinal(self)
+    cdef int get_backend_and_device_type_ordinal(self)

dpctl/_sycl_device.pyx

@@ -61,6 +61,8 @@ from ._backend cimport (  # noqa: E211
     DPCTLDevice_IsCPU,
     DPCTLDevice_IsGPU,
     DPCTLDevice_IsHost,
+    DPCTLDeviceMgr_GetDevices,
+    DPCTLDeviceMgr_GetPositionInDevices,
     DPCTLDeviceMgr_GetRelativeId,
     DPCTLDeviceMgr_PrintDeviceInfo,
     DPCTLDeviceSelector_Delete,
@@ -825,8 +827,23 @@ cdef class SyclDevice(_SyclDevice):
 
     @property
     def filter_string(self):
-        """ For a parent device, returns a ``tuple (backend, device_kind,
-            relative_id)``. Raises an exception for sub-devices.
+        """
+        For a parent device, returns a fully specified filter selector
+        string``backend:device_type:relative_id`` selecting the device.
+
+        Raises an exception for sub-devices.
+
+        :Example:
+            .. code-block:: python
+
+                import dpctl
+
+                # Create a SyclDevice with an explicit filter string,
+                # in this case the first level_zero gpu device.
+                level_zero_gpu = dpctl.SyclDevice("level_zero:gpu:0")
+                # filter_string property should be "level_zero:gpu:0"
+                dev = dpctl.SyclDevice(level_zero_gpu.filter_string)
+                assert level_zero_gpu == dev
         """
         cdef DPCTLSyclDeviceRef pDRef = NULL
         cdef DPCTLSyclBackendType BTy
@@ -846,3 +863,134 @@ cdef class SyclDevice(_SyclDevice):
             # this a sub-device, free it, and raise an exception
             DPCTLDevice_Delete(pDRef)
             raise TypeError("This SyclDevice is not a root device")
+
+    cdef int get_backend_and_device_type_ordinal(self):
+        """
+        If this device is a root ``sycl::device`` returns the ordinal
+        position of this device in the vector
+        ``sycl::device::get_devices(device_type_of_this_device)``
+        filtered to contain only devices with the same backend as this
+        device.
+
+        Returns -1 if the device is a sub-device, or the device could not
+        be found in the vector.
+        """
+        cdef int64_t relId = DPCTLDeviceMgr_GetRelativeId(self._device_ref)
+        return relId
+
+    cdef int get_device_type_ordinal(self):
+        """
+        If this device is a root ``sycl::device`` returns the ordinal
+        position of this device in the vector
+        ``sycl::device::get_devices(device_type_of_this_device)``
+
+        Returns -1 if the device is a sub-device, or the device could not
+        be found in the vector.
+        """
+        cdef DPCTLSyclDeviceType DTy
+        cdef int64_t relId = -1
+
+        DTy = DPCTLDevice_GetDeviceType(self._device_ref)
+        relId = DPCTLDeviceMgr_GetPositionInDevices(
+            self._device_ref, _backend_type._ALL_BACKENDS | DTy)
+        return relId
+
+    cdef int get_backend_ordinal(self):
+        """
+        If this device is a root ``sycl::device`` returns the ordinal
+        position of this device in the vector ``sycl::device::get_devices()``
+        filtered to contain only devices with the same backend as this
+        device.
+
+        Returns -1 if the device is a sub-device, or the device could not
+        be found in the vector.
+        """
+        cdef DPCTLSyclBackendType BTy
+        cdef int64_t relId = -1
+
+        BTy = DPCTLDevice_GetBackend(self._device_ref)
+        relId = DPCTLDeviceMgr_GetPositionInDevices(
+            self._device_ref, BTy | _device_type._ALL_DEVICES)
+        return relId
+
+    cdef int get_overall_ordinal(self):
+        """
+        If this device is a root ``sycl::device`` returns the ordinal
+        position of this device in the vector ``sycl::device::get_devices()``
+        filtered to contain only devices with the same backend as this
+        device.
+
+        Returns -1 if the device is a sub-device, or the device could not
+        be found in the vector.
+        """
+        cdef int64_t relId = -1
+
+        relId = DPCTLDeviceMgr_GetPositionInDevices(
+            self._device_ref,
+            (_backend_type._ALL_BACKENDS | _device_type._ALL_DEVICES)
+        )
+        return relId
+
+    def get_filter_string(self, include_backend=True, include_device_type=True):
+        """
+        For a parent device returns a filter selector string
+        that includes backend or device type based on the value
+        of the given keyword arguments.
+
+        Raises a TypeError if this devices is a sub-device, or
+        a ValueError if no match was found in the vector returned
+        by ``sycl::device::get_devices()``.
+
+        :Example:
+            .. code-block:: python
+
+                import dpctl
+
+                # Create a GPU SyclDevice
+                gpu_dev = dpctl.SyclDevice("gpu:0")
+                # filter string should be "gpu:0"
+                fs = gpu_dev.get_filter_string(use_backend=False)
+                dev = dpctl.SyclDevice(fs)
+                assert gpu _dev == dev
+        """
+        cdef int relId = -1
+        cdef DPCTLSyclDeviceRef pDRef = NULL
+        cdef DPCTLSyclDeviceType DTy
+        cdef DPCTLSyclBackendType BTy
+
+        if include_backend:
+            if include_device_type:
+                relId = self.get_backend_and_device_type_ordinal()
+            else:
+                relId = self.get_backend_ordinal()
+        else:
+            if include_device_type:
+                relId = self.get_device_type_ordinal()
+            else:
+                relId = self.get_overall_ordinal()
+
+        if relId < 0:
+            pDRef = DPCTLDevice_GetParentDevice(self._device_ref)
+            if (pDRef is NULL):
+                raise ValueError
+            else:
+                # this a sub-device, free it, and raise an exception
+                DPCTLDevice_Delete(pDRef)
+                raise TypeError("This SyclDevice is not a root device")
+        else:
+            if include_backend:
+                BTy = DPCTLDevice_GetBackend(self._device_ref)
+                be_str = _backend_type_to_filter_string_part(BTy)
+                if include_device_type:
+                    DTy = DPCTLDevice_GetDeviceType(self._device_ref)
+                    dt_str = _device_type_to_filter_string_part(DTy)
+                    return ":".join((be_str, dt_str, str(relId)))
+                else:
+                    return ":".join((be_str, str(relId)))
+            else:
+                if include_device_type:
+                    DTy = DPCTLDevice_GetDeviceType(self._device_ref)
+                    dt_str = _device_type_to_filter_string_part(DTy)
+                    return ":".join((dt_str, str(relId)))
+                else:
+                    return str(relId)

dpctl/tests/test_sycl_device.py

@@ -591,13 +591,29 @@ def test_filter_string(valid_filter):
     )
 
 
-def test_filter_string2():
+def test_filter_string_property():
     """
     Test that filter_string reconstructs the same device.
     """
     devices = dpctl.get_devices()
     for d in devices:
-        if d.default_selector_score > 0:
+        if d.default_selector_score >= 0:
             dev_id = d.filter_string
             d_r = dpctl.SyclDevice(dev_id)
             assert d == d_r
+
+
+def test_filter_string_method():
+    """
+    Test that filter_string reconstructs the same device.
+    """
+    devices = dpctl.get_devices()
+    for d in devices:
+        for be in [True, False]:
+            for dt in [True, False]:
+                if d.default_selector_score >= 0:
+                    dev_id = d.get_filter_string(
+                        include_backend=be, include_device_type=dt
+                    )
+                    d_r = dpctl.SyclDevice(dev_id)
+                    assert d == d_r, "Failed "