From 56d0343ab290e5ff919afc97abd0947f2fc329f9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 16:22:16 -0700 Subject: [PATCH 1/4] Add dtype requirements --- spec/API_specification/linear_algebra_functions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 209a2f787..dfa6cda2f 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -29,11 +29,11 @@ Returns the cross product of 3-element vectors. If `x1` and `x2` are multi-dimen - **x1**: _<array>_ - - first input array. Must have a data type of either `float32` or `float64`. + - first input array. Must have a numeric data type. - **x2**: _<array>_ - - second input array. Must have the same shape as `x1`. Must have a data type of either `float32` or `float64`. + - second input array. Must have the same shape as `x1`. Must have a numeric data type. - **axis**: _int_ @@ -54,13 +54,13 @@ Returns the determinant of a square matrix (or stack of square matrices) `x`. - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a numeric data type. #### Returns - **out**: _<array>_ - - if `x` is a two-dimensional array, a zero-dimensional array containing the determinant; otherwise, a non-zero dimensional array containing the determinant for each square matrix. The returned array must have a data type determined by {ref}`type-promotion` rules. + - if `x` is a two-dimensional array, a zero-dimensional array containing the determinant; otherwise, a non-zero dimensional array containing the determinant for each square matrix. The returned array must have the same data type as `x`. (function-diagonal)= ### diagonal(x, /, *, axis1=0, axis2=1, offset=0) @@ -242,11 +242,11 @@ Computes the outer product of two vectors `x1` and `x2`. - **x1**: _<array>_ - - first one-dimensional input array of size `N`. Must have a data type of either `float32` or `float64`. + - first one-dimensional input array of size `N`. Must have a numeric data type. - **x2**: _<array>_ - - second one-dimensional input array of size `M`. Must have a data type of either `float32` or `float64`. + - second one-dimensional input array of size `M`. Must have a numeric data type. #### Returns @@ -288,7 +288,7 @@ Returns the sum along the specified diagonals. If `x` has more than two dimensio - **x**: _<array>_ - - input array. Must have at least `2` dimensions. + - input array. Must have at least `2` dimensions. Must have a numeric data type. - **axis1**: _int_ From 456042c882acd1407f5bcb53ea53d2e12d5add79 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 16:26:40 -0700 Subject: [PATCH 2/4] Loosen dtype requirements --- .../linear_algebra_functions.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index dfa6cda2f..0d85f0f62 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -29,11 +29,11 @@ Returns the cross product of 3-element vectors. If `x1` and `x2` are multi-dimen - **x1**: _<array>_ - - first input array. Must have a numeric data type. + - first input array. Should have a numeric data type. - **x2**: _<array>_ - - second input array. Must have the same shape as `x1`. Must have a numeric data type. + - second input array. Must have the same shape as `x1`. Should have a numeric data type. - **axis**: _int_ @@ -54,7 +54,7 @@ Returns the determinant of a square matrix (or stack of square matrices) `x`. - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a numeric data type. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a numeric data type. #### Returns @@ -120,13 +120,13 @@ TODO (function-inv)= ### inv(x, /) -Computes the multiplicative inverse of a square matrix (or stack of square matrices) `x`. +Computes the multiplicative inverse of a square matrix (or a stack of square matrices) `x`. #### Parameters - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a floating-point data type. #### Returns @@ -163,7 +163,7 @@ Computes the matrix or vector norm of `x`. - **x**: _<array>_ - - input array. Must have a data type of either `float32` or `float64`. + - input array. Should have a floating-point data type. - **axis**: _Optional\[ Union\[ int, Tuple\[ int, int ] ] ]_ @@ -242,17 +242,17 @@ Computes the outer product of two vectors `x1` and `x2`. - **x1**: _<array>_ - - first one-dimensional input array of size `N`. Must have a numeric data type. + - first one-dimensional input array of size `N`. Should have a numeric data type. - **x2**: _<array>_ - - second one-dimensional input array of size `M`. Must have a numeric data type. + - second one-dimensional input array of size `M`. Should have a numeric data type. #### Returns - **out**: _<array>_ - - 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. + - a two-dimensional array containing the outer product and whose shape is `(N, M)`. The returned array must have a data type determined by {ref}`type-promotion` rules. (function-pinv)= ### pinv() @@ -288,7 +288,7 @@ Returns the sum along the specified diagonals. If `x` has more than two dimensio - **x**: _<array>_ - - input array. Must have at least `2` dimensions. Must have a numeric data type. + - input array. Must have at least `2` dimensions. Should have a numeric data type. - **axis1**: _int_ From e3d8fcc99473e9b09aec1785f7f28cfe4940cc22 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:52:50 -0700 Subject: [PATCH 3/4] 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 0d85f0f62..7d8872ce7 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -43,7 +43,7 @@ Returns the cross product of 3-element vectors. If `x1` and `x2` are multi-dimen - **out**: _<array>_ - - an array containing the cross products. The returned array must have a data type determined by {ref}`type-promotion` rules. + - an array containing the cross products. The returned array must have a data type determined by {ref}`type-promotion`. (function-det)= ### det(x, /) @@ -132,7 +132,7 @@ Computes the multiplicative inverse of a square matrix (or a stack of square mat - **out**: _<array>_ - - an array containing the multiplicative inverses. The returned array must have the same data type and shape as `x`. + - an array containing the multiplicative inverses. The returned array must have a floating-point data type determined by {ref}`type-promotion` and must have the same shape as `x`. (function-lstsq)= ### lstsq() @@ -231,7 +231,7 @@ Computes the matrix or vector norm of `x`. - **out**: _<array>_ - - an array containing the norms. If `axis` is `None`, the output array must be a zero-dimensional array containing a vector norm. If `axis` is a scalar value (`int` or `float`), the output array must have a rank which is one less than the rank of `x`. If `axis` is a 2-tuple, the output array must have a rank which is two less than the rank of `x`. The returned array must have the same data type as `x`. + - an array containing the norms. If `axis` is `None`, the returned array must be a zero-dimensional array containing a vector norm. If `axis` is a scalar value (`int` or `float`), the returned array must have a rank which is one less than the rank of `x`. If `axis` is a 2-tuple, the returned array must have a rank which is two less than the rank of `x`. The returned array must have a floating-point data type determined by {ref}`type-promotion`. (function-outer)= ### outer(x1, x2, /) @@ -252,7 +252,7 @@ Computes the outer product of two vectors `x1` and `x2`. - **out**: _<array>_ - - a two-dimensional array containing the outer product and whose shape is `(N, M)`. The returned array must have a data type determined by {ref}`type-promotion` rules. + - a two-dimensional array containing the outer product and whose shape is `(N, M)`. The returned array must have a data type determined by {ref}`type-promotion`. (function-pinv)= ### pinv() From 0882b788c97eeac71405c5cc2b27d6c9341f3fed Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 29 Mar 2021 12:24:05 -0700 Subject: [PATCH 4/4] Restrict `det` to floating-point data types For more than 3-dimensions, efficiently computing the determinant relies on factorization, which is likely to be inexact and require floating-point computation. Accordingly, we should restrict input dtypes to avoid potential casting issues (e.g., int64 to float64). --- 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 7d8872ce7..100efccf2 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -54,7 +54,7 @@ Returns the determinant of a square matrix (or stack of square matrices) `x`. - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a numeric data type. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a floating-point data type. #### Returns