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

SGTHR, DGTHR, CGTHR, and ZGTHR--Gather Specified Elements of a Sparse Vector Y in Full-Vector Storage Mode into a Sparse Vector X in Compressed-Vector Storage Mode

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

Table 58. 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 58.

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.

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

On Return

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 58.

Notes

1. Vectors x and y must have no common elements; otherwise, results are unpredictable. See Concepts.
2. For a description of how sparse vectors are stored, see Sparse Vector.

Function

The copy is expressed as follows:

x_i <-- y_INDX(i)    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 copy is performed.

Error Conditions

Computational Errors

None

Input-Argument Errors

nz < 0

Example 1

This example shows how to use SGTHR 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 SGTHR( 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

X        =  (6.0, 4.0, 7.0, -2.0, 9.0)

Example 2

This example shows how to use SGTHR 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 SGTHR( 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

X        =  (7.0, 4.0, 6.0, 0.0, -2.0)

Example 3

This example shows how to use CGTHR 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 CGTHR( 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

X        =  ((9.0, 0.0), (6.0, 5.0), (15.0, 4.0))