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

PDSYR and PZHER--Rank-One Update of a Real Symmetric or a Complex Hermitian Matrix

PDSYR computes the following rank-one update:

A<--alphaxx^T+A

PZHER computes the following rank-one update:

A<--alphaxx^H+A

where, in the formula above:

A represents the global submatrix A_{ia:ia+n-1,
ja:ja+n-1}.

x represents the global vector:

For incx = M_X, it is X_{ix:ix,
jx:jx+n-1}.
For incx = 1 and incx <> M_X, it is X_{ix:ix+n-1,
jx:jx}.

alpha is a scalar.

and:

For PDSYR, submatrix A is real symmetric.
For PZHER, submatrix A is complex Hermitian.

Note:: No data should be moved to form x^T or x^H; that is, the vector x should always be stored in its untransposed form.

In the following two cases, no computation is performed and the subroutine returns after doing some parameter checking:

n = 0
alpha is zero.

See references [14] and [15].

Table 40. Data Types

A, x	alpha	Subprogram
Long-precision real	Long-precision real	PDSYR
Long-precision complex	Long-precision real	PZHER

Syntax

Fortran	CALL PDSYR \| PZHER (`uplo`, `n`, `alpha`, `x`, `ix`, `jx`, `desc_x`, `incx`, `a`, `ia`, `ja`, `desc_a`)
C and C++	pdsyr \| pzher (`uplo`, `n`, `alpha`, `x`, `ix`, `jx`, `desc_x`, `incx`, `a`, `ia`, `ja`, `desc_a`);

On Entry

uplo

indicates whether the upper or lower triangular part of the global submatrix A is referenced, where:

If uplo = 'U', the upper triangular part is referenced.

If uplo = 'L', the lower triangular part is referenced.

Scope: global

Specified as: a single character; uplo = 'U' or 'L'.

n

is the number of rows and columns in submatrix A and the number of elements in vector x used in the computation.

Scope: global

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

alpha

is the scalar alpha.

Scope: global

Specified as: a number of the data type indicated in Table 40.

x

is the local part of the global matrix X. This identifies the first element of the local array X. This subroutine computes the location of the first element of the local subarray used, based on ix, jx, desc_x, p, q, myrow, and mycol; therefore:

If incx = M_X, the leading LOCp(ix) by LOCq(jx+n-1) part of the local array X must contain the local pieces of the leading ix by jx+n-1 part of the global matrix.
If incx = 1 and incx <> M_X, the leading LOCp(ix+n-1) by LOCq(jx) part of the local array X must contain the local pieces of the leading ix+n-1 by jx part of the global matrix.

Note:: No data should be moved to form x^T or x^H; that is, the vector x should always be stored in its untransposed form.

Scope: local

Specified as: an LLD_X by (at least) LOCq(N_X) array, containing numbers of the data type indicated in Table 40. Details about the block-cyclic data distribution of the global matrix X are stored in desc_x.

ix

has the following meaning:

If incx = M_X, it indicates which row of global matrix X is used for vector x.

If incx = 1 and incx <> M_X, it is the row index of global matrix X, identifying the first element of vector x.

Scope: global

Specified as: a fullword integer; 1 <= ix <= M_X and:

If incx = 1 and incx <> M_X, then ix+n-1 <= M_X.

jx

has the following meaning:

If incx = M_X, it is the column index of global matrix X, identifying the first element of vector x.

If incx = 1 and incx <> M_X, it indicates which column of global matrix X is used for vector x.

Scope: global

Specified as: a fullword integer; 1 <= jx <= N_X and:

If incx = M_X, then jx+n-1 <= N_X.

desc_x

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

`desc_x`	Name	Description	Limits	Scope
1	DTYPE_X	Descriptor type	DTYPE_X=1	Global
2	CTXT_X	BLACS context	Valid value, as returned by BLACS_GRIDINIT or BLACS_GRIDMAP	Global
3	M_X	Number of rows in the global matrix	If `n` = 0: M_X >= 0 Otherwise: M_X >= 1	Global
4	N_X	Number of columns in the global matrix	If `n` = 0: N_X >= 0 Otherwise: N_X >= 1	Global
5	MB_X	Row block size	MB_X >= 1	Global
6	NB_X	Column block size	NB_X >= 1	Global
7	RSRC_X	The process row of the `p` × `q` grid over which the first row of the global matrix is distributed	0 <= RSRC_X < `p`	Global
8	CSRC_X	The process column of the `p` × `q` grid over which the first column of the global matrix is distributed	0 <= CSRC_X < `q`	Global
9	LLD_X	The leading dimension of the local array	LLD_X >= max(1,LOCp(M_X))	Local

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

incx

is the stride for global vector x.

Scope: global

Specified as: a fullword integer; incx = 1 or incx = M_X, where:

If incx = M_X, then x is a row-distributed vector.

If incx = 1 and incx <> M_X, then x is a column-distributed vector.

a

is the local part of the global real symmetric or complex Hermitian 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+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, and:

If uplo = 'U', the leading n × n upper triangular part of the global submatrix A_{ia:ia+n-1,
ja:ja+n-1} must contain the upper triangular part of the submatrix, and the strictly lower triangular part is not referenced.
If uplo = 'L', the leading n × n lower triangular part of the global submatrix A_{ia:ia+n-1,
ja:ja+n-1} must contain the lower triangular part of the submatrix, and the strictly upper triangular part is not referenced.

Scope: local

Specified as: an LLD_A by (at least) LOCq(N_A) array, containing numbers of the data type indicated in Table 40. 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.

On Return

a

is the updated local part of the global matrix A, containing the results of the computation.

Scope: local

Returned as: an LLD_A by (at least) LOCq(N_A) array, containing numbers of the data type indicated in Table 40.

Notes and Coding Rules

These subroutines accept lowercase letters for the uplo argument.
The matrix and vector must have no common elements; otherwise, results are unpredictable.
The imaginary parts of the diagonal elements of the complex Hermitian matrix are assumed to be zero, so you do not have to set these values. On output, they are set to zero except when N is zero or alpha is zero, in which case no computation is performed.
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.
For suggested block sizes, see Coding Tips for Optimizing Parallel Performance.
The following values must be equal: CTXT_A = CTXT_X.
The global matrix A must be distributed using a square block-cyclic distribution; that is, MB_A = NB_A.
The block row and block column offsets of the global matrix A must be equal; that is, mod(ia-1, MB_A) = mod(ja-1, NB_A).
If incx = M_X:
- In the process grid, the process column containing the first column of the submatrix A must also contain the first column of the submatrix X; that is, iacol = ixcol, where:
  
  iacol = mod((((ja-1)/NB_A)+CSRC_A), q)
  ixcol = mod((((jx-1)/NB_X)+CSRC_X), q)
- The block column offset of x must be equal to the block row offset of A; that is, mod(jx-1, NB_X) = mod(ia-1, MB_A).
- The following block sizes must be equal: NB_X = NB_A.
If incx = 1( <> M_X):
- In the process grid, the process row containing the first row of the submatrix A must also contain the first row of the submatrix X; that is, iarow = ixrow, where:
  
  iarow = mod((((ia-1)/MB_A)+RSRC_A), p)
  ixrow = mod((((ix-1)/MB_X)+RSRC_X), p)
- The block row offset of x must be equal to the block row offset of A; that is, mod(ix-1, MB_X) = mod(ia-1, MB_A).
- The following block sizes must be equal: MB_X = MB_A.

DTYPE_A is invalid.
DTYPE_X is invalid.

Stage 2:

CTXT_A is invalid.

Stage 3:

This subroutine was called from outside the process grid.

Stage 4:

uplo <> 'U' or 'L'
n < 0
M_X < 0 and n = 0; M_X < 1 otherwise
N_X < 0 and n = 0; N_X < 1 otherwise
MB_X < 1
NB_X < 1
RSRC_X < 0 or RSRC_X >= p
CSRC_X < 0 or CSRC_X >= q
CTXT_A <> CTXT_X
ix < 1
jx < 1
M_A < 0 and n = 0; M_A < 1 otherwise
N_A < 0 and n = 0; N_A < 1 otherwise
MB_A < 1
NB_A < 1
RSRC_A < 0 or RSRC_A >= p
CSRC_A < 0 or CSRC_A >= q
ia < 1
ja < 1

Stage 5:

NB_A <> MB_A

If n <> 0:
ia > M_A
ja > N_A
ia+n-1 > M_A
ja+n-1 > N_A
ix > M_X
jx > N_X

If incx = M_X:
NB_X <> NB_A
mod(jx-1, NB_X) <> mod(ia-1, MB_A)
n <> 0 and jx+n-1 > N_X

If incx = 1( <> M_X):
MB_X <> MB_A
mod(ix-1, MB_X) <> mod(ia-1, MB_A)
n <> 0 and ix+n-1 > M_X

Otherwise:
incx <> M_X and incx <> 1

Stage 6:

mod(ja-1, NB_A) <> mod(ia-1, MB_A)
If incx = M_X, then (in the process grid) the process column containing the first column of the submatrix A does not contain the first column of the submatrix X; that is, iacol <> ixcol, where:

iacol = mod((((ja-1)/NB_A)+CSRC_A), q)
ixcol = mod((((jx-1)/NB_X)+CSRC_X), q)
If incx = 1( <> M_X), then (in the process grid) the process row containing the first row of the submatrix A does not contain the first row of the submatrix X; that is, iarow <> ixrow, where:

iarow = mod((((ia-1)/MB_A)+RSRC_A), p)
ixrow = mod((((ix-1)/MB_X)+RSRC_X), p)
LLD_A < max(1, LOCp(M_A))
LLD_X < max(1, LOCp(M_X))

Example 1

This example computes A = alphaxx^T+A 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)
 
            UPLO  N   ALPHA   X  IX  JX   DESC_X  INCX  A  IA  JA   DESC_A
             |    |     |     |   |   |     |      |    |   |   |     |
CALL PDSYR( 'L' , 9 , 1.0D0 , X , 1 , 1 , DESC_X , 1  , A , 1 , 1 , DESC_A)

	Desc_A	Desc_X
DTYPE_	1	1
CTXT_	`icontxt`^(IOBGC9)	`icontxt`^(IOBGC9)
M_	9	9
N_	9	1
MB_	4	4
NB_	4	1
RSRC_	0	0
CSRC_	0	0
LLD_	See below^(EPSSLA9)	See below^(EPSSLA9)
Notes: `icontxt` is the output of the BLACS_GRIDINIT call. Each process should set the LLD_ as follows: LLD_A = MAX(1,NUMROC(M_A, MB_A, MYROW, RSRC_A, NPROW)) LLD_X = MAX(1,NUMROC(M_X, MB_X, MYROW, RSRC_X, NPROW)) In this example, LLD_A = 5 on P₀₀ and P₀₁, LLD_A = 4 on P₁₀ and P₁₁, LLD_X = 5 on P₀₀, and LLD_X = 4 on P₁₀.

Global real symmetric matrix A of order 9 with block size 4 × 4:

B,D               0                           1                  2
     *                                                               *
     |   1.0    .     .     .   |     .     .     .     .   |     .  |
     |   2.0  12.0    .     .   |     .     .     .     .   |     .  |
 0   |   3.0  13.0  23.0    .   |     .     .     .     .   |     .  |
     |   4.0  14.0  24.0  34.0  |     .     .     .     .   |     .  |
     | -------------------------|---------------------------|------- |
     |   5.0  15.0  25.0  35.0  |   45.0    .     .     .   |     .  |
     |   6.0  16.0  26.0  36.0  |   46.0  56.0    .     .   |     .  |
 1   |   7.0  17.0  27.0  37.0  |   47.0  57.0  67.0    .   |     .  |
     |   8.0  18.0  28.0  38.0  |   48.0  58.0  68.0  78.0  |     .  |
     | -------------------------|---------------------------|------- |
 2   |   9.0  19.0  29.0  39.0  |   49.0  59.0  69.0  79.0  |   89.0 |
     *                                                               *

The following is the 2 × 2 process grid:

B,D  |  0 2  | 1 
-----|-------|-----
0    |   P₀₀   |  P₀₁
2    |       |
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for A:

p,q  |               0                |             1
-----|--------------------------------|--------------------------
     |   1.0    .     .     .     .   |     .     .     .     .
     |   2.0  12.0    .     .     .   |     .     .     .     .
 0   |   3.0  13.0  23.0    .     .   |     .     .     .     .
     |   4.0  14.0  24.0  34.0    .   |     .     .     .     .
     |   9.0  19.0  29.0  39.0  89.0  |   49.0  59.0  69.0  79.0
-----|--------------------------------|--------------------------
     |   5.0  15.0  25.0  35.0    .   |   45.0    .     .     .
     |   6.0  16.0  26.0  36.0    .   |   46.0  56.0    .     .
 1   |   7.0  17.0  27.0  37.0    .   |   47.0  57.0  67.0    .
     |   8.0  18.0  28.0  38.0    .   |   48.0  58.0  68.0  78.0

Global vector x of size 9 × 1 with block size 4:

B,D     0
     *      *
     |  1.0 |
     |  1.0 |
 0   |  1.0 |
     |  1.0 |
     | ---- |
     |  1.0 |
     |  1.0 |
 1   |  1.0 |
     |  1.0 |
     | ---- |
 2   |  1.0 |
     *      *

The following is the 2 × 2 process grid:

B,D  |   0   |-- 
-----|-------|-----
0    |   P₀₀   |  P₀₁
2    |       |
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for x:

p,q  |  0
-----|------
     |  1.0
     |  1.0
 0   |  1.0
     |  1.0
     |  1.0
-----|------
     |  1.0
     |  1.0
 1   |  1.0
     |  1.0

Output:

Global real symmetric matrix A of order 9 with block size 4 × 4:

B,D               0                           1                  2
     *                                                               *
     |   2.0    .     .     .   |     .     .     .     .   |     .  |
     |   3.0  13.0    .     .   |     .     .     .     .   |     .  |
 0   |   4.0  14.0  24.0    .   |     .     .     .     .   |     .  |
     |   5.0  15.0  25.0  35.0  |     .     .     .     .   |     .  |
     | -------------------------|---------------------------|------- |
     |   6.0  16.0  26.0  36.0  |   46.0    .     .     .   |     .  |
     |   7.0  17.0  27.0  37.0  |   47.0  57.0    .     .   |     .  |
 1   |   8.0  18.0  28.0  38.0  |   48.0  58.0  68.0    .   |     .  |
     |   9.0  19.0  29.0  39.0  |   49.0  59.0  69.0  79.0  |     .  |
     | -------------------------|---------------------------|------- |
 2   |  10.0  20.0  30.0  40.0  |   50.0  60.0  70.0  80.0  |   90.0 |
     *                                                               *

The following is the 2 × 2 process grid:

B,D  |  0 2  | 1 
-----|-------|-----
0    |   P₀₀   |  P₀₁
2    |       |
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for A:

p,q  |               0                |             1
-----|--------------------------------|--------------------------
     |   2.0    .     .     .     .   |     .     .     .     .
     |   3.0  13.0    .     .     .   |     .     .     .     .
 0   |   4.0  14.0  24.0    .     .   |     .     .     .     .
     |   5.0  15.0  25.0  35.0    .   |     .     .     .     .
     |  10.0  20.0  30.0  40.0  90.0  |   50.0  60.0  70.0  80.0
-----|--------------------------------|--------------------------
     |   6.0  16.0  26.0  36.0    .   |   46.0    .     .     .
     |   7.0  17.0  27.0  37.0    .   |   47.0  57.0    .     .
 1   |   8.0  18.0  28.0  38.0    .   |   48.0  58.0  68.0    .
     |   9.0  19.0  29.0  39.0    .   |   49.0  59.0  69.0  79.0

Example 2

This example computes A = alphaxx^H+A using a 2 × 2 process grid.

Note:: The imaginary parts of the diagonal elements of a complex Hermitian matrix are assumed to be zero, so you do not have to set these values. On output, they are set to zero except when N is zero or alpha is zero.

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)
 
            UPLO  N   ALPHA   X  IX  JX   DESC_X  INCX  A  IA  JA   DESC_A
             |    |     |     |   |   |     |      |    |   |   |     |
CALL PZHER( 'L' , 3 , 1.0D0 , X , 1 , 1 , DESC_X , 1  , A , 1 , 1 , DESC_A)

	Desc_A	Desc_X
DTYPE_	1	1
CTXT_	`icontxt`^(IOBG10)	`icontxt`^(IOBG10)
M_	3	3
N_	3	1
MB_	2	2
NB_	2	1
RSRC_	0	0
CSRC_	0	0
LLD_	See below^(EPSSL10)	See below^(EPSSL10)
Notes: `icontxt` is the output of the BLACS_GRIDINIT call. Each process should set the LLD_ as follows: LLD_A = MAX(1,NUMROC(M_A, MB_A, MYROW, RSRC_A, NPROW)) LLD_X = MAX(1,NUMROC(M_X, MB_X, MYROW, RSRC_X, NPROW)) In this example, LLD_A = 2 on P₀₀ and P₀₁, LLD_A = 1 on P₁₀ and P₁₁, LLD_X = 2 on P₀₀, and LLD_X = 1 on P₁₀.

Global complex Hermitian matrix A of order 3 with block size 2 × 2:

B,D                0                   1
     *                                        *
     |  ( 1.0, 0.0)      .      |      .      |
 0   |  ( 3.0,-5.0) ( 7.0, 0.0) |      .      |
     | -------------------------|------------ |
 1   |  ( 2.0, 3.0) ( 4.0, 8.0) | ( 6.0, 0.0) |
     *                                        *

The following is the 2 × 2 process grid:

B,D  |  0 2  | 1 
-----|-------|-----
0    |   P₀₀   |  P₀₁
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for A:

p,q  |            0            |            1         
-----|-------------------------|--------------------------
     | ( 1.0,  . )      .      |            .       
 0   | ( 3.0,-5.0) ( 7.0,  . ) |            .      
-----|-------------------------|--------------------------
 1   | ( 2.0, 3.0) ( 4.0, 8.0) | ( 6.0,  . )      .

Global vector x of size 3 × 1 with block size 2:

B,D     0
     *           *
     | (1.0,2.0) |
 0   | (4.0,0.0) |
     | --------- |
 1   | (3.0,4.0) |
     *           *

The following is the 2 × 2 process grid:

B,D  |   0   |-- 
-----|-------|-----
0    |   P₀₀   |  P₀₁
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for x:

p,q  |     0
-----|-----------
     | (1.0,2.0) 
 0   | (4.0,0.0) 
-----|----------- 
 1   | (3.0,4.0)

Output:

Global complex Hermitian matrix A of order 3 with block size 2 × 2:

B,D                0                   1
     *                                        *
     | ( 6.0,  0.0)      .      |      .      |
 0   | ( 7.0,-13.0) (23.0, 0.0) |      .      |           
     | -------------------------|-------------|
 1   | (13.0,  1.0) (16.0,24.0) | (31.0, 0.0) |         
     *                                        *

The following is the 2 × 2 process grid:

B,D  |  0 2  | 1 
-----|-------|-----
0    |   P₀₀   |  P₀₁
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for A:

p,q  |             0            |      1
-----|--------------------------|-------------
     | ( 6.0,  0.0)      .      |      .
 0   | ( 7.0,-13.0) (23.0, 0.0) |      .
-----|--------------------------|-------------
 1   | (13.0,  1.0) (16.0,24.0) | (31.0, 0.0)

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

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

PDSYR and PZHER--Rank-One Update of a Real Symmetric or a Complex Hermitian Matrix

Syntax

On Entry

On Return

Notes and Coding Rules

Error Conditions

Computational Errors

Resource Errors

Input-Argument and Miscellaneous Errors

Example 1

Call Statements and Input

Example 2

Call Statements and Input