From 3e310ad7a1c4171578af63b2c92b7c0ac44e3e1e Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 8 Oct 2021 17:09:27 -0600 Subject: [PATCH 1/8] Fix the input description for cholesky() --- 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 15a2e7efe..19b7fc0f2 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -86,7 +86,7 @@ Returns the Cholesky decomposition of a symmetric positive-definite matrix (or a - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a floating-point data type. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square symmetric positive-definite matrices. Should have a floating-point data type. - **upper**: _bool_ From 4d3e9434a51b7069a99019aaf1d73d7d3b33cf21 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 8 Oct 2021 17:10:36 -0600 Subject: [PATCH 2/8] Add some additional error cases for @ and matmul Also use more consistent variable names for the shapes in the error cases. --- spec/API_specification/array_object.md | 4 +++- spec/API_specification/linear_algebra_functions.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 823fdc6b2..ca1819369 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -837,7 +837,9 @@ The `matmul` function must implement the same semantics as the built-in `@` oper #### Raises - 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 a one-dimensional array having shape `(K)`, `other` is a one-dimensional array having shape `(L)`, and `K != L`. +- if `self` is a one-dimensional array having shape `(K)`, `other` is an array having shape `(..., L, M)`, and `K != L`. +- if `self` is an array having shape `(..., N, K)`, `other` is a one-dimensional array having shape `(L)`, 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__)= diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 139dea215..4748357c0 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -52,7 +52,9 @@ The `matmul` function must implement the same semantics as the built-in `@` oper #### Raises - if either `x1` or `x2` is a zero-dimensional array. -- if `x1` is a one-dimensional array having shape `(N)`, `x2` is a one-dimensional array having shape `(M)`, and `N != M`. +- if `x1` is a one-dimensional array having shape `(K)`, `x2` is a one-dimensional array having shape `(L)`, and `K != L`. +- if `x1` is a one-dimensional array having shape `(K)`, `x2` is an array having shape `(..., L, M)`, and `K != L`. +- if `x1` is an array having shape `(..., N, K)`, `x2` is a one-dimensional array having shape `(L)`, and `K != L`. - if `x1` is an array having shape `(..., M, K)`, `x2` is an array having shape `(..., L, N)`, and `K != L`. (function-matrix-transpose)= From 20a01e3e3c3a74b6ae6c3f8cce340f5206abcd81 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Wed, 13 Oct 2021 16:44:07 -0600 Subject: [PATCH 3/8] Fix the output shape for qr(mode='complete').r --- 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 19b7fc0f2..d936fa4f5 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -419,7 +419,7 @@ Computes the qr factorization of a matrix (or a stack of matrices), where `q` is - a namedtuple `(q, r)` whose - first element must have the field name `q` and must be an array whose shape depends on the value of `mode` and contain orthonormal matrices. If `mode` is `'complete'`, the array must have shape `(..., M, M)`. If `mode` is `'reduced'`, the array must have shape `(..., M, K)`, where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same size as those of the input `x`. - - second element must have the field name `r` and must be an array whose shape depends on the value of `mode` and contain upper-triangular matrices. If `mode` is `'complete'`, the array must have shape `(..., M, M)`. If `mode` is `'reduced'`, the array must have shape `(..., K, N)`, where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same size as those of the input `x`. + - second element must have the field name `r` and must be an array whose shape depends on the value of `mode` and contain upper-triangular matrices. If `mode` is `'complete'`, the array must have shape `(..., M, N)`. If `mode` is `'reduced'`, the array must have shape `(..., K, N)`, where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same size as those of the input `x`. Each returned array must have a floating-point data type determined by {ref}`type-promotion`. From cac0ae146ff26bfcdc7fc5b2ab9e4e82faeeb09b Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Wed, 27 Oct 2021 16:21:20 -0600 Subject: [PATCH 4/8] Clarify what K equals in the svd and svdvals specifications --- spec/extensions/linear_algebra_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/extensions/linear_algebra_functions.md b/spec/extensions/linear_algebra_functions.md index d936fa4f5..27d30942b 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -495,7 +495,7 @@ Computes the singular value decomposition `A = USVh` of a matrix (or a stack of - a namedtuple `(u, s, vh)` whose - first element must have the field name `u` and 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 have the field name `s` and 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`. + - second element must have the field name `s` and must be an array with shape `(..., K)` that contains the vector(s) of singular values of length `K`, where `K = min(M, N)`. 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 have the field name `vh` and 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`. @@ -515,7 +515,7 @@ Computes the singular values of a matrix (or a stack of matrices) `x`. - **out**: _<array>_ - - 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`. + - an array with shape `(..., K)` that contains the vector(s) of singular values of length `K`, where `K = min(M, N)`. 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) From c42abda9b53b8e93d3aa0de221fb76482f1ff842 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 4 Nov 2021 21:30:54 -0700 Subject: [PATCH 5/8] Use consistent naming conventions --- 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 ca1819369..452fe39ec 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -839,7 +839,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 `(K)`, `other` is a one-dimensional array having shape `(L)`, and `K != L`. - if `self` is a one-dimensional array having shape `(K)`, `other` is an array having shape `(..., L, M)`, and `K != L`. -- if `self` is an array having shape `(..., N, K)`, `other` is a one-dimensional array having shape `(L)`, and `K != L`. +- if `self` is an array having shape `(..., M, K)`, `other` is a one-dimensional array having shape `(L)`, 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__)= From 53089e9a55211432faba86f0e0bf59a2ed377cc2 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 4 Nov 2021 21:32:45 -0700 Subject: [PATCH 6/8] Use consistent naming conventions --- 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 452fe39ec..7a5696310 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -838,7 +838,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 `(K)`, `other` is a one-dimensional array having shape `(L)`, and `K != L`. -- if `self` is a one-dimensional array having shape `(K)`, `other` is an array having shape `(..., L, M)`, and `K != L`. +- if `self` is a one-dimensional array having shape `(K)`, `other` is an array having shape `(..., L, N)`, and `K != L`. - if `self` is an array having shape `(..., M, K)`, `other` is a one-dimensional array having shape `(L)`, and `K != L`. - if `self` is an array having shape `(..., M, K)`, `other` is an array having shape `(..., L, N)`, and `K != L`. From 32dcf8a6e658a2e75335657b8f6a6b6ace9cf0e3 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 4 Nov 2021 22:04:07 -0700 Subject: [PATCH 7/8] Use consistent naming conventions --- spec/API_specification/linear_algebra_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 4748357c0..66db0d079 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -53,8 +53,8 @@ The `matmul` function must implement the same semantics as the built-in `@` oper - if either `x1` or `x2` is a zero-dimensional array. - if `x1` is a one-dimensional array having shape `(K)`, `x2` is a one-dimensional array having shape `(L)`, and `K != L`. -- if `x1` is a one-dimensional array having shape `(K)`, `x2` is an array having shape `(..., L, M)`, and `K != L`. -- if `x1` is an array having shape `(..., N, K)`, `x2` is a one-dimensional array having shape `(L)`, and `K != L`. +- if `x1` is a one-dimensional array having shape `(K)`, `x2` is an array having shape `(..., L, N)`, and `K != L`. +- if `x1` is an array having shape `(..., M, K)`, `x2` is a one-dimensional array having shape `(L)`, and `K != L`. - if `x1` is an array having shape `(..., M, K)`, `x2` is an array having shape `(..., L, N)`, and `K != L`. (function-matrix-transpose)= From a5200a49a5749b82b6b553a15d50835c34241025 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 4 Nov 2021 22:18:24 -0700 Subject: [PATCH 8/8] Restore changes --- 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 6642b33f9..0e432a896 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -516,7 +516,7 @@ Returns a singular value decomposition A = USVh of a matrix (or a stack of matri - a namedtuple `(U, S, Vh)` whose - first element must have the field name `U` and must be an array whose shape depends on the value of `full_matrices` and contain matrices with orthonormal columns (i.e., the columns are left singular vectors). 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 have the field name `S` and 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`. + - second element must have the field name `S` and must be an array with shape `(..., K)` that contains the vector(s) of singular values of length `K`, where `K = min(M, N)`. 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 have the field name `Vh` and must be an array whose shape depends on the value of `full_matrices` and contain orthonormal rows (i.e., the rows are the right singular vectors and 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`.