.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 \fIDONE\fP .PP .nf !> 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\&. !> .fi .PP .br \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 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\&.