S3L_2_norm and S3L_gbl_2_norm

Description

Multiple-Instance 2-norm - The multiple-instance 2-norm routine, S3L_2_norm, computes one or more instances of the 2-norm of a vector. The single-instance 2-norm routine, S3L_gbl_2_norm, computes the global 2-norm of a parallel array.

For each instance z of z, the multiple-instance routine S3L_2_norm performs the operation shown in Table 8-1.

Upon successful completion, S3L_2_norm overwrites each element of z with the 2-norm of the corresponding vector in x.

Single-Instance 2-norm - The single-instance routine S3L_gbl_2_norm routine performs the operations shown in Table 8-2.

Upon successful completion, S3L_gbl_2_norm overwrites a with the global 2-norm of x.

Syntax

The C and Fortran syntax for S3L_2_norm and S3L_gbl_2_norm are shown below.

C/C++ Syntax

Example 8-1

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_2_norm(z, x, x_vector_axis)
S3L_gbl_2_norm(a, x)
    S3L_array_t        a
    S3L_array_t        z
    S3L_array_t        x
    int                x_vector_axis

F77/F90 Syntax

Example 8-2

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_2_norm(z, x, ier)
S3L_gbl_2_norm(a, x, ier)
    integer*8          a
    integer*8          z
    integer*8          x
    integer*4          x_vector_axis
    integer*4          ier

Input

• x - Array handle for an S3L parallel array. For calls to S3L_2_norm (multiple-instance routine), x must represent a parallel array of rank >= 2, with at least one nonlocal instance axis. The variable x contains one or more instances of the vector x whose 2-norm will be computed.

• For calls to S3L_gbl_2_norm (single-instance routine), x must represent a parallel array of rank >= 1, with any instance axes declared to have length 1.

• x_vector_axis - Scalar variable. Identifies the axis of x along which the vectors lie.

Output

These functions use the following argument for output:

• z - Array handle for the S3L parallel array that will contain the results of the multiple-instance 2-norm routine. The rank of z must be one less than that of x. The axes of z must match the instance axes of x in length and order of declaration. Thus, each vector x in x corresponds to a single destination value z in z.

• a - Pointer to a scalar variable. Destination for the single-instance 2-norm routine.

• ier (Fortran only) - When called from a Fortran program, these functions return error status in ier.

Error Handling

On success, S3L_2_norm and S3L_gbl_2_norm return S3L_SUCCESS.

S3L_2_norm and S3L_gbl_2_norm perform generic checking of the validity of the arrays they accept as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions will cause the functions to terminate and return the associated error code.

• S3L_ERR_ARG_RANK - x has invalid rank.

• S3L_ERR_ARG_AXISNUM - (S3L_2_norm only) x_vector_axis is a bad axis number. For C program calls, this parameter must be >= 0 and less than the rank of x. For Fortran program calls, it must be >= 1 and not exceed the rank of x.

• S3L_ERR_MATCH_RANK - z does not have a rank of one less than that of x.

Examples

../examples/s3l/dense_matrix_ops/norm2.c
../examples/s3l/dense_matrix_ops-f/norm2.f

Related Functions

S3L_inner_prod(3)
S3L_outer_prod(3)
S3L_mat_vec_mult(3)
S3L_mat_mult(3)