to_device

array.to_device(device: device, /, *, stream: int | Any | None = None) → array

Copy the array from the device on which it currently resides to the specified device.

Parameters:

  • self (array) – array instance.

  • device (device) – a device object (see Device support).

  • stream (Optional[Union[int, Any]]) – stream object to use during copy. In addition to the types supported in array.__dlpack__(), implementations may choose to support any library-specific stream object with the caveat that any code using such an object would not be portable.

Returns:

out (array) – an array with the same data and data type as self and located on the specified device.

Notes

  • When a provided device object corresponds to the same device on which an array instance resides, implementations may choose to perform an explicit copy or return self.

  • If stream is provided, the copy operation should be enqueued on the provided stream; otherwise, the copy operation should be enqueued on the default stream/queue. Whether the copy is performed synchronously or asynchronously is implementation-dependent. Accordingly, if synchronization is required to guarantee data safety, this must be clearly explained in a conforming array library’s documentation.

Changed in version 2023.12: Clarified behavior when a provided device object corresponds to the device on which an array instance resides.