From 335afd5e176bc545a137a571af6c1b0aa2afaa3b Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Tue, 15 Nov 2022 13:55:16 -0600 Subject: [PATCH] Expanded doc-string of dpctl.tensor.usm_ndarray.to_device --- dpctl/tensor/_usmarray.pyx | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/dpctl/tensor/_usmarray.pyx b/dpctl/tensor/_usmarray.pyx index 8fbb131265..7ddf191296 100644 --- a/dpctl/tensor/_usmarray.pyx +++ b/dpctl/tensor/_usmarray.pyx @@ -638,13 +638,43 @@ cdef class usm_ndarray: res.array_namespace_ = self.array_namespace_ return res - def to_device(self, target_device): + def to_device(self, target): """ - Transfer array to target device + Transfers this array to specified target device. + + :Example: + .. code-block:: python + + import dpctl + import dpctl.tensor as dpt + + x = dpt.full(10**6, 2, dtype="int64") + q_prof = dpctl.SyclQueue( + x.sycl_device, property="enable_profiling") + # return a view with profile-enabled queue + y = x.to_device(q_prof) + timer = dpctl.SyclTimer() + with timer(q_prof): + z = y * y + print(timer.dt) + + Args: + target: array API concept of target device. + It can be a oneAPI filter selector string, + an instance of :class:`dpctl.SyclDevice` corresponding to a + non-partitioned SYCL device, an instance of + :class:`dpctl.SyclQueue`, or a :class:`dpctl.tensor.Device` + object returned by :attr:`dpctl.tensor.usm_array.device`. + + Returns: + A view if data copy is not required, and a copy otherwise. + If copying is required, it is done by copying from the original + allocation device to the host, followed by copying from host + to the target device. """ cdef c_dpctl.DPCTLSyclQueueRef QRef = NULL cdef c_dpmem._Memory arr_buf - d = Device.create_device(target_device) + d = Device.create_device(target) if (d.sycl_context == self.sycl_context): arr_buf = self.usm_data QRef = ( d.sycl_queue).get_queue_ref()