From f28314710cce2e39366b9097b1eadc12f6d622b6 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 21 Jun 2021 16:39:38 -0600 Subject: [PATCH 1/6] Fix alphabetical function ordering in the linear algebra extension --- spec/extensions/linear_algebra_functions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/spec/extensions/linear_algebra_functions.md b/spec/extensions/linear_algebra_functions.md index 5f9eaf0a7..6cf5fdfb3 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -565,21 +565,16 @@ Computes the singular value decomposition `A = USV` of a matrix (or a stack of m #### Returns -- **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ +- **out**: _Tuple\[ <array>, <array>, <array> ]_ - a namedtuple `(u, s, v)` whose - + - first element must be an array whose shape depends on the value of `full_matrices` and contain unitary array(s) (i.e., the left singular vectors). The left singular vectors must be stored as columns. If `full_matrices` is `True`, the array must have shape `(..., M, M)`. If `full_matrices` is `False`, the array must have shape `(..., M, K)`, where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`. - second element must be an array with shape `(..., K)` that contains the vector(s) of singular values of length `K`. For each vector, the singular values must be sorted in descending order by magnitude, such that `s[..., 0]` is the largest value, `s[..., 1]` is the second largest value, et cetera. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`. - third element must be an array whose shape depends on the value of `full_matrices` and contain unitary array(s) (i.e., the right singular vectors). The right singular vectors must be stored as rows (i.e., the array is the adjoint). If `full_matrices` is `True`, the array must have shape `(..., N, N)`. If `full_matrices` is `False`, the array must have shape `(..., K, N)` where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`. Each returned array must have the same floating-point data type as `x`. -(function-linalg-tensordot)= -### linalg.tensordot(x1, x2, /, *, axes=2) - -Alias for {ref}`function-tensordot`. - (function-linalg-svdvals)= ### linalg.svdvals(x, /) @@ -597,6 +592,11 @@ Computes the singular values of a matrix (or a stack of matrices) `x`. - an array with shape `(..., K)` that contains the vector(s) of singular values of length `K`. For each vector, the singular values must be sorted in descending order by magnitude, such that `s[..., 0]` is the largest value, `s[..., 1]` is the second largest value, et cetera. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`. The returned array must have the same floating-point data type as `x`. +(function-linalg-tensordot)= +### linalg.tensordot(x1, x2, /, *, axes=2) + +Alias for {ref}`function-tensordot`. + (function-linalg-trace)= ### linalg.trace(x, /, *, axis1=0, axis2=1, offset=0) From 311fda8404a20b8370cccaaf5720810cb6b525bd Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 16 Jul 2021 16:48:16 -0600 Subject: [PATCH 2/6] Update some type hints in the spec These come from comments on the NumPy pull request https://github.com/numpy/numpy/pull/18585. --- spec/API_specification/creation_functions.md | 2 +- spec/API_specification/manipulation_functions.md | 4 ++-- spec/API_specification/searching_functions.md | 4 ++-- spec/extensions/linear_algebra_functions.md | 14 +++++++------- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 8b1bec16e..e2eb7d6f3 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -57,7 +57,7 @@ Convert the input to an array. #### Parameters -- **obj**: _Union\[ float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_ +- **obj**: _Union\[ <array>, float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_ - Object to be converted to an array. Can be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting DLPack or the Python buffer protocol. diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index ae8499370..e1e0e98ea 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -19,7 +19,7 @@ Joins a sequence of arrays along an existing axis. #### Parameters -- **arrays**: _Tuple\[ <array>, ... ]_ +- **arrays**: _Union\[Tuple\[ <array>, ... ], List\[ <array> ] ]_ - input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`. @@ -154,7 +154,7 @@ Joins a sequence of arrays along a new axis. #### Parameters -- **arrays**: _Tuple\[ <array>, ... ]_ +- **arrays**: _Union\[Tuple\[ <array>, ... ], List\[ <array> ] ]_ - input arrays to join. Each array must have the same shape. diff --git a/spec/API_specification/searching_functions.md b/spec/API_specification/searching_functions.md index d3d06d7a6..c86bef28d 100644 --- a/spec/API_specification/searching_functions.md +++ b/spec/API_specification/searching_functions.md @@ -27,7 +27,7 @@ Returns the indices of the maximum values along a specified axis. When the maxim - input array. -- **axis**: _int_ +- **axis**: _Optional\[ int ]_ - axis along which to search. If `None`, the function must return the index of the maximum value of the flattened array. Default: `None`. @@ -52,7 +52,7 @@ Returns the indices of the minimum values along a specified axis. When the minim - input array. -- **axis**: _int_ +- **axis**: _Optional\[ int ]_ - axis along which to search. If `None`, the function must return the index of the minimum value of the flattened array. Default: `None`. diff --git a/spec/extensions/linear_algebra_functions.md b/spec/extensions/linear_algebra_functions.md index 6cf5fdfb3..ad5505bc7 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -201,7 +201,7 @@ Returns the eigenvalues and eigenvectors of a symmetric matrix (or a stack of sy - **out**: _Tuple\[ <array> ]_ - a namedtuple (`e`, `v`) whose - + - first element must have shape `(..., M)` and consist of computed eigenvalues. - second element must have shape `(..., M, M)`and have the columns of the inner most matrices contain the computed eigenvectors. @@ -291,7 +291,7 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - **out**: _Tuple\[ <array>, <array>, <array>, <array> ]_ - a namedtuple `(x, residuals, rank, s)` whose - + - first element must have the field name `x` and must be an array containing the least-squares solution for each `MxN` matrix in `x1`. The array containing the solutions must have shape `(N, K)` and must have a floating-point data type determined by {ref}`type-promotion`. - second element must have the field name `residuals` and must be an array containing the sum of squares residuals (i.e., the squared Euclidean 2-norm for each column in `b - Ax`). The array containing the residuals must have shape `(K,)` and must have a floating-point data type determined by {ref}`type-promotion`. - third element must have the field name `rank` and must be an array containing the effective rank of each `MxN` matrix. The array containing the ranks must have shape `shape(x1)[:-2]` and must have an integer data type. @@ -300,7 +300,7 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. (function-linalg-matmul)= ### linalg.matmul(x1, x2, /) -Alias for {ref}`function-matmul`. +Alias for {ref}`function-matmul`. (function-linalg-matrix_power)= ### linalg.matrix_power(x, n, /) @@ -458,7 +458,7 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of square ma - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type. - **rtol**: _Optional\[ Union\[ float, <array> ] ]_ - + - relative tolerance for small singular values. Singular values less than or equal to `rtol * largest_singular_value` are set to zero. If a `float`, the value is equivalent to a zero-dimensional array having a floating-point data type determined by {ref}`type-promotion` (as applied to `x`) and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the floating-point data type determined by {ref}`type-promotion` (as applied to `x`). Default: `None`. #### Returns @@ -519,10 +519,10 @@ The purpose of this function is to calculate the determinant more accurately whe - **out**: _Tuple\[ <array>, <array> ]_ - a namedtuple (`sign`, `logabsdet`) whose - + - first element must be an array containing a number representing the sign of the determinant for each square matrix. - second element must be an array containing the determinant for each square matrix. - + For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. Each returned array must have shape `shape(x)[:-2]` and a floating-point data type determined by {ref}`type-promotion`. @@ -648,4 +648,4 @@ Alias for {ref}`function-transpose`. (function-linalg-vecdot)= ### linalg.vecdot(x1, x2, /, *, axis=None) -Alias for {ref}`function-vecdot`. \ No newline at end of file +Alias for {ref}`function-vecdot`. From 3802800acc003618fdec70bd489ce61f15de3565 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 16 Jul 2021 16:49:02 -0600 Subject: [PATCH 3/6] Clarify that the where() result type is only based on the last two arguments --- spec/API_specification/searching_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/searching_functions.md b/spec/API_specification/searching_functions.md index c86bef28d..cc3574614 100644 --- a/spec/API_specification/searching_functions.md +++ b/spec/API_specification/searching_functions.md @@ -106,4 +106,4 @@ Returns elements chosen from `x1` or `x2` depending on `condition`. - **out**: _<array>_ - - an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. The returned array must have a data type determined by {ref}`type-promotion` rules. + - an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. The returned array must have a data type determined by {ref}`type-promotion` rules with the arrays `x1` and `x2`. From 96440e2e0d84da7fe709257c1ee74f5862a088a4 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 16 Jul 2021 16:49:44 -0600 Subject: [PATCH 4/6] Use Literal[] for the qr() mode argument type hint --- spec/extensions/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/extensions/linear_algebra_functions.md b/spec/extensions/linear_algebra_functions.md index ad5505bc7..efb8779ec 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -478,7 +478,7 @@ Computes the qr factorization of a matrix (or a stack of matrices), where `q` is - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type. -- **mode**: _str_ +- **mode**: _Literal\[ 'reduced', 'complete' ]_ - factorization mode. Should be one of the following modes: From dc07c0fa8849d00f707630b7cc9e6e7872d82938 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 20 Jul 2021 12:36:48 -0600 Subject: [PATCH 5/6] Add bool and int to the asarray type hints --- spec/API_specification/creation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index e2eb7d6f3..da7b250b4 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -57,7 +57,7 @@ Convert the input to an array. #### Parameters -- **obj**: _Union\[ <array>, float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_ +- **obj**: _Union\[ <array>, bool, int, float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_ - Object to be converted to an array. Can be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting DLPack or the Python buffer protocol. From f58e381b988e26d239e4e6f7a980c00e51a6efe6 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 12 Aug 2021 15:24:43 -0600 Subject: [PATCH 6/6] Fix a typo in the __setitem__ annotations --- spec/API_specification/array_object.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 93e806de3..dcf78228b 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -780,7 +780,7 @@ The `matmul` function must implement the same semantics as the built-in `@` oper - **self**: _<array>_ - - array instance. Should have a numeric data type. Must have at least one dimension. If `self` is one-dimensional having shape `(M)` and `other` has more than one dimension, `self` must be promoted to a two-dimensional array by prepending `1` to its dimensions (i.e., must have shape `(1, M)`). After matrix multiplication, the prepended dimensions in the returned array must be removed. If `self` has more than one dimension (including after vector-to-matrix promotion), `self` must be compatible with `other` (see {ref}`broadcasting`). If `self` has shape `(..., M, K)`, the innermost two dimensions form matrices on which to perform matrix multiplication. + - array instance. Should have a numeric data type. Must have at least one dimension. If `self` is one-dimensional having shape `(M)` and `other` has more than one dimension, `self` must be promoted to a two-dimensional array by prepending `1` to its dimensions (i.e., must have shape `(1, M)`). After matrix multiplication, the prepended dimensions in the returned array must be removed. If `self` has more than one dimension (including after vector-to-matrix promotion), `self` must be compatible with `other` (see {ref}`broadcasting`). If `self` has shape `(..., M, K)`, the innermost two dimensions form matrices on which to perform matrix multiplication. - **other**: _<array>_ @@ -809,7 +809,7 @@ The `matmul` function must implement the same semantics as the built-in `@` oper - if either `self` or `other` is a zero-dimensional array. - if `self` is a one-dimensional array having shape `(N)`, `other` is a one-dimensional array having shape `(M)`, and `N != M`. -- if `self` is an array having shape `(..., M, K)`, `other` is an array having shape `(..., L, N)`, and `K != L`. +- if `self` is an array having shape `(..., M, K)`, `other` is an array having shape `(..., L, N)`, and `K != L`. (method-__mod__)= ### \_\_mod\_\_(self, other, /) @@ -1066,7 +1066,7 @@ Sets `self[key]` to `value`. #### Parameters -- **self**: _<array;>_ +- **self**: _<array>_ - array instance.