From bac887c3063001541cff56a4e3c24e7edd04e245 Mon Sep 17 00:00:00 2001 From: crusaderky Date: Tue, 1 Apr 2025 08:50:34 +0100 Subject: [PATCH 1/4] Clarify input arrays in device placement --- spec/2021.12/design_topics/device_support.rst | 6 ++++-- spec/2022.12/design_topics/device_support.rst | 6 ++++-- spec/2023.12/design_topics/device_support.rst | 6 ++++-- spec/2024.12/design_topics/device_support.rst | 6 ++++-- spec/draft/design_topics/device_support.rst | 6 ++++-- 5 files changed, 20 insertions(+), 10 deletions(-) diff --git a/spec/2021.12/design_topics/device_support.rst b/spec/2021.12/design_topics/device_support.rst index 29f0789bb..a89f9db1b 100644 --- a/spec/2021.12/design_topics/device_support.rst +++ b/spec/2021.12/design_topics/device_support.rst @@ -81,9 +81,11 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the setting from a context manager, if set. + 2. If ``device=None``, then use the device of the input array(s), if any. - 3. If no context manager was used, then use the global default device/strategy + 3. If there are no input arrays, then use the setting from a context manager, if set. + + 4. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: diff --git a/spec/2022.12/design_topics/device_support.rst b/spec/2022.12/design_topics/device_support.rst index 29f0789bb..a89f9db1b 100644 --- a/spec/2022.12/design_topics/device_support.rst +++ b/spec/2022.12/design_topics/device_support.rst @@ -81,9 +81,11 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the setting from a context manager, if set. + 2. If ``device=None``, then use the device of the input array(s), if any. - 3. If no context manager was used, then use the global default device/strategy + 3. If there are no input arrays, then use the setting from a context manager, if set. + + 4. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: diff --git a/spec/2023.12/design_topics/device_support.rst b/spec/2023.12/design_topics/device_support.rst index 593b0b9fa..bed521df1 100644 --- a/spec/2023.12/design_topics/device_support.rst +++ b/spec/2023.12/design_topics/device_support.rst @@ -82,9 +82,11 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the setting from a context manager, if set. + 2. If ``device=None``, then use the device of the input array(s), if any. - 3. If no context manager was used, then use the global default device/strategy + 3. If there are no input arrays, then use the setting from a context manager, if set. + + 4. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: diff --git a/spec/2024.12/design_topics/device_support.rst b/spec/2024.12/design_topics/device_support.rst index 593b0b9fa..bed521df1 100644 --- a/spec/2024.12/design_topics/device_support.rst +++ b/spec/2024.12/design_topics/device_support.rst @@ -82,9 +82,11 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the setting from a context manager, if set. + 2. If ``device=None``, then use the device of the input array(s), if any. - 3. If no context manager was used, then use the global default device/strategy + 3. If there are no input arrays, then use the setting from a context manager, if set. + + 4. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: diff --git a/spec/draft/design_topics/device_support.rst b/spec/draft/design_topics/device_support.rst index 593b0b9fa..bed521df1 100644 --- a/spec/draft/design_topics/device_support.rst +++ b/spec/draft/design_topics/device_support.rst @@ -82,9 +82,11 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the setting from a context manager, if set. + 2. If ``device=None``, then use the device of the input array(s), if any. - 3. If no context manager was used, then use the global default device/strategy + 3. If there are no input arrays, then use the setting from a context manager, if set. + + 4. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: From b7e80d340d8f6a91f17ba6403f6498a6fedb1fb2 Mon Sep 17 00:00:00 2001 From: crusaderky Date: Fri, 18 Apr 2025 10:23:39 +0100 Subject: [PATCH 2/4] Revert 2021-2024 --- spec/2021.12/design_topics/device_support.rst | 6 ++---- spec/2022.12/design_topics/device_support.rst | 6 ++---- spec/2023.12/design_topics/device_support.rst | 6 ++---- spec/2024.12/design_topics/device_support.rst | 6 ++---- 4 files changed, 8 insertions(+), 16 deletions(-) diff --git a/spec/2021.12/design_topics/device_support.rst b/spec/2021.12/design_topics/device_support.rst index a89f9db1b..29f0789bb 100644 --- a/spec/2021.12/design_topics/device_support.rst +++ b/spec/2021.12/design_topics/device_support.rst @@ -81,11 +81,9 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the device of the input array(s), if any. + 2. If ``device=None``, then use the setting from a context manager, if set. - 3. If there are no input arrays, then use the setting from a context manager, if set. - - 4. If no context manager was used, then use the global default device/strategy + 3. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: diff --git a/spec/2022.12/design_topics/device_support.rst b/spec/2022.12/design_topics/device_support.rst index a89f9db1b..29f0789bb 100644 --- a/spec/2022.12/design_topics/device_support.rst +++ b/spec/2022.12/design_topics/device_support.rst @@ -81,11 +81,9 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the device of the input array(s), if any. + 2. If ``device=None``, then use the setting from a context manager, if set. - 3. If there are no input arrays, then use the setting from a context manager, if set. - - 4. If no context manager was used, then use the global default device/strategy + 3. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: diff --git a/spec/2023.12/design_topics/device_support.rst b/spec/2023.12/design_topics/device_support.rst index bed521df1..593b0b9fa 100644 --- a/spec/2023.12/design_topics/device_support.rst +++ b/spec/2023.12/design_topics/device_support.rst @@ -82,11 +82,9 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the device of the input array(s), if any. + 2. If ``device=None``, then use the setting from a context manager, if set. - 3. If there are no input arrays, then use the setting from a context manager, if set. - - 4. If no context manager was used, then use the global default device/strategy + 3. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: diff --git a/spec/2024.12/design_topics/device_support.rst b/spec/2024.12/design_topics/device_support.rst index bed521df1..593b0b9fa 100644 --- a/spec/2024.12/design_topics/device_support.rst +++ b/spec/2024.12/design_topics/device_support.rst @@ -82,11 +82,9 @@ rather than hard requirements: 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None``, then use the device of the input array(s), if any. + 2. If ``device=None``, then use the setting from a context manager, if set. - 3. If there are no input arrays, then use the setting from a context manager, if set. - - 4. If no context manager was used, then use the global default device/strategy + 3. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: From b25da1a4768a27314687558a931a60ce9ec5ee43 Mon Sep 17 00:00:00 2001 From: crusaderky Date: Fri, 18 Apr 2025 10:35:09 +0100 Subject: [PATCH 3/4] rework --- spec/draft/design_topics/device_support.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/spec/draft/design_topics/device_support.rst b/spec/draft/design_topics/device_support.rst index bed521df1..b4897a06a 100644 --- a/spec/draft/design_topics/device_support.rst +++ b/spec/draft/design_topics/device_support.rst @@ -76,16 +76,14 @@ rather than hard requirements: - Respect explicit device assignment (i.e. if the input to the ``device=`` keyword is not ``None``, guarantee that the array is created on the given device, and raise an exception otherwise). - Preserve device assignment as much as possible (e.g. output arrays from a function are expected to be on the same device as input arrays to the function). +- When a function accepts a mix of arrays and Python scalars, the scalars should inherit the device of the arrays, much like it happens with :ref:`type-promotion`. - Raise an exception if an operation involves arrays on different devices (i.e. avoid implicit data transfer between devices). - Use a default for ``device=None`` which is consistent between functions within the same library. -- If a library has multiple ways of controlling device placement, the most explicit method should have the highest priority. For example: +- If a library has multiple ways of controlling device placement, the most explicit method has the highest priority: 1. If ``device=`` keyword is specified, that always takes precedence - - 2. If ``device=None``, then use the device of the input array(s), if any. - - 3. If there are no input arrays, then use the setting from a context manager, if set. - + 2. If ``device=None`` or the function does not accept a ``device`` parameter, then use the device of the input array(s), if any. + 3. If there are no input arrays, then use the setting from a context manager, if any. 4. If no context manager was used, then use the global default device/strategy .. _device-out-of-scope: From 0b9225854f58d5795a0d545635b2cb059e775ab9 Mon Sep 17 00:00:00 2001 From: crusaderky Date: Fri, 18 Apr 2025 10:37:53 +0100 Subject: [PATCH 4/4] rework --- spec/draft/design_topics/device_support.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/draft/design_topics/device_support.rst b/spec/draft/design_topics/device_support.rst index b4897a06a..6f9332319 100644 --- a/spec/draft/design_topics/device_support.rst +++ b/spec/draft/design_topics/device_support.rst @@ -76,15 +76,15 @@ rather than hard requirements: - Respect explicit device assignment (i.e. if the input to the ``device=`` keyword is not ``None``, guarantee that the array is created on the given device, and raise an exception otherwise). - Preserve device assignment as much as possible (e.g. output arrays from a function are expected to be on the same device as input arrays to the function). -- When a function accepts a mix of arrays and Python scalars, the scalars should inherit the device of the arrays, much like it happens with :ref:`type-promotion`. - Raise an exception if an operation involves arrays on different devices (i.e. avoid implicit data transfer between devices). +- When a function accepts a mix of arrays and Python scalars, the scalars should inherit the device of the arrays, much like it happens with :ref:`type-promotion`. - Use a default for ``device=None`` which is consistent between functions within the same library. -- If a library has multiple ways of controlling device placement, the most explicit method has the highest priority: +- If a library has multiple ways of controlling device placement, the most explicit method should have the highest priority: - 1. If ``device=`` keyword is specified, that always takes precedence - 2. If ``device=None`` or the function does not accept a ``device`` parameter, then use the device of the input array(s), if any. - 3. If there are no input arrays, then use the setting from a context manager, if any. - 4. If no context manager was used, then use the global default device/strategy + 1. If the ``device=`` keyword is specified, that always takes precedence; + 2. If ``device=None`` or the function does not accept a ``device`` parameter, then use the device of the input array(s), if any; + 3. If there are no input arrays, then use the setting from a context manager, if any; + 4. If no context manager was used, then use the global default device/strategy. .. _device-out-of-scope: