IBM Books

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

PDLANGE and PZLANGE--General Matrix Norm

These functions compute the norm of real or complex general matrix A, where in this description A represents the global general submatrix Aia:ia+m-1, ja:ja+n-1.

If m = 0 or n = 0, then zero is returned as the value of the function.

Table 118. Data Types

A Result work Subprogram
Long-precision real Long-precision real Long-precision real PDLANGE
Long-precision complex Long-precision real Long-precision real PZLANGE

Syntax

Fortran PDLANGE | PZLANGE (norm, m, n, a, ia, ja, desc_a, work)


C and C++ pdlange | pzlange (norm, m, n, a, ia, ja, desc_a, work);

On Entry

norm
specifies the type of computation; where:

If norm = 'O' or '1', the one norm of A is computed.

If norm = 'I', the infinity norm of A is computed.

If norm = 'F' or 'E', the Frobenius norm of A is computed.

If norm = 'M', the absolute value of the matrix element having the largest absolute value, i.e., max ( |A|), is returned.

Scope: global

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

m
is the number of rows in submatrix A.

Scope: global

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

n
is the number of columns in submatrix A.

Scope: global

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

a
is the local part of the global general matrix A. 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+m-1) by LOCq(ja+n-1) part of the local array A must contain the local pieces of the leading ia+m-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 118. Details about the 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+m-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 m = 0 or n = 0:
M_A >= 0
Otherwise:
M_A >= 1
Global
4 N_A Number of columns in the global matrix If m = 0 or 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.

work
a work array with at least the following dimension:

where:

iroffa = mod(ia-1, MB_A)
icoffa = mod(ja-1, NB_A)
iarow = mod(RSRC_A + (ia-1)/MB_A, nprow)
iacol = mod(CSRC_A + (ja-1)/NB_A, npcol)
mp0 = NUMROC(m+iroffa, MB_A, myrow, iarow, nprow)
nq0 = NUMROC(n+icoffa, NB_A, mycol, iacol, npcol)

Scope: local

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

On Return

Function value

If norm = 'O' or '1', the one norm of A is returned.

If norm = 'I', the infinity norm of A is returned.

If norm = 'F' or 'E', the Frobenius norm of A is returned.

If norm = 'M', the absolute value of the matrix element having the largest absolute value, i.e., max ( |A|), is returned.

Scope: global

If m = 0 or n = 0, the function returns zero.

Returned as: a long-precision real value.

Note:
Declare this function in your program as returning a value of the data type indicated in Table 118.

Notes and Coding Rules
  1. 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.
  2. This subprogram accepts lowercase letters for the norm argument.

Error Conditions

Computational Errors

None

Resource Errors

None

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', 'I', 'F', 'E', or 'M'
  2. m < 0
  3. n < 0
  4. M_A < 0 and m = 0 or n = 0; M_A < 1 otherwise
  5. N_A < 0 and m = 0 or n = 0; N_A < 1 otherwise
  6. MB_A < 1
  7. NB_A < 1
  8. RSRC_A < 0 or RSRC_A >= p
  9. CSRC_A < 0 or CSRC_A >= q
  10. ia < 1
  11. ja < 1

Stage 5:  

    If (m <> 0 and n <> 0):

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

Stage 6:  

  1. LLD_A < max(1, LOCp(M_A))

Example 1

This example computes the one norm of a real general matrix A of order 9, using a 2 × 2 process grid.

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  M   N   A  IA  JA   DESC_A   WORK
                 |   |   |   |   |   |     |       |
ANORM = PDLANGE('O', 9 , 9 , A , 1 , 1 , DESC_A , WORK )


Desc_A
DTYPE_ 1
CTXT_ icontxt(IOBG59)
M_ 9
N_ 9
MB_ 3
NB_ 3
RSRC_ 1
CSRC_ 0
LLD_ See below(EPSSL59)

Notes:

  1. icontxt is the output of the BLACS_GRIDINIT call.

  2. Each process should set the LLD_ as follows: 
    LLD_A = MAX(1,NUMROC(M_A, MB_A, MYROW, RSRC_A, NPROW))

    In this example, LLD_A = 3 on P00 and P01, and LLD_A = 6 on P10 and P11.

Input:

Global general 9 × 9 matrix A with block size 3 × 3: 

B,D          0                  1                  2
     *                                                      *
     |  1.0  1.2  1.4  |   1.6  1.8  2.0  |   2.2  2.4  2.6 |
 0   |  1.2  1.0  1.2  |   1.4  1.6  1.8  |   2.0  2.2  2.4 |
     |  1.4  1.2  1.0  |   1.2  1.4  1.6  |   1.8  2.0  2.2 |
     | ----------------|------------------|---------------- |
     |  1.6  1.4  1.2  |   1.0  1.2  1.4  |   1.6  1.8  2.0 |
 1   |  1.8  1.6  1.4  |   1.2  1.0  1.2  |   1.4  1.6  1.8 |
     |  2.0  1.8  1.6  |   1.4  1.2  1.0  |   1.2  1.4  1.6 |
     | ----------------|------------------|---------------- |
     |  2.2  2.0  1.8  |   1.6  1.4  1.2  |   1.0  1.2  1.4 |
 2   |  2.4  2.2  2.0  |   1.8  1.6  1.4  |   1.2  1.0  1.2 |
     |  2.6  2.4  2.2  |   2.0  1.8  1.6  |   1.4  1.2  1.0 |
     *                                                      *

The following is the 2 × 2 process grid: 

B,D  |   0 2   |  1  
-----| ------- |-----
1    |   P00   |  P01
-----| ------- |-----
0    |   P10   |  P11
2    |         |
Note:
The first row of A begins in the second row of the process grid.

Local arrays for A: 

p,q  |               0                |        1
-----|--------------------------------|-----------------
     |  1.6  1.4  1.2  1.6  1.8  2.0  |   1.0  1.2  1.4
 0   |  1.8  1.6  1.4  1.4  1.6  1.8  |   1.2  1.0  1.2
     |  2.0  1.8  1.6  1.2  1.4  1.6  |   1.4  1.2  1.0
-----|--------------------------------|-----------------
     |  1.0  1.2  1.4  2.2  2.4  2.6  |   1.6  1.8  2.0
     |  1.2  1.0  1.2  2.0  2.2  2.4  |   1.4  1.6  1.8
     |  1.4  1.2  1.0  1.8  2.0  2.2  |   1.2  1.4  1.6
 1   |  2.2  2.0  1.8  1.0  1.2  1.4  |   1.6  1.4  1.2
     |  2.4  2.2  2.0  1.2  1.0  1.2  |   1.8  1.6  1.4
     |  2.6  2.4  2.2  1.4  1.2  1.0  |   2.0  1.8  1.6

Output:

anorm = 16.2 on all processes.

Example 2

This example computes the one norm of a complex general matrix A of order 9, using a 2 × 2 process grid.

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  M   N   A  IA  JA   DESC_A   WORK
                 |   |   |   |   |   |     |       |
ANORM = PZLANGE('O', 9 , 9 , A , 1 , 1 , DESC_A , WORK )


Desc_A
DTYPE_ 1
CTXT_ icontxt(IOBG60)
M_ 9
N_ 9
MB_ 3
NB_ 3
RSRC_ 1
CSRC_ 0
LLD_A See below(EPSSL60)

Notes:

  1. icontxt is the output of the BLACS_GRIDINIT call.

  2. Each process should set the LLD_ as follows: 
    LLD_A = MAX(1,NUMROC(M_A, MB_A, MYROW, RSRC_A, NPROW))

    In this example, LLD_A = 3 on P00 and P01, and LLD_A = 6 on P10 and P11.

Global general 9 × 9 matrix A with block size 3 × 3: 


B,D                     0                                       1                                       2
     *                                                                                                                     *
     |  (2.0, 1.0)  (2.4,-1.0)  (2.8,-1.0)  |   (3.2,-1.0)  (3.6,-1.0)  (4.0,-1.0)  |   (4.4,-1.0)  (4.8,-1.0)  (5.2,-1.0) |
 0   |  (2.4, 1.0)  (2.0, 1.0)  (2.4,-1.0)  |   (2.8,-1.0)  (3.2,-1.0)  (3.6,-1.0)  |   (4.0,-1.0)  (4.4,-1.0)  (4.8,-1.0) |
     |  (2.8, 1.0)  (2.4, 1.0)  (2.0, 1.0)  |   (2.4,-1.0)  (2.8,-1.0)  (3.2,-1.0)  |   (3.6,-1.0)  (4.0,-1.0)  (4.4,-1.0) |
     | -------------------------------------|---------------------------------------|------------------------------------- |
     |  (3.2, 1.0)  (2.8, 1.0)  (2.4, 1.0)  |   (2.0, 1.0)  (2.4,-1.0)  (2.8,-1.0)  |   (3.2,-1.0)  (3.6,-1.0)  (4.0,-1.0) |
 1   |  (3.6, 1.0)  (3.2, 1.0)  (2.8, 1.0)  |   (2.4, 1.0)  (2.0, 1.0)  (2.4,-1.0)  |   (2.8,-1.0)  (3.2,-1.0)  (3.6,-1.0) |
     |  (4.0, 1.0)  (3.6, 1.0)  (3.2, 1.0)  |   (2.8, 1.0)  (2.4, 1.0)  (2.0, 1.0)  |   (2.4,-1.0)  (2.8,-1.0)  (3.2,-1.0) |
     | -------------------------------------|---------------------------------------|------------------------------------- |
     |  (4.4, 1.0)  (4.0, 1.0)  (3.6, 1.0)  |   (3.2, 1.0)  (2.8, 1.0)  (2.4, 1.0)  |   (2.0, 1.0)  (2.4,-1.0)  (2.8,-1.0) |
 2   |  (4.8, 1.0)  (4.4, 1.0)  (4.0, 1.0)  |   (3.6, 1.0)  (3.2, 1.0)  (2.8, 1.0)  |   (2.4, 1.0)  (2.0, 1.0)  (2.4,-1.0) |
     |  (5.2, 1.0)  (4.8, 1.0)  (4.4, 1.0)  |   (4.0, 1.0)  (3.6, 1.0)  (3.2, 1.0)  |   (2.8, 1.0)  (2.4, 1.0)  (2.0, 1.0) |
     *                                                                                                                     *

The following is the 2 × 2 process grid: 

B,D  |   0 2   |  1  
-----| ------- |-----
1    |   P00   |  P01
-----| ------- |-----
0    |   P10   |  P11
2    |         |
Note:
The first row of A begins in the second row of the process grid.

Local arrays for A: 


p,q  |                                    0                                     |                   1
-----|--------------------------------------------------------------------------|--------------------------------------
     |  (3.2, 1.0)  (2.8, 1.0)  (2.4, 1.0)  (3.2,-1.0)  (3.6,-1.0)  (4.0,-1.0)  |   (2.0, 1.0)  (2.4,-1.0)  (2.8,-1.0)
 0   |  (3.6, 1.0)  (3.2, 1.0)  (2.8, 1.0)  (2.8,-1.0)  (3.2,-1.0)  (3.6,-1.0)  |   (2.4, 1.0)  (2.0, 1.0)  (2.4,-1.0)
     |  (4.0, 1.0)  (3.6, 1.0)  (3.2, 1.0)  (2.4,-1.0)  (2.8,-1.0)  (3.2,-1.0)  |   (2.8, 1.0)  (2.4, 1.0)  (2.0, 1.0)
-----|--------------------------------------------------------------------------|--------------------------------------
     |  (2.0, 1.0)  (2.4,-1.0)  (2.8,-1.0)  (4.4,-1.0)  (4.8,-1.0)  (5.2,-1.0)  |   (3.2,-1.0)  (3.6,-1.0)  (4.0,-1.0)
     |  (2.4, 1.0)  (2.0, 1.0)  (2.4,-1.0)  (4.0,-1.0)  (4.4,-1.0)  (4.8,-1.0)  |   (2.8,-1.0)  (3.2,-1.0)  (3.6,-1.0)
     |  (2.8, 1.0)  (2.4, 1.0)  (2.0, 1.0)  (3.6,-1.0)  (4.0,-1.0)  (4.4,-1.0)  |   (2.4,-1.0)  (2.8,-1.0)  (3.2,-1.0)
 1   |  (4.4, 1.0)  (4.0, 1.0)  (3.6, 1.0)  (2.0, 1.0)  (2.4,-1.0)  (2.8,-1.0)  |   (3.2, 1.0)  (2.8, 1.0)  (2.4, 1.0)
     |  (4.8, 1.0)  (4.4, 1.0)  (4.0, 1.0)  (2.4, 1.0)  (2.0, 1.0)  (2.4,-1.0)  |   (3.6, 1.0)  (3.2, 1.0)  (2.8, 1.0)
     |  (5.2, 1.0)  (4.8, 1.0)  (4.4, 1.0)  (2.8, 1.0)  (2.4, 1.0)  (2.0, 1.0)  |   (4.0, 1.0)  (3.6, 1.0)  (3.2, 1.0)

Output:

anorm = 33.73 on all processes.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]