From 5bc330b84c7f2c39576b2472ab5c1cc65fa5d080 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 25 Jan 2021 11:07:47 -0800 Subject: [PATCH 01/17] Stub spec --- spec/API_specification/linear_algebra_functions.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ba92aa7b0..27878d635 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -135,9 +135,19 @@ Computes the multiplicative inverse of a square matrix (or stack of square matri - an array containing the multiplicative inverses. The returned array must have the same data type and shape as `x`. (function-lstsq)= -### lstsq() +### lstsq(x1, x2, /, *, rcond=None) -TODO +Returns the least-squares solution to a linear matrix equation `Ax = b`. + +#### Parameters + +- **x1**: _<array>_ + + - coefficient array `A` having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Must have a data type of either `float32` or `float64`. + +- **x2**: _<array>_ + + - ordinate (or "dependent variable") array `b` having shape `(..., M, K)`. Must have a data type of either `float32` or `float64`. (function-matmul)= ### matmul() From fc28df7bec7b592c54f3e7a95c08df137a464889 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 25 Jan 2021 11:10:16 -0800 Subject: [PATCH 02/17] Document keyword --- spec/API_specification/linear_algebra_functions.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 27878d635..41014d312 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -149,6 +149,16 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - ordinate (or "dependent variable") array `b` having shape `(..., M, K)`. Must have a data type of either `float32` or `float64`. +- **rcond**: _<array>_ + + - Cutoffs for small singular values. Singular values less than or equal to `rcond * largest_singular_value` are set to zero. Must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `10.0 * max(M, N) * eps`, where `eps` must be the floating-point epsilon associated with the data type of `x`. Default: `None`. + +#### Returns + +- **out**: _Tuple\[ <array>, ... ]_ + + - a namedtuple whose first element must have the field name `x` and must be an array containing the solution to the system `AX = B` for each square matrix. The array containing the solutions must have the same shape as `x2` (i.e., the array corresponding to `B`) and must have a data type determined by {ref}`type-promotion` rules. + (function-matmul)= ### matmul() From e3f336d38f6b71dae2ffb943c8eb8dee555e6f73 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 25 Jan 2021 11:42:37 -0800 Subject: [PATCH 03/17] Update spec --- spec/API_specification/linear_algebra_functions.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 41014d312..4708ff7d5 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -149,15 +149,20 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - ordinate (or "dependent variable") array `b` having shape `(..., M, K)`. Must have a data type of either `float32` or `float64`. -- **rcond**: _<array>_ +- **rcond**: _Optional\[ <array> ]_ - - Cutoffs for small singular values. Singular values less than or equal to `rcond * largest_singular_value` are set to zero. Must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `10.0 * max(M, N) * eps`, where `eps` must be the floating-point epsilon associated with the data type of `x`. Default: `None`. + - Cutoffs for small singular values. Singular values less than or equal to `rcond * largest_singular_value` are set to zero. 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 floating-point epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. #### Returns - **out**: _Tuple\[ <array>, ... ]_ - - a namedtuple whose first element must have the field name `x` and must be an array containing the solution to the system `AX = B` for each square matrix. The array containing the solutions must have the same shape as `x2` (i.e., the array corresponding to `B`) and must have a data type determined by {ref}`type-promotion` rules. + - a namedtuple `(x, residuals, rank, s)` whose + + - 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 data type determined by {ref}`type-promotion` rules. + - whose 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 data type determined by {ref}`type-promotion` rules. + - whose 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. + - whose fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N)` and must have a data type determined by {ref}`type-promotion` rules. (function-matmul)= ### matmul() From b698326e6f9a451671d752ffffb1fdcff4f405b6 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 1 Feb 2021 11:15:33 -0800 Subject: [PATCH 04/17] Add missing parenthesis --- 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 4708ff7d5..ed1ca7476 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -162,7 +162,7 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - 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 data type determined by {ref}`type-promotion` rules. - whose 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 data type determined by {ref}`type-promotion` rules. - whose 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. - - whose fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N)` and must have a data type determined by {ref}`type-promotion` rules. + - whose fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N))` and must have a data type determined by {ref}`type-promotion` rules. (function-matmul)= ### matmul() From b5c3ee735a34a33f484aabd2d6014f183ec89f96 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 15 Feb 2021 00:02:45 -0800 Subject: [PATCH 05/17] Remove duplicate words --- spec/API_specification/linear_algebra_functions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ed1ca7476..46aa2be35 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -159,10 +159,10 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - a namedtuple `(x, residuals, rank, s)` whose - - 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 data type determined by {ref}`type-promotion` rules. - - whose 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 data type determined by {ref}`type-promotion` rules. - - whose 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. - - whose fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N))` and must have a data type determined by {ref}`type-promotion` rules. + - 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 data type determined by {ref}`type-promotion` rules. + - 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 data type determined by {ref}`type-promotion` rules. + - 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. + - fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N))` and must have a data type determined by {ref}`type-promotion` rules. (function-matmul)= ### matmul() From dcbedd43b9a0db54351b6b793db915af5b99c207 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 15 Feb 2021 21:06:01 -0800 Subject: [PATCH 06/17] Rename keyword argument and add support for setting tolerance to a float --- 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 46aa2be35..b661ea964 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -135,7 +135,7 @@ Computes the multiplicative inverse of a square matrix (or stack of square matri - an array containing the multiplicative inverses. The returned array must have the same data type and shape as `x`. (function-lstsq)= -### lstsq(x1, x2, /, *, rcond=None) +### lstsq(x1, x2, /, *, tol=None) Returns the least-squares solution to a linear matrix equation `Ax = b`. @@ -149,9 +149,9 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - ordinate (or "dependent variable") array `b` having shape `(..., M, K)`. Must have a data type of either `float32` or `float64`. -- **rcond**: _Optional\[ <array> ]_ +- **tol**: _Optional\[ Union\[ float, <array> ] ]_ - - Cutoffs for small singular values. Singular values less than or equal to `rcond * largest_singular_value` are set to zero. 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 floating-point epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. + - cutoffs for small singular values. Singular values less than or equal to `tol * largest_singular_value` are set to zero. If a `float`, the value is equivalent to a zero-dimensional array having the same data type as `x` and is broadcast against each matrix. 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 floating-point epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. #### Returns From 1e565ed64af223e443b7d96ecb3a1a3725f410bc Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 15 Feb 2021 21:11:29 -0800 Subject: [PATCH 07/17] Update copy --- 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 b661ea964..6c04a6d6c 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -151,7 +151,7 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - **tol**: _Optional\[ Union\[ float, <array> ] ]_ - - cutoffs for small singular values. Singular values less than or equal to `tol * largest_singular_value` are set to zero. If a `float`, the value is equivalent to a zero-dimensional array having the same data type as `x` and is broadcast against each matrix. 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 floating-point epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. + - cutoffs for small singular values. Singular values less than or equal to `tol * largest_singular_value` are set to zero. If a `float`, the value is equivalent to a zero-dimensional array having a data type determined by {ref}`type-promotion` rules and is broadcast against each matrix. 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 floating-point epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. #### Returns From 37e55589f350a7400a552b248d8d2c35e39a8e50 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 15 Feb 2021 21:12:27 -0800 Subject: [PATCH 08/17] Reorder sentences --- 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 6c04a6d6c..4bc32e738 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -151,7 +151,7 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - **tol**: _Optional\[ Union\[ float, <array> ] ]_ - - cutoffs for small singular values. Singular values less than or equal to `tol * largest_singular_value` are set to zero. If a `float`, the value is equivalent to a zero-dimensional array having a data type determined by {ref}`type-promotion` rules and is broadcast against each matrix. 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 floating-point epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. + - cutoffs for small singular values. Singular values less than or equal to `tol * largest_singular_value` are set to zero. Must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If a `float`, the value is equivalent to a zero-dimensional array having a data type determined by {ref}`type-promotion` rules and is broadcast against each matrix. If `None`, the default value is `max(M, N) * eps`, where `eps` must be the floating-point epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. #### Returns From 0443dcfdbbb2f41fdbb51a309de6924ed7845126 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 4 Mar 2021 01:16:23 -0800 Subject: [PATCH 09/17] Rename keyword argument --- 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 4bc32e738..8989d24d0 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -149,9 +149,9 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - ordinate (or "dependent variable") array `b` having shape `(..., M, K)`. Must have a data type of either `float32` or `float64`. -- **tol**: _Optional\[ Union\[ float, <array> ] ]_ +- **rtol**: _Optional\[ Union\[ float, <array> ] ]_ - - cutoffs for small singular values. Singular values less than or equal to `tol * largest_singular_value` are set to zero. Must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If a `float`, the value is equivalent to a zero-dimensional array having a data type determined by {ref}`type-promotion` rules and is broadcast against each matrix. If `None`, the default value is `max(M, N) * eps`, where `eps` must be the floating-point epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. + - relative tolerance for small singular values. Singular values less than or equal to `rtol * largest_singular_value` are set to zero. Must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If a `float`, the value is equivalent to a zero-dimensional array having a data type determined by {ref}`type-promotion` rules and is broadcast against each matrix. If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. #### Returns From 27172b06e65a3619b59c3eb3c7ffddb149b74308 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 4 Mar 2021 01:20:07 -0800 Subject: [PATCH 10/17] Fix name --- 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 8989d24d0..cd904a907 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -135,7 +135,7 @@ Computes the multiplicative inverse of a square matrix (or stack of square matri - an array containing the multiplicative inverses. The returned array must have the same data type and shape as `x`. (function-lstsq)= -### lstsq(x1, x2, /, *, tol=None) +### lstsq(x1, x2, /, *, rtol=None) Returns the least-squares solution to a linear matrix equation `Ax = b`. From 827153c070e05c2c18d3ff271afaf487a5167eff Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 13:57:46 -0700 Subject: [PATCH 11/17] 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 cd904a907..10aa6d334 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -147,11 +147,11 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - **x2**: _<array>_ - - ordinate (or "dependent variable") array `b` having shape `(..., M, K)`. Must have a data type of either `float32` or `float64`. + - ordinate (or "dependent variable") array `b` having shape `(..., M, K)`, where each column `k` defines a set of ordinate values for which to compute a solution. Must be compatible with `shape(x1)[:-1]` (see {ref}`broadcasting`). Must have a data type of either `float32` or `float64`. - **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. Must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If a `float`, the value is equivalent to a zero-dimensional array having a data type determined by {ref}`type-promotion` rules and is broadcast against each matrix. If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. + - relative tolerance for small singular values. Singular values less than or equal to `rtol * largest_singular_value` are set to zero. Must be compatible with `shape(x1)[:-2]` (see {ref}`broadcasting`). If a `float`, the value is equivalent to a zero-dimensional array having a data type determined by {ref}`type-promotion` rules and is broadcast against each matrix. If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. #### Returns From 066c58f22a6d4a68f59cc31b69319db502503cb4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 14:46:01 -0700 Subject: [PATCH 12/17] Add support for providing an ordinate vector --- 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 10aa6d334..132609917 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -147,11 +147,11 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - **x2**: _<array>_ - - ordinate (or "dependent variable") array `b` having shape `(..., M, K)`, where each column `k` defines a set of ordinate values for which to compute a solution. Must be compatible with `shape(x1)[:-1]` (see {ref}`broadcasting`). Must have a data type of either `float32` or `float64`. + - ordinate (or "dependent variable") array `b`. If `x2` has shape `(..., M)`, `x2` is equivalent to an array having shape `(..., M, 1)`, and `shape(x2)` must be compatible with `shape(x1)[:-1]` (see {ref}`broadcasting`). If `x2` has shape `(..., M, K)`, each column `k` defines a set of ordinate values for which to compute a solution, and `shape(x2)[:-1]` must be compatible with `shape(x1)[:-1]` (see {ref}`broadcasting`). Must have a data type of either `float32` or `float64`. - **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. Must be compatible with `shape(x1)[:-2]` (see {ref}`broadcasting`). If a `float`, the value is equivalent to a zero-dimensional array having a data type determined by {ref}`type-promotion` rules and is broadcast against each matrix. If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. + - 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 data type determined by {ref}`type-promotion` rules and must be broadcast against each matrix. If an `array`, must have a data type of either `float32` or `float64` and must be compatible with `shape(x1)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. #### Returns From b31ae6c0e46f304a8c682af92aee23f3b3395536 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:10:40 -0700 Subject: [PATCH 13/17] Update dtype requirements --- spec/API_specification/linear_algebra_functions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 2d9469982..4d4afcd32 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -143,15 +143,15 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - **x1**: _<array>_ - - coefficient array `A` having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Must have a data type of either `float32` or `float64`. + - coefficient array `A` having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type. - **x2**: _<array>_ - - ordinate (or "dependent variable") array `b`. If `x2` has shape `(..., M)`, `x2` is equivalent to an array having shape `(..., M, 1)`, and `shape(x2)` must be compatible with `shape(x1)[:-1]` (see {ref}`broadcasting`). If `x2` has shape `(..., M, K)`, each column `k` defines a set of ordinate values for which to compute a solution, and `shape(x2)[:-1]` must be compatible with `shape(x1)[:-1]` (see {ref}`broadcasting`). Must have a data type of either `float32` or `float64`. + - ordinate (or "dependent variable") array `b`. If `x2` has shape `(..., M)`, `x2` is equivalent to an array having shape `(..., M, 1)`, and `shape(x2)` must be compatible with `shape(x1)[:-1]` (see {ref}`broadcasting`). If `x2` has shape `(..., M, K)`, each column `k` defines a set of ordinate values for which to compute a solution, and `shape(x2)[:-1]` must be compatible with `shape(x1)[:-1]` (see {ref}`broadcasting`). 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 data type determined by {ref}`type-promotion` rules and must be broadcast against each matrix. If an `array`, must have a data type of either `float32` or `float64` and must be compatible with `shape(x1)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type determined by {ref}`type-promotion` rules. Default: `None`. + - 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 data type determined by {ref}`type-promotion` rules and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x1)[:-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` rules. Default: `None`. #### Returns @@ -159,10 +159,10 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - 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 data type determined by {ref}`type-promotion` rules. - - 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 data type determined by {ref}`type-promotion` rules. + - 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` rules. + - 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` rules. - 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. - - fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N))` and must have a data type determined by {ref}`type-promotion` rules. + - fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N))` and must have a floating-point data type determined by {ref}`type-promotion` rules. (function-matmul)= ### matmul() From bd013d1dc9fc8ea65666646a71f8758b593ba614 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:15:41 -0700 Subject: [PATCH 14/17] Update dtype requirements --- 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 4d4afcd32..4a84fe526 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -151,7 +151,7 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - **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 data type determined by {ref}`type-promotion` rules and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x1)[:-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` rules. Default: `None`. + - 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 data type determined by {ref}`type-promotion` rules (as applied to `x1` and `x2`) and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x1)[:-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` rules (as applied to `x1` and `x2`). Default: `None`. #### Returns From b10efeed6e8cc2e43bfea6aa739cbba4f33f29ee Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:20:40 -0700 Subject: [PATCH 15/17] Update 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 4a84fe526..07352044c 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -155,7 +155,7 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. #### Returns -- **out**: _Tuple\[ <array>, ... ]_ +- **out**: _Tuple\[ <array>, <array>, <array>, <array> ]_ - a namedtuple `(x, residuals, rank, s)` whose From d406aa420b5cd9ec524f1a1256d611dda5bdefab Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:41:03 -0700 Subject: [PATCH 16/17] Update copy --- spec/API_specification/linear_algebra_functions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 07352044c..8c21befba 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -151,7 +151,7 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - **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 data type determined by {ref}`type-promotion` rules (as applied to `x1` and `x2`) and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x1)[:-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` rules (as applied to `x1` and `x2`). Default: `None`. + - 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 data type determined by {ref}`type-promotion` (as applied to `x1` and `x2`) and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x1)[:-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 `x1` and `x2`). Default: `None`. #### Returns @@ -159,10 +159,10 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. - 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` rules. - - 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` rules. + - 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. - - fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N))` and must have a floating-point data type determined by {ref}`type-promotion` rules. + - fourth element must have the field name `s` and must be an array containing the singular values for each `MxN` matrix in `x1`. The array containing the singular values must have shape `(..., min(M, N))` and must have a floating-point data type determined by {ref}`type-promotion`. (function-matmul)= ### matmul() From d670e1260561c72c1f3966663f65fb078e514f10 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 26 Apr 2021 02:27:13 -0700 Subject: [PATCH 17/17] 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 8c21befba..204882a9e 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -134,8 +134,8 @@ Computes the multiplicative inverse of a square matrix (or stack of square matri - an array containing the multiplicative inverses. The returned array must have the same data type and shape as `x`. -(function-lstsq)= -### lstsq(x1, x2, /, *, rtol=None) +(function-linalg-lstsq)= +### linalg.lstsq(x1, x2, /, *, rtol=None) Returns the least-squares solution to a linear matrix equation `Ax = b`.