Guide and Reference

Performance and Accuracy Considerations

1. In ESSL, the SSCAL and DSCAL subroutines provide the fastest way to zero out contiguous (stride 1) arrays, by specifying incx = 1 and alpha = 0.

2. Where possible, use the matrix-vector linear algebra subprograms, rather than the vector-scalar, to optimize performance. Because data is presented in matrices rather than vectors, multiple operations can be performed by a single ESSL subprogram.

3. Where possible, use subprograms that do multiple computations, such as SNDOT and SNAXPY, rather than individual computations, such as SDOT and SAXPY. You get better performance.

4. Many of the short-precision subprograms provide increased accuracy by accumulating results in long precision. This is noted in the functional description of each subprogram.

5. In some of the subprograms, because implementation techniques vary to optimize performance, accuracy of the results may vary for different array sizes. In the subprograms in which this occurs, a general description of the implementation techniques is given in the functional description for each subprogram.

6. To select the sparse matrix subroutine that gives you the best performance, you must consider the layout of the data in your matrix. From this, you can determine the most efficient storage mode for your sparse matrix. ESSL provides two versions of each of its sparse matrix-vector subroutines that you can use. One operates on sparse matrices stored in compressed-matrix storage mode, and the other operates on sparse matrices stored in compressed-diagonal storage mode. These two storage modes are described in "Sparse Matrix".

   Compressed-matrix storage mode is generally applicable. It should be used when each row of the matrix contains approximately the same number of nonzero elements. However, if the matrix has a special form--that is, where the nonzero elements are concentrated along a few diagonals--compressed-diagonal storage mode gives improved performance.

7. There are some ESSL-specific rules that apply to the results of computations on the workstation processors using the ANSI/IEEE standards. For details, see "What Data Type Standards Are Used by ESSL, and What Exceptions Should You Know About?".

Vector-Scalar Subprograms

This section contains the vector-scalar subprogram descriptions.

ISAMAX, IDAMAX, ICAMAX, and IZAMAX--Position of the First or Last Occurrence of the Vector Element Having the Largest Magnitude

ISAMAX and IDAMAX find the position i of the first or last occurrence of a vector element having the maximum absolute value. ICAMAX and IZAMAX find the position i of the first or last occurrence of a vector element having the largest sum of the absolute values of the real and imaginary parts of the vector elements.

You get the position of the first or last occurrence of an element by specifying positive or negative stride, respectively, for vector x. Regardless of the stride, the position i is always relative to the location specified in the calling sequence for vector x (in argument x).

Table 36. Data Types

x	Subprogram
Short-precision real	ISAMAX
Long-precision real	IDAMAX
Short-precision complex	ICAMAX
Long-precision complex	IZAMAX

Syntax

On Entry

n

is the number of elements in vector x. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 36.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

On Return

Function value

 

is the position i of the element in the array, where:

If incx >= 0, i is the position of the first occurrence.

If incx < 0, i is the position of the last occurrence.

Returned as: a fullword integer; 0 <= i <= n.

Note

Declare the ISAMAX, IDAMAX, ICAMAX, and IZAMAX functions in your program as returning a fullword integer value.

Function

ISAMAX and IDAMAX find the first element x_k, where k is defined as the smallest index k, such that:

|x_k| = max{|x_j| for j = 1, n}

ICAMAX and IZAMAX find the first element x_k, where k is defined as the smallest index k, such that:

|a_k|+|b_k| = max{|a_j|+|b_j| for j = 1, n}

where x_k = (a_k, b_k)

By specifying a positive or negative stride for vector x, the first or last occurrence, respectively, is found in the array. The position i, returned as the value of the function, is always figured relative to the location specified in the calling sequence for vector x (in argument x). Therefore, depending on the stride specified for incx, i has the following values:

For incx >= 0, i = k

For incx < 0, i = n-k+1

See reference [73]. The result is returned as a function value. If n is 0, then 0 is returned as the value of the function.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows a vector, x, with a stride of 1.

Function Reference and Input

               N   X   INCX
               |   |    |
IMAX = ISAMAX( 9 , X ,  1   )
 
X        =  (1.0, 2.0, 7.0, -8.0, -5.0, -10.0, -9.0, 10.0, 6.0)

Output

IMAX     =  6

Example 2

This example shows a vector, x, with a stride greater than 1.

Function Reference and Input

               N   X   INCX
               |   |    |
IMAX = ISAMAX( 5 , X ,  2   )
 
X        =  (1.0, . , 7.0, . , -5.0, . , -9.0, . , 6.0)

Output

IMAX     =  4

Example 3

This example shows a vector, x, with a stride of 0.

Function Reference and Input

               N   X   INCX
               |   |    |
IMAX = ISAMAX( 9 , X ,  0   )
 
X        =  (1.0, . , . , . , . , . , . , . , .)

Output

IMAX     =  1

Example 4

This example shows a vector, x, with a negative stride. Processing begins at element X(15), which is 2.0.

Function Reference and Input

               N   X   INCX
               |   |    |
IMAX = ISAMAX( 8 , X , -2   )
 
X        =  (3.0, . , 5.0, . , -8.0, . , 6.0, . , 8.0, . ,
             4.0, . , 8.0, . , 2.0)

Output

IMAX     =  7

Example 5

This example shows a vector, x, containing complex numbers and having a stride of 1.

Function Reference and Input

               N   X   INCX
               |   |    |
IMAX = ICAMAX( 5 , X ,  1   )
 
X        =  ((9.0 , 2.0) , (7.0 , -8.0) , (-5.0 , -10.0) , (-4.0 , 10.0),
             (6.0 , 3.0))

Output

IMAX     =  2

ISAMIN and IDAMIN--Position of the First or Last Occurrence of the Vector Element Having Minimum Absolute Value

These subprograms find the position i of the first or last occurrence of a vector element having the minimum absolute value.

You get the position of the first or last occurrence of an element by specifying positive or negative stride, respectively, for vector x. Regardless of the stride, the position i is always relative to the location specified in the calling sequence for vector x (in argument x).

Table 37. Data Types

x	Subprogram
Short-precision real	ISAMIN
Long-precision real	IDAMIN

Syntax

On Entry

n

is the number of elements in vector x. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 37.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

On Return

Function value

 

is the position i of the element in the array, where:

If incx >= 0, i is the position of the first occurrence.

If incx < 0, i is the position of the last occurrence.

Returned as: a fullword integer; 0 <= i <= n.

Note

Declare the ISAMIN and IDAMIN functions in your program as returning a fullword integer value.

Function

These subprograms find the first element x_k, where k is defined as the smallest index k, such that:

|x_k| = min{|x_j| for j = 1, n}

By specifying a positive or negative stride for vector x, the first or last occurrence, respectively, is found in the array. The position i, returned as the value of the function, is always figured relative to the location specified in the calling sequence for vector x (in argument x). Therefore, depending on the stride specified for incx, i has the following values:

For incx >= 0, i = k

For incx < 0, i = n-k+1

See reference [73]. The result is returned as a function value. If n is 0, then 0 is returned as the value of the function.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows a vector, x, with a stride of 1.

Function Reference and Input

               N   X   INCX
               |   |    |
IMIN = ISAMIN( 6 , X ,  1  )
 
X        =  (3.0, 4.0, 1.0, 8.0, 1.0, 3.0)

Output

IMIN     =  3

Example 2

This example shows a vector, x, with a stride greater than 1.

Function Reference and Input

               N   X   INCX
               |   |    |
IMIN = ISAMIN( 4 , X ,  2  )
 
X        =  (-3.0, . , -9.0, . , -8.0, . , 3.0)

Output

IMIN     =  1

Example 3

This example shows a vector, x, with a positive stride and two elements with the minimum absolute value. The position of the first occurrence is returned.

Function Reference and Input

               N   X   INCX
               |   |    |
IMIN = ISAMIN( 4 , X ,  2  )
 
X        =  (2.0, . , -1.0, . , 4.0, . , 1.0)

Output

IMIN     =  2

Example 4

This example shows a vector, x, with a negative stride and two elements with the minimum absolute value. The position of the last occurrence is returned. Processing begins at element X(7), which is 1.0.

Function Reference and Input

               N   X   INCX
               |   |    |
IMIN = ISAMIN( 4 , X , -2  )
 
X        =  (2.0, . , -1.0, . , 4.0, . , 1.0)

Output

IMIN     =  4

ISMAX and IDMAX--Position of the First or Last Occurrence of the Vector Element Having the Maximum Value

These subprograms find the position i of the first or last occurrence of a vector element having the maximum value.

You get the position of the first or last occurrence of an element by specifying positive or negative stride, respectively, for vector x. Regardless of the stride, the position i is always relative to the location specified in the calling sequence for vector x (in argument x).

Table 38. Data Types

x	Subprogram
Short-precision real	ISMAX
Long-precision real	IDMAX

Syntax

On Entry

n

is the number of elements in vector x. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 38.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

On Return

Function value

 

is the position i of the element in the array, where:

If incx >= 0, i is the position of the first occurrence.

If incx < 0, i is the position of the last occurrence.

Returned as: a fullword integer; 0 <= i <= n.

Note

Declare the ISMAX and IDMAX functions in your program as returning a fullword integer value.

Function

These subprograms find the first element x_k, where k is defined as the smallest index k, such that:

x_k = max{x_j for j = 1, n}

By specifying a positive or negative stride for vector x, the first or last occurrence, respectively, is found in the array. The position i, returned as the value of the function, is always figured relative to the location specified in the calling sequence for vector x (in argument x). Therefore, depending on the stride specified for incx, i has the following values:

For incx >= 0, i = k

For incx < 0, i = n-k+1

See reference [73]. The result is returned as a function value. If n is 0, then 0 is returned as the value of the function.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows a vector, x, with a stride of 1.

Function Reference and Input

              N   X  INCX
              |   |   |
IMAX = ISMAX( 6 , X , 1  )
 
X        =  (3.0, 4.0, 1.0, 8.0, 1.0, 8.0)

Output

IMAX     =  4

Example 2

This example shows a vector, x, with a stride greater than 1.

Function Reference and Input

              N   X  INCX
              |   |   |
IMAX = ISMAX( 4 , X , 2  )
 
X        =  (-3.0, . , 9.0, . , -8.0, . , 3.0)

Output

IMAX     =  2

Example 3

This example shows a vector, x, with a positive stride and two elements with the maximum value. The position of the first occurrence is returned.

Function Reference and Input

              N   X  INCX
              |   |   |
IMAX = ISMAX( 4 , X , 2  )
 
X        =  (2.0, . , 4.0, . , 4.0, . , 1.0)

Output

IMAX     =  2

Example 4

This example shows a vector, x, with a negative stride and two elements with the maximum value. The position of the last occurrence is returned. Processing begins at element X(7), which is 1.0.

Function Reference and Input

              N   X   INCX
              |   |    |
IMAX = ISMAX( 4 , X , -2  )
 
X        =  (2.0, . , 4.0, . , 4.0, . , 1.0)

Output

IMAX     =  3

ISMIN and IDMIN--Position of the First or Last Occurrence of the Vector Element Having Minimum Value

These subprograms find the position i of the first or last occurrence of a vector element having the minimum value.

You get the position of the first or last occurrence of an element by specifying positive or negative stride, respectively, for vector x. Regardless of the stride, the position i is always relative to the location specified in the calling sequence for vector x (in argument x).

Table 39. Data Types

x	Subprogram
Short-precision real	ISMIN
Long-precision real	IDMIN

Syntax

On Entry

n

is the number of elements in vector x. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 39.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

On Return

Function value

 

is the position i of the element in the array, where:

If incx >= 0, i is the position of the first occurrence.

If incx < 0, i is the position of the last occurrence.

Returned as: a fullword integer; 0 <= i <= n.

Note

Declare the ISMIN and IDMIN functions in your program as returning a fullword integer value.

Function

These subprograms find the first element x_k, where k is defined as the smallest index k, such that:

x_k = min{x_j for j = 1, n}

By specifying a positive or negative stride for vector x, the first or last occurrence, respectively, is found in the array. The position i, returned as the value of the function, is always figured relative to the location specified in the calling sequence for vector x (in argument x). Therefore, depending on the stride specified for incx, i has the following values:

For incx >= 0, i = k

For incx < 0, i = n-k+1

See reference [73]. The result is returned as a function value. If n is 0, then 0 is returned as the value of the function.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows a vector, x, with a stride of 1.

Function Reference and Input

              N   X  INCX
              |   |   |
IMIN = ISMIN( 6 , X , 1  )
 
X        =  (3.0, 4.0, 1.0, 8.0, 1.0, 3.0)

Output

IMIN     =  3

Example 2

This example shows a vector, x, with a stride greater than 1.

Function Reference and Input

              N   X  INCX
              |   |   |
IMIN = ISMIN( 4 , X , 2  )
 
X        =  (-3.0, . , -9.0, . , -8.0, . , 3.0)

Output

IMIN     =  2

Example 3

This example shows a vector, x, with a positive stride and two elements with the minimum value. The position of the first occurrence is returned. Processing begins at element X(7), which is 1.0.

Function Reference and Input

              N   X  INCX
              |   |   |
IMIN = ISMIN( 4 , X , 2  )
 
X        =  (2.0, . , 1.0, . , 4.0, . , 1.0)

Output

IMIN     =  2

Example 4

This example shows a vector, x, with a negative stride and two elements with the minimum value. The position of the last occurrence is returned. Processing begins at element X(7), which is 1.0.

Function Reference and Input

              N   X   INCX
              |   |    |
IMIN = ISMIN( 4 , X , -2  )
 
X        =  (2.0, . , 1.0, . , 4.0, . , 1.0)

Output

IMIN     =  4

SASUM, DASUM, SCASUM, and DZASUM--Sum of the Magnitudes of the Elements in a Vector

SASUM and DASUM compute the sum of the absolute values of the elements in vector x. SCASUM and DZASUM compute the sum of the absolute values of the real and imaginary parts of the elements in vector x.

Table 40. Data Types

x	Result	Subprogram
Short-precision real	Short-precision real	SASUM
Long-precision real	Long-precision real	DASUM
Short-precision complex	Short-precision real	SCASUM
Long-precision complex	Long-precision real	DZASUM

Syntax

On Entry

n

is the number of elements in vector x. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 40.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

On Return

Function value

is the result of the summation. Returned as: a number of the data type indicated in Table 40.

Note

Declare this function in your program as returning a value of the type indicated in Table 40.

Function

SASUM and DASUM compute the sum of the absolute values of the elements of x, which is expressed as follows:

SCASUM and DZASUM compute the sum of the absolute values of the real and imaginary parts of the elements of x, which is expressed as follows:

See reference [73]. The result is returned as a function value. If n is 0, then 0.0 is returned as the value of the function. For SASUM and SCASUM, intermediate results are accumulated in long precision.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows a vector, x, with a stride of 1.

Function Reference and Input

              N   X  INCX
              |   |   |
SUMM = SASUM( 7 , X , 1  )
 
X        =  (1.0, -3.0, -6.0, 7.0, 5.0, 2.0, -4.0)

Output

SUMM     =  28.0

Example 2

This example shows a vector, x, with a stride greater than 1.

Function Reference and Input

              N   X  INCX
              |   |   |
SUMM = SASUM( 4 , X , 2  )
 
X        =  (1.0, . , -6.0, . , 5.0, . , -4.0)

Output

SUMM     =  16.0

Example 3

This example shows a vector, x, with negative stride. Processing begins at element X(7), which is -4.0.

Function Reference and Input

              N   X   INCX
              |   |    |
SUMM = SASUM( 4 , X , -2  )
 
X        =  (1.0, . , -6.0, . , 5.0, . , -4.0)

Output

SUMM     =  16.0

Example 4

This example shows a vector, x, with a stride of 0. The result in SUMM is nx₁.

Function Reference and Input

              N   X  INCX
              |   |   |
SUMM = SASUM( 7 , X , 0  )
 
X        =  (-2.0, . , . , . , . , . , .)

Output

SUMM     =  14.0

Example 5

This example shows a vector, x, containing complex numbers and having a stride of 1.

Function Reference and Input

               N   X  INCX
               |   |   |
SUMM = SCASUM( 5 , X , 1  )
 
X        =  ((1.0, 2.0), (-3.0, 4.0), (5.0, -6.0 ), (-7.0, -8.0),
             (9.0, 10.0))

Output

SUMM     =  55.0

SAXPY, DAXPY, CAXPY, and ZAXPY--Multiply a Vector X by a Scalar, Add to a Vector Y, and Store in the Vector Y

These subprograms perform the following computation, using the scalar alpha and vectors x and y:

y <-- y+alphax

Table 41. Data Types

alpha, x, y	Subprogram
Short-precision real	SAXPY
Long-precision real	DAXPY
Short-precision complex	CAXPY
Long-precision complex	ZAXPY

Syntax

On Entry

n

is the number of elements in vectors x and y. Specified as: a fullword integer; n >= 0.

alpha

is the scalar alpha. Specified as: a number of the data type indicated in Table 41.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 41.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

is the vector y of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 41.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

On Return

y

is the vector y, containing the results of the computation y+alphax. Returned as: a one-dimensional array, containing numbers of the data type indicated in Table 41.

Notes

1. If you specify the same vector for x and y, incx and incy must be equal; otherwise, results are unpredictable.

2. If you specify different vectors for x and y, they must have no common elements; otherwise, results are unpredictable. See "Concepts".

Function

The computation is expressed as follows:

See reference [73]. If alpha or n is zero, no computation is performed. For CAXPY, intermediate results are accumulated in long precision.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows vectors x and y with positive strides.

Call Statement and Input

            N  ALPHA  X  INCX  Y  INCY
            |    |    |   |    |   |
CALL SAXPY( 5 , 2.0 , X , 1  , Y , 2  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (1.0, . , 1.0, . , 1.0, . , 1.0, . , 1.0)

Output

Y        =  (3.0, . , 5.0, . , 7.0, . , 9.0, . , 11.0)

Example 2

This example shows vectors x and y having strides of opposite signs. For y, which has negative stride, processing begins at element Y(5), which is 1.0.

Call Statement and Input

            N  ALPHA  X  INCX  Y   INCY
            |    |    |   |    |    |
CALL SAXPY( 5 , 2.0 , X , 1  , Y , -1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Y        =  (15.0, 12.0, 9.0, 6.0, 3.0)

Example 3

This example shows a vector, x, with 0 stride. Vector x is treated like a vector of length n, all of whose elements are the same as the single element in x.

Call Statement and Input

            N  ALPHA  X  INCX  Y  INCY
            |    |    |   |    |   |
CALL SAXPY( 5 , 2.0 , X , 0  , Y , 1  )
 
X        =  (1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Y        =  (7.0, 6.0, 5.0, 4.0, 3.0)

Example 4

This example shows how SAXPY can be used to compute a scalar value. In this case, vectors x and y contain scalar values and the strides for both vectors are 0. The number of elements to be processed, n, is 1.

Call Statement and Input

            N  ALPHA  X  INCX  Y  INCY
            |    |    |   |    |   |
CALL SAXPY( 1 , 2.0 , X , 0  , Y , 0  )
 
X        =  (1.0)
Y        =  (5.0)

Output

Y        =  (7.0)

Example 5

This example shows how to use CAXPY, where vectors x and y contain complex numbers. In this case, vectors x and y have positive strides.

Call Statement and Input

            N  ALPHA  X  INCX  Y  INCY
            |    |    |   |    |   |
CALL CAXPY( 3 ,ALPHA, X , 1  , Y , 2  )
 
ALPHA    =  (2.0, 3.0)
X        =  ((1.0, 2.0), (2.0, 0.0), (3.0, 5.0))
Y        =  ((1.0, 1.0 ), . , (0.0, 2.0), . , (5.0, 4.0))

Output

Y        =  ((-3.0, 8.0), . , (4.0, 8.0), . , (-4.0, 23.0))

SCOPY, DCOPY, CCOPY, and ZCOPY--Copy a Vector

These subprograms copy vector x to another vector, y:

y <-- x

Table 42. Data Types

x, y	Subprogram
Short-precision real	SCOPY
Long-precision real	DCOPY
Short-precision complex	CCOPY
Long-precision complex	ZCOPY

Syntax

On Entry

n

is the number of elements in vectors x and y. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 42.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

See 'On Return'.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

On Return

y

is the vector y of length n. Returned as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 42.

Notes

1. If you specify the same vector for x and y, incx and incy must be equal; otherwise, results are unpredictable.

2. If you specify different vectors for x and y, they must have no common elements; otherwise, results are unpredictable. See "Concepts".

Function

The copy is expressed as follows:

See reference [73]. If n is 0, no copy is performed.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows input vector x and output vector y with positive strides.

Call Statement and Input

            N   X  INCX  Y  INCY
            |   |   |    |   |
CALL SCOPY( 5 , X , 1  , Y , 2  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)

Output

Y        =  (1.0, . , 2.0, . , 3.0, . , 4.0, . , 5.0)

Example 2

This example shows how to obtain a reverse copy of the input vector x by specifying strides with the same absolute value, but with opposite signs, for input vector x and output vector y. For y, which has a negative stride, results are stored beginning at element Y(5).

Call Statement and Input

            N   X  INCX  Y   INCY
            |   |   |    |    |
CALL SCOPY( 5 , X , 1  , Y , -1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)

Output

Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Example 3

This example shows an input vector, x, with 0 stride. Vector x is treated like a vector of length n, all of whose elements are the same as the single element in x. This is a technique for replicating an element of a vector.

Call Statement and Input

            N   X  INCX  Y  INCY
            |   |   |    |   |
CALL SCOPY( 5 , X , 0  , Y , 1  )
 
X        =  (13.0)

Output

Y        =  (13.0, 13.0, 13.0, 13.0, 13.0)

Example 4

This example shows input vector x and output vector y, containing complex numbers and having positive strides.

Call Statement and Input

            N   X  INCX  Y  INCY
            |   |   |    |   |
CALL CCOPY( 4 , X , 1  , Y , 2  )
 
X        =  ((1.0, 1.0), (2.0, 2.0), (3.0, 3.0), (4.0, 4.0))

Output

Y        =  ((1.0, 1.0), . , (2.0, 2.0), . , (3.0, 3.0), . ,
             (4.0, 4.0))

SDOT, DDOT, CDOTU, ZDOTU, CDOTC, and ZDOTC--Dot Product of Two Vectors

SDOT, DDOT, CDOTU, and ZDOTU compute the dot product of vectors x and y:

CDOTC and ZDOTC compute the dot product of the complex conjugate of vector x with vector y:

Table 43. Data Types

x, y, Result	Subprogram
Short-precision real	SDOT
Long-precision real	DDOT
Short-precision complex	CDOTU and CDOTC
Long-precision complex	ZDOTU and ZDOTC

Syntax

On Entry

n

is the number of elements in vectors x and y. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 43.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

is the vector y of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 43.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

On Return

Function value

is the result of the dot product computation. Returned as: a number of the data type indicated in Table 43.

Note

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

Function

SDOT, DDOT, CDOTU, and ZDOTU compute the dot product of the vectors x and y, which is expressed as follows:

CDOTC and ZDOTC compute the dot product of the complex conjugate of vector x with vector y, which is expressed as follows:

See reference [73]. The result is returned as a function value. If n is 0, then zero is returned as the value of the function.

For SDOT, CDOTU, and CDOTC, intermediate results are accumulated in long precision.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows how to compute the dot product of two vectors, x and y, having strides of 1.

Function Reference and Input

             N   X  INCX  Y  INCY
             |   |   |    |   |
DOTT = SDOT( 5 , X , 1  , Y , 1  )
 
X        =  (1.0, 2.0, -3.0, 4.0, 5.0)
Y        =  (9.0, 8.0, 7.0, -6.0, 5.0)

Output

DOTT     =  (9.0 + 16.0 - 21.0 - 24.0 + 25.0) = 5.0

Example 2

This example shows how to compute the dot product of a vector, x, with a stride of 1, and a vector, y, with a stride greater than 1.

Function Reference and Input

             N   X  INCX  Y  INCY
             |   |   |    |   |
DOTT = SDOT( 5 , X , 1  , Y , 2  )
 
X        =  (1.0, 2.0, -3.0, 4.0, 5.0)
Y        =  (9.0, . , 7.0, . , 5.0, . , -3.0, . , 1.0)

Output

DOTT     =  (9.0 + 14.0 - 15.0 - 12.0 + 5.0) = 1.0

Example 3

This example shows how to compute the dot product of a vector, x, with a negative stride, and a vector, y, with a stride greater than 1. For x, processing begins at element X(5), which is 5.0.

Function Reference and Input

             N   X   INCX  Y  INCY
             |   |    |    |   |
DOTT = SDOT( 5 , X , -1  , Y , 2  )
 
X        =  (1.0, 2.0, -3.0, 4.0, 5.0)
Y        =  (9.0, . , 7.0, . , 5.0, . , -3.0, . , 1.0)

Output

DOTT     =  (45.0 + 28.0 - 15.0 - 6.0 + 1.0) = 53.0

Example 4

This example shows how to compute the dot product of a vector, x, with a stride of 0, and a vector, y, with a stride of 1. The result in DOTT is x₁(y₁+...+y_n).

Function Reference and Input

             N   X  INCX  Y  INCY
             |   |   |    |   |
DOTT = SDOT( 5 , X , 0  , Y , 1  )
 
X        =  (1.0, . , . , . , .)
Y        =  (9.0, 8.0, 7.0, -6.0, 5.0)

Output

DOTT     =  (1.0) × (9.0 + 8.0 + 7.0 - 6.0 + 5.0) = 23.0

Example 5

This example shows how to compute the dot product of two vectors, x and y, with strides of 0. The result in DOTT is nx₁y₁.

Function Reference and Input

             N   X  INCX  Y  INCY
             |   |   |    |   |
DOTT = SDOT( 5 , X , 0  , Y , 0  )
 
X        =  (1.0, . , . , . , .)
Y        =  (9.0, . , . , . , .)

Output

DOTT     =  (5) × (1.0) × (9.0) = 45.0

Example 6

This example shows how to compute the dot product of two vectors, x and y, containing complex numbers, where x has a stride of 1, and y has a stride greater than 1.

Function Reference and Input

              N   X  INCX  Y  INCY
              |   |   |    |   |
DOTT = CDOTU( 3 , X , 1  , Y , 2  )
 
X        =  ((1.0, 2.0), (3.0, -4.0), (-5.0, 6.0))
Y        =  ((10.0, 9.0), . , (-6.0, 5.0), . , (2.0, 1.0))

Output

DOTT     =  ((10.0 - 18.0 - 10.0) - (18.0 - 20.0 + 6.0),
             (9.0 + 15.0 - 5.0) + (20.0 + 24.0 + 12.0))
         =  (-22.0, 75.0)

Example 7

This example shows how to compute the dot product of the conjugate of a vector, x, with vector y, both containing complex numbers, where x has a stride of 1, and y has a stride greater than 1.

Function Reference and Input

              N   X  INCX  Y  INCY
              |   |   |    |   |
DOTT = CDOTC( 3 , X , 1  , Y , 2  )
 
X        =  ((1.0, 2.0), (3.0, -4.0), (-5.0, 6.0))
Y        =  ((10.0, 9.0), . , (-6.0, 5.0), . , (2.0, 1.0))

Output

DOTT     =  ((10.0 - 18.0 - 10.0) + (18.0 - 20.0 + 6.0),
             (9.0  +  15.0  -  5.0)  -  (20.0  +  24.0  +  12.0))
         =  (-14.0, -37.0)

SNAXPY and DNAXPY--Compute SAXPY or DAXPY N Times

These subprograms compute SAXPY or DAXPY, respectively, n times:

y_i <-- y_i + alpha_ix_i    for i = 1, n

where each alpha_i is a scalar value, contained in the vector a, and each x_i and y_i are vectors, contained in vectors (or matrices) x and y, respectively. For an explanation of the SAXPY and DAXPY computations, see SAXPY, DAXPY, CAXPY, and ZAXPY--Multiply a Vector X by a Scalar, Add to a Vector Y, and Store in the Vector Y.

Table 44. Data Types

a, x, y	Subprogram
Short-precision real	SNAXPY
Long-precision real	DNAXPY

Syntax

On Entry

n

is the number of SAXPY or DAXPY computations to be performed and the number of elements in vector a. Specified as: a fullword integer; n >= 0.

m

is the number of elements in vectors x_i and y_i for each SAXPY or DAXPY computation. Specified as: a fullword integer; m >= 0.

a

is the vector a of length n, containing the scalar values alpha_i, used in each computation of y_i + alpha_ix_i. Specified as: a one-dimensional array of (at least) length 1+(n-1)|inca|, containing numbers of the data type indicated in Table 44.

inca

is the stride for vector a. Specified as: a fullword integer. It can have any value.

x

is the vector (or matrix) x, containing the x_i vectors of length m, used in the n computations of y_i + alpha_ix_i. Specified as: a one- or two-dimensional array of (at least) length (1+(n-1)(incxo)) + (m-1)|incxi|, containing numbers of the data type indicated in Table 44.

incxi

is the stride for x in the inner loop--that is, the stride identifying the elements in each vector x_i. Specified as: a fullword integer. It can have any value.

incxo

is the stride for x in the outer loop--that is, the stride identifying each vector x_i in x. Specified as: a fullword integer; incxo >= 0.

y

is the vector (or matrix) y, containing the y_i vectors of length m, used in the n computations of y_i + alpha_ix_i. Specified as: a one- or two-dimensional array of (at least) length (1+(n-1)(incyo)) + (m-1)|incyi|, containing numbers of the data type indicated in Table 44.

incyi

is the stride for y in the inner loop--that is, the stride identifying the elements in each vector y_i in y. Specified as: a fullword integer; incyi > 0 or incyi < 0.

incyo

is the stride for y in the outer loop--that is, the stride identifying each vector y_i in y. Specified as: a fullword integer; incyo >= 0.

On Return

y

is the vector (or matrix) y, containing the y_i vectors of length m, which contain the results of the n SAXPY or DAXPY computations, y_i + alpha_ix_i for i = 1, n. Returned as: a one- or two-dimensional array, containing numbers of the data type indicated in Table 44.

Note

Vector y must have no common elements with vector a or vector x; otherwise, results are unpredictable. See "Concepts".

Function

The SAXPY or DAXPY computations:

y <-- y + alphax

are performed n times. This is expressed as follows:

y_i <-- y_i + alpha_ix_i    for i = 1, n

where each alpha_i is a scalar value, contained in the vector a, and each x_i and y_i are vectors, contained in vectors (or matrices) x and y, respectively.

Each computation of SAXPY or DAXPY on page SAXPY, DAXPY, CAXPY, and ZAXPY--Multiply a Vector X by a Scalar, Add to a Vector Y, and Store in the Vector Y uses the length of the x_i and y_i vectors, m, for its input argument, n. It also uses the strides for the inner loop, incxi and incyi, for its parameters incx and incy, respectively. See "Function" for a description of how the computation is done.

The outer loop of the SNAXPY or DNAXPY computation uses the strides of inca, incxo, and incyo to locate the elements in a and vectors in x and y for each i-th computation. These are:

For i = 1, n:

alpha_{((i-1)inca+1)}    for inca >= 0

alpha_{((i-n)inca+1)}    for inca < 0

x_{((i-1)incxo+1)}

y_{((i-1)incyo+1)}

If m or n is 0, no computation is performed.

Error Conditions

Computational Errors

None

Input-Argument Errors

1. n < 0
2. m < 0
3. incxo < 0
4. incyi = 0
5. incyo < 0

Example 1

This example shows vectors, contained in matrices, with the stride of the inner loops incxi and incyi equal to 1.

Call Statement and Input

             N   M   A  INCA  X  INCXI INCXO  Y  INCYI INCYO
             |   |   |   |    |    |     |    |    |     |
CALL SNAXPY( 3 , 4 , A , 1  , X ,  1  , 10  , Y ,  1  ,  5  )
 
A        =  (3.0, 2.0, 4.0)

        *               *
        | 1.0  4.0  3.0 |
        | 2.0  3.0  4.0 |
        | 3.0  2.0  2.0 |
        | 4.0  1.0  1.0 |
X    =  |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        *               *

        *               *
        | 4.0  1.0  3.0 |
        | 3.0  2.0  4.0 |
Y    =  | 2.0  3.0  2.0 |
        | 1.0  4.0  1.0 |
        |  .    .    .  |
        *               *

Output

        *                 *
        |  7.0  9.0  15.0 |
        |  9.0  8.0  20.0 |
Y    =  | 11.0  7.0  10.0 |
        | 13.0  6.0   5.0 |
        |   .    .     .  |
        *                 *

Example 2

This example shows vectors, contained in matrices, with a stride of the inner loop incxi greater than 1.

Call Statement and Input

             N   M   A  INCA  X  INCXI INCXO  Y  INCYI INCYO
             |   |   |   |    |    |     |    |    |     |
CALL SNAXPY( 3 , 4 , A , 1  , X ,  2  , 10  , Y ,  1  ,  5  )
 
A        =  (3.0, 2.0, 4.0)

        *               *
        | 1.0  4.0  3.0 |
        |  .    .    .  |
        | 2.0  3.0  4.0 |
        |  .    .    .  |
X    =  | 3.0  2.0  2.0 |
        |  .    .    .  |
        | 4.0  1.0  1.0 |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        *               *

        *               *
        | 4.0  1.0  3.0 |
        | 3.0  2.0  4.0 |
Y    =  | 2.0  3.0  2.0 |
        | 1.0  4.0  1.0 |
        |  .    .    .  |
        *               *

Output

Y        =(same as output Y in Example 1)

Example 3

This example shows vectors, contained in matrices, with a negative stride, incyi, for the inner loop.

Call Statement and Input

             N   M   A  INCA  X  INCXI INCXO  Y  INCYI INCYO
             |   |   |   |    |    |     |    |    |     |
CALL SNAXPY( 3 , 4 , A , 1  , X ,  1  , 10  , Y , -1  ,  5  )
 
A        =  (3.0, 2.0, 4.0)

        *               *
        | 1.0  4.0  3.0 |
        | 2.0  3.0  4.0 |
        | 3.0  2.0  2.0 |
        | 4.0  1.0  1.0 |
X    =  |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        *               *

        *               *
        | 1.0  4.0  1.0 |
        | 2.0  3.0  2.0 |
Y    =  | 3.0  2.0  4.0 |
        | 4.0  1.0  3.0 |
        |  .    .    .  |
        *               *

Output

        *                 *
        | 13.0  6.0   5.0 |
        | 11.0  7.0  10.0 |
Y    =  |  9.0  8.0  20.0 |
        |  7.0  9.0  15.0 |
        |   .    .     .  |
        *                 *

Example 4

This example shows vectors, contained in matrices, with a negative stride, inca, for vector a. For vector a, processing begins at element A(5), which is 3.0.

Call Statement and Input

             N   M   A   INCA  X  INCXI INCXO  Y  INCYI INCYO
             |   |   |    |    |    |     |    |    |     |
CALL SNAXPY( 3 , 4 , A , -2  , X ,  1  , 10  , Y ,  1  ,  5  )
 
A        =  (4.0, . , 2.0, . , 3.0)

        *               *
        | 1.0  4.0  3.0 |
        | 2.0  3.0  4.0 |
        | 3.0  2.0  2.0 |
        | 4.0  1.0  1.0 |
X    =  |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        *               *

        *               *
        | 4.0  1.0  3.0 |
        | 3.0  2.0  4.0 |
Y    =  | 2.0  3.0  2.0 |
        | 1.0  4.0  1.0 |
        |  .    .    .  |
        *               *

Output

Y        =(same as output Y in Example 1)

SNDOT and DNDOT--Compute Special Dot Products N Times

These subprograms compute one of the following special dot products n times:

si <-- xi * yi	Store positive dot product
si <-- -xi * yi	Store negative dot product
si <-- si+xi * yi	Accumulate positive dot product
si <-- si-xi * yi	Accumulate negative dot product
for i = 1, n

where each s_i is an element in vector s, and each x_i and y_i are vectors contained in vectors (or matrices) x and y, respectively.

Table 45. Data Types

s, x, y	Subprogram
Short-precision real	SNDOT
Long-precision real	DNDOT

Syntax

On Entry

n

is the number of dot product computations to be performed and the number of elements in the vector s. Specified as: a fullword integer; n >= 0.

m

is the number of elements in vectors x_i and y_i for each dot product computation. Specified as: a fullword integer; m >= 0.

s

is the vector s, containing the n scalar values s_i, where: If isw = 1 or 2, s_i is not used in the computation (no input value specified.)

If isw = 3 or 4, s_i is used in the computation (input value specified.)

Specified as: a one-dimensional array of (at least) length 1+(n-1)|incs|, containing numbers of the data type indicated in Table 45.

incs

is the stride for vector s. Specified as: a fullword integer; incs > 0 or incs < 0.

isw

indicates the type of computation to perform, depending on the value specified:

If isw = 1,    s_i <-- x_i * y_i

If isw = 2,    s_i <-- -x_i * y_i

If isw = 3,    s_i <-- s_i + x_i * y_i

If isw = 4,    s_i <-- s_i - x_i * y_i

where i = 1, n

Specified as: a fullword integer. Its value must be 1, 2, 3, or 4.

x

is the vector (or matrix) x, containing the x_i vectors of length m, used in the n dot product computations. Specified as: a one- or two-dimensional array of (at least) length (1+(n-1)(incxo))+(m-1)|incxi|, containing numbers of the data type indicated in Table 45.

incxi

is the stride for x in the inner loop--that is, the stride identifying the elements in each vector x_i. Specified as: a fullword integer. It can have any value.

incxo

is the stride for x in the outer loop--that is, the stride identifying each vector x_i in x. Specified as: a fullword integer; incxo >= 0.

y

is the vector (or matrix) y, containing the y_i vectors of length m, used in the n dot product computations. Specified as: a one- or two-dimensional array of (at least) length (1+(n-1)(incyo)) + (m-1)|incyi|, containing numbers of the data type indicated in Table 45.

incyi

is the stride for y in the inner loop--that is, the stride identifying the elements in each vector y_i. Specified as: a fullword integer. It can have any value.

incyo

is the stride for y in the outer loop--that is, the stride identifying each vector y_i in y. Specified as: a fullword integer; incyo >= 0.

On Return

s

is the vector s of length n, containing the results of the n dot product computations. The type of dot product computation depends of the value specified for isw.

If isw = 1,    s_i <-- x_i * y_i

If isw = 2,    s_i <-- -x_i * y_i

If isw = 3,    s_i <-- s_i + x_i * y_i

If isw = 4,    s_i <-- s_i - x_i * y_i

where i = 1, n

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

Function

The four possible computations that can be performed by these subprograms are:

si <-- xi * yi	Store positive dot product
si <-- -xi * yi	Store negative dot product
si <-- si+xi * yi	Accumulate positive dot product
si <-- si-xi * yi	Accumulate negative dot product
for i = 1, n

where each s_i is a scalar element in the vector s of length n, and each of the n x_i and y_i vectors of length m are contained in vectors (or matrices) x and y, respectively. Each computation uses the dot product, which is expressed:

x_i * y_i = u₁v₁ + u₂v₂ + ... + u_mv_m

where u_i and v_i are elements of x_i and y_i, respectively. To find the elements for the computation, it uses:

• The strides for the inner loops, incxi and incyi, to locate the elements in vectors x_i and y_i, respectively.

• The strides for the outer loops, incs, incxo, and incyo, to locate the element s_i in vector s and the vectors x_i and y_i in vectors (or matrices) x and y, respectively.

If m or n is 0, no computation is performed. For SNDOT, intermediate results are accumulated in long precision.

Error Conditions

Computational Errors

None

Input-Argument Errors

1. n < 0
2. m < 0
3. incs = 0
4. isw < 1 or isw > 4
5. incxo < 0
6. incyo < 0

Example 1

This example shows a store positive dot product computation using vectors with positive strides.

Call Statement and Input

            N   M   S  INCS ISW  X  INCXI INCXO  Y  INCYI INCYO
            |   |   |   |    |   |    |     |    |    |     |
CALL SNDOT( 3 , 4 , S , 1  , 1 , X ,  1  ,  4  , Y ,  1  ,  4  )
 
        *               *
        | 1.0  2.0  3.0 |
X    =  | 2.0  3.0  4.0 |
        | 3.0  4.0  5.0 |
        | 4.0  5.0  6.0 |
        *               *
 
        *               *
        | 4.0  3.0  2.0 |
Y    =  | 3.0  2.0  1.0 |
        | 2.0  1.0  4.0 |
        | 1.0  4.0  3.0 |
        *               *

Output

S        =  (20.0, 36.0, 48.0)

Example 2

This example shows a store negative dot product computation using vectors with positive and negative strides.

Call Statement and Input

            N   M   S   INCS ISW  X  INCXI INCXO  Y  INCYI INCYO
            |   |   |    |    |   |    |     |    |    |     |
CALL SNDOT( 3 , 4 , S , -1  , 2 , X ,  2  , 10  , Y , -1  ,  6  )

        *               *
        | 1.0  2.0  3.0 |
        |  .    .    .  |
        | 2.0  3.0  4.0 |
        |  .    .    .  |
X    =  | 3.0  4.0  5.0 |
        |  .    .    .  |
        | 4.0  5.0  6.0 |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        *               *

        *               *
        | 4.0  3.0  2.0 |
        | 3.0  2.0  1.0 |
Y    =  | 2.0  1.0  4.0 |
        | 1.0  4.0  3.0 |
        |  .    .    .  |
        |  .    .    .  |
        *               *

Output

S        =  (-42.0, -34.0, -30.0)

Example 3

This example shows an accumulative positive dot product using vectors with positive and negative strides.

Call Statement and Input

            N   M   S  INCS ISW  X  INCXI INCXO  Y  INCYI INCYO
            |   |   |   |    |   |    |     |    |    |     |
CALL SNDOT( 3 , 4 , S , 1  , 3 , X , -2  , 10  , Y ,  2  , 10  )
 
S        =  (2.0, 5.0, 8.0)

        *               *
        | 1.0  2.0  3.0 |
        |  .    .    .  |
        | 2.0  3.0  4.0 |
        |  .    .    .  |
X    =  | 3.0  4.0  5.0 |
        |  .    .    .  |
        | 4.0  5.0  6.0 |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        *               *

        *               *
        | 4.0  3.0  2.0 |
        |  .    .    .  |
        | 3.0  2.0  1.0 |
        |  .    .    .  |
Y    =  | 2.0  1.0  4.0 |
        |  .    .    .  |
        | 1.0  4.0  3.0 |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        *               *

Output

S        =  (32.0, 39.0, 50.0)

Example 4

This example shows an accumulative negative dot product using vectors with positive and negative strides.

Call Statement and Input

            N   M   S   INCS ISW  X  INCXI INCXO  Y  INCYI INCYO
            |   |   |    |    |   |    |     |    |    |     |
CALL SNDOT( 3 , 4 , S , -1  , 4 , X ,  1  ,  6  , Y ,  2  , 10  )

S        =  (3.0, 6.0, 9.0)
        *               *
        | 1.0  2.0  3.0 |
        | 2.0  3.0  4.0 |
X    =  | 3.0  4.0  5.0 |
        | 4.0  5.0  6.0 |
        |  .    .    .  |
        |  .    .    .  |
        *               *

        *               *
        | 4.0  3.0  2.0 |
        |  .    .    .  |
        | 3.0  2.0  1.0 |
        |  .    .    .  |
Y    =  | 2.0  1.0  4.0 |
        |  .    .    .  |
        | 1.0  4.0  3.0 |
        |  .    .    .  |
        |  .    .    .  |
        |  .    .    .  |
        *               *

Output

S        =  (-45.0, -30.0, -11.0)

SNRM2, DNRM2, SCNRM2, and DZNRM2--Euclidean Length of a Vector with Scaling of Input to Avoid Destructive Underflow and Overflow

These subprograms compute the Euclidean length (l₂ norm) of vector x, with scaling of input to avoid destructive underflow and overflow.

Table 46. Data Types

x	Result	Subprogram
Short-precision real	Short-precision real	SNRM2
Long-precision real	Long-precision real	DNRM2
Short-precision complex	Short-precision real	SCNRM2
Long-precision complex	Long-precision real	DZNRM2

Note:

If there is a possibility that your data will cause the computation to overflow or underflow, you should use these subroutines instead of SNORM2, DNORM2, CNORM2, and ZNORM2, because the intermediate computational results may exceed the maximum or minimum limits of the machine. "Notes" explains how to estimate whether your data will cause an overflow or underflow.

Syntax

On Entry

n

is the number of elements in vector x. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n, whose Euclidean length is to be computed. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 46.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

On Return

Function value

is the Euclidean length (l₂ norm) of the vector x. Returned as: a number of the data type indicated in Table 46.

Note

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

Function

The Euclidean length (l₂ norm) of vector x is expressed as follows, with scaling of input to avoid destructive underflow and overflow:

See reference [73]. The result is returned as the function value. If n is 0, then 0.0 is returned as the value of the function.

For SNRM2 and SCNRM2, the sum of the squares of the absolute values of the elements is accumulated in long precision. The square root of this long-precision sum is then computed and, if necessary, is unscaled.

Although these subroutines eliminate destructive underflow, nondestructive underflows may occur if the input elements differ greatly in magnitude. This does not affect accuracy, but it degrades performance. The system default is to mask underflow, which improves the performance of these subroutines.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Important Information About the Following Examples

Workstations use workstation architecture precisions: ANSI/IEEE 32-bit and 64-bit binary floating-point format. The ranges are:

• For short-precision: 3.37×10^-38 to 3.37×10³⁸
• For long-precision: 1.67×10^-308 to 1.67×10³⁰⁸

Example 1

This example shows a vector, x, whose elements must be scaled to prevent overflow.

Function Reference and Input

               N   X  INCX
               |   |   |
DNORM = DNRM2( 6 , X , 1  )
 
X      = (0.68056D+200, 0.25521D+200, 0.34028D+200,
          0.85071D+200, 0.25521D+200, 0.85071D+200)

Output

DNORM    =  0.1469D+201

Example 2

This example shows a vector, x, whose elements must be scaled to prevent destructive underflow.

Function Reference and Input

               N   X  INCX
               |   |   |
DNORM = DNRM2( 4 , X , 2  )
 
X     = (0.10795D-200, . , 0.10795D-200, . , 0.10795D-200,
         . , 0.10795D-200)

Output

DNORM    =  0.21590D-200

Example 3

This example shows a vector, x, with a stride of 0. The result in SNORM is:

Function Reference and Input

               N   X  INCX
               |   |   |
SNORM = SNRM2( 4 , X , 0  )
 
X        =  (4.0)

Output

SNORM    =  8.0

Example 4

This example shows a vector, x, containing complex numbers, and whose elements must be scaled to prevent overflow.

Function Reference and Input

                 N   X  INCX
                 |   |   |
DZNORM = DZNRM2( 3 , X , 1  )
 
X     = ((0.68056D+200, 0.25521D+200), (0.34028D+200, 0.85071D+200),
         (0.25521D+200, 0.85071D+200))

Output

DZNORM   =  0.1469D+201

Example 5

This example shows a vector, x, containing complex numbers, and whose elements must be scaled to prevent destructive underflow.

Function Reference and Input

                 N   X  INCX
                 |   |   |
DZNORM = DZNRM2( 2 , X , 2  )
 
X     = ((0.10795D-200, 0.10795D-200), . ,
         (0.10795D-200, 0.10795D-200))

Output

DZNORM   =  0.2159D-200

SNORM2, DNORM2, CNORM2, and ZNORM2--Euclidean Length of a Vector with No Scaling of Input

These subprograms compute the euclidean length (l₂ norm) of vector x with no scaling of input.

Table 47. Data Types

x	Result	Subprogram
Short-precision real	Short-precision real	SNORM2
Long-precision real	Long-precision real	DNORM2
Short-precision complex	Short-precision real	CNORM2
Long-precision complex	Long-precision real	ZNORM2

Syntax

On Entry

n

is the number of elements in vector x. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n, whose euclidean length is to be computed. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 47.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

On Return

Function value

is the euclidean length (l₂ norm) of the vector x. Returned as: a number of the data type indicated in Table 47.

Notes

1. This subroutine does not underflow or overflow if the values of the elements in vector x conform to the following conditions. If these conditions are violated, overflow or destructive underflow may occur:

   • For short-precision numbers:

     Any valid short-precision number.

   • For long-precision numbers:

     |x_i| = 0 or 0.10010E-145 < |x_i| < 0.13408E+155 for i = 1, n

2. Declare this function in your program as returning a value of the data type indicated in Table 47.

Function

The euclidean length (l₂ norm) of vector x is expressed as follows with no scaling of input:

See reference [73]. The result is returned as the function value. If n is 0, then 0.0 is returned as the value of the function.

For SNORM2 and CNORM2, the sum of the squares of the absolute values of the elements is accumulated in long-precision. The square root of this long-precision sum is then computed.

This subroutine should not be used if the values in vector x do not conform to the restriction given in "Notes".

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows a vector, x, with a stride of 1.

Function Reference and Input

                N   X  INCX
                |   |   |
SNORM = SNORM2( 6 , X , 1  )
 
X        =  (3.0, 4.0, 1.0, 8.0, 1.0, 3.0)

Output

SNORM    =  10.0

Example 2

This example shows a vector, x, with a stride greater than 1.

Function Reference and Input

                N   X  INCX
                |   |   |
SNORM = SNORM2( 6 , X , 2  )
 
X        =  (3.0, . , 4.0, . , 1.0, . , 8.0, . , 1.0, . , 3.0)

Output

SNORM    =  10.0

Example 3

This example shows a vector, x, with a stride of 0. The result in SNORM is:

Function Reference and Input

                N   X  INCX
                |   |   |
SNORM = SNORM2( 4 , X , 0  )
 
X        =  (4.0)

Output

SNORM    =  8.0

Example 4

This example shows a vector, x, containing complex numbers and having a stride of 1.

Function Reference and Input

                N   X  INCX
                |   |   |
CNORM = CNORM2( 3 , X , 1  )
 
X        =  ((3.0, 4.0), (1.0, 8.0), (-1.0, 3.0))

Output

CNORM    =  10.0

SROTG, DROTG, CROTG, and ZROTG--Construct a Givens Plane Rotation

SROTG and DROTG construct a real Givens plane rotation, and CROTG and ZROTG construct a complex Givens plane rotation. The computations use rotational elimination parameters a and b. Values are returned for r, as well as the cosine c and the sine s of the angle of rotation. SROTG and DROTG also return a value for z.

Note:

Throughout this description, the symbols r and z are used to represent two of the output values returned for this computation. It is important to note that the values for r and z are actually returned in the input-output arguments a and b, respectively, overwriting the original values passed in a and b.

Table 48. Data Types

a, b, r, s	c	z	Subprogram
Short-precision real	Short-precision real	Short-precision real	SROTG
Long-precision real	Long-precision real	Long-precision real	DROTG
Short-precision complex	Short-precision real	(No value returned)	CROTG
Long-precision complex	Long-precision real	(No value returned)	ZROTG

Syntax

On Entry

a

is the rotational elimination parameter a. Specified as: a number of the data type indicated in Table 48.

b

is the rotational elimination parameter b. Specified as: a number of the data type indicated in Table 48.

c

See 'On Return'.

s

See 'On Return'.

On Return

a

is the value computed for r.

For SROTG and DROTG:

where:

sigma = SIGN(a) if |a| > |b|

sigma = SIGN(b) if |a| <= |b|

For CROTG and ZROTG:

where:

psi = a/|a|

Returned as: a number of the data type indicated in Table 48.

b

is the value computed for z.

For SROTG and DROTG:

z = s    if |a| > |b|

z = 1/c    if |a| <= |b| and c <> 0 and r <> 0

z = 1    if |a| <= |b| and c = 0 and r <> 0

z = 0    if r = 0

For CROTG and ZROTG: no value is returned, and the input value is not changed.

Returned as: a number of the data type indicated in Table 48.

c

is the cosine c of the angle of (Givens) rotation. For SROTG and DROTG:

c = a/r    if r <> 0

c = 1    if r = 0

For CROTG and ZROTG:

Returned as: a number of the data type indicated in Table 48.

s

is the sine s of the angle of (Givens) rotation.

For SROTG and DROTG:

s = b/r    if r <> 0

s = 0    if r = 0

For CROTG and ZROTG:

where psi = a/|a|

Returned as: a number of the data type indicated in Table 48.

Note

In your C program, arguments a, b, c, and s must be passed by reference.

Function

SROTG and DROTG

A real Givens plane rotation is constructed for values a and b by computing values for r, c, s, and z, where:

where:

sigma = SIGN(a)    if |a| > |b|

sigma = SIGN(b)    if |a| <= |b|

c = a/r    if r <> 0

c = 1    if r = 0

s = b/r    if r <> 0

s = 0    if r = 0

z = s    if |a| > |b|

z = 1/c    if |a| <= |b| and c <> 0 and r <> 0

z = 1    if |a| <= |b| and c = 0 and r <> 0

z = 0    if r = 0

See reference [73].

Following are some important points about the computation:

1. The numbers for c, s, and r satisfy:

   
   
   

   
   
   

2. Where necessary, scaling is used to avoid overflow and destructive underflow in the computation of r, which is expressed as follows:

   
   
   
   
   

3. sigma is not essential to the computation of a Givens rotation matrix, but its use permits later stable reconstruction of c and s from just one stored number, z. See reference [85]. c and s are reconstructed from z as follows:

   
   
   
   
   

CROTG and ZROTG

A complex Givens plane rotation is constructed for values a and b by computing values for r, c, and s, where:

where:

psi = a/|a|

See reference [73].

Following are some important points about the computation:

1. The numbers for c, s, and r satisfy:

   
   
   

   
   
   

2. Where necessary, scaling is used to avoid overflow and destructive underflow in the computation of r, which is expressed as follows:

   
   
   
   
   

Error Conditions

Computational Errors

None

Input-Argument Errors

None

Example 1

This example shows the construction of a real Givens plane rotation, where r is 0.

Call Statement and Input

             A     B    C   S
             |     |    |   |
CALL SROTG( 0.0 , 0.0 , C , S )

Output

A        =  0.0
B        =  0.0
C        =  1.0
S        =  0.0

Example 2

This example shows the construction of a real Givens plane rotation, where c is 0.

Call Statement and Input

             A     B    C   S
             |     |    |   |
CALL SROTG( 0.0 , 2.0 , C , S )

Output

A        =  2.0
B        =  1.0
C        =  0.0
S        =  1.0

Example 3

This example shows the construction of a real Givens plane rotation, where |b| > |a|.

Call Statement and Input

             A      B    C   S
             |      |    |   |
CALL SROTG( 6.0 , -8.0 , C , S )

Output

A        =  -10.0
                 _
B        =  -1.666
C        =  -0.6
S        =  0.8

Example 4

This example shows the construction of a real Givens plane rotation, where |a| > |b|.

Call Statement and Input

             A     B    C   S
             |     |    |   |
CALL SROTG( 8.0 , 6.0 , C , S )

Output

A        =  10.0
B        =  0.6
C        =  0.8
S        =  0.6

Example 5

This example shows the construction of a complex Givens plane rotation, where |a| = 0.

Call Statement and Input

            A   B   C   S
            |   |   |   |
CALL CROTG( A , B , C , S )
 
A        =  (0.0, 0.0)
B        =  (1.0, 0.0)
 

Output

A        =  (1.0, 0.0)
C        =  0.0
S        =  (1.0, 0.0)

Example 6

This example shows the construction of a complex Givens plane rotation, where |a| <> 0.

Call Statement and Input

            A   B   C   S
            |   |   |   |
CALL CROTG( A , B , C , S )
 
A        =  (3.0, 4.0)
B        =  (4.0, 6.0)

Output

A        =  (5.26, 7.02)
C        =  0.57
S        =  (0.82, -0.05)

SROT, DROT, CROT, ZROT, CSROT, and ZDROT--Apply a Plane Rotation

SROT and DROT apply a real plane rotation to real vectors; CROT and ZROT apply a complex plane rotation to complex vectors; and CSROT and ZDROT apply a real plane rotation to complex vectors. The plane rotation is applied to n points, where the points to be rotated are contained in vectors x and y, and where the cosine and sine of the angle of rotation are c and s, respectively.

Table 49. Data Types

x, y	c	s	Subprogram
Short-precision real	Short-precision real	Short-precision real	SROT
Long-precision real	Long-precision real	Long-precision real	DROT
Short-precision complex	Short-precision real	Short-precision complex	CROT
Long-precision complex	Long-precision real	Long-precision complex	ZROT
Short-precision complex	Short-precision real	Short-precision real	CSROT
Long-precision complex	Long-precision real	Long-precision real	ZDROT

Syntax

On Entry

n

is the number of points to be rotated--that is, the number of elements in vectors x and y. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n, containing the x_i coordinates of the points to be rotated. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 49.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

is the vector y of length n, containing the y_i coordinates of the points to be rotated. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 49.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

c

the cosine, c, of the angle of rotation. Specified as: a number of the data type indicated in Table 49.

s

the sine, s, of the angle of rotation. Specified as: a number of the data type indicated in Table 49.

On Return

x

is the vector x of length n, containing the rotated x_i coordinates, where:

x_i <-- cx_i+sy_i    for i = 1,

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

y

is the vector y of length n, containing the rotated y_i coordinates, where:

For SROT, DROT, CSROT, and ZDROT:

y_i <-- -sx_i+cy_i    for i = 1, n

For CROT and ZROT:

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

Note

The vectors x and y must have no common elements; otherwise, results are unpredictable. See "Concepts".

Function

Applying a plane rotation to n points, where the points to be rotated are contained in vectors x and y, is expressed as follows, where c and s are the cosine and sine of the angle of rotation, respectively. For SROT, DROT, CSROT, and ZDROT:

For CROT and ZROT:

See references [54] and [73]. No computation is performed if n is 0 or if c is 1.0 and s is zero. For SROT, CROT, and CSROT, intermediate results are accumulated in long precision.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows how to apply a real plane rotation to real vectors x and y having positive strides.

Call Statement and Input

           N   X  INCX  Y  INCY   C    S
           |   |   |    |   |     |    |
CALL SROT( 5 , X , 1  , Y , 2  , 0.5 , S )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (-1.0, . , -2.0, . , -3.0, . , -4.0, . , -5.0)

Output

X        =  (-0.366, -0.732, -1.098, -1.464, -1.830)
Y        =  (-1.366, -2.732, -4.098, -5.464, -6.830)

Example 2

This example shows how to apply a real plane rotation to real vectors x and y having strides of opposite sign.

Call Statement and Input

           N   X  INCX  Y   INCY   C    S
           |   |   |    |    |     |    |
CALL SROT( 5 , X , 1  , Y , -1  , 0.5 , S )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (-5.0, -4.0, -3.0, -2.0, -1.0)

Output

X        =(same as output X in Example 1)
Y        =  (-6.830, -5.464, -4.098, -2.732, -1.366)

Example 3

This example shows how scalar values in vectors x and y can be processed by specifying 0 strides and the number of elements to be processed, n, equal to 1.

Call Statement and Input

           N   X  INCX  Y  INCY   C    S
           |   |   |    |   |     |    |
CALL SROT( 1 , X , 0  , Y , 0  , 0.5 , S )
 
X        =  (1.0)
Y        =  (-1.0)

Output

X        =  (-0.366)
Y        =  (-1.366)

Example 4

This example shows how to apply a complex plane rotation to complex vectors x and y having positive strides.

Call Statement and Input

           N   X  INCX  Y  INCY   C    S
           |   |   |    |   |     |    |
CALL CROT( 3 , X , 1  , Y , 2  , 0.5 , S )
 
X        =  ((1.0, 2.0), (2.0, 3.0), (3.0, 4.0))
Y        =  ((-1.0, 5.0), . , (-2.0, 4.0), . , (-3.0, 3.0))
S        =  (0.75, 0.50)

Output

X        =  ((-2.750, 4.250), (-2.500, 3.500), (-2.250, 2.750))
Y        =  ((-2.250, 1.500), . , (-4.000, 0.750), . ,
             (-5.750, 0.000))

Example 5

This example shows how to apply a real plane rotation to complex vectors x and y having positive strides.

Call Statement and Input

            N   X  INCX  Y  INCY   C    S
            |   |   |    |   |     |    |
CALL CSROT( 3 , X , 1  , Y , 2  , 0.5 , S )
 
X        =  ((1.0, 2.0), (2.0, 3.0), (3.0, 4.0))
Y        =  ((-1.0, 5.0), . , (-2.0, 4.0), . , (-3.0, 3.0))

Output

X        =  ((-0.366, 5.330), (-0.732, 4.964), (-1.098, 4.598))
Y        =  ((-1.366, 0.768), . , (-2.732, -0.598), . ,
             (-4.098, -1.964))

SSCAL, DSCAL, CSCAL, ZSCAL, CSSCAL, and ZDSCAL--Multiply a Vector X by a Scalar and Store in the Vector X

These subprograms perform the following computation, using the scalar alpha and the vector x:

x <-- alphax

Table 50. Data Types

alpha	x	Subprogram
Short-precision real	Short-precision real	SSCAL
Long-precision real	Long-precision real	DSCAL
Short-precision complex	Short-precision complex	CSCAL
Long-precision complex	Long-precision complex	ZSCAL
Short-precision real	Short-precision complex	CSSCAL
Long-precision real	Long-precision complex	ZDSCAL

Syntax

On Entry

n

is the number of elements in vector x. Specified as: a fullword integer; n >= 0.

alpha

is the scalar alpha. Specified as: a number of the data type indicated in Table 50.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 50.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

On Return

x

is the vector x of length n, containing the result of the computation alphax. Returned as: a one-dimensional array, containing numbers of the data type indicated in Table 50.

Note

The fastest way in ESSL to zero out contiguous (stride 1) arrays is to call SSCAL or DSCAL, specifying incx = 1 and alpha = 0.

Function

The computation is expressed as follows:

See reference [73]. If n is 0, no computation is performed. For CSCAL, intermediate results are accumulated in long precision.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows a vector, x, with a stride of 1.

Call Statement and Input

            N  ALPHA  X  INCX
            |    |    |   |
CALL SSCAL( 5 , 2.0 , X , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)

Output

X        =  (2.0, 4.0, 6.0, 8.0, 10.0)

Example 2

This example shows vector, x, with a stride greater than 1.

Call Statement and Input

            N  ALPHA  X  INCX
            |    |    |   |
CALL SSCAL( 5 , 2.0 , X , 2  )
 
X        =  (1.0, . , 2.0, . , 3.0, . , 4.0, . , 5.0)

Output

X        =  (2.0, . , 4.0, . , 6.0, . , 8.0, . , 10.0)

Example 3

This example illustrates that when the strides for two similar computations (Example 1 and Example 3) have the same absolute value but have opposite signs, the output is the same. This example is the same as Example 1, except the stride for x is negative (-1). For performance reasons, it is better to specify the positive stride. For x, processing begins at element X(5), which is 5.0, and results are stored beginning at the same element.

Call Statement and Input

            N  ALPHA  X   INCX
            |    |    |    |
CALL SSCAL( 5 , 2.0 , X , -1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)

Output

X        =  (2.0, 4.0, 6.0, 8.0, 10.0)

Example 4

This example shows how SSCAL can be used to compute a scalar value. In this case, input vector x contains a scalar value, and the stride is 0. The number of elements to be processed, n, is 1.

Call Statement and Input

            N  ALPHA  X  INCX
            |    |    |   |
CALL SSCAL( 1 , 2.0 , X , 0  )
 
X        =  (1.0)

Output

X        =  (2.0)

Example 5

This example shows a scalar, alpha, and a vector, x, containing complex numbers, where vector x has a stride of 1.

Call Statement and Input

            N  ALPHA  X  INCX
            |    |    |   |
CALL CSCAL( 3 ,ALPHA, X , 1  )
 
ALPHA    =  (2.0, 3.0)
X        =  ((1.0, 2.0), (2.0, 0.0), (3.0, 5.0))

Output

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

Example 6

This example shows a scalar, alpha, containing a real number, and a vector, x, containing complex numbers, where vector x has a stride of 1.

Call Statement and Input

             N  ALPHA  X  INCX
             |    |    |   |
CALL CSSCAL( 3 , 2.0 , X , 1  )
 
X        =  ((1.0, 2.0), (2.0, 0.0), (3.0, 5.0))

Output

X        =  ((2.0, 4.0), (4.0, 0.0), (6.0, 10.0))

SSWAP, DSWAP, CSWAP, and ZSWAP--Interchange the Elements of Two Vectors

These subprograms interchange the elements of vectors x and y:

y <--> x

Table 51. Data Types

x, y	Subprogram
Short-precision real	SSWAP
Long-precision real	DSWAP
Short-precision complex	CSWAP
Long-precision complex	ZSWAP

Syntax

On Entry

n

is the number of elements in vectors x and y. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 51.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

is the vector y of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 51.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

On Return

x

is the vector x of length n, containing the elements that were swapped from vector y. Returned as: a one-dimensional array, containing numbers of the data type indicated in Table 51.

y

is the vector y of length n, containing the elements that were swapped from vector x. Returned as: a one-dimensional array, containing numbers of the data type indicated in Table 51.

Notes

1. If you specify the same vector for x and y, then incx and incy must be equal; otherwise, results are unpredictable.

2. If you specify different vectors for x and y, they must have no common elements; otherwise, results are unpredictable. See "Concepts".

Function

The elements of vectors x and y are interchanged as follows:

See reference [73]. If n is 0, no elements are interchanged.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows vectors x and y with positive strides.

Call Statement and Input

            N   X  INCX  Y  INCY
            |   |   |    |   |
CALL SSWAP( 5 , X , 1  , Y , 2  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (-1.0, . , -2.0, . , -3.0, . , -4.0, . , -5.0)

Output

X        =  (-1.0, -2.0, -3.0, -4.0, -5.0)
Y        =  (1.0, . , 2.0, . , 3.0, . , 4.0, . , 5.0)

Example 2

This example shows how to obtain output vectors x and y that are reverse copies of the input vectors y and x. You must specify strides with the same absolute value, but with opposite signs. For y, which has negative stride, processing begins at element Y(5), which is -5.0, and the results of the swap are stored beginning at the same element.

Call Statement and Input

            N   X  INCX  Y   INCY
            |   |   |    |    |
CALL SSWAP( 5 , X , 1  , Y , -1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (-1.0, -2.0, -3.0, -4.0, -5.0)

Output

X        =  (-5.0, -4.0, -3.0, -2.0, -1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Example 3

This example shows how SSWAP can be used to interchange scalar values in vectors x and y by specifying 0 strides and the number of elements to be processed as 1.

Call Statement and Input

            N   X  INCX  Y  INCY
            |   |   |    |   |
CALL SSWAP( 1 , X , 0  , Y , 0  )
 
X        =  (1.0)
Y        =  (-4.0)

Output

X        =  (-4.0)
Y        =  (1.0)

Example 4

This example shows vectors x and y, containing complex numbers and having positive strides.

Call Statement and Input

            N   X  INCX  Y  INCY
            |   |   |    |   |
CALL CSWAP( 4 , X , 1  , Y , 2  )
 
X        =  ((1.0, 6.0), (2.0, 7.0), (3.0, 8.0), (4.0, 9.0))
Y        =  ((-1.0, -1.0), . , (-2.0, -2.0), . , (-3.0, -3.0), . ,
             (-4.0, -4.0))

Output

X        =  ((-1.0, -1.0), (-2.0, -2.0), (-3.0, -3.0), (-4.0, -4.0))
Y        =  ((1.0, 6.0), . , (2.0, 7.0), . , (3.0, 8.0), . ,
             (4.0, 9.0))

SVEA, DVEA, CVEA, and ZVEA--Add a Vector X to a Vector Y and Store in a Vector Z

These subprograms perform the following computation, using vectors x, y, and z:

z <-- x+y

Table 52. Data Types

x, y, z	Subprogram
Short-precision real	SVEA
Long-precision real	DVEA
Short-precision complex	CVEA
Long-precision complex	ZVEA

Syntax

On Entry

n

is the number of elements in vectors x, y, and z. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 52.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

is the vector y of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 52.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

z

See 'On Return'.

incz

is the stride for vector z. Specified as: a fullword integer. It can have any value.

On Return

z

is the vector z of length n, containing the result of the computation. Returned as: a one-dimensional array of (at least) length 1+(n-1)|incz|, containing numbers of the data type indicated in Table 52.

Notes

1. If you specify the same vector for x and z, then incx and incz must be equal; otherwise, results are unpredictable. The same is true for y and z.

2. If you specify different vectors for x and z, they must have no common elements; otherwise, results are unpredictable. The same is true for y and z. See "Concepts".

Function

The computation is expressed as follows:

If n is 0, no computation is performed.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows vectors x, y, and z, with positive strides.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVEA( 5 , X , 1  , Y , 2  , Z , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (1.0, . , 1.0, . , 1.0, . , 1.0, . , 1.0)

Output

Z        =  (2.0, 3.0, 4.0, 5.0, 6.0)

Example 2

This example shows vectors x and y having strides of opposite sign, and an output vector z having a positive stride. For y, which has negative stride, processing begins at element Y(5), which is 1.0.

Call Statement and Input

           N   X  INCX  Y   INCY  Z  INCZ
           |   |   |    |    |    |   |
CALL SVEA( 5 , X , 1  , Y , -1  , Z , 2  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (2.0, . , 4.0, . , 6.0, . , 8.0, . , 10.0)

Example 3

This example shows a vector, x, with 0 stride and a vector, z, with negative stride. x is treated like a vector of length n, all of whose elements are the same as the single element in x. For vector z, results are stored beginning in element Z(5).

Call Statement and Input

           N   X  INCX  Y  INCY  Z   INCZ
           |   |   |    |   |    |    |
CALL SVEA( 5 , X , 0  , Y , 1  , Z , -1  )
 
X        =  (1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (2.0, 3.0, 4.0, 5.0, 6.0)

Example 4

This example shows a vector, y, with 0 stride. y is treated like a vector of length n, all of whose elements are the same as the single element in y.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVEA( 5 , X , 1  , Y , 0  , Z , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0)

Output

Z        =  (6.0, 7.0, 8.0, 9.0, 10.0)

Example 5

This example shows the output vector, z, with 0 stride, where the vector x has positive stride, and the vector y has 0 stride. The number of elements to be processed, n, is greater than 1.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVEA( 5 , X , 1  , Y , 0  , Z , 0  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0)

Output

Z        =  (10.0)

Example 6

This example shows the output vector z, with 0 stride, where the vector x has 0 stride, and the vector y has negative stride. The number of elements to be processed, n, is greater than 1.

Call Statement and Input

           N   X  INCX  Y   INCY  Z  INCZ
           |   |   |    |    |    |   |
CALL SVEA( 5 , X , 0  , Y , -1  , Z , 0  )
 
X        =  (1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (6.0)

Example 7

This example shows how SVEA can be used to compute a scalar value. In this case, vectors x and y contain scalar values. The strides of all vectors, x, y, and z, are 0. The number of elements to be processed, n, is 1.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVEA( 1 , X , 0  , Y , 0  , Z , 0  )
 
X        =  (1.0)
Y        =  (5.0)

Output

Z        =  (6.0)

Example 8

This example shows vectors x and y, containing complex numbers and having positive strides.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL CVEA( 3 , X , 1  , Y , 2  , Z , 1  )
 
X        =  ((1.0, 2.0), (3.0, 4.0), (5.0, 6.0))
Y        =  ((7.0, 8.0), . , (9.0, 10.0), . , (11.0, 12.0))

Output

Z        =  ((8.0, 10.0), (12.0, 14.0), (16.0, 18.0))

SVES, DVES, CVES, and ZVES--Subtract a Vector Y from a Vector X and Store in a Vector Z

These subprograms perform the following computation, using vectors x, y, and z:

z <-- x-y

Table 53. Data Types

x, y, z	Subprogram
Short-precision real	SVES
Long-precision real	DVES
Short-precision complex	CVES
Long-precision complex	ZVES

Syntax

On Entry

n

is the number of elements in vectors x, y, and z. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 53.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

is the vector y of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 53.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

z

See 'On Return'.

incz

is the stride for vector z. Specified as: a fullword integer. It can have any value.

On Return

z

is the vector z of length n, containing the result of the computation. Returned as: a one-dimensional array of (at least) length 1+(n-1)|incz|, containing numbers of the data type indicated in Table 53.

Notes

1. If you specify the same vector for x and z, then incx and incz must be equal; otherwise, results are unpredictable. The same is true for y and z.

2. If you specify different vectors for x and z, they must have no common elements; otherwise, results are unpredictable. The same is true for y and z. See "Concepts".

Function

The computation is expressed as follows:

If n is 0, no computation is performed.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows vectors x, y, and z, with positive strides.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVES( 5 , X , 1  , Y , 2  , Z , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (1.0, . , 1.0, . , 1.0, . , 1.0, . , 1.0)

Output

Z        =  (0.0, 1.0, 2.0, 3.0, 4.0)

Example 2

This example shows vectors x and y having strides of opposite sign, and an output vector z having a positive stride. For y, which has negative stride, processing begins at element Y(5), which is 1.0.

Call Statement and Input

           N   X  INCX  Y   INCY  Z  INCZ
           |   |   |    |    |    |   |
CALL SVES( 5 , X , 1  , Y , -1  , Z , 2  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (0.0, . , 0.0, . , 0.0, . , 0.0, . , 0.0)

Example 3

This example shows a vector, x, with 0 stride, and a vector, z, with negative stride. x is treated like a vector of length n, all of whose elements are the same as the single element in x. For vector z, results are stored beginning in element Z(5).

Call Statement and Input

           N   X  INCX  Y  INCY  Z   INCZ
           |   |   |    |   |    |    |
CALL SVES( 5 , X , 0  , Y , 1  , Z , -1  )
 
X        =  (1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (0.0, -1.0, -2.0, -3.0, -4.0)

Example 4

This example shows a vector, y, with 0 stride. y is treated like a vector of length n, all of whose elements are the same as the single element in y.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVES( 5 , X , 1  , Y , 0  , Z , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0)

Output

Z        =  (-4.0, -3.0, -2.0, -1.0, 0.0)

Example 5

This example shows the output vector z, with 0 stride, where the vector x has positive stride, and the vector y has 0 stride. The number of elements to be processed, n, is greater than 1.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVES( 5 , X , 1  , Y , 0  , Z , 0  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0)

Output

Z        =  (0.0)

Example 6

This example shows the output vector z, with 0 stride, where the vector x has 0 stride, and the vector y has negative stride. The number of elements to be processed, n, is greater than 1.

Call Statement and Input

           N   X  INCX  Y   INCY  Z  INCZ
           |   |   |    |    |    |   |
CALL SVES( 5 , X , 0  , Y , -1  , Z , 0  )
 
X        =  (1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (-4.0)

Example 7

This example shows how SVES can be used to compute a scalar value. In this case, vectors x and y contain scalar values. The strides of all vectors, x, y, and z, are 0. The number of elements to be processed, n, is 1.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVES( 1 , X , 0  , Y , 0  , Z , 0  )
 
X        =  (1.0)
Y        =  (5.0)

Output

Z        =  (-4.0)

Example 8

This example shows vectors x and y, containing complex numbers and having positive strides.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL CVES( 3 , X , 1  , Y , 2  , Z , 1  )
 
X        =  ((1.0, 2.0), (3.0, 4.0), (5.0, 6.0))
Y        =  ((7.0, 8.0), . , (9.0, 10.0), . , (11.0, 12.0))

Output

Z        =  ((-6.0, -6.0), (-6.0, -6.0), (-6.0, -6.0))

SVEM, DVEM, CVEM, and ZVEM--Multiply a Vector X by a Vector Y and Store in a Vector Z

These subprograms perform the following computation, using vectors x, y, and z:

z <-- xy

Table 54. Data Types

x, y, z	Subprogram
Short-precision real	SVEM
Long-precision real	DVEM
Short-precision complex	CVEM
Long-precision complex	ZVEM

Syntax

On Entry

n

is the number of elements in vectors x, y, and z. Specified as: a fullword integer; n >= 0.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 54.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

is the vector y of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 54.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

z

See 'On Return'.

incz

is the stride for vector z. Specified as: a fullword integer. It can have any value.

On Return

z

is the vector z of length n, containing the result of the computation. Returned as: a one-dimensional array of (at least) length 1+(n-1)|incz|, containing numbers of the data type indicated in Table 54.

Notes

1. If you specify the same vector for x and z, then incx and incz must be equal; otherwise, results are unpredictable. The same is true for y and z.

2. If you specify different vectors for x and z, they must have no common elements; otherwise, results are unpredictable. The same is true for y and z. See "Concepts".

Function

The computation is expressed as follows:

z_i <-- x_iy_i    for i = 1, n

If n is 0, no computation is performed. For CVEM, intermediate results are accumulated in long precision (short-precision Multiply followed by a long-precision Add), with the final result truncated to short precision.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows vectors x, y, and z, with positive strides.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVEM( 5 , X , 1  , Y , 2  , Z , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (1.0, . , 1.0, . , 1.0, . , 1.0, . , 1.0)

Output

Z        =  (1.0, 2.0, 3.0, 4.0, 5.0)

Example 2

This example shows vectors x and y having strides of opposite sign, and an output vector z having a positive stride. For y, which has negative stride, processing begins at element Y(5), which is 1.0.

Call Statement and Input

           N   X  INCX  Y   INCY  Z  INCZ
           |   |   |    |    |    |   |
CALL SVEM( 5 , X , 1  , Y , -1  , Z , 2  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (1.0, . , 4.0, . , 9.0, . , 16.0, . , 25.0)

Example 3

This example shows a vector, x, with 0 stride, and a vector, z, with negative stride. x is treated like a vector of length n, all of whose elements are the same as the single element in x. For vector z, results are stored beginning in element Z(5).

Call Statement and Input

           N   X  INCX  Y  INCY  Z   INCZ
           |   |   |    |   |    |    |
CALL SVEM( 5 , X , 0  , Y , 1  , Z , -1  )
 
X        =  (1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (1.0, 2.0, 3.0, 4.0, 5.0)

Example 4

This example shows a vector, y, with 0 stride. y is treated like a vector of length n, all of whose elements are the same as the single element in y.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVEM( 5 , X , 1  , Y , 0  , Z , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0)

Output

Z        =  (5.0, 10.0, 15.0, 20.0, 25.0)

Example 5

This example shows the output vector, z, with 0 stride, where the vector x has positive stride, and the vector y has 0 stride. The number of elements to be processed, n, is greater than 1.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVEM( 5 , X , 1  , Y , 0  , Z , 0  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0)

Output

Z        =  (25.0)

Example 6

This example shows the output vector z, with 0 stride, where the vector x has 0 stride, and the vector y has negative stride. The number of elements to be processed, n, is greater than 1.

Call Statement and Input

           N   X  INCX  Y   INCY  Z  INCZ
           |   |   |    |    |    |   |
CALL SVEM( 5 , X , 0  , Y , -1  , Z , 0  )
 
X        =  (1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (5.0)

Example 7

This example shows how SVEM can be used to compute a scalar value. In this case, vectors x and y contain scalar values. The strides of all vectors, x, y, and z, are 0. The number of elements to be processed, n, is 1.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL SVEM( 1 , X , 0  , Y , 0  , Z , 0  )
 
X        =  (1.0)
Y        =  (5.0)

Output

Z        =  (5.0)

Example 8

This example shows vectors x and y, containing complex numbers and having positive strides.

Call Statement and Input

           N   X  INCX  Y  INCY  Z  INCZ
           |   |   |    |   |    |   |
CALL CVEM( 3 , X , 1  , Y , 2  , Z , 1  )
 
X        =  ((1.0, 2.0), (3.0, 4.0), (5.0, 6.0))
Y        =  ((7.0, 8.0), . , (9.0, 10.0), . , (11.0, 12.0))

Output

Z        =  ((-9.0, 22.0), (-13.0, 66.0), (-17.0, 126.0))

SYAX, DYAX, CYAX, ZYAX, CSYAX, and ZDYAX--Multiply a Vector X by a Scalar and Store in a Vector Y

These subprograms perform the following computation, using the scalar alpha and vectors x and y:

y <-- alphax

Table 55. Data Types

alpha	x, y	Subprogram
Short-precision real	Short-precision real	SYAX
Long-precision real	Long-precision real	DYAX
Short-precision complex	Short-precision complex	CYAX
Long-precision complex	Long-precision complex	ZYAX
Short-precision real	Short-precision complex	CSYAX
Long-precision real	Long-precision complex	ZDYAX

Syntax

On Entry

n

is the number of elements in vector x and y. Specified as: a fullword integer; n >= 0.

alpha

is the scalar alpha. Specified as: a number of the data type indicated in Table 55.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 55.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

See 'On Return'.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

On Return

y

is the vector y of length n, containing the result of the computation alphax. Returned as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 55.

Notes

1. If you specify the same vector for x and y, then incx and incy must be equal; otherwise, results are unpredictable.

2. If you specify different vectors for x and y, they must have no common elements; otherwise, results are unpredictable. See "Concepts".

Function

The computation is expressed as follows:

See reference [73]. If n is 0, no computation is performed. For CYAX, intermediate results are accumulated in long precision.

Error Condition

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows vectors x and y with positive strides.

Call Statement and Input

           N  ALPHA  X  INCX  Y  INCY
           |    |    |   |    |   |
CALL SYAX( 5 , 2.0 , X , 1  , Y , 2  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)

Output

Y        =  (2.0, . , 4.0, . , 6.0, . , 8.0, . , 10.0)

Example 2

This example shows vectors x and y that have strides of opposite signs. For y, which has negative stride, results are stored beginning in element Y(5).

Call Statement and Input

           N  ALPHA  X  INCX  Y   INCY
           |    |    |   |    |    |
CALL SYAX( 5 , 2.0 , X , 1  , Y , -1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)

Output

Y        =  (10.0, 8.0, 6.0, 4.0, 2.0)

Example 3

This example shows a vector, x, with 0 stride. x is treated like a vector of length n, all of whose elements are the same as the single element in x.

Call Statement and Input

           N  ALPHA  X  INCX  Y  INCY
           |    |    |   |    |   |
CALL SYAX( 5 , 2.0 , X , 0  , Y , 1  )
 
X        =  (1.0)

Output

Y        =  (2.0, 2.0, 2.0, 2.0, 2.0)

Example 4

This example shows how SYAX can be used to compute a scalar value. In this case both vectors x and y contain scalar values, and the strides for both vectors are 0. The number of elements to be processed, n, is 1.

Call Statement and Input

           N  ALPHA  X  INCX  Y  INCY
           |    |    |   |    |   |
CALL SYAX( 1 , 2.0 , X , 0  , Y , 0  )
 
X        =  (1.0)

Output

Y        =  (2.0)

Example 5

This example shows a scalar, alpha, and vectors x and y, containing complex numbers, where both vectors have a stride of 1.

Call Statement and Input

           N  ALPHA  X  INCX  Y  INCY
           |    |    |   |    |   |
CALL CYAX( 3 ,ALPHA, X , 1  , Y , 1  )
 
ALPHA    =  (2.0, 3.0)
X        =  ((1.0, 2.0), (2.0, 0.0), (3.0, 5.0))

Output

Y        =  ((-4.0, 7.0), (4.0, 6.0), (-9.0, 19.0))

Example 6

This example shows a scalar, alpha, containing a real number, and vectors x and y, containing complex numbers, where both vectors have a stride of 1.

Call Statement and Input

            N  ALPHA  X  INCX  Y  INCY
            |    |    |   |    |   |
CALL CSYAX( 3 , 2.0 , X , 1  , Y , 1  )
 
X        =  ((1.0, 2.0), (2.0, 0.0), (3.0, 5.0))

Output

Y        =  ((2.0, 4.0), (4.0, 0.0), (6.0, 10.0))

SZAXPY, DZAXPY, CZAXPY, and ZZAXPY--Multiply a Vector X by a Scalar, Add to a Vector Y, and Store in a Vector Z

These subprograms perform the following computation, using the scalar alpha and vectors x, y, and z:

z <-- y+alphax

Table 56. Data Types

alpha, x, y, z	Subprogram
Short-precision real	SZAXPY
Long-precision real	DZAXPY
Short-precision complex	CZAXPY
Long-precision complex	ZZAXPY

Syntax

On Entry

n

is the number of elements in vectors x, y, and z. Specified as: a fullword integer; n >= 0.

alpha

is the scalar alpha. Specified as: a number of the data type indicated in Table 56.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 56.

incx

is the stride for vector x. Specified as: a fullword integer. It can have any value.

y

is the vector y of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 56.

incy

is the stride for vector y. Specified as: a fullword integer. It can have any value.

z

See 'On Return'.

incz

is the stride for vector z. Specified as: a fullword integer. It can have any value.

On Return

z

is the vector z of length n, containing the result of the computation y+alphax . Returned as: a one-dimensional array of (at least) length 1+(n-1)|incz|, containing numbers of the data type indicated in Table 56.

Notes

1. If you specify the same vector for x and z, then incx and incz must be equal; otherwise, results are unpredictable. The same is true for y and z.

2. If you specify different vectors for x and z, they must have no common elements; otherwise, results are unpredictable. The same is true for y and z. See "Concepts".

Function

The computation is expressed as follows:

See reference [73]. If n is 0, no computation is performed. For CZAXPY, intermediate results are accumulated in long precision.

Error Conditions

Computational Errors

None

Input-Argument Errors

n < 0

Example 1

This example shows vectors x and y with positive strides.

Call Statement and Input

             N  ALPHA  X  INCX  Y  INCY  Z  INCZ
             |    |    |   |    |   |    |   |
CALL SZAXPY( 5 , 2.0 , X , 1  , Y , 2  , Z , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (1.0, . , 1.0, . , 1.0, . , 1.0, . , 1.0)

Output

Z        =  (3.0, 5.0, 7.0, 9.0, 11.0)

Example 2

This example shows vectors x and y having strides of opposite sign, and an output vector z having a positive stride. For y, which has negative stride, processing begins at element Y(5), which is 1.0.

Call Statement and Input

             N  ALPHA  X  INCX  Y   INCY  Z  INCZ
             |    |    |   |    |    |    |   |
CALL SZAXPY( 5 , 2.0 , X , 1  , Y , -1  , Z , 2  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (3.0, . , 6.0, . , 9.0, . , 12.0, . , 15.0)

Example 3

This example shows a vector, x, with 0 stride, and a vector, z, with negative stride. x is treated like a vector of length n, all of whose elements are the same as the single element in x. For vector z, results are stored beginning in element Z(5).

Call Statement and Input

             N  ALPHA  X  INCX  Y  INCY  Z   INCZ
             |    |    |   |    |   |    |    |
CALL SZAXPY( 5 , 2.0 , X , 0  , Y , 1  , Z , -1  )
 
X        =  (1.0)
Y        =  (5.0, 4.0, 3.0, 2.0, 1.0)

Output

Z        =  (3.0, 4.0, 5.0, 6.0, 7.0)

Example 4

This example shows a vector, y, with 0 stride. y is treated like a vector of length n, all of whose elements are the same as the single element in y.

Call Statement and Input

             N  ALPHA  X  INCX  Y  INCY  Z  INCZ
             |    |    |   |    |   |    |   |
CALL SZAXPY( 5 , 2.0 , X , 1  , Y , 0  , Z , 1  )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (5.0)

Output

Z        =  (7.0, 9.0, 11.0, 13.0, 15.0)

Example 5

This example shows how SZAXPY can be used to compute a scalar value. In this case, vectors x and y contain scalar values. The strides of all vectors, x, y, and z, are 0. The number of elements to be processed, n, is 1.

Call Statement and Input

             N  ALPHA  X  INCX  Y  INCY  Z  INCZ
             |    |    |   |    |   |    |   |
CALL SZAXPY( 1 , 2.0 , X , 0  , Y , 0  , Z , 0  )
 
X        =  (1.0)
Y        =  (5.0)

Output

Z        =  (7.0)

Example 6

This example shows vectors x and y, containing complex numbers and having positive strides.

Call Statement and Input

             N  ALPHA  X  INCX  Y  INCY  Z  INCZ
             |    |    |   |    |   |    |   |
CALL CZAXPY( 3 ,ALPHA, X , 1  , Y , 2  , Z , 1  )
 
ALPHA    =  (2.0, 3.0)
X        =  ((1.0, 2.0), (2.0, 0.0), (3.0, 5.0))
Y        =  ((1.0, 1.0), . , (0.0, 2.0), . , (5.0, 4.0))

Output

Z        =  ((-3.0, 8.0), (4.0, 8.0), (-4.0, 23.0))

Sparse Vector-Scalar Subprograms

This section contains the sparse vector-scalar subprogram descriptions.

SSCTR, DSCTR, CSCTR, ZSCTR--Scatter the Elements of a Sparse Vector X in Compressed-Vector Storage Mode into Specified Elements of a Sparse Vector Y in Full-Vector Storage Mode

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

Table 57. Data Types

x, y	Subprogram
Short-precision real	SSCTR
Long-precision real	DSCTR
Short-precision complex	CSCTR
Long-precision complex	ZSCTR

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.

x

is the sparse vector x, containing nz elements, stored in compressed-vector storage mode in an array, referred to as X. Specified as: a one-dimensional array of (at least) length nz, containing numbers of the data type indicated in Table 57.

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 into which the elements are copied.

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

y

See 'On Return'.

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, into which nz elements of vector x are copied at positions indicated by the indices array INDX.

Returned 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 57.

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:

y_INDX(i) <-- x_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 SSCTR to copy a sparse vector x of length 5 into the following vector y, where the elements of array INDX are in ascending order:

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

Call Statement and Input

            NZ  X   INDX   Y
            |   |    |     |
CALL SSCTR( 5 , X , INDX , Y )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
INDX     =  (1, 3, 4, 7, 10)

Output

Y        =  (1.0, 2.0, 2.0, 3.0, 6.0, 10.0, 4.0, 8.0, 9.0, 5.0)

Example 2

This example shows how to use SSCTR to copy a sparse vector x of length 5 into the following vector y, where the elements of array INDX are in random order:

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

Call Statement and Input

            NZ  X   INDX   Y
            |   |    |     |
CALL SSCTR( 5 , X , INDX , Y )
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
INDX     =  (4, 3, 1, 10, 7)

Output

Y        =  (3.0, 2.0, 2.0, 1.0, 6.0, 10.0, 5.0, 8.0, 9.0, 4.0)

Example 3

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

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

Call Statement and Input

            NZ  X   INDX   Y
            |   |    |     |
CALL CSCTR( 3 , X , INDX , Y )
 
X        =  ((1.0, 2.0), (3.0, 4.0), (5.0, 6.0))
INDX     =  (4, 1, 3)

Output

Y        =  ((3.0, 4.0), (-2.0, 3.0), (5.0, 6.0), (1.0, 2.0))

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

x, y	Subprogram
Short-precision real	SGTHR
Long-precision real	DGTHR
Short-precision complex	CGTHR
Long-precision complex	ZGTHR

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))

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

x, y	Subprogram
Short-precision real	SGTHRZ
Long-precision real	DGTHRZ
Short-precision complex	CGTHRZ
Long-precision complex	ZGTHRZ

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.