Parallel Engineering and Scientific Subroutine Library for AIX Version 2 Release 3: Guide and Reference

PDGECON and PZGECON--Estimate the Reciprocal of the Condition Number of a General Matrix

PDGECON and PZGECON estimate the reciprocal of the condition number of general matrix A. These subroutines use the results of the factorization of matrix A, produced by a preceding call to PDGETRF or PZGETRF, respectively. For details on the factorization, see PDGETRF and PZGETRF--General Matrix Factorization.

If n = 0, the subroutines return with rcond  = 1.0

See references [16], [18], [22], [36], and [37].

Table 62. Data Types

Syntax

On Entry

norm

specifies whether the estimate of the condition number is computed using the one norm or the infinity norm; where:

If norm = 'O' or '1', the one norm is used in the computation.

If norm = 'I', the infinity norm is used in the computation.

Scope: global

Specified as: a single character; norm = 'O', '1', or 'I'.

n

is the order of the factored submatrix A.

Scope: global

Specified as: a fullword integer; n >= 0.

a

is the local part of the global general matrix A, containing the factorization of matrix A produced by a preceding call to PDGETRF or PZGETRF, respectively. This identifies the first element of the local array A. This subroutine computes the location of the first element of the local subarray used, based on ia, ja, desc_a, p, q, myrow, and mycol; therefore, the leading LOCp(ia+n-1) by LOCq(ja+n-1) part of the local array A must contain the local pieces of the leading ia+n-1 by ja+n-1 part of the global matrix.

Scope: local

Specified as: an LLD_A by (at least) LOCq(N_A) array, containing numbers of the data type indicated in Table 62. Details about the square block-cyclic data distribution of global matrix A are stored in desc_a.

ia

is the row index of the global matrix A, identifying the first row of the submatrix A.

Scope: global

Specified as: a fullword integer; 1 <= ia <= M_A and ia+n-1 <= M_A.

ja

is the column index of the global matrix A, identifying the first column of the submatrix A.

Scope: global

Specified as: a fullword integer; 1 <= ja <= N_A and ja+n-1 <= N_A.

desc_a

is the array descriptor for global matrix A, described in the following table:

desc_a	Name	Description	Limits	Scope
1	DTYPE_A	Descriptor type	DTYPE_A=1	Global
2	CTXT_A	BLACS context	Valid value, as returned by BLACS_GRIDINIT or BLACS_GRIDMAP	Global
3	M_A	Number of rows in the global matrix	If n = 0: M_A >= 0 Otherwise: M_A >= 1	Global
4	N_A	Number of columns in the global matrix	If n = 0: N_A >= 0 Otherwise: N_A >= 1	Global
5	MB_A	Row block size	MB_A >= 1	Global
6	NB_A	Column block size	NB_A >= 1	Global
7	RSRC_A	The process row of the p × q grid over which the first row of the global matrix is distributed	0 <= RSRC_A < p	Global
8	CSRC_A	The process column of the p × q grid over which the first column of the global matrix is distributed	0 <= CSRC_A < q	Global
9	LLD_A	The leading dimension of the local array	LLD_A >= max(1,LOCp(M_A))	Local

Specified as: an array of (at least) length 9, containing fullword integers.

anorm

has the following meaning:

If norm = 'O' or '1', then anorm is the one norm of the original matrix.

If norm = 'I', then anorm is the infinity norm of the original matrix.

Note:

You may obtain the value of anorm by a preceding call to PDLANGE or PZLANGE, respectively. Refer to PDLANGE and PZLANGE--General Matrix Norm.

Scope: global

Specified as: long-precision real number >= 0.0

rcond

See On Return.

work

has the following meaning:

If lwork = 0, work is ignored.

If lwork <> 0, work is a work area used by this subroutine, where:

• If lwork  <>  -1, then its size is (at least) of length lwork.
• If lwork  =  -1, then its size is (at least) of length 1.

Scope: local

Specified as: an area of storage containing numbers of data type indicated in Table 62.

lwork

is the number of elements in array WORK.

Scope:

• If lwork  >=  0, lwork is local.
• If lwork  =  -1, lwork is global.

Specified as: a fullword integer; where:

• If lwork = 0, PDGECON and PZGECON dynamically allocate the work area used by the subroutine. The work area is deallocated before control is returned to the calling program. This option is an extension to the ScaLAPACK standard.
• If lwork = -1, PDGECON and PZGECON perform a work area query and return the minimum size of work in work₁. No computation is performed and the subroutine returns after error checking is complete.
• Otherwise, use the following rules to determine the value to specify:

  For PDGECON, lwork >= 2np0 + 2nq0 + max(2, max(nb(max(1, iceil(nprow-1, npcol))), nq0 + nb(max(1, iceil(npcol-1, nprow)))))

  For PZGECON, lwork >= 2np0 + max(2, max(nb(max(1, iceil(nprow-1, npcol))), nq0 + nb(max(1, iceil(npcol-1, nprow)))))

  where:

  mb = MB_A

  nb = NB_A

  iroff = mod(ia-1, mb)

  icoff = mod(ja-1, nb)

  iarow = mod(RSRC_A + (ia-1)/mb, nprow)

  iacol = mod(CSRC_A + (ja-1)/nb, npcol)

  np0 = NUMROC(n+iroff, mb, myrow, iarow, nprow)

  nq0 = NUMROC(n+icoff, nb, mycol, iacol, npcol)

iwork

has the following meaning:

If liwork = 0, iwork is ignored.

If liwork <> 0, iwork is a work area used by this subroutine, where:

• If liwork  <>  -1, then its size is (at least) of length liwork.
• If liwork  =  -1, then its size is (at least) of length 1.

Scope: local

Specified as: an area of storage containing fullword integers.

liwork

is the number of elements in array iwork.

Scope:

• If liwork  >=  0, liwork is local.
• If liwork  =  -1, liwork is global.

Specified as: a fullword integer; where:

• If liwork = 0, PDGECON dynamically allocates the work area used by the subroutine. The work area is deallocated before control is returned to the calling program. This option is an extension to the ScaLAPACK standard.
• If liwork = -1, PDGECON performs a work area query and return the minimum size of iwork in iwork₁. No computation is performed and the subroutine returns after error checking is complete.
• Otherwise, use the following rules to determine the value to specify:

  liwork >= np0

  where:

  mb = MB_A

  iroff = mod(ia-1, mb)

  iarow = mod(RSRC_A + (ia-1)/mb, nprow)

  np0 = NUMROC(n+iroff, mb, myrow, iarow, nprow)

rwork

has the following meaning:

If lrwork = 0, rwork is ignored.

If lrwork <> 0, rwork is a work area used by this subroutine, where:

• If lrwork  <>  -1, then its size is (at least) of length lrwork.
• If lrwork  =  -1, then its size is (at least) of length 1.

Scope: local

Specified as: an area of storage containing long-precision real numbers.

lrwork

is the number of elements in array rwork.

Scope:

• If lrwork  >=  0, lrwork is local.
• If lrwork  =  -1, lrwork is global.

Specified as: a fullword integer; where:

• If lrwork = 0, PZGECON dynamically allocates the work area used by the subroutine. The work area is deallocated before control is returned to the calling program. This option is an extension to the ScaLAPACK standard.
• If lrwork = -1, PZGECON performs a work area query and return the minimum size of rwork in rwork₁. No computation is performed and the subroutine returns after error checking is complete.
• Otherwise, use the following rules to determine the value to specify:

  lrwork >= 2nq0

  where:

  nb = NB_A

  icoff = mod(ja-1, nb)

  iacol = mod(CSRC_A + (ja-1)/nb, npcol)

  nq0 = NUMROC(n+icoff, nb, mycol, iacol, npcol)

info

See On Return.

On Return

rcond

has the following meaning:

If info = 0, an estimate of the reciprocal of the condition number of general matrix A is returned.

If n = 0, the subroutines return with rcond  = 1.0

Else if n <> 0 and anorm = 0.0, the subroutines return with rcond  = 0.0

Scope: global

Returned as: a long-precision real number; rcond >= 0.0.

info

has the following meaning:

If info = 0, the computation completed normally.

Scope: global

Returned as: a fullword integer; info = 0.

Notes and Coding Rules

1. In your C program, arguments rcond and info must be passed by reference.
2. This subroutine accepts lowercase letters for the norm argument.
3. The matrix and vector must have no common elements; otherwise, results are unpredictable.
4. The scalar data specified for input argument n must be the same for PDLANGE/PZLANGE, PDGETRF/PZGETRF, and PDGECON/PZGECON. In addition, the scalar data specified for input argument m in PDLANGE/PZLANGE and PDGETRF/PZGETRF must be the same as input argument n in PDLANGE/PZLANGE, PDGETRF/PZGETRF, and PDGECON/PZGECON.
5. The global submatrix for A input to PDLANGE/PZLANGE must be the same as the corresponding input arguments for PDGETRF/PZGETRF; and thus, the scalar data specified for ia, ja, and the contents of desc_a must also be the same.
6. The global submatrix for A input to PDGECON/PZGECON must be the same as the corresponding output arguments for PDGETRF/PZGETRF; and thus, the scalar data specified for ia, ja, and the contents of desc_a must also be the same.
7. The NUMROC utility subroutine can be used to determine the values of LOCp(M_) and LOCq(N_) used in the argument descriptions above. For details, see Determining the Number of Rows and Columns in Your Local Arrays and NUMROC--Compute the Number of Rows or Columns of a Block-Cyclically Distributed Matrix Contained in a Process.
8. For suggested block sizes, see Coding Tips for Optimizing Parallel Performance.
9. On both input and output, matrix A conforms to ScaLAPACK format.
10. The global general matrix A must be distributed using a square block-cyclic distribution; that is, MB_A = NB_A.
11. The global general matrix A must be aligned on a block row boundary; that is, ia-1 must be a multiple of MB_A.
12. The block row offset of A must be equal to the block column offset of A; that is, mod(ia-1, MB_A) = mod(ja-1, NB_A).

Error Conditions

Computational Errors

None.

Resource Errors

Unable to allocate work space.

Input-Argument and Miscellaneous Errors

Stage 1:  

1. DTYPE_A is invalid.

Stage 2:  

1. CTXT_A is invalid.

Stage 3:  

1. This subroutine was called from outside the process grid.

Stage 4:  

1. norm <> 'O, '1', or 'I'
2. n < 0
3. M_A < 0 and n = 0; M_A < 1 otherwise
4. N_A < 0 and n = 0; N_A < 1 otherwise
5. anorm < 0
6. ia < 1
7. ja < 1
8. MB_A < 1
9. NB_A < 1
10. RSRC_A < 0 or RSRC_A >= p
11. CSRC_A < 0 or CSRC_A >= q

Stage 5:  

If n <> 0:

1. ia > M_A
2. ja > N_A
3. ia+n-1 > M_A
4. ja+n-1 > N_A

   In all cases:

5. MB_A <> NB_A
6. mod(ia-1, MB_A) <> mod(ja-1, NB_A)
7. mod(ia-1, MB_A) <> 0

Stage 6:  

1. LLD_A < max(1, LOCp(M_A))
2. lwork <> 0, lwork <> -1, and lwork < (minimum value). (For the minimum value, see the lwork argument description.)
3. liwork <> 0, liwork <> -1, and liwork < (minimum value). (For the minimum value, see the liwork argument description.)
4. lrwork <> 0, lrwork <> -1, and lrwork < (minimum value). (For the minimum value, see the lrwork argument description.)

Stage 7:  

Each of the following global input arguments are checked to determine whether its value differs from the value specified on process P₀₀:

1. norm differs.
2. n differs.
3. ia differs.
4. ja differs.
5. DTYPE_A differs.
6. M_A differs.
7. N_A differs.
8. MB_A differs.
9. NB_A differs.
10. RSRC_A differs.
11. CSRC_A differs.
12. anorm differs.

    Also:

13. lwork = -1 on a subset of processes.
14. liwork = -1 on a subset of processes.
15. lrwork = -1 on a subset of processes.

Example 1

This example estimates the reciprocal of the condition number of real general matrix A. The input matrix A to PDLANGE and PDGETRF is the same as input matrix A in the PDGETRF Example 1.

Notes:

1. Because WORK is used by both PDLANGE and PDGECON, we do not dynamically allocate the WORK area.

2. Because liwork = 0, PDGECON dynamically allocates the IWORK area used by this subroutine.

Call Statements and Input

ORDER = 'R'
NPROW = 2
NPCOL = 2
CALL BLACS_GET(0, 0, ICONTXT)
CALL BLACS_GRIDINIT(ICONTXT, ORDER, NPROW, NPCOL)
CALL BLACS_GRIDINFO(ICONTXT, NPROW, NPCOL, MYROW, MYCOL)
 
                 NORM, N   N   A  IA  JA  DESC_A  WORK
                   |   |   |   |   |   |    |       | 
ANORM = PDLANGE(  'O', 9 , 9,  A , 1 , 1, DESC_A, WORK )
 
 
               N   N   A  IA  JA  DESC_A  IPIV  INFO
               |   |   |   |   |    |       |     | 
CALL PDGETRF(  9 , 9 , A , 1 , 1, DESC_A, IPIV, INFO )
 
 
             NORM  N   A  IA  JA  DESC_A  ANORM  RCOND  WORK  LWORK  IWORK LIWORK INFO
               |   |   |   |   |    |       |      |      |     |      |      |     | 
CALL PDGECON( 'O', 9 , A , 1 , 1, DESC_A, ANORM, RCOND, WORK,  100 , IWORK ,  0 , INFO )

Output:

The value of rcond = 0.6173D-02 on all processes.

The value of info is 0 on all processes.

Example 2

This example estimates the reciprocal of the condition number of complex general matrix A. The input matrix A to PZLANGE and PZGETRF is the same as input matrix A in the PZGETRF Example 2.

Notes:

1. Because RWORK is used by both PZLANGE and PZGECON, we do not dynamically allocate the RWORK area.

2. Because lwork = 0, PZGECON dynamically allocates the WORK area used by this subroutine.

Call Statements and Input

ORDER = 'R'
NPROW = 2
NPCOL = 2
CALL BLACS_GET(0, 0, ICONTXT)
CALL BLACS_GRIDINIT(ICONTXT, ORDER, NPROW, NPCOL)
CALL BLACS_GRIDINFO(ICONTXT, NPROW, NPCOL, MYROW, MYCOL)
 
                 NORM, N   N   A  IA  JA  DESC_A  RWORK
                   |   |   |   |   |   |    |       | 
ANORM = PZLANGE(  'O', 9 , 9,  A , 1 , 1, DESC_A, RWORK )
 
 
               N   N   A  IA  JA  DESC_A  IPIV  INFO
               |   |   |   |   |    |       |     | 
CALL PZGETRF(  9 , 9 , A , 1 , 1, DESC_A, IPIV, INFO )
 
 
             NORM  N   A  IA  JA  DESC_A  ANORM  RCOND  WORK  LWORK  RWORK LRWORK INFO
               |   |   |   |   |    |       |      |      |     |      |      |     | 
CALL PZGECON( 'O', 9 , A , 1 , 1, DESC_A, ANORM, RCOND, WORK,   0  , RWORK,  100, INFO )

Output:

The value of rcond = 0.3053D-01 on all processes.

The value of info is 0 on all processes.