From 7b67d011c8f43d9260ee1fbb58d244d42adc450a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 14 Jan 2021 09:19:38 -0800 Subject: [PATCH 01/20] Add SVD spec --- .../linear_algebra_functions.md | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ba92aa7b0..1163fc480 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -275,9 +275,33 @@ TODO TODO (function-svd)= -### svd() +### svd(x, /, *, compute_uv=True, full_matrices=True) -TODO +Computes the singular value decomposition of a matrix (or stack of matrices) `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, N)` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Must have a data type of either `float32` or `float64`. + +- **compute_uv**: _bool_ + + - If `True`, compute the left and right singular vectors and return as `u` and `v`, respectively. Default: `True`. + +- **full_matrices**: _bool_ + + - If `True`, compute full-sized `u` and `v`, such that `u` has shape `(..., M, M)` and `v` has shape `(..., N, N)`. If `False`, compute on the leading `K` singular vectors, such that `u` has shape `(..., M, K)` and `v` has shape `(..., K, N)` and where `K = min(M, N)`. This option must be ignored if `compute_uv` is `False`. Default: `True`. + +#### Returns + +- **out**: _<array>_ + + - a namedtuple `(s, u, v)` whose + + - first element must be an array having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size as those of the input `x`. + - second 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). 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 size as those of the input `x`. The second element is only returned when `compute_uv` is `True`. + - 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). 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 size as those of the input `x`. The third element is only returned when `compute_uv` is `True`. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From 1ffd531b3d94a4cfc254e84e8179f9bc1e3ebdbb Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 14 Jan 2021 09:37:13 -0800 Subject: [PATCH 02/20] Update spec --- spec/API_specification/linear_algebra_functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 1163fc480..4500bb1a7 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -291,7 +291,7 @@ Computes the singular value decomposition of a matrix (or stack of matrices) `x` - **full_matrices**: _bool_ - - If `True`, compute full-sized `u` and `v`, such that `u` has shape `(..., M, M)` and `v` has shape `(..., N, N)`. If `False`, compute on the leading `K` singular vectors, such that `u` has shape `(..., M, K)` and `v` has shape `(..., K, N)` and where `K = min(M, N)`. This option must be ignored if `compute_uv` is `False`. Default: `True`. + - If `True`, compute full-sized `u` and `v`, such that `u` has shape `(..., M, M)` and `v` has shape `(..., N, N)`. If `False`, compute on the leading `K` singular vectors, such that `u` has shape `(..., M, K)` and `v` has shape `(..., N, K)` and where `K = min(M, N)`. This option must be ignored if `compute_uv` is `False`. Default: `True`. #### Returns @@ -300,8 +300,8 @@ Computes the singular value decomposition of a matrix (or stack of matrices) `x` - a namedtuple `(s, u, v)` whose - first element must be an array having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size as those of the input `x`. - - second 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). 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 size as those of the input `x`. The second element is only returned when `compute_uv` is `True`. - - 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). 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 size as those of the input `x`. The third element is only returned when `compute_uv` is `True`. + - second 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 size as those of the input `x`. The second element is only returned when `compute_uv` is `True`. + - 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 columns. If `full_matrices` is `True`, the array must have shape `(..., N, N)`. If `full_matrices` is `False`, the array must have shape `(..., N, K)` where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same size as those of the input `x`. The third element is only returned when `compute_uv` is `True`. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From 44db4878a87f240565fa29dc32d9237aa0cc1d75 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 11 Feb 2021 10:53:40 -0800 Subject: [PATCH 03/20] Update to follow NumPy --- spec/API_specification/linear_algebra_functions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 4500bb1a7..c678af0be 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -277,7 +277,7 @@ TODO (function-svd)= ### svd(x, /, *, compute_uv=True, full_matrices=True) -Computes the singular value decomposition of a matrix (or stack of matrices) `x`. +Computes the singular value decomposition `A = USV` of a matrix (or stack of matrices) `x`. #### Parameters @@ -297,11 +297,11 @@ Computes the singular value decomposition of a matrix (or stack of matrices) `x` - **out**: _<array>_ - - a namedtuple `(s, u, v)` whose + - a namedtuple `(u, s, v)` whose - - first element must be an array having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size as those of the input `x`. - - second 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 size as those of the input `x`. The second element is only returned when `compute_uv` is `True`. - - 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 columns. If `full_matrices` is `True`, the array must have shape `(..., N, N)`. If `full_matrices` is `False`, the array must have shape `(..., N, K)` where `K = min(M, N)`. The first `x.ndim-2` dimensions must have the same size as those of the input `x`. The third element is only returned when `compute_uv` is `True`. + - 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 size as those of the input `x`. The second element is only returned when `compute_uv` is `True`. + - second element must be an array having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size 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 size as those of the input `x`. The third element is only returned when `compute_uv` is `True`. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From 34b07ce8e653cba04e758be25377dc71e455f5d7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 14 Feb 2021 23:46:47 -0800 Subject: [PATCH 04/20] Fix annotation --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index c678af0be..c7a8095f5 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -295,7 +295,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat #### Returns -- **out**: _<array>_ +- **out**: _Tuple\[ <array> ]_ - a namedtuple `(u, s, v)` whose From 4cf11c777c850ff1025fa01a5731675c57356cd6 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 14 Feb 2021 23:50:10 -0800 Subject: [PATCH 05/20] Update type --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index c7a8095f5..c613258d1 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -295,7 +295,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat #### Returns -- **out**: _Tuple\[ <array> ]_ +- **out**: _Tuple\[ Union\[ <array>, None ] ]_ - a namedtuple `(u, s, v)` whose From f89ec081b29398200f9c11e5cbbe330931976c59 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 14 Feb 2021 23:51:46 -0800 Subject: [PATCH 06/20] Update descriptions --- 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 c613258d1..249405c0e 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -299,9 +299,9 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - 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 size as those of the input `x`. The second element is only returned when `compute_uv` is `True`. + - 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 size as those of the input `x`. The first element is only returned when `compute_uv` is `True` and is `None` when `compute_uv` is `False`. - second element must be an array having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size 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 size as those of the input `x`. The third element is only returned when `compute_uv` is `True`. + - 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 size as those of the input `x`. The third element is only returned when `compute_uv` is `True` and is `None` when `compute_uv` is `False`. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From c66943baa1031df74cbf554dfaed79555f89cdcf Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 15 Feb 2021 00:00:01 -0800 Subject: [PATCH 07/20] Update annotation --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 249405c0e..97b9e3c5d 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -295,7 +295,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat #### Returns -- **out**: _Tuple\[ Union\[ <array>, None ] ]_ +- **out**: _Tuple\[ Union\[ <array>, None ], ... ]_ - a namedtuple `(u, s, v)` whose From 0963d428f8ea608b32fbd0b062f32cbdf8471607 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 15 Feb 2021 21:39:42 -0800 Subject: [PATCH 08/20] Return a tuple only when `compute_uv` is `True` --- spec/API_specification/linear_algebra_functions.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 97b9e3c5d..3abd5c30c 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -295,13 +295,15 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat #### Returns -- **out**: _Tuple\[ Union\[ <array>, None ], ... ]_ +- **out**: _Union\[ <array>, Tuple\[ Union\[ <array>, None ], ... ] ]_ - - a namedtuple `(u, s, v)` whose + - if `compute_uv` is `False`, an array having shape `(..., K)` and containing the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size as those of the input `x`. + + - if `compute_uv` is `True`, 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 size as those of the input `x`. The first element is only returned when `compute_uv` is `True` and is `None` when `compute_uv` is `False`. + - 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 size as those of the input `x`. - second element must be an array having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size 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 size as those of the input `x`. The third element is only returned when `compute_uv` is `True` and is `None` when `compute_uv` is `False`. + - 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 size as those of the input `x`. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From 2524838c888abc374edce20e86cfedb8aaf13264 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 15 Feb 2021 21:44:58 -0800 Subject: [PATCH 09/20] Fix type annotation --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 3abd5c30c..ba4c25e53 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -295,7 +295,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat #### Returns -- **out**: _Union\[ <array>, Tuple\[ Union\[ <array>, None ], ... ] ]_ +- **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ - if `compute_uv` is `False`, an array having shape `(..., K)` and containing the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size as those of the input `x`. From 88317b64ed1fdec8bc13b2b494c2c5aaed1f509d Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 1 Mar 2021 09:38:30 -0800 Subject: [PATCH 10/20] Update copy Co-authored-by: Leo Fang --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ba4c25e53..84be5655e 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -297,7 +297,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ - - if `compute_uv` is `False`, an array having shape `(..., K)` and containing the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size as those of the input `x`. + - if `compute_uv` is `False`, 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`. - if `compute_uv` is `True`, a namedtuple `(u, s, v)` whose From b586f5156a7f90c6b6307c94fc057d3d998b61b4 Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 1 Mar 2021 09:39:13 -0800 Subject: [PATCH 11/20] Update copy Co-authored-by: Leo Fang --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 84be5655e..b46524a3a 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -301,7 +301,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - if `compute_uv` is `True`, 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 size as those of the input `x`. + - 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 having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size 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 size as those of the input `x`. From ed814d9aed0d474f5ea20dbd1847976de2bf101e Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 1 Mar 2021 09:39:30 -0800 Subject: [PATCH 12/20] Update copy Co-authored-by: Leo Fang --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index b46524a3a..fd613d7e0 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -303,7 +303,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - 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 having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size 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 size 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`. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From 9899c864da93830897a43fa8b53643e62b5d284e Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 1 Mar 2021 09:40:19 -0800 Subject: [PATCH 13/20] Update copy Co-authored-by: Leo Fang --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index fd613d7e0..9a5680e7e 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -302,7 +302,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - if `compute_uv` is `True`, 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 having shape `(..., K)` and contain the vector(s) containing the singular values. For each vector, the values must be sorted in descending order according to 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 size 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`. (function-trace)= From 1f5c96517adad2a034efb6fa92871fd390ce6628 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 1 Mar 2021 09:44:26 -0800 Subject: [PATCH 14/20] Fix docs --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ba4c25e53..47da86ec3 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -291,7 +291,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - **full_matrices**: _bool_ - - If `True`, compute full-sized `u` and `v`, such that `u` has shape `(..., M, M)` and `v` has shape `(..., N, N)`. If `False`, compute on the leading `K` singular vectors, such that `u` has shape `(..., M, K)` and `v` has shape `(..., N, K)` and where `K = min(M, N)`. This option must be ignored if `compute_uv` is `False`. Default: `True`. + - If `True`, compute full-sized `u` and `v`, such that `u` has shape `(..., M, M)` and `v` has shape `(..., N, N)`. If `False`, compute on the leading `K` singular vectors, such that `u` has shape `(..., M, K)` and `v` has shape `(..., K, N)` and where `K = min(M, N)`. This option must be ignored if `compute_uv` is `False`. Default: `True`. #### Returns From f86167703cc4d7bb5d2c9c7dcf51ebb4beff8445 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 16:51:44 -0700 Subject: [PATCH 15/20] Update dtype requirements --- spec/API_specification/linear_algebra_functions.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index c9ab9fdb4..c8522f3da 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -283,7 +283,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - **x**: _<array>_ - - input array having shape `(..., M, N)` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Must have a data type of either `float32` or `float64`. + - input array having shape `(..., M, N)` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Should have a floating-point data type. - **compute_uv**: _bool_ @@ -297,13 +297,15 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ - - if `compute_uv` is `False`, 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`. + - if `compute_uv` is `False`, 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 a floating-point data type determined by {ref}`type-promotion` rules. - if `compute_uv` is `True`, 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`. + - 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 determined by {ref}`type-promotion` rules. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From 686d19d6f18fe4590c7c48c747c2fef32eb04e81 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:38:57 -0700 Subject: [PATCH 16/20] Update copy --- 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 c8522f3da..95bd513d4 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -297,7 +297,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ - - if `compute_uv` is `False`, 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 a floating-point data type determined by {ref}`type-promotion` rules. + - if `compute_uv` is `False`, 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 a floating-point data type determined by {ref}`type-promotion`. - if `compute_uv` is `True`, a namedtuple `(u, s, v)` whose @@ -305,7 +305,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - 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 determined by {ref}`type-promotion` rules. + Each returned array must have the same floating-point data type as determined by {ref}`type-promotion`. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From ddec299515a15d9ab9ceac0f584e44661a080256 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 12 Apr 2021 09:35:04 -0700 Subject: [PATCH 17/20] Always return u and v singular vectors --- spec/API_specification/linear_algebra_functions.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 95bd513d4..b55a56a38 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -275,7 +275,7 @@ TODO TODO (function-svd)= -### svd(x, /, *, compute_uv=True, full_matrices=True) +### svd(x, /, *, full_matrices=True) Computes the singular value decomposition `A = USV` of a matrix (or stack of matrices) `x`. @@ -285,21 +285,15 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - input array having shape `(..., M, N)` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Should have a floating-point data type. -- **compute_uv**: _bool_ - - - If `True`, compute the left and right singular vectors and return as `u` and `v`, respectively. Default: `True`. - - **full_matrices**: _bool_ - - If `True`, compute full-sized `u` and `v`, such that `u` has shape `(..., M, M)` and `v` has shape `(..., N, N)`. If `False`, compute on the leading `K` singular vectors, such that `u` has shape `(..., M, K)` and `v` has shape `(..., K, N)` and where `K = min(M, N)`. This option must be ignored if `compute_uv` is `False`. Default: `True`. + - If `True`, compute full-sized `u` and `v`, such that `u` has shape `(..., M, M)` and `v` has shape `(..., N, N)`. If `False`, compute on the leading `K` singular vectors, such that `u` has shape `(..., M, K)` and `v` has shape `(..., K, N)` and where `K = min(M, N)`. Default: `True`. #### Returns - **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ - - if `compute_uv` is `False`, 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 a floating-point data type determined by {ref}`type-promotion`. - - - if `compute_uv` is `True`, a namedtuple `(u, s, v)` whose + - 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`. From 9c1700155d20258f644a9a0f5c179124a6ca6f32 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 12 Apr 2021 09:40:29 -0700 Subject: [PATCH 18/20] Update return type --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 964015f2f..e338fafb7 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -299,7 +299,7 @@ Computes the singular value decomposition `A = USV` of a matrix (or stack of mat - 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 determined by {ref}`type-promotion`. + Each returned array must have the same floating-point data type as `x`. (function-trace)= ### trace(x, /, *, axis1=0, axis2=1, offset=0) From 760135d36f07e32a82dcd86a42a32752211ee6c0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 12 Apr 2021 09:49:37 -0700 Subject: [PATCH 19/20] Add article --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index e338fafb7..9fbce8f3a 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -277,7 +277,7 @@ TODO (function-svd)= ### svd(x, /, *, full_matrices=True) -Computes the singular value decomposition `A = USV` of a matrix (or stack of matrices) `x`. +Computes the singular value decomposition `A = USV` of a matrix (or a stack of matrices) `x`. #### Parameters From 6e0e2324e74123b8b58e657af3d598ad8a49a4a7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 26 Apr 2021 02:31:55 -0700 Subject: [PATCH 20/20] Move API to submodule --- 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 9fbce8f3a..d0461dbe8 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -274,8 +274,8 @@ TODO TODO -(function-svd)= -### svd(x, /, *, full_matrices=True) +(function-linalg-svd)= +### linalg.svd(x, /, *, full_matrices=True) Computes the singular value decomposition `A = USV` of a matrix (or a stack of matrices) `x`.