From 8c34c2eb81b7d695ac1651b6a75c19c363e2f586 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 25 Jan 2021 09:42:35 -0800 Subject: [PATCH 01/14] Add pinv specification --- .../linear_algebra_functions.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ba92aa7b0..d24bed39e 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -255,9 +255,25 @@ Computes the outer product of two vectors `x1` and `x2`. - a two-dimensional array containing the outer product and whose shape is `NxM`. The returned array must have a data type determined by {ref}`type-promotion` rules. (function-pinv)= -### pinv() +### pinv(x, /, *, rcond=None) -TODO +Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matrices) `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. 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 `x` (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**: _<array>_ + + - an array containing the pseudo-inverses. The returned array must have the same data type and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). (function-qr)= ### qr() From dc8ffd344a5598d5c6f808ad884af1a65653fe02 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 25 Jan 2021 11:00:39 -0800 Subject: [PATCH 02/14] Fix statement on broadcasting --- 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 d24bed39e..6fd3cf238 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -267,7 +267,7 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matr - **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 `x` (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 `10.0 * max(M, N) * eps`, where `eps` must be the floating-point epsilon associated with the data type of `x`. Default: `None`. #### Returns From 9e52d1665e891e524e27e397f249f33bff5ae59b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 25 Jan 2021 11:11:03 -0800 Subject: [PATCH 03/14] 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 6fd3cf238..b894ddf6a 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -265,7 +265,7 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matr - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. 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`. From 7613ba7aac88bfe1e2865719dba2fe9e3b56d43e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 15 Feb 2021 21:26:40 -0800 Subject: [PATCH 04/14] Rename keyword argument and drop scaling factor --- 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 b894ddf6a..ff3d177b6 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -255,7 +255,7 @@ Computes the outer product of two vectors `x1` and `x2`. - a two-dimensional array containing the outer product and whose shape is `NxM`. The returned array must have a data type determined by {ref}`type-promotion` rules. (function-pinv)= -### pinv(x, /, *, rcond=None) +### pinv(x, /, *, tol=None) Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matrices) `x`. @@ -265,9 +265,9 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matr - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. 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 `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 `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 the same data type as `x` 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 of `x`. Default: `None`. #### Returns From a3fb89106e77fb7e93cac6df24aded1497d34f28 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 1 Mar 2021 09:47:25 -0800 Subject: [PATCH 05/14] 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 ff3d177b6..644b6540b 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -267,7 +267,7 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matr - **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. Must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). 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. If `None`, the default value is `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 `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 the same data type as `x` 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 of `x`. Default: `None`. #### Returns From 53ff721f36df405ad7a274ec22a54d398d62ed9c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 4 Mar 2021 01:13:10 -0800 Subject: [PATCH 06/14] 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 644b6540b..9f8f972ea 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -265,9 +265,9 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matr - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. 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 the same data type as `x` 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 of `x`. 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 the same data type as `x` 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 of `x`. Default: `None`. #### Returns From b3dff5ed48c2d495f41b8bd0683d2da47b7fcf41 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 4 Mar 2021 01:21:13 -0800 Subject: [PATCH 07/14] Fix argument 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 9f8f972ea..b955d7765 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -255,7 +255,7 @@ Computes the outer product of two vectors `x1` and `x2`. - a two-dimensional array containing the outer product and whose shape is `NxM`. The returned array must have a data type determined by {ref}`type-promotion` rules. (function-pinv)= -### pinv(x, /, *, tol=None) +### pinv(x, /, *, rtol=None) Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matrices) `x`. From 10435af021359746be9f6960c054479e7c047968 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:01:25 -0700 Subject: [PATCH 08/14] Update dtype requirements --- 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 a37fcf665..60c3a330c 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -257,23 +257,23 @@ Computes the outer product of two vectors `x1` and `x2`. (function-pinv)= ### pinv(x, /, *, rtol=None) -Computes the (Moore-Penrose) pseudo-inverse of a matrix (or stack of square matrices) `x`. +Computes the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of square matrices) `x`. #### Parameters - **x**: _<array>_ - - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Must have a data type of either `float32` or `float64`. + - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type - **rtol**: _Optional\[ Union\[ float, <array> ] ]_ - - relative tolerance for small singular values. Singular values less than or equal to `rtol * largest_singular_value` are set to zero. Must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). 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. If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type of `x`. 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 the same data type as `x` and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type of `x`. Default: `None`. #### Returns - **out**: _<array>_ - - an array containing the pseudo-inverses. The returned array must have the same data type and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). + - an array containing the pseudo-inverses. The returned array must have the same data type as `x` and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). (function-qr)= ### qr() From 6f550e563719ff5102bb520a6aaf2603c353baac Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:02:13 -0700 Subject: [PATCH 09/14] Fix missing period --- 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 60c3a330c..4de79f1aa 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -263,7 +263,7 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of square ma - **x**: _<array>_ - - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type + - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type. - **rtol**: _Optional\[ Union\[ float, <array> ] ]_ From a02b48025e55221129ee0a0a071a2cc243a495f6 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:03:34 -0700 Subject: [PATCH 10/14] 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 4de79f1aa..72a73c738 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -273,7 +273,7 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of square ma - **out**: _<array>_ - - an array containing the pseudo-inverses. The returned array must have the same data type as `x` and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). + - an array containing the pseudo-inverses. The returned array must have a floating-point data type as determined by {ref}`type-promotion` rules and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). (function-qr)= ### qr() From 59bcf474ec2adcf8b0b699cff475bb1d878e4afa Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:03:54 -0700 Subject: [PATCH 11/14] 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 72a73c738..1b4e1297a 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -273,7 +273,7 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of square ma - **out**: _<array>_ - - an array containing the pseudo-inverses. The returned array must have a floating-point data type as determined by {ref}`type-promotion` rules and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). + - an array containing the pseudo-inverses. The returned array must have a floating-point data type determined by {ref}`type-promotion` rules and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). (function-qr)= ### qr() From 97571d07fb2db8c8b2cd83d509366c7445b8d4ff Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:14:43 -0700 Subject: [PATCH 12/14] 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 1b4e1297a..a2efbc6f6 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -267,7 +267,7 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of square ma - **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 the same data type as `x` and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the data type of `x`. 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 floating-point data type determined by {ref}`type-promotion` rules (as applied to `x`) and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the floating-point data type determined by {ref}`type-promotion` rules (as applied to `x`). Default: `None`. #### Returns From e310f08557e687c356ca69bee1f1f49550c94d82 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:40:22 -0700 Subject: [PATCH 13/14] 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 a2efbc6f6..c57507be6 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -267,13 +267,13 @@ Computes the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of square ma - **rtol**: _Optional\[ Union\[ float, <array> ] ]_ - - relative tolerance for small singular values. Singular values less than or equal to `rtol * largest_singular_value` are set to zero. If a `float`, the value is equivalent to a zero-dimensional array having a floating-point data type determined by {ref}`type-promotion` rules (as applied to `x`) and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the floating-point data type determined by {ref}`type-promotion` rules (as applied to `x`). 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 floating-point data type determined by {ref}`type-promotion` (as applied to `x`) and must be broadcast against each matrix. If an `array`, must have a floating-point data type and must be compatible with `shape(x)[:-2]` (see {ref}`broadcasting`). If `None`, the default value is `max(M, N) * eps`, where `eps` must be the machine epsilon associated with the floating-point data type determined by {ref}`type-promotion` (as applied to `x`). Default: `None`. #### Returns - **out**: _<array>_ - - an array containing the pseudo-inverses. The returned array must have a floating-point data type determined by {ref}`type-promotion` rules and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). + - an array containing the pseudo-inverses. The returned array must have a floating-point data type determined by {ref}`type-promotion` and must have shape `(..., N, M)` (i.e., must have the same shape as `x`, except the innermost two dimensions must be transposed). (function-qr)= ### qr() From ecdfd435228e5fa3425035736d1ff621afcff80d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 26 Apr 2021 02:30:17 -0700 Subject: [PATCH 14/14] 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 c57507be6..81a1f2205 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -254,8 +254,8 @@ Computes the outer product of two vectors `x1` and `x2`. - a two-dimensional array containing the outer product and whose shape is `NxM`. The returned array must have a data type determined by {ref}`type-promotion` rules. -(function-pinv)= -### pinv(x, /, *, rtol=None) +(function-linalg-pinv)= +### linalg.pinv(x, /, *, rtol=None) Computes the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of square matrices) `x`.