Skip to content

Add notes concerning input array validation #302

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.

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
Nov 4, 2021
Merged
Changes from all commits
Commits
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
40 changes: 29 additions & 11 deletions spec/extensions/linear_algebra_functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,10 @@ Returns the lower (upper) Cholesky decomposition x = LLᵀ (x = UᵀU) of a symm

<!-- NOTE: once complex numbers are supported, each square matrix must be Hermitian. -->

```{note}
Whether an array library explicitly checks whether an input array is a symmetric positive-definite matrix (or a stack of matrices) is implementation-defined.
```

#### Parameters

- **x**: _&lt;array&gt;_
Expand Down Expand Up @@ -170,10 +174,18 @@ Returns the specified diagonals of a matrix (or a stack of matrices) `x`.
(function-linalg-eigh)=
### linalg.eigh(x, /)

```{note}
The function `eig` will be added in a future version of the specification, as it requires complex number support.
```

Returns an eigendecomposition x = QLQᵀ of a symmetric matrix (or a stack of symmetric matrices) `x`, where `Q` is an orthogonal matrix (or a stack of matrices) and `L` is a vector (or a stack of vectors).

<!-- NOTE: once complex number support, each matrix must be Hermitian and the returned Q unitary. We might also want to make the dtype of `eigenvalues` unconditionally real -->

```{note}
Whether an array library explicitly checks whether an input array is a symmetric matrix (or a stack of symmetric matrices) is implementation-defined.
```

#### Parameters

- **x**: _&lt;array&gt;_
Expand All @@ -195,18 +207,21 @@ Returns an eigendecomposition x = QLQᵀ of a symmetric matrix (or a stack of sy
Eigenvalue sort order is left unspecified.
```

```{note}
The function `eig` will be added in a future version of the specification,
as it requires complex number support.
```

(function-linalg-eigvalsh)=
### linalg.eigvalsh(x, /)

```{note}
The function `eigvals` will be added in a future version of the specification, as it requires complex number support.
```

Returns the eigenvalues of a symmetric matrix (or a stack of symmetric matrices) `x`.

<!-- NOTE: once complex number support, each matrix must be Hermitian -->

```{note}
Whether an array library explicitly checks whether an input array is a symmetric matrix (or a stack of symmetric matrices) is implementation-defined.
```

#### Parameters

- **x**: _&lt;array&gt;_
Expand All @@ -223,11 +238,6 @@ Returns the eigenvalues of a symmetric matrix (or a stack of symmetric matrices)
Eigenvalue sort order is left unspecified.
```

```{note}
The function `eigvals` will be added in a future version of the specification,
as it requires complex number support.
```

(function-linalg-inv)=
### linalg.inv(x, /)

Expand Down Expand Up @@ -395,11 +405,15 @@ Returns the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of matrices)

Returns the qr decomposition x = QR of a full column rank matrix (or a stack of matrices), where `Q` is an orthonormal matrix (or a stack of matrices) and `R` is an upper-triangular matrix (or a stack of matrices).

```{note}
Whether an array library explicitly checks whether an input array is a full column rank matrix (or a stack of full column rank matrices) is implementation-defined.
```

#### Parameters

- **x**: _&lt;array&gt;_

- input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices of rank equal to `N`. Should have a floating-point data type.
- input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices of rank `N`. Should have a floating-point data type.

- **mode**: _Literal\[ 'reduced', 'complete' ]_

Expand Down Expand Up @@ -454,6 +468,10 @@ The purpose of this function is to calculate the determinant more accurately whe

Returns the solution to the system of linear equations represented by the well-determined (i.e., full rank) linear matrix equation `AX = B`.

```{note}
Whether an array library explicitly checks whether an input array is full rank is implementation-defined.
```

#### Parameters

- **x1**: _&lt;array&gt;_
Expand Down