From 72b86e233c9e2b396e9c21ceabb837855bfdcde4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 4 Nov 2021 03:57:15 -0700 Subject: [PATCH 1/2] Require that NaNs be considered distinct --- spec/API_specification/set_functions.md | 29 +++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index 3f3a9d192..4c5bdb37e 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -23,6 +23,15 @@ The shapes of two of the output arrays for this function depend on the data valu Returns the unique elements of an input array `x`. +```{note} +Uniqueness should be determined based on value equality (i.e., `x_i == x_j`). For input arrays having floating-point data types, value-based equality implies the following behavior. + +- As `nan` values compare as `False`, `nan` values should be considered distinct. +- As `-0` and `+0` compare as `True`, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return `-0` if `-0` occurs before `+0`). + +As signed zeros are not distinct, using `inverse_indices` to reconstruct the input array is not guaranteed to return an array having the exact same values. Furthermore, each `nan` value will have a count of one, while the counts for signed zeros will be aggregated as a single count. +``` + #### Parameters - **x**: _<array>_ @@ -47,14 +56,23 @@ Returns the unique elements of an input array `x`. (function-unique-inverse)= ### unique_inverse(x, /) -Returns the unique elements of an input array `x` and the indices from the set of unique elements that reconstruct `x`. - :::{admonition} Data-dependent output shape :class: important The shape of one of the output arrays for this function depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details. ::: +Returns the unique elements of an input array `x` and the indices from the set of unique elements that reconstruct `x`. + +```{note} +Uniqueness should be determined based on value equality (i.e., `x_i == x_j`). For input arrays having floating-point data types, value-based equality implies the following behavior. + +- As `nan` values compare as `False`, `nan` values should be considered distinct. +- As `-0` and `+0` compare as `True`, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return `-0` if `-0` occurs before `+0`). + +As signed zeros are not distinct, using `inverse_indices` to reconstruct the input array is not guaranteed to return an array having the exact same values. +``` + #### Parameters - **x**: _<array>_ @@ -85,6 +103,13 @@ The shape of the output array for this function depends on the data values in th Returns the unique elements of an input array `x`. +```{note} +Uniqueness should be determined based on value equality (i.e., `x_i == x_j`). For input arrays having floating-point data types, value-based equality implies the following behavior. + +- As `nan` values compare as `False`, `nan` values should be considered distinct. +- As `-0` and `+0` compare as `True`, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return `-0` if `-0` occurs before `+0`). +``` + #### Parameters - **x**: _<array>_ From 04d6d82f56cc9526b104c5b017fc7b276c6e91e5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 4 Nov 2021 04:02:25 -0700 Subject: [PATCH 2/2] Update copy --- spec/API_specification/set_functions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index 4c5bdb37e..74408b0b1 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -29,7 +29,9 @@ Uniqueness should be determined based on value equality (i.e., `x_i == x_j`). Fo - As `nan` values compare as `False`, `nan` values should be considered distinct. - As `-0` and `+0` compare as `True`, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return `-0` if `-0` occurs before `+0`). -As signed zeros are not distinct, using `inverse_indices` to reconstruct the input array is not guaranteed to return an array having the exact same values. Furthermore, each `nan` value will have a count of one, while the counts for signed zeros will be aggregated as a single count. +As signed zeros are not distinct, using `inverse_indices` to reconstruct the input array is not guaranteed to return an array having the exact same values. + +Each `nan` value should have a count of one, while the counts for signed zeros should be aggregated as a single count. ``` #### Parameters