Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 23, 2021
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 92 additions & 71 deletions spec/extensions/linear_algebra_functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**: _&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, /)
Expand Down Expand Up @@ -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**: _&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`.