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

SGTHRZ, DGTHRZ, CGTHRZ, and ZGTHRZ--Gather Specified Elements of a Sparse Vector Y in Full-Vector Mode into a Sparse Vector X in Compressed-Vector Mode, and Zero the Same Specified Elements of Y

These subprograms gather specified elements of sparse vector y, stored in full-vector storage mode, into sparse vector x, stored in compressed-vector storage mode, and zero the same specified elements of vector y.

Table 59. Data Types

Syntax

On Entry

nz

is the number of elements in sparse vector x, stored in compressed-vector storage mode. Specified as: a fullword integer; nz >= 0.

y

is the sparse vector y, stored in full-vector storage mode, of (at least) length max(INDX(i)) for i = 1, nz, from which nz elements are copied from positions indicated by the indices array INDX.

Specified as: a one-dimensional array of (at least) length max(INDX(i)) for i = 1, nz, containing numbers of the data type indicated in Table 59.

x

See On Return.

indx

is the array, referred to as INDX, containing the nz indices that indicate the positions of the elements of the sparse vector x when in full-vector storage mode. They also indicate the positions in vector y from which elements are copied then set to zero.

Specified as: a one-dimensional array of (at least) length nz, containing fullword integers.

On Return

y

is the sparse vector y, stored in full-vector storage mode, of (at least) length max(INDX(i)) for i = 1, nz, whose elements are set to zero at positions indicated by the indices array INDX.

Returned as: a one-dimensional array, containing numbers of the data type indicated in Table 59.

x

is the sparse vector x, containing nz elements stored in compressed-vector storage mode in an array, referred to as X, into which are copied the elements of vector y from positions indicated by the indices array INDX.

Returned as: a one-dimensional array of (at least) length nz, containing numbers of the data type indicated in Table 59.

Notes

1. Each value specified in array INDX must be unique; otherwise, results are unpredictable.
2. Vectors x and y must have no common elements; otherwise, results are unpredictable. See Concepts.
3. For a description of how sparse vectors are stored, see Sparse Vector.

Function

The copy is expressed as follows:

x_i <-- y_INDX(i)

y_INDX(i)<--0.0    (for SGTHRZ and DGTHRZ)

y_INDX(i)<--(0.0,0.0)    (for CGTHRZ and ZGTHRZ)

   for i = 1,nz

where:

x is a sparse vector, stored in compressed-vector storage mode.

INDX is the indices array for sparse vector x.

y is a sparse vector, stored in full-vector storage mode.

See reference [29]. If nz is 0, no computation is performed.

Error Conditions

Computational Errors

None

Input-Argument Errors

nz < 0

Example 1

This example shows how to use SGTHRZ to copy specified elements of a vector y into a sparse vector x of length 5, where the elements of array INDX are in ascending order.

Call Statement and Input

             NZ  Y   X   INDX
             |   |   |    |
CALL SGTHRZ( 5 , Y , X , INDX )
 
Y        =  (6.0, 2.0, 4.0, 7.0, 6.0, 10.0, -2.0, 8.0, 9.0, 0.0)
INDX     =  (1, 3, 4, 7, 9)

Output

Y        =  (0.0, 2.0, 0.0, 0.0, 6.0, 10.0, 0.0, 8.0, 0.0, 0.0)
X        =  (6.0, 4.0, 7.0, -2.0, 9.0)

Example 2

This example shows how to use SGTHRZ to copy specified elements of a vector y into a sparse vector x of length 5, where the elements of array INDX are in random order. (Note that the element 0.0 occurs in output vector x. This does not produce an error.)

Call Statement and Input

             NZ  Y   X   INDX
             |   |   |    |
CALL SGTHRZ( 5 , Y , X , INDX )
 
Y        =  (6.0, 2.0, 4.0, 7.0, 6.0, 10.0, -2.0, 8.0, 9.0, 0.0)
INDX     =  (4, 3, 1, 10, 7)

Output

Y        =  (0.0, 2.0, 0.0, 0.0, 6.0, 10.0, 0.0, 8.0, 9.0, 0.0)
X        =  (7.0, 4.0, 6.0, 0.0, -2.0)

Example 3

This example shows how to use CGTHRZ to copy specified elements of a vector y into a sparse vector x of length 3, where the elements of array INDX are in random order.

Call Statement and Input

             NZ  Y   X   INDX
             |   |   |    |
CALL CGTHRZ( 3 , Y , X , INDX )
 
Y        =  ((6.0, 5.0), (-2.0, 3.0), (15.0, 4.0), (9.0, 0.0))
INDX     =  (4, 1, 3)

Output

Y        =  ((0.0, 0.0), (-2.0, 3.0), (0.0, 0.0), (0.0, 0.0))
X        =  ((9.0, 0.0), (6.0, 5.0), (15.0, 4.0))