From 0637d8417fd4d663f0aafbe0119133b75cff7436 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 21 Oct 2021 01:00:00 -0700 Subject: [PATCH 1/4] Specify shape behavior --- spec/API_specification/array_object.md | 39 ++++++++++++++++---------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 823fdc6b2..ff807b21b 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -234,11 +234,13 @@ Number of array dimensions (axes). #### Returns -- **out**: _int_ +- **out**: _Optional\[ int ]_ - - number of array dimensions (axes). + - number of array dimensions (axes). The returned value must be `None` if and only if an array has unknown rank. -_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of dimensions may be dynamic._ +```{note} +For array libraries having graph-based computational models, an array may have an unknown rank due to operations which return an array having a data-dependent shape (e.g., returning an array of unique values). +``` (attribute-shape)= ### shape @@ -247,24 +249,36 @@ Array dimensions. #### Returns -- **out**: _Union\[ Tuple\[ int, ...], <shape> ]_ +- **out**: _Optional\[ Tuple\[ Optional\[ int ], ... ] ]_ - - array dimensions as either a tuple or a custom shape object. If a shape object, the object must be immutable and must support indexing for dimension retrieval. + - array dimensions. An array dimension must be `None` if and only if a dimension is unknown. -_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic._ +```{note} +For array libraries having graph-based computational models, array dimensions may be unknown due to data-dependent operations (e.g., boolean indexing; `A[:, B > 0]`) and thus cannot be statically resolved without knowing array contents. +``` + +```{note} +The returned value should be a tuple; however, where warranted, an array library may choose to return a custom shape object. If an array library returns a custom shape object, the object must be immutable, must support indexing for dimension retrieval, and must behave similarly to a tuple. +``` (attribute-size)= ### size -Number of elements in an array. This must equal the product of the array's dimensions. +Number of elements in an array. + +```{note} +This must equal the product of the array's dimensions. +``` #### Returns -- **out**: _int_ +- **out**: _Optional\[ int ]_ - - number of elements in an array. + - number of elements in an array. The returned value must be `None` if and only if the array rank or an array dimension is unknown. -_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of elements may be dynamic._ +```{note} +For array libraries having graph-based computational models, an array may have unknown rank or dimensions due to data-dependent operations. +``` (attribute-T)= ### T @@ -742,11 +756,6 @@ Computes the truth value of `self_i <= other_i` for each element of an array ins Element-wise results must equal the results returned by the equivalent element-wise function [`less_equal(x1, x2)`](elementwise_functions.md#less_equalx1-x2-). ``` -(method-__len__)= -### \_\_len\_\_(self, /) - -_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic. Furthermore, not clear whether this should be implemented, as, e.g., NumPy's behavior of returning the size of the first dimension is not necessarily intuitive, as opposed to, say, the total number of elements._ - (method-__lshift__)= ### \_\_lshift\_\_(self, other, /) From 1284dfd822899eb63aa65ea51e92cbf6007f2c02 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 21 Oct 2021 01:02:18 -0700 Subject: [PATCH 2/4] Update copy --- spec/API_specification/array_object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index ff807b21b..dbd0cfe43 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -251,7 +251,7 @@ Array dimensions. - **out**: _Optional\[ Tuple\[ Optional\[ int ], ... ] ]_ - - array dimensions. An array dimension must be `None` if and only if a dimension is unknown. + - array dimensions. The returned value must be `None` if and only if the rank of an array is unknown. An array dimension must be `None` if and only if a dimension is unknown. ```{note} For array libraries having graph-based computational models, array dimensions may be unknown due to data-dependent operations (e.g., boolean indexing; `A[:, B > 0]`) and thus cannot be statically resolved without knowing array contents. From ee41a100e8ce73db3c96ec79563b447249565102 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 4 Nov 2021 12:18:53 -0700 Subject: [PATCH 3/4] Update guidance to remove support for arrays of unknown rank --- spec/API_specification/array_object.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index dbd0cfe43..0636b991b 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -234,13 +234,9 @@ Number of array dimensions (axes). #### Returns -- **out**: _Optional\[ int ]_ - - - number of array dimensions (axes). The returned value must be `None` if and only if an array has unknown rank. +- **out**: _int_ -```{note} -For array libraries having graph-based computational models, an array may have an unknown rank due to operations which return an array having a data-dependent shape (e.g., returning an array of unique values). -``` + - number of array dimensions (axes). (attribute-shape)= ### shape @@ -249,9 +245,9 @@ Array dimensions. #### Returns -- **out**: _Optional\[ Tuple\[ Optional\[ int ], ... ] ]_ +- **out**: _Tuple\[ Optional\[ int ], ... ]_ - - array dimensions. The returned value must be `None` if and only if the rank of an array is unknown. An array dimension must be `None` if and only if a dimension is unknown. + - array dimensions. An array dimension must be `None` if and only if a dimension is unknown. ```{note} For array libraries having graph-based computational models, array dimensions may be unknown due to data-dependent operations (e.g., boolean indexing; `A[:, B > 0]`) and thus cannot be statically resolved without knowing array contents. @@ -274,10 +270,10 @@ This must equal the product of the array's dimensions. - **out**: _Optional\[ int ]_ - - number of elements in an array. The returned value must be `None` if and only if the array rank or an array dimension is unknown. + - number of elements in an array. The returned value must be `None` if and only if an array dimension is unknown. ```{note} -For array libraries having graph-based computational models, an array may have unknown rank or dimensions due to data-dependent operations. +For array libraries having graph-based computational models, an array may have unknown dimensions due to data-dependent operations. ``` (attribute-T)= From 1ab47b229ca1c0248230498a5577d7aec3e037da Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 4 Nov 2021 21:03:57 -0700 Subject: [PATCH 4/4] Update copy --- spec/API_specification/array_object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 0636b991b..5ecb80e1d 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -270,7 +270,7 @@ This must equal the product of the array's dimensions. - **out**: _Optional\[ int ]_ - - number of elements in an array. The returned value must be `None` if and only if an array dimension is unknown. + - number of elements in an array. The returned value must be `None` if and only if one or more array dimensions are unknown. ```{note} For array libraries having graph-based computational models, an array may have unknown dimensions due to data-dependent operations.