From 1d020e4a22278c5960bc25dc33f7445de61d57e5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 26 Jul 2021 10:07:54 -0700 Subject: [PATCH] Split `linalg.norm` into separate vector and matrix APIs --- spec/extensions/linear_algebra_functions.md | 163 +++++++++++--------- 1 file changed, 92 insertions(+), 71 deletions(-) diff --git a/spec/extensions/linear_algebra_functions.md b/spec/extensions/linear_algebra_functions.md index 00e05ab86..3e5b64895 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -302,123 +302,98 @@ Returns the least-squares solution to a linear matrix equation `Ax = b`. Alias for {ref}`function-matmul`. -(function-linalg-matrix_power)= -### linalg.matrix_power(x, n, /) +(function-linalg-matrix-norm)= +### linalg.matrix_norm(x, /, *, axis=(-2, -1), keepdims=False, ord='fro') -Raises a square matrix (or a stack of square matrices) `x` to an integer power `n`. +Computes the matrix norm of a matrix (or a stack of matrices) `x`. #### Parameters - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a floating-point data type. + - input array. Must have at least `2` dimensions. Should have a floating-point data type. -- **n**: _int_ +- **axis**: _Tuple\[ int, int ]_ - - integer exponent. + - a 2-tuple which specifies the axes (dimensions) defining two-dimensional matrices for which to compute matrix norms. Negative indices must be supported. Default: `(-2, -1)` (i.e., the last two-dimensions). -#### Returns +- **keepdims**: _bool_ -- **out**: _<array>_ + - If `True`, the axes (dimensions) specified by `axis` must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see {ref}`broadcasting`). Otherwise, if `False`, the axes (dimensions) specified by `axis` must not be included in the result. Default: `False`. - - if `n` is equal to zero, an array containing the identity matrix for each square matrix. If `n` is less than zero, an array containing the inverse of each square matrix raised to the absolute value of `n`, provided that each square matrix is invertible. If `n` is greater than zero, an array containing the result of raising each square matrix to the power `n`. The returned array must have the same shape as `x` and a floating-point data type determined by {ref}`type-promotion`. +- **ord**: _Optional\[ Union\[ int, float, Literal\[ inf, -inf, 'fro', 'nuc' ] ] ]_ -(function-linalg-matrix_rank)= -### linalg.matrix_rank(x, /, *, rtol=None) + - order of the norm. The following mathematical norms must be supported: + | ord | description | + | ---------------- | ------------------------------- | + | 'fro' | Frobenius norm | + | 'nuc' | nuclear norm | + | 1 | max(sum(abs(x), axis=0)) | + | 2 | largest singular value | + | inf | max(sum(abs(x), axis=1)) | -Computes the rank (i.e., number of non-zero singular values) of a matrix (or a stack of matrices). + The following non-mathematical "norms" must be supported: + | ord | description | + | ---------------- | ------------------------------- | + | -1 | min(sum(abs(x), axis=0)) | + | -2 | smallest singular value | + | -inf | min(sum(abs(x), axis=1)) | -#### Parameters + If `ord=1`, the norm corresponds to the induced matrix norm where `p=1` (i.e., the maximum absolute value column sum). -- **x**: _<array>_ + If `ord=2`, the norm corresponds to the induced matrix norm where `p=inf` (i.e., the maximum absolute value row sum). - - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type. + If `ord=inf`, the norm corresponds to the induced matrix norm where `p=2` (i.e., the largest singular value). -- **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` (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`. + Default: `'fro'`. #### Returns - **out**: _<array>_ - - an array containing the ranks. The returned array must have a floating-point data type determined by {ref}`type-promotion` and must have shape `(...)` (i.e., must have a shape equal to `shape(x)[:-2]`). + - an array containing the norms. If `keepdims` is `False`, 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-linalg-norm)= -### linalg.norm(x, /, *, axis=None, keepdims=False, ord=None) +(function-linalg-matrix_power)= +### linalg.matrix_power(x, n, /) -Computes the matrix or vector norm of `x`. +Raises a square matrix (or a stack of square matrices) `x` to an integer power `n`. #### Parameters - **x**: _<array>_ - - input array. Should have a floating-point data type. - -- **axis**: _Optional\[ Union\[ int, Tuple\[ int, int ] ] ]_ - - - If an integer, `axis` specifies the axis (dimension) along which to compute vector norms. - - If a 2-tuple, `axis` specifies the axes (dimensions) defining two-dimensional matrices for which to compute matrix norms. - - If `None`, - - - if `x` is one-dimensional, the function must compute the vector norm. - - if `x` is two-dimensional, the function must compute the matrix norm. - - if `x` has more than two dimensions, the function must compute the vector norm over all array values (i.e., equivalent to computing the vector norm of a flattened array). - - Negative indices must be supported. Default: `None`. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a floating-point data type. -- **keepdims**: _bool_ +- **n**: _int_ - - If `True`, the axes (dimensions) specified by `axis` must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see {ref}`broadcasting`). Otherwise, if `False`, the axes (dimensions) specified by `axis` must not be included in the result. Default: `False`. + - integer exponent. -- **ord**: _Optional\[ Union\[ int, float, Literal\[ inf, -inf, 'fro', 'nuc' ] ] ]_ +#### Returns - - order of the norm. The following mathematical norms must be supported: - | ord | matrix | vector | - | ---------------- | ------------------------------- | -------------------------- | - | 'fro' | 'fro' | - | - | 'nuc' | 'nuc' | - | - | 1 | max(sum(abs(x), axis=0)) | L1-norm (Manhattan) | - | 2 | largest singular value | L2-norm (Euclidean) | - | inf | max(sum(abs(x), axis=1)) | infinity norm | - | (int,float >= 1) | - | p-norm | +- **out**: _<array>_ - The following non-mathematical "norms" must be supported: - | ord | matrix | vector | - | ---------------- | ------------------------------- | ------------------------------ | - | 0 | - | sum(a != 0) | - | -1 | min(sum(abs(x), axis=0)) | 1./sum(1./abs(a)) | - | -2 | smallest singular value | 1./sqrt(sum(1./abs(a)\*\*2)) | - | -inf | min(sum(abs(x), axis=1)) | min(abs(a)) | - | (int,float < 1) | - | sum(abs(a)\*\*ord)\*\*(1./ord) | + - if `n` is equal to zero, an array containing the identity matrix for each square matrix. If `n` is less than zero, an array containing the inverse of each square matrix raised to the absolute value of `n`, provided that each square matrix is invertible. If `n` is greater than zero, an array containing the result of raising each square matrix to the power `n`. The returned array must have the same shape as `x` and a floating-point data type determined by {ref}`type-promotion`. - When `ord` is `None`, the following norms must be the default norms: - | ord | matrix | vector | - | ---------------- | ------------------------------- | -------------------------- | - | None | 'fro' | L2-norm (Euclidean) | +(function-linalg-matrix_rank)= +### linalg.matrix_rank(x, /, *, rtol=None) - where `fro` corresponds to the **Frobenius norm**, `nuc` corresponds to the **nuclear norm**, and `-` indicates that the norm is **not** supported. +Computes the rank (i.e., number of non-zero singular values) of a matrix (or a stack of matrices). - For matrices, +#### Parameters - - if `ord=1`, the norm corresponds to the induced matrix norm where `p=1` (i.e., the maximum absolute value column sum). - - if `ord=2`, the norm corresponds to the induced matrix norm where `p=inf` (i.e., the maximum absolute value row sum). - - if `ord=inf`, the norm corresponds to the induced matrix norm where `p=2` (i.e., the largest singular value). +- **x**: _<array>_ - If `None`, + - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type. - - if matrix (or matrices), the function must compute the Frobenius norm. - - if vector (or vectors), the function must compute the L2-norm (Euclidean norm). +- **rtol**: _Optional\[ Union\[ float, <array> ] ]_ - 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 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`. + - an array containing the ranks. The returned array must have a floating-point data type determined by {ref}`type-promotion` and must have shape `(...)` (i.e., must have a shape equal to `shape(x)[:-2]`). (function-linalg-outer)= ### linalg.outer(x1, x2, /) @@ -644,3 +619,49 @@ Alias for {ref}`function-transpose`. ### linalg.vecdot(x1, x2, /, *, axis=None) Alias for {ref}`function-vecdot`. + +(function-linalg-vector-norm)= +### linalg.vector_norm(x, /, *, axis=None, keepdims=False, ord=2) + +Computes the vector norm of a vector (or batch of vectors) `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array. Should have a floating-point data type. + +- **axis**: _Optional\[ Union\[ int, Tuple\[ int, int ] ] ]_ + + - If an integer, `axis` specifies the axis (dimension) along which to compute vector norms. If an n-tuple, `axis` specifies the axes (dimensions) along which to compute batched vector norms. If `None`, the vector norm must be computed over all array values (i.e., equivalent to computing the vector norm of a flattened array). Negative indices must be supported. Default: `None`. + +- **keepdims**: _bool_ + + - If `True`, the axes (dimensions) specified by `axis` must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see {ref}`broadcasting`). Otherwise, if `False`, the axes (dimensions) specified by `axis` must not be included in the result. Default: `False`. + +- **ord**: _Optional\[ Union\[ int, float, Literal\[ inf, -inf ] ] ]_ + + - order of the norm. The following mathematical norms must be supported: + | ord | description | + | ---------------- | -------------------------- | + | 1 | L1-norm (Manhattan) | + | 2 | L2-norm (Euclidean) | + | inf | infinity norm | + | (int,float >= 1) | p-norm | + + The following non-mathematical "norms" must be supported: + | ord | description | + | ---------------- | ------------------------------ | + | 0 | sum(a != 0) | + | -1 | 1./sum(1./abs(a)) | + | -2 | 1./sqrt(sum(1./abs(a)\*\*2)) | + | -inf | min(abs(a)) | + | (int,float < 1) | sum(abs(a)\*\*ord)\*\*(1./ord) | + + Default: `2`. + +#### Returns + +- **out**: _<array>_ + + - an array containing the vector 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 `n`-tuple, the returned array must have a rank which is `n` less than the rank of `x`. The returned array must have a floating-point data type determined by {ref}`type-promotion`.