.TH "SRC/zlaqp3rk.f" 3 "Version 3.12.0" "LAPACK" \" -*- nroff -*- .ad l .nh .SH NAME SRC/zlaqp3rk.f .SH SYNOPSIS .br .PP .SS "Functions/Subroutines" .in +1c .ti -1c .RI "subroutine \fBzlaqp3rk\fP (m, n, nrhs, ioffset, nb, abstol, reltol, kp1, maxc2nrm, a, lda, done, kb, maxc2nrmk, relmaxc2nrmk, jpiv, tau, vn1, vn2, auxv, f, ldf, iwork, info)" .br .RI "\fBZLAQP3RK\fP computes a step of truncated QR factorization with column pivoting of a complex m-by-n matrix A using Level 3 BLAS and overwrites a complex m-by-nrhs matrix B with Q**H * B\&. " .in -1c .SH "Function/Subroutine Documentation" .PP .SS "subroutine zlaqp3rk (integer m, integer n, integer nrhs, integer ioffset, integer nb, double precision abstol, double precision reltol, integer kp1, double precision maxc2nrm, complex*16, dimension( lda, * ) a, integer lda, logical done, integer kb, double precision maxc2nrmk, double precision relmaxc2nrmk, integer, dimension( * ) jpiv, complex*16, dimension( * ) tau, double precision, dimension( * ) vn1, double precision, dimension( * ) vn2, complex*16, dimension( * ) auxv, complex*16, dimension( ldf, * ) f, integer ldf, integer, dimension( * ) iwork, integer info)" .PP \fBZLAQP3RK\fP computes a step of truncated QR factorization with column pivoting of a complex m-by-n matrix A using Level 3 BLAS and overwrites a complex m-by-nrhs matrix B with Q**H * B\&. .PP \fBPurpose:\fP .RS 4 .PP .nf ZLAQP3RK computes a step of truncated QR factorization with column pivoting of a complex M-by-N matrix A block A(IOFFSET+1:M,1:N) by using Level 3 BLAS as A * P(KB) = Q(KB) * R(KB)\&. The routine tries to factorize NB columns from A starting from the row IOFFSET+1 and updates the residual matrix with BLAS 3 xGEMM\&. The number of actually factorized columns is returned is smaller than NB\&. Block A(1:IOFFSET,1:N) is accordingly pivoted, but not factorized\&. The routine also overwrites the right-hand-sides B matrix stored in A(IOFFSET+1:M,1:N+1:N+NRHS) with Q(KB)**H * B\&. Cases when the number of factorized columns KB < NB: (1) In some cases, due to catastrophic cancellations, it cannot factorize all NB columns and need to update the residual matrix\&. Hence, the actual number of factorized columns in the block returned in KB is smaller than NB\&. The logical DONE is returned as FALSE\&. The factorization of the whole original matrix A_orig must proceed with the next block\&. (2) Whenever the stopping criterion ABSTOL or RELTOL is satisfied, the factorization of the whole original matrix A_orig is stopped, the logical DONE is returned as TRUE\&. The number of factorized columns which is smaller than NB is returned in KB\&. (3) In case both stopping criteria ABSTOL or RELTOL are not used, and when the residual matrix is a zero matrix in some factorization step KB, the factorization of the whole original matrix A_orig is stopped, the logical DONE is returned as TRUE\&. The number of factorized columns which is smaller than NB is returned in KB\&. (4) Whenever NaN is detected in the matrix A or in the array TAU, the factorization of the whole original matrix A_orig is stopped, the logical DONE is returned as TRUE\&. The number of factorized columns which is smaller than NB is returned in KB\&. The INFO parameter is set to the column index of the first NaN occurrence\&. .fi .PP .RE .PP \fBParameters\fP .RS 4 \fIM\fP .PP .nf M is INTEGER The number of rows of the matrix A\&. M >= 0\&. .fi .PP .br \fIN\fP .PP .nf N is INTEGER The number of columns of the matrix A\&. N >= 0 .fi .PP .br \fINRHS\fP .PP .nf NRHS is INTEGER The number of right hand sides, i\&.e\&., the number of columns of the matrix B\&. NRHS >= 0\&. .fi .PP .br \fIIOFFSET\fP .PP .nf 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\&. .fi .PP .br \fINB\fP .PP .nf NB is INTEGER Factorization block size, i\&.e the number of columns to factorize in the matrix A\&. 0 <= NB If NB = 0, then 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\&. .fi .PP .br \fIABSTOL\fP .PP .nf ABSTOL is DOUBLE PRECISION, cannot be NaN\&. 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 NB and RELTOL\&. This includes the case ABSTOL = -Inf\&. b) If 0\&.0 <= ABSTOL then the input value of ABSTOL is used\&. .fi .PP .br \fIRELTOL\fP .PP .nf RELTOL is DOUBLE PRECISION, cannot be NaN\&. 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 NB and ABSTOL\&. This includes the case RELTOL = -Inf\&. d) If 0\&.0 <= RELTOL then the input value of RELTOL is used\&. .fi .PP .br \fIKP1\fP .PP .nf 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 ZGEQP3RK\&. 1 <= KP1 <= N_orig\&. .fi .PP .br \fIMAXC2NRM\fP .PP .nf MAXC2NRM is DOUBLE PRECISION The maximum column 2-norm of the whole original matrix A_orig computed in the main routine ZGEQP3RK\&. MAXC2NRM >= 0\&. .fi .PP .br \fIA\fP .PP .nf A is COMPLEX*16 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:KB) below the diagonal together with the array TAU represent the unitary matrix Q(KB) as a product of elementary reflectors\&. 2\&. The upper triangular block of the matrix A stored in A(IOFFSET+1:M,1:KB) 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,KB+1:N+NRHS)\&. The left part A(IOFFSET+1:M,KB+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(KB)**H\&. .fi .PP .br \fILDA\fP .PP .nf LDA is INTEGER The leading dimension of the array A\&. LDA >= max(1,M)\&. .fi .PP .br \fI\fP .RE .PP verbatim DONE is LOGICAL TRUE: a) if the factorization completed before processing all min(M-IOFFSET,NB,N) columns due to ABSTOL or RELTOL criterion, b) if the factorization completed before processing all min(M-IOFFSET,NB,N) columns due to the residual matrix being a ZERO matrix\&. c) when NaN was detected in the matrix A or in the array TAU\&. FALSE: otherwise\&. .PP \fBParameters\fP .RS 4 \fIKB\fP .PP .nf KB 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 <= KB <= min(M-IOFFSET,NB,N)\&. KB also represents the number of non-zero Householder vectors\&. .fi .PP .br \fIMAXC2NRMK\fP .PP .nf MAXC2NRMK is DOUBLE PRECISION The maximum column 2-norm of the residual matrix, when the factorization stopped at rank KB\&. MAXC2NRMK >= 0\&. .fi .PP .br \fIRELMAXC2NRMK\fP .PP .nf RELMAXC2NRMK is DOUBLE PRECISION The ratio MAXC2NRMK / MAXC2NRM of the maximum column 2-norm of the residual matrix (when the factorization stopped at rank KB) to the maximum column 2-norm of the original matrix A_orig\&. RELMAXC2NRMK >= 0\&. .fi .PP .br \fIJPIV\fP .PP .nf 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)\&. .fi .PP .br \fITAU\fP .PP .nf TAU is COMPLEX*16 array, dimension (min(M-IOFFSET,N)) The scalar factors of the elementary reflectors\&. .fi .PP .br \fIVN1\fP .PP .nf VN1 is DOUBLE PRECISION array, dimension (N) The vector with the partial column norms\&. .fi .PP .br \fIVN2\fP .PP .nf VN2 is DOUBLE PRECISION array, dimension (N) The vector with the exact column norms\&. .fi .PP .br \fIAUXV\fP .PP .nf AUXV is COMPLEX*16 array, dimension (NB) Auxiliary vector\&. .fi .PP .br \fIF\fP .PP .nf F is COMPLEX*16 array, dimension (LDF,NB) Matrix F**H = L*(Y**H)*A\&. .fi .PP .br \fILDF\fP .PP .nf LDF is INTEGER The leading dimension of the array F\&. LDF >= max(1,N+NRHS)\&. .fi .PP .br \fIIWORK\fP .PP .nf IWORK is INTEGER array, dimension (N-1)\&. Is a work array\&. ( IWORK is used to store indices of 'bad' columns for norm downdating in the residual matrix )\&. .fi .PP .br \fIINFO\fP .PP .nf 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 KB+1 ( when KB columns have been factorized )\&. On exit: KB is set to the number of factorized columns without exception\&. MAXC2NRMK is set to NaN\&. RELMAXC2NRMK is set to NaN\&. TAU(KB+1:min(M,N)) is not set and contains undefined elements\&. If j_1=KB+1, TAU(KB+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 actorization step KB+1 ( when KB columns have been factorized )\&. .fi .PP .RE .PP \fBAuthor\fP .RS 4 Univ\&. of Tennessee .PP Univ\&. of California Berkeley .PP Univ\&. of Colorado Denver .PP NAG Ltd\&. .RE .PP \fBReferences:\fP .RS 4 [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\&. .RE .PP [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\&. .PP \fBContributors:\fP .RS 4 .PP .nf November 2023, Igor Kozachenko, James Demmel, EECS Department, University of California, Berkeley, USA\&. .fi .PP .RE .PP .PP Definition at line \fB392\fP of file \fBzlaqp3rk\&.f\fP\&. .SH "Author" .PP Generated automatically by Doxygen for LAPACK from the source code\&.