qr — Python array API standard 2024.12 documentation (original) (raw)

qr(x: array, /, *, mode: Literal['reduced', 'complete'] = 'reduced') → Tuple[array, array]¶

Returns the QR decomposition of a full column rank matrix (or a stack of matrices).

If x is real-valued, let \(\mathbb{K}\) be the set of real numbers \(\mathbb{R}\), and, if x is complex-valued, let \(\mathbb{K}\) be the set of complex numbers \(\mathbb{C}\).

The complete QR decomposition of a matrix \(x \in\ \mathbb{K}^{n \times n}\) is defined as

\[x = QR\]

where \(Q \in\ \mathbb{K}^{m \times m}\) is orthogonal when x is real-valued and unitary when x is complex-valued and where \(R \in\ \mathbb{K}^{m \times n}\) is an upper triangular matrix with real diagonal (even when x is complex-valued).

When \(m \gt n\) (tall matrix), as \(R\) is upper triangular, the last \(m - n\) rows are zero. In this case, the last \(m - n\) columns of \(Q\) can be dropped to form the reduced QR decomposition.

\[x = QR\]

where \(Q \in\ \mathbb{K}^{m \times n}\) and \(R \in\ \mathbb{K}^{n \times n}\).

The reduced QR decomposition equals with the complete QR decomposition when \(n \geq m\) (wide matrix).

When x is a stack of matrices, the function must compute the QR decomposition for each matrix in the stack.

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.

Warning

The elements in the diagonal of \(R\) are not necessarily positive. Accordingly, the returned QR decomposition is only unique up to the sign of the diagonal of \(R\), and different libraries or inputs on different devices may produce different valid decompositions.

Warning

The QR decomposition is only well-defined if the first k = min(m,n) columns of every matrix in x are linearly independent.

Parameters:

• x (array) – 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' ]) –
  decomposition mode. Should be one of the following modes:
  • 'reduced': compute only the leading K columns of q, such that q and r have dimensions (..., M, K) and (..., K, N), respectively, and where K = min(M, N).
  • 'complete': compute q and r with dimensions (..., M, M) and (..., M, N), respectively.
    Default: 'reduced'.

Returns:

out (Tuple[array, array]) – a namedtuple (Q, R) whose

• first element must have the field name Q and must be an array whose shape depends on the value of mode and contain matrices with orthonormal columns. If mode is 'complete', the array must have shape (..., M, M). If mode is 'reduced', the array must have shape (..., M, K), where K = min(M, N). The first x.ndim-2 dimensions must have the same size as those of the input array x.
• second element must have the field name R and must be an array whose shape depends on the value of mode and contain upper-triangular matrices. If mode is 'complete', the array must have shape (..., M, N). If mode is 'reduced', the array must have shape (..., K, N), where K = min(M, N). The first x.ndim-2 dimensions must have the same size as those of the input x.

Each returned array must have a floating-point data type determined by Type Promotion Rules.

Notes

Changed in version 2022.12: Added complex data type support.