naginterfaces.library.lapackeig.zgeqp3

naginterfaces.library.lapackeig.zgeqp3(a, jpvt)

zgeqp3 computes the $QR$ factorization, with column pivoting, of a complex $m\times n$ matrix.

For full information please refer to the NAG Library document for f08bt

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f08/f08btf.html

Parameters

acomplex, array-like, shape $(m,n)$

The $m\times n$ matrix $A$.

jpvtint, array-like, shape $\left(n\right)$

If $jpvt[j-1]\ne 0$, the $j$ th column of $A$ is moved to the beginning of $AP$ before the decomposition is computed and is fixed in place during the computation. Otherwise, the $j$ th column of $A$ is a free column (i.e., one which may be interchanged during the computation with any other free column).

Returns

acomplex, ndarray, shape $(m,n)$

If $m\ge n$, the elements below the diagonal are overwritten by details of the unitary matrix $Q$ and the upper triangle is overwritten by the corresponding elements of the $n\times n$ upper triangular matrix $R$.

If $m<n$, the strictly lower triangular part is overwritten by details of the unitary matrix $Q$ and the remaining elements are overwritten by the corresponding elements of the $m\times n$ upper trapezoidal matrix $R$.

The diagonal elements of $R$ are real.

jpvtint, ndarray, shape $\left(n\right)$

Details of the permutation matrix $P$. More precisely, if $jpvt[j-1]=k$, the $k$th column of $A$ is moved to become the $j$ th column of $AP$; in other words, the columns of $AP$ are the columns of $A$ in the order $jpvt\left[0\right],jpvt\left[1\right],\dots ,jpvt[n-1]$.

taucomplex, ndarray, shape $(min(m,n))$

Further details of the unitary matrix $Q$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $\text{m}$.

Constraint: $m\ge 0$.

(errno $-2$)

On entry, error in parameter $\text{n}$.

Constraint: $n\ge 0$.

Notes

zgeqp3 forms the $QR$ factorization, with column pivoting, of an arbitrary rectangular complex $m\times n$ matrix.

If $m\ge n$, the factorization is given by:

$$\begin{array}{c}AP=Q\left(\begin{array}{c}R\\ 0\end{array}\right)\text{,}\end{array}$$

where $R$ is an $n\times n$ upper triangular matrix (with real diagonal elements), $Q$ is an $m\times m$ unitary matrix and $P$ is an $n\times n$ permutation matrix. It is sometimes more convenient to write the factorization as

$$\begin{array}{c}AP=\left(\begin{array}{cc}{Q}_1& Q_2\end{array}\right)\left(\begin{array}{c}R\\ 0\end{array}\right)\text{,}\end{array}$$

which reduces to

$$AP=Q_{1}R\text{,}$$

where $Q_1$ consists of the first $n$ columns of $Q$, and $Q_2$ the remaining $m-n$ columns.

If $m<n$, $R$ is trapezoidal, and the factorization can be written

$$AP=Q\left(\begin{array}{cc}{R}_1& R_2\end{array}\right)\text{,}$$

where $R_1$ is upper triangular and $R_2$ is rectangular.

The matrix $Q$ is not formed explicitly but is represented as a product of $min(m,n)$ elementary reflectors (see the F08 Introduction for details). Functions are provided to work with $Q$ in this representation (see Further Comments).

Note also that for any $k<n$, the information returned in the first $k$ columns of the array $a$ represents a $QR$ factorization of the first $k$ columns of the permuted matrix $AP$.

The function allows specified columns of $A$ to be moved to the leading columns of $AP$ at the start of the factorization and fixed there. The remaining columns are free to be interchanged so that at the $i$th stage the pivot column is chosen to be the column which maximizes the $2$-norm of elements $i$ to $m$ over columns $i$ to $n$.

References

Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, LAPACK Users’ Guide, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore