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

Tue Nov 28 2023 12:08:41 Version 3.12.0 LAPACK