Split linalg.norm into separate vector and matrix APIs (#236)

Author: kgryte

spec/extensions/linear_algebra_functions.md

@@ -264,123 +264,98 @@ Computes the multiplicative inverse of a square matrix (or a stack of square mat
 
 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**: _&lt;array&gt;_
 
-        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, &lt;array&gt; ] ]_
 
-        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**: _&lt;array&gt;_
 
-    -   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, /)
@@ -596,3 +571,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**: _&lt;array&gt;_
+
+    -   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**: _&lt;array&gt;_
+
+    -   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`.