From dad104852dd02ac8848516047f7f28c3fc661819 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 23 Apr 2026 00:02:08 -0700 Subject: [PATCH 1/5] Consolidate USM examples --- examples/python/usm_memory_allocation.py | 41 ------- examples/python/usm_memory_host_access.py | 59 ---------- examples/python/usm_memory_operation.py | 51 --------- examples/python/usm_operations.py | 131 ++++++++++++++++++++++ 4 files changed, 131 insertions(+), 151 deletions(-) delete mode 100644 examples/python/usm_memory_allocation.py delete mode 100644 examples/python/usm_memory_host_access.py delete mode 100644 examples/python/usm_memory_operation.py create mode 100644 examples/python/usm_operations.py diff --git a/examples/python/usm_memory_allocation.py b/examples/python/usm_memory_allocation.py deleted file mode 100644 index 0c23b8bd20..0000000000 --- a/examples/python/usm_memory_allocation.py +++ /dev/null @@ -1,41 +0,0 @@ -# Data Parallel Control (dpctl) -# -# Copyright 2020-2025 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. - -""" -Demonstrates SYCL USM memory usage in Python using dpctl.memory. -""" - -import dpctl.memory as dpmem - -# allocate USM-shared byte-buffer -ms = dpmem.MemoryUSMShared(16) - -# allocate USM-device byte-buffer -md = dpmem.MemoryUSMDevice(16) - -# allocate USM-host byte-buffer -mh = dpmem.MemoryUSMHost(16) - -# specify alignment -mda = dpmem.MemoryUSMDevice(128, alignment=16) - -# allocate using given queue, -# i.e. on the device and bound to the context stored in the queue -mdq = dpmem.MemoryUSMDevice(256, queue=mda.sycl_queue) - -# information about device associate with USM buffer -print("Allocation performed on device:") -mda.sycl_queue.print_device_info() diff --git a/examples/python/usm_memory_host_access.py b/examples/python/usm_memory_host_access.py deleted file mode 100644 index 21092a01a5..0000000000 --- a/examples/python/usm_memory_host_access.py +++ /dev/null @@ -1,59 +0,0 @@ -# Data Parallel Control (dpctl) -# -# Copyright 2020-2025 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. - -""" -Demonstrates how USM allocated memory can be accessed from the host in a -Python program. -""" - -import dpctl.memory as dpmem - -# USM-shared and USM-host pointers are host-accessible, -# meaning they are accessible from Python, therefore -# they implement Pyton buffer protocol - -# allocate 1K of USM-shared buffer -ms = dpmem.MemoryUSMShared(1024) - -# create memoryview into USM-shared buffer -msv = memoryview(ms) - -# populate buffer from host one byte at a type -for i in range(len(ms)): - ir = i % 256 - msv[i] = ir**2 % 256 - -mh = dpmem.MemoryUSMHost(64) -mhv = memoryview(mh) - -# copy content of block of USM-shared buffer to -# USM-host buffer -mhv[:] = msv[78 : 78 + len(mh)] - -print("Byte-values of the USM-host buffer") -print(list(mhv)) - -# USM-device buffer is not host accessible -md = dpmem.MemoryUSMDevice(16) -try: - mdv = memoryview(md) -except Exception as e: - print("") - print( - "An expected exception was raised during attempted construction of " - "memoryview from USM-device memory object." - ) - print("\t", e) diff --git a/examples/python/usm_memory_operation.py b/examples/python/usm_memory_operation.py deleted file mode 100644 index 7c52baca09..0000000000 --- a/examples/python/usm_memory_operation.py +++ /dev/null @@ -1,51 +0,0 @@ -# Data Parallel Control (dpctl) -# -# Copyright 2020-2025 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. - -""" -Demonstrates host to device copy functions using dpctl.memory. -""" - -import numpy as np - -import dpctl.memory as dpmem - -ms = dpmem.MemoryUSMShared(32) -md = dpmem.MemoryUSMDevice(32) - -host_buf = np.random.randint(0, 42, dtype=np.uint8, size=32) - -# copy host byte-like object to USM-device buffer -md.copy_from_host(host_buf) - -# copy USM-device buffer to USM-shared buffer in parallel using -# sycl::queue::memcpy. -ms.copy_from_device(md) - -# build numpy array reusing host-accessible USM-shared memory -X = np.ndarray((len(ms),), buffer=ms, dtype=np.uint8) - -# Display Python object NumPy ndarray is viewing into -print("numpy.ndarray.base: ", X.base) -print("") - -# Print content of the view -print("View..........: ", X) - -# Print content of the original host buffer -print("host_buf......: ", host_buf) - -# use copy_to_host to retrieve memory of USM-device memory -print("copy_to_host(): ", md.copy_to_host()) diff --git a/examples/python/usm_operations.py b/examples/python/usm_operations.py new file mode 100644 index 0000000000..3a8036a6be --- /dev/null +++ b/examples/python/usm_operations.py @@ -0,0 +1,131 @@ +# Data Parallel Control (dpctl) +# +# Copyright 2020-2025 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. + +""" +Demonstrates SYCL USM memory usage in Python using dpctl.memory. +Includes allocation, host access, and host-device copying. +""" + +import numpy as np + +import dpctl.memory as dpmem + + +def usm_allocation(): + """ + Example demonstrating ways to allocate USM using dpctl.memory. + """ + # allocate USM-shared byte-buffer + ms = dpmem.MemoryUSMShared(16) + + # allocate USM-device byte-buffer + md = dpmem.MemoryUSMDevice(16) + + # allocate USM-host byte-buffer + mh = dpmem.MemoryUSMHost(16) + + # specify alignment + mda = dpmem.MemoryUSMDevice(128, alignment=16) + + # allocate using given queue, + # i.e. on the device and bound to the context stored in the queue + mdq = dpmem.MemoryUSMDevice(256, queue=mda.sycl_queue) + + # information about device associate with USM buffer + print("Allocation performed on device:") + mda.sycl_queue.print_device_info() + + +def usm_host_access(): + """ + Example demonstrating that shared and host USM allocations are + host-accessible and thus accessible from Python via buffer protocol. + """ + # USM-shared and USM-host pointers are host-accessible, + # meaning they are accessible from Python, therefore + # they implement Pyton buffer protocol + + # allocate 1K of USM-shared buffer + ms = dpmem.MemoryUSMShared(1024) + + # create memoryview into USM-shared buffer + msv = memoryview(ms) + + # populate buffer from host one byte at a type + for i in range(len(ms)): + ir = i % 256 + msv[i] = ir**2 % 256 + + mh = dpmem.MemoryUSMHost(64) + mhv = memoryview(mh) + + # copy content of block of USM-shared buffer to + # USM-host buffer + mhv[:] = msv[78 : 78 + len(mh)] + + print("Byte-values of the USM-host buffer") + print(list(mhv)) + + # USM-device buffer is not host accessible + md = dpmem.MemoryUSMDevice(16) + try: + mdv = memoryview(md) + except Exception as e: + print("") + print( + "An expected exception was raised during attempted construction of " + "memoryview from USM-device memory object." + ) + print(f"\t{e}") + + +def usm_host_device_copy(): + """ + Example demonstrating copying operations using dpctl.memory. + """ + ms = dpmem.MemoryUSMShared(32) + md = dpmem.MemoryUSMDevice(32) + + host_buf = np.random.randint(0, 42, dtype=np.uint8, size=32) + + # copy host byte-like object to USM-device buffer + md.copy_from_host(host_buf) + + # copy USM-device buffer to USM-shared buffer in parallel using + # sycl::queue::memcpy. + ms.copy_from_device(md) + + # build numpy array reusing host-accessible USM-shared memory + X = np.ndarray((len(ms),), buffer=ms, dtype=np.uint8) + + # Display Python object NumPy ndarray is viewing into + print("numpy.ndarray.base: ", X.base) + print("") + + # Print content of the view + print("View..........: ", X) + + # Print content of the original host buffer + print("host_buf......: ", host_buf) + + # use copy_to_host to retrieve memory of USM-device memory + print("copy_to_host(): ", md.copy_to_host()) + + +if __name__ == "__main__": + import _runner as runner + + runner.run_examples("Memory examples for dpctl.", globals()) From b7081c8b52fc5f33ec04f15144e448f7187e3ae2 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 23 Apr 2026 00:04:35 -0700 Subject: [PATCH 2/5] run all Python examples in workflow --- .github/workflows/conda-package.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/conda-package.yml b/.github/workflows/conda-package.yml index 39fc8cd61b..d8e509ab96 100644 --- a/.github/workflows/conda-package.yml +++ b/.github/workflows/conda-package.yml @@ -662,7 +662,7 @@ jobs: for script in $(find . \( -not -name "_*" -and -name "*.py" \)) do echo "Executing ${script}" - python ${script} || exit 1 + python ${script} --run all || exit 1 done cleanup_packages: From d86e1e7fd78c74f7ca66768b987ec394c42724fb Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 23 Apr 2026 00:30:57 -0700 Subject: [PATCH 3/5] Add more outputs to usm_allocation example --- examples/python/usm_operations.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/examples/python/usm_operations.py b/examples/python/usm_operations.py index 3a8036a6be..289750968d 100644 --- a/examples/python/usm_operations.py +++ b/examples/python/usm_operations.py @@ -30,19 +30,27 @@ def usm_allocation(): """ # allocate USM-shared byte-buffer ms = dpmem.MemoryUSMShared(16) + print(f"USM-shared buffer allocated with size: {len(ms)}") # allocate USM-device byte-buffer md = dpmem.MemoryUSMDevice(16) + print(f"USM-device buffer allocated with size: {len(md)}") # allocate USM-host byte-buffer mh = dpmem.MemoryUSMHost(16) + print(f"USM-host buffer allocated with size: {len(mh)}") # specify alignment mda = dpmem.MemoryUSMDevice(128, alignment=16) + print(f"16-byte aligned USM-device buffer allocated with size: {len(mda)}") # allocate using given queue, # i.e. on the device and bound to the context stored in the queue mdq = dpmem.MemoryUSMDevice(256, queue=mda.sycl_queue) + print( + "USM-device buffers share the same queue: " + f"{mdq.sycl_queue == mda.sycl_queue}" + ) # information about device associate with USM buffer print("Allocation performed on device:") @@ -82,7 +90,7 @@ def usm_host_access(): # USM-device buffer is not host accessible md = dpmem.MemoryUSMDevice(16) try: - mdv = memoryview(md) + memoryview(md) except Exception as e: print("") print( From a45f8c692c48f16667e2191985aa4da546a275d1 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 23 Apr 2026 00:42:30 -0700 Subject: [PATCH 4/5] Add exception handling in subdevices example as some devices (especially those in GH runners) cannot be partitioned into sub-devices, we print that the device cannot be partitioned and discard the exception --- examples/python/subdevices.py | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/examples/python/subdevices.py b/examples/python/subdevices.py index e5e69373b8..6897714d7b 100644 --- a/examples/python/subdevices.py +++ b/examples/python/subdevices.py @@ -43,7 +43,11 @@ def subdivide_root_cpu_device(): "cpu_d is " + ("a root device." if is_root_device(cpu_d) else "not a root device.") ) - sub_devs = cpu_d.create_sub_devices(partition=4) + try: + sub_devs = cpu_d.create_sub_devices(partition=4) + except dpctl.SyclSubDeviceCreationError: + print("Device partitioning was not successful.") + return print("Sub-device #EU: ", [d.max_compute_units for d in sub_devs]) print("Sub-device is_root: ", [is_root_device(d) for d in sub_devs]) print( @@ -70,7 +74,7 @@ def subdivide_by_affinity(affinity="numa"): f"{len(sub_devs)} sub-devices were created with respective #EUs " f"being {[d.max_compute_units for d in sub_devs]}" ) - except Exception: + except dpctl.SyclSubDeviceCreationError: print("Device partitioning by affinity was not successful.") @@ -82,9 +86,13 @@ def create_subdevice_queue(): """ cpu_d = dpctl.SyclDevice("cpu") cpu_count = cpu_d.max_compute_units - sub_devs = cpu_d.create_sub_devices(partition=cpu_count // 2) + try: + sub_devs = cpu_d.create_sub_devices(partition=cpu_count // 2) + except dpctl.SyclSubDeviceCreationError: + print("Device partitioning was not successful.") + return multidevice_ctx = dpctl.SyclContext(sub_devs) - # create a SyclQueue for each sub-device, using commont + # create a SyclQueue for each sub-device, using common # multi-device context q0, q1 = [dpctl.SyclQueue(multidevice_ctx, d) for d in sub_devs] # for each sub-device allocate 26 bytes From e401e1a7e1dc1ed0fd99bf18cbb785c4cff374b0 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 23 Apr 2026 01:04:05 -0700 Subject: [PATCH 5/5] use Python 3.14 for examples --- .github/workflows/conda-package.yml | 2 +- examples/python/usm_operations.py | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/conda-package.yml b/.github/workflows/conda-package.yml index d8e509ab96..d618edbd28 100644 --- a/.github/workflows/conda-package.yml +++ b/.github/workflows/conda-package.yml @@ -509,7 +509,7 @@ jobs: runs-on: ${{ matrix.runner }} strategy: matrix: - python: ['3.11'] + python: ['3.14'] experimental: [false] runner: [ubuntu-22.04] continue-on-error: ${{ matrix.experimental }} diff --git a/examples/python/usm_operations.py b/examples/python/usm_operations.py index 289750968d..478ae65b89 100644 --- a/examples/python/usm_operations.py +++ b/examples/python/usm_operations.py @@ -41,6 +41,7 @@ def usm_allocation(): print(f"USM-host buffer allocated with size: {len(mh)}") # specify alignment + # TODO: add alignment check mda = dpmem.MemoryUSMDevice(128, alignment=16) print(f"16-byte aligned USM-device buffer allocated with size: {len(mda)}")