# claqp2rk.f - Man Page

SRC/claqp2rk.f

## Synopsis

### Functions/Subroutines

subroutine **claqp2rk** (m, n, nrhs, ioffset, kmax, abstol, reltol, kp1, maxc2nrm, a, lda, k, maxc2nrmk, relmaxc2nrmk, jpiv, tau, vn1, vn2, work, info)**CLAQP2RK** computes truncated QR factorization with column pivoting of a complex matrix block using Level 2 BLAS and overwrites a complex m-by-nrhs matrix B with Q**H * B.

## Function/Subroutine Documentation

### subroutine claqp2rk (integer m, integer n, integer nrhs, integer ioffset, integer kmax, real abstol, real reltol, integer kp1, real maxc2nrm, complex, dimension( lda, * ) a, integer lda, integer k, real maxc2nrmk, real relmaxc2nrmk, integer, dimension( * ) jpiv, complex, dimension( * ) tau, real, dimension( * ) vn1, real, dimension( * ) vn2, complex, dimension( * ) work, integer info)

**CLAQP2RK** computes truncated QR factorization with column pivoting of a complex matrix block using Level 2 BLAS and overwrites a complex m-by-nrhs matrix B with Q**H * B.

**Purpose:**

CLAQP2RK computes a truncated (rank K) or full rank Householder QR factorization with column pivoting of the complex matrix block A(IOFFSET+1:M,1:N) as A * P(K) = Q(K) * R(K). The routine uses Level 2 BLAS. The block A(1:IOFFSET,1:N) is accordingly pivoted, but not factorized. The routine also overwrites the right-hand-sides matrix block B stored in A(IOFFSET+1:M,N+1:N+NRHS) with Q(K)**H * B.

**Parameters***M*M is INTEGER The number of rows of the matrix A. M >= 0.

*N*N is INTEGER The number of columns of the matrix A. N >= 0.

*NRHS*NRHS is INTEGER The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.

*IOFFSET*IOFFSET is INTEGER The number of rows of the matrix A that must be pivoted but not factorized. IOFFSET >= 0. IOFFSET also represents the number of columns of the whole original matrix A_orig that have been factorized in the previous steps.

*KMAX*KMAX is INTEGER The first factorization stopping criterion. KMAX >= 0. The maximum number of columns of the matrix A to factorize, i.e. the maximum factorization rank. a) If KMAX >= min(M-IOFFSET,N), then this stopping criterion is not used, factorize columns depending on ABSTOL and RELTOL. b) If KMAX = 0, then this stopping criterion is satisfied on input and the routine exits immediately. This means that the factorization is not performed, the matrices A and B and the arrays TAU, IPIV are not modified.

*ABSTOL*ABSTOL is REAL, cannot be NaN. The second factorization stopping criterion. The absolute tolerance (stopping threshold) for maximum column 2-norm of the residual matrix. The algorithm converges (stops the factorization) when the maximum column 2-norm of the residual matrix is less than or equal to ABSTOL. a) If ABSTOL < 0.0, then this stopping criterion is not used, the routine factorizes columns depending on KMAX and RELTOL. This includes the case ABSTOL = -Inf. b) If 0.0 <= ABSTOL then the input value of ABSTOL is used.

*RELTOL*RELTOL is REAL, cannot be NaN. The third factorization stopping criterion. The tolerance (stopping threshold) for the ratio of the maximum column 2-norm of the residual matrix to the maximum column 2-norm of the original matrix A_orig. The algorithm converges (stops the factorization), when this ratio is less than or equal to RELTOL. a) If RELTOL < 0.0, then this stopping criterion is not used, the routine factorizes columns depending on KMAX and ABSTOL. This includes the case RELTOL = -Inf. d) If 0.0 <= RELTOL then the input value of RELTOL is used.

*KP1*KP1 is INTEGER The index of the column with the maximum 2-norm in the whole original matrix A_orig determined in the main routine CGEQP3RK. 1 <= KP1 <= N_orig_mat.

*MAXC2NRM*MAXC2NRM is REAL The maximum column 2-norm of the whole original matrix A_orig computed in the main routine CGEQP3RK. MAXC2NRM >= 0.

*A*A is COMPLEX array, dimension (LDA,N+NRHS) On entry: the M-by-N matrix A and M-by-NRHS matrix B, as in N NRHS array_A = M [ mat_A, mat_B ] On exit: 1. The elements in block A(IOFFSET+1:M,1:K) below the diagonal together with the array TAU represent the unitary matrix Q(K) as a product of elementary reflectors. 2. The upper triangular block of the matrix A stored in A(IOFFSET+1:M,1:K) is the triangular factor obtained. 3. The block of the matrix A stored in A(1:IOFFSET,1:N) has been accordingly pivoted, but not factorized. 4. The rest of the array A, block A(IOFFSET+1:M,K+1:N+NRHS). The left part A(IOFFSET+1:M,K+1:N) of this block contains the residual of the matrix A, and, if NRHS > 0, the right part of the block A(IOFFSET+1:M,N+1:N+NRHS) contains the block of the right-hand-side matrix B. Both these blocks have been updated by multiplication from the left by Q(K)**H.

*LDA*LDA is INTEGER The leading dimension of the array A. LDA >= max(1,M).

*K*K is INTEGER Factorization rank of the matrix A, i.e. the rank of the factor R, which is the same as the number of non-zero rows of the factor R. 0 <= K <= min(M-IOFFSET,KMAX,N). K also represents the number of non-zero Householder vectors.

*MAXC2NRMK*MAXC2NRMK is REAL The maximum column 2-norm of the residual matrix, when the factorization stopped at rank K. MAXC2NRMK >= 0.

*RELMAXC2NRMK*RELMAXC2NRMK is REAL The ratio MAXC2NRMK / MAXC2NRM of the maximum column 2-norm of the residual matrix (when the factorization stopped at rank K) to the maximum column 2-norm of the whole original matrix A. RELMAXC2NRMK >= 0.

*JPIV*JPIV is INTEGER array, dimension (N) Column pivot indices, for 1 <= j <= N, column j of the matrix A was interchanged with column JPIV(j).

*TAU*TAU is COMPLEX array, dimension (min(M-IOFFSET,N)) The scalar factors of the elementary reflectors.

*VN1*VN1 is REAL array, dimension (N) The vector with the partial column norms.

*VN2*VN2 is REAL array, dimension (N) The vector with the exact column norms.

*WORK*WORK is COMPLEX array, dimension (N-1) Used in CLARF subroutine to apply an elementary reflector from the left.

*INFO*INFO is INTEGER 1) INFO = 0: successful exit. 2) If INFO = j_1, where 1 <= j_1 <= N, then NaN was detected and the routine stops the computation. The j_1-th column of the matrix A or the j_1-th element of array TAU contains the first occurrence of NaN in the factorization step K+1 ( when K columns have been factorized ). On exit: K is set to the number of factorized columns without exception. MAXC2NRMK is set to NaN. RELMAXC2NRMK is set to NaN. TAU(K+1:min(M,N)) is not set and contains undefined elements. If j_1=K+1, TAU(K+1) may contain NaN. 3) If INFO = j_2, where N+1 <= j_2 <= 2*N, then no NaN was detected, but +Inf (or -Inf) was detected and the routine continues the computation until completion. The (j_2-N)-th column of the matrix A contains the first occurrence of +Inf (or -Inf) in the factorization step K+1 ( when K columns have been factorized ).

**Author**Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

**References:**

[1] A Level 3 BLAS QR factorization algorithm with column pivoting developed in 1996. G. Quintana-Orti, Depto. de Informatica, Universidad Jaime I, Spain. X. Sun, Computer Science Dept., Duke University, USA. C. H. Bischof, Math. and Comp. Sci. Div., Argonne National Lab, USA. A BLAS-3 version of the QR factorization with column pivoting. LAPACK Working Note 114 and in SIAM J. Sci. Comput., 19(5):1486-1494, Sept. 1998.

[2] A partial column norm updating strategy developed in 2006. Z. Drmac and Z. Bujanovic, Dept. of Math., University of Zagreb, Croatia. On the failure of rank revealing QR factorization software – a case study. LAPACK Working Note 176. and in ACM Trans. Math. Softw. 35, 2, Article 12 (July 2008), 28 pages.

**Contributors:**

November 2023, Igor Kozachenko, James Demmel, EECS Department, University of California, Berkeley, USA.

Definition at line **341** of file **claqp2rk.f**.

## Author

Generated automatically by Doxygen for LAPACK from the source code.

## Referenced By

The man page claqp2rk(3) is an alias of claqp2rk.f(3).