From 8c414d644da1e88427948e0a14bce376670a8c9c Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 17 Feb 2021 00:03:25 -0500 Subject: [PATCH 1/9] add finfo and iinfo in the spec --- spec/API_specification/data_type_functions.md | 63 +++++++++++++++++++ spec/API_specification/index.rst | 1 + 2 files changed, 64 insertions(+) create mode 100644 spec/API_specification/data_type_functions.md diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md new file mode 100644 index 000000000..db4e19ce1 --- /dev/null +++ b/spec/API_specification/data_type_functions.md @@ -0,0 +1,63 @@ +# Data type functions + +> Array API specification for data type functions. + +A conforming implementation of the array API standard must provide and support the following data type functions. + + + +## Objects in API + +(finfo)= +### finfo(type) + +Defines the machine limits for floating point types. + +#### Parameters + +- **type**: _Union\[ float, <dtype>, instance ]_ + + - the kind of floating point data-type about which to get information + +#### Returns + +- **out**: _<class>_ + + - a class with that encapsules the following attributes: + + - **bits**: _int_ + - The number of bits occupied by the type + - **eps**: _float_ + - The difference between 1.0 and the next smallest representable float larger than 1.0 following the IEEE 754 standard. + - **max**: _float_ + - The largest representable number. + - **min**: _float_ + - The smallest representable number. + - **tiny**: _float_ + - The smallest positive representable number. + - **resolution**: _float_ + - The approximate decimal resolution of this type. + +(iinfo)= +### iinfo(type) + +Defines the machine limits for integer types. + +#### Parameters + +- **type**: _Union\[ integer, <dtype>, instance ]_ + + - the kind of integer data-type about which to get information + +#### Returns + +- **out**: _<class>_ + + - a class with that encapsules the following attributes: + + - **bits**: _int_ + - The number of bits occupied by the type + - **max**: _int_ + - The largest representable number. + - **min**: _int_ + - The smallest representable number. diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index 3d38b9c6b..55faa1c4d 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -11,6 +11,7 @@ API specification array_object indexing data_types + data_type_functions type_promotion broadcasting creation_functions From 39a9cb27c9ad98d174a1227d24127bdc69abdc95 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 17 Feb 2021 14:45:12 -0500 Subject: [PATCH 2/9] move result_type function to new file and minor fixes --- spec/API_specification/data_type_functions.md | 29 ++++++++++++++++--- spec/API_specification/utility_functions.md | 24 --------------- 2 files changed, 25 insertions(+), 28 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index db4e19ce1..689087185 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -15,7 +15,7 @@ Defines the machine limits for floating point types. #### Parameters -- **type**: _Union\[ float, <dtype>, instance ]_ +- **type**: _Union\[ <dtype>, instance ]_ - the kind of floating point data-type about which to get information @@ -35,8 +35,6 @@ Defines the machine limits for floating point types. - The smallest representable number. - **tiny**: _float_ - The smallest positive representable number. - - **resolution**: _float_ - - The approximate decimal resolution of this type. (iinfo)= ### iinfo(type) @@ -45,7 +43,7 @@ Defines the machine limits for integer types. #### Parameters -- **type**: _Union\[ integer, <dtype>, instance ]_ +- **type**: _Union\[ <dtype>, instance ]_ - the kind of integer data-type about which to get information @@ -61,3 +59,26 @@ Defines the machine limits for integer types. - The largest representable number. - **min**: _int_ - The smallest representable number. + +(function-result_type)= +### result_type(*arrays_and_dtypes) + +Returns the dtype that results from applying the type promotion rules +(see {ref}`type-promotion`) to the arguments. + +```{note} +If mixed dtypes (e.g. integer and floating-point) are used, the output of +`result_type` will be implementation-specific. +``` + +#### Parameters + +- **arrays_and_dtypes**: _Sequence\[Union\[<array>, <dtype>\]\];_ + + - input arrays and dtypes. + +#### Returns + +- **out**: _<dtype>_ + + - the dtype resulting from an operation involving the input arrays and dtypes. diff --git a/spec/API_specification/utility_functions.md b/spec/API_specification/utility_functions.md index a81b709ca..aad65a71b 100644 --- a/spec/API_specification/utility_functions.md +++ b/spec/API_specification/utility_functions.md @@ -64,27 +64,3 @@ Tests whether any input array element evaluates to `True` along a specified axis - **out**: _<array>_ - if a logical OR reduction was performed over the entire array, the returned array must be a zero-dimensional array containing the test result; otherwise, the returned array must be a non-zero-dimensional array containing the test results. The returned array must have a data type of `bool`. - - -(function-result_type)= -### result_type(*arrays_and_dtypes) - -Returns the dtype that results from applying the type promotion rules -(see {ref}`type-promotion`) to the arguments. - -```{note} -If mixed dtypes (e.g. integer and floating-point) are used, the output of -`result_type` will be implementation-specific. -``` - -#### Parameters - -- **arrays_and_dtypes**: _Sequence\[Union\[<array>, <dtype>\]\];_ - - - input arrays and dtypes. - -#### Returns - -- **out**: _<dtype>_ - - - the dtype resulting from an operation involving the input arrays and dtypes. From 11b596a2c3260c82265eef9a848719eb0c3ddc45 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 17 Feb 2021 17:35:57 -0500 Subject: [PATCH 3/9] add can_cast spec --- spec/API_specification/data_type_functions.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 689087185..38a60953e 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -7,6 +7,26 @@ A conforming implementation of the array API standard must provide and support t ## Objects in API +(can_cast)= +### can_cast(from_, to) + +Determines if a type conversion is allowed under the rules described by {ref}`type-promotion`. + +#### Parameters + +- **from_**: _Union\[ <dtype> ]_ + + - the data type, scalar or array to cast from. + +- **to**: _<dtype>_ + + - the data type to cast to. + +#### Returns + +- **out**: _bool_ + + - True if the cast can occur according to the {ref}`type-promotion`. (finfo)= ### finfo(type) From 79dc82c176b1c040f3528d3d66b21c203846555f Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Thu, 18 Feb 2021 14:47:34 -0500 Subject: [PATCH 4/9] add review changes and remove tiny from the finfo object --- spec/API_specification/data_type_functions.md | 35 +++++++++---------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 689087185..30e541af6 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -11,41 +11,39 @@ A conforming implementation of the array API standard must provide and support t (finfo)= ### finfo(type) -Defines the machine limits for floating point types. +Machine limits for floating-point data types. #### Parameters -- **type**: _Union\[ <dtype>, instance ]_ +- **type**: _Union\[ <dtype>, <array> ]_ - - the kind of floating point data-type about which to get information + - the kind of floating-point data-type about which to get information. #### Returns - **out**: _<class>_ - - a class with that encapsules the following attributes: + - an object having the following attributes: - **bits**: _int_ - - The number of bits occupied by the type + - number of bits occupied by the floating-point data type. - **eps**: _float_ - - The difference between 1.0 and the next smallest representable float larger than 1.0 following the IEEE 754 standard. + - difference between 1.0 and the next smallest representable floating-point number larger than 1.0 according to the IEEE-754 standard. - **max**: _float_ - - The largest representable number. + - largest representable number. - **min**: _float_ - - The smallest representable number. - - **tiny**: _float_ - - The smallest positive representable number. + - smallest representable number. (iinfo)= ### iinfo(type) -Defines the machine limits for integer types. +Machine limits for integer data types. #### Parameters -- **type**: _Union\[ <dtype>, instance ]_ +- **type**: _Union\[ <dtype>, <array> ]_ - - the kind of integer data-type about which to get information + - the kind of integer data-type about which to get information. #### Returns @@ -54,11 +52,11 @@ Defines the machine limits for integer types. - a class with that encapsules the following attributes: - **bits**: _int_ - - The number of bits occupied by the type + - number of bits occupied by the type - **max**: _int_ - - The largest representable number. + - largest representable number. - **min**: _int_ - - The smallest representable number. + - smallest representable number. (function-result_type)= ### result_type(*arrays_and_dtypes) @@ -67,13 +65,12 @@ Returns the dtype that results from applying the type promotion rules (see {ref}`type-promotion`) to the arguments. ```{note} -If mixed dtypes (e.g. integer and floating-point) are used, the output of -`result_type` will be implementation-specific. +If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific. ``` #### Parameters -- **arrays_and_dtypes**: _Sequence\[Union\[<array>, <dtype>\]\];_ +- **arrays_and_dtypes**: _Sequence\[ Union\[ <array>, <dtype> \] \];_ - input arrays and dtypes. From 4df55fbced877baedfa865ad6dd4240742ecdeed Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Thu, 18 Feb 2021 19:22:00 -0500 Subject: [PATCH 5/9] add broadcast_to function --- spec/API_specification/data_type_functions.md | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 74155d86e..9c38c8d33 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -7,6 +7,30 @@ A conforming implementation of the array API standard must provide and support t ## Objects in API +(broadcast_to)= +### broadcast_to(array, shape) + +Broadcast an array to a new shape. + +- A `ValueError` exception must be raised if the array is not compatible with the new shape according to the semantics defined in {ref}`broadcasting`. + +#### Parameters + +- **array**: _<array>_ + + - array to broadcast. + +- **shape**: _<dtype>_ + + - shape of the desired array. + +#### Returns + +- **out**: _<array>_ + + - a readonly view on the original array with the given shape where more than one element of a broadcasted array may refer to a single memory location. + + (can_cast)= ### can_cast(from_, to) @@ -16,11 +40,11 @@ Determines if a type conversion is allowed under the rules described by {ref}`ty - **from_**: _Union\[ <dtype> ]_ - - the data type, scalar or array to cast from. + - data type, scalar or array to cast from. - **to**: _<dtype>_ - - the data type to cast to. + - data type to cast to. #### Returns From 59940f2c2a8af6c0ec6de3a393f1b668d59685f6 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Mon, 22 Feb 2021 17:21:14 -0500 Subject: [PATCH 6/9] add broadcast_arrays function --- spec/API_specification/data_type_functions.md | 29 ++++++++++++++----- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 9b869e027..7982700ca 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -7,8 +7,26 @@ A conforming implementation of the array API standard must provide and support t ## Objects in API -(broadcast_to)= -### broadcast_to(array, shape) +(broadcast-arrays)= +### broadcast_arrays(args, /, *) + +Broadcast any number of arrays against each other. + +#### Parameters + +- **args**: [_<array>_] + + - arrays to broadcast. + +#### Returns + +- **out**: [_<array>_] + + - readonly views on the original arrays. Furthermore, more than one element of a broadcasted array may refer to a single memory location. + + +(broadcast-to)= +### broadcast_to(array, /, shape, /) Broadcast an array to a new shape. @@ -30,9 +48,8 @@ Broadcast an array to a new shape. - a readonly view on the original array with the given shape where more than one element of a broadcasted array may refer to a single memory location. - -(can_cast)= -### can_cast(from_, to) +(can-cast)= +### can_cast(from_, /, to, /) Determines if a type conversion is allowed under the rules described by {ref}`type-promotion`. @@ -52,8 +69,6 @@ Determines if a type conversion is allowed under the rules described by {ref}`ty - True if the cast can occur according to the {ref}`type-promotion`. -(finfo)= -### finfo(type) (finfo)= ### finfo(type, /) From 96ee992f3768becb6b963aa1bb216eca20c03365 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Tue, 23 Feb 2021 19:28:27 -0500 Subject: [PATCH 7/9] add review changes --- spec/API_specification/data_type_functions.md | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 7982700ca..ef99d0b03 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -4,29 +4,30 @@ A conforming implementation of the array API standard must provide and support the following data type functions. + ## Objects in API -(broadcast-arrays)= -### broadcast_arrays(args, /, *) +(function-broadcast-arrays)= +### broadcast_arrays(*args, /) Broadcast any number of arrays against each other. #### Parameters -- **args**: [_<array>_] +- ***args**: _\[<array>\]_ - arrays to broadcast. #### Returns -- **out**: [_<array>_] +- **out**: _\[<array>\]_ - - readonly views on the original arrays. Furthermore, more than one element of a broadcasted array may refer to a single memory location. + - a list of arrays where more than one element of a broadcasted array may refer to a single memory location. -(broadcast-to)= -### broadcast_to(array, /, shape, /) +(function-broadcast-to)= +### broadcast_to(array, /, shape) Broadcast an array to a new shape. @@ -38,7 +39,7 @@ Broadcast an array to a new shape. - array to broadcast. -- **shape**: _<dtype>_ +- **shape**: Tuple[int, …] - shape of the desired array. @@ -46,20 +47,20 @@ Broadcast an array to a new shape. - **out**: _<array>_ - - a readonly view on the original array with the given shape where more than one element of a broadcasted array may refer to a single memory location. + - an array with the given shape where more than one element may refer to a single memory location. -(can-cast)= -### can_cast(from_, /, to, /) +(function-can-cast)= +### can_cast(from_, /, *, to) Determines if a type conversion is allowed under the rules described by {ref}`type-promotion`. #### Parameters -- **from_**: _Union\[ <dtype> ]_ +- **from_**: _Union\[ <dtype>, <array>]_ - data type, scalar or array to cast from. -- **to**: _<dtype>_ +- **to**: _<dtype>_ - data type to cast to. From 5dd0b9ea537b874ef2d3ef76a915569181c2fef1 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Thu, 1 Apr 2021 13:51:00 -0500 Subject: [PATCH 8/9] add review changes --- spec/API_specification/data_type_functions.md | 43 +++++++++---------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index ef99d0b03..83634232b 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -4,72 +4,71 @@ A conforming implementation of the array API standard must provide and support the following data type functions. - ## Objects in API (function-broadcast-arrays)= -### broadcast_arrays(*args, /) +### broadcast_arrays(\*args, /) -Broadcast any number of arrays against each other. +Broadcasts one or more arrays against one another. #### Parameters -- ***args**: _\[<array>\]_ +- **\*args**: _Sequence\[ <array> ]_ - arrays to broadcast. #### Returns -- **out**: _\[<array>\]_ - - - a list of arrays where more than one element of a broadcasted array may refer to a single memory location. +- **out**: _List\[ <array> ]_ + - a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array. (function-broadcast-to)= -### broadcast_to(array, /, shape) - -Broadcast an array to a new shape. +### broadcast_to(x, shape, /) -- A `ValueError` exception must be raised if the array is not compatible with the new shape according to the semantics defined in {ref}`broadcasting`. +Broadcasts an array to a specified shape. #### Parameters -- **array**: _<array>_ +- **x**: _<array>_ - array to broadcast. -- **shape**: Tuple[int, …] +- **shape**: _Tuple\[int, ...]_ - - shape of the desired array. + - array shape. Must be compatible with `x` (see {ref}`broadcasting`). #### Returns - **out**: _<array>_ - - an array with the given shape where more than one element may refer to a single memory location. + - an array having a specified shape. Must have the same data type as `x`. + +#### Raises + + - if the array is incompatible with the specified shape (see {ref}`broadcasting`). (function-can-cast)= -### can_cast(from_, /, *, to) +### can_cast(from, to, /) -Determines if a type conversion is allowed under the rules described by {ref}`type-promotion`. +Determines if one data type can be cast to another data type according {ref}`type-promotion` rules. #### Parameters -- **from_**: _Union\[ <dtype>, <array>]_ +- **from**: _Union\[ <dtype>, <array>]_ - - data type, scalar or array to cast from. + - input data type or array from which to cast. - **to**: _<dtype>_ - - data type to cast to. + - desired data type. #### Returns - **out**: _bool_ - - True if the cast can occur according to the {ref}`type-promotion`. - + - `True` if the cast can occur according to {ref}`type-promotion` rules; otherwise, `False`. (finfo)= ### finfo(type, /) From c374a6fd17a49caabf0faed28fc44ffa6010857d Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 12 Apr 2021 10:41:19 -0700 Subject: [PATCH 9/9] Remove indentation --- spec/API_specification/data_type_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 83634232b..125bca50b 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -47,7 +47,7 @@ Broadcasts an array to a specified shape. #### Raises - - if the array is incompatible with the specified shape (see {ref}`broadcasting`). +- if the array is incompatible with the specified shape (see {ref}`broadcasting`). (function-can-cast)= ### can_cast(from, to, /)