SRC/slaqp3rk.f(3)

NAME
SRC/slaqp3rk.f

SYNOPSIS

  Functions/Subroutines
subroutine slaqp3rk (m, n, nrhs, ioffset, nb, abstol, reltol, kp1, maxc2nrm, a, lda, done, kb, maxc2nrmk, relmaxc2nrmk, jpiv, tau, vn1, vn2, auxv, f, ldf, iwork, info)
SLAQP3RK computes a step of truncated QR factorization with column pivoting of a real m-by-n matrix A using Level 3 BLAS and overwrites a real m-by-nrhs matrix B with Q**T * B.

Function/Subroutine Documentation

  subroutine slaqp3rk (integer m, integer n, integer nrhs, integer ioffset, integer nb, real abstol, real reltol, integer kp1, real maxc2nrm, real, dimension( lda, * ) a, integer lda, logical done, integer kb, real maxc2nrmk, real relmaxc2nrmk, integer, dimension( * ) jpiv, real, dimension( * ) tau, real, dimension( * ) vn1, real, dimension( * ) vn2, real, dimension( * ) auxv, real, dimension( ldf, * ) f, integer ldf, integer, dimension( * ) iwork, integer info)

SLAQP3RK computes a step of truncated QR factorization with column pivoting of a real m-by-n matrix A using Level 3 BLAS and overwrites a real m-by-nrhs matrix B with Q**T * B.

Purpose:

    !>
    !> SLAQP3RK computes a step of truncated QR factorization with column
    !> pivoting of a real 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)**T * 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.
    !>
    !>

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.
    !>

    NB

    !>          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.
    !>

    ABSTOL

    !>          ABSTOL is REAL, 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.
    !>

    RELTOL

    !>          RELTOL is REAL, 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.
    !>

    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 SGEQP3RK. 1 <= KP1 <= N_orig.
    !>

    MAXC2NRM

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

    A

    !>          A is REAL 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 orthogonal 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)**T.
    !>

    LDA

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

    DONE

    !>          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.
    !>

    KB

    !>          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.
    !>

    MAXC2NRMK

    !>          MAXC2NRMK is REAL
    !>          The maximum column 2-norm of the residual matrix,
    !>          when the factorization stopped at rank KB. 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 KB) to the maximum column 2-norm of the
    !>          original matrix A_orig. 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 REAL 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.
    !>

    AUXV

    !>          AUXV is REAL array, dimension (NB)
    !>          Auxiliary vector.
    !>

    F

    !>          F is REAL array, dimension (LDF,NB)
    !>          Matrix F**T = L*(Y**T)*A.
    !>

    LDF

    !>          LDF is INTEGER
    !>          The leading dimension of the array F. LDF >= max(1,N+NRHS).
    !>

    IWORK

    !>          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 ).
    !>

    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 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 ).
    !>

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 398 of file slaqp3rk.f.

Author

Generated automatically by Doxygen for LAPACK from the source code.