S3L_grade_down, S3L_grade_up, S3L_grade_down_detailed, S3L_grade_up_detailed

Description

The S3L_grade family of functions computes the grade of the elements of a parallel array A. Grading is done in either descending or ascending order and is done either across the whole array or along a specified axis. The graded elements are stored in array G, using zero-based indexing when called from a C or C++ program and one-based indexing when called from an F77 or F90 program.

S3L_grade_down and S3L_grade_up

These two functions grade the elements across the entire array A and store the indices of the elements in descending or ascending order (S3L_grade_down or S3L_grade_up, respectively).

If A is an array of rank n and the product of its extents is l, G is a two-dimensional array whose extents are n x l.

Upon return of the function, every j-th column of array G is set to the indices of the j-th smallest (S3L_grade_down) or largest (S3L_grade_up) element of array A.

For example, if A is the 3 x 3 array

Example 8-102

   _         _
  | 6   2   4 |
  |           |
  | 1   3   8 |
  |           |
  | 9   7   5 |
   -         -

and S3L_grade_down is called from a C program, it will store the following values in G.

Example 8-103

   _                         _
  | 2  1  2  0  2  0  1  0  1 |
  |                           |
  | 0  2  1  0  2  2  1  1  0 |
   -                         -

For the same array A, S3L_grade_up would store the following values in G (again, using zero-based indexing).

Example 8-104

   _                         _
  | 1  0  1  0  2  0  2  1  2 |
  |                           |
  | 0  1  1  2  2  0  1  2  0 |
   -                         -

When called by a Fortran program (F77/F90) each value in G would be one greater. For example, S3L_grade_up would store the following set of values.

Example 8-105

   _                         _
  | 2  1  2  1  3  1  3  2  3 |
  |                           |
  | 1  2  2  3  3  1  2  3  1 |
   -                         -

S3L_grade_detailed_down and S3L_grade_detailed_up

The S3L_grade_detailed_down and S3L_grade_detailed_up functions differ from S3L_grade_down and S3L_grade_up in two respects:

• Both grade along a single axis of A, as specified by the axis argument.

• Both store a set of indices, but these indices do not indicate element positions directly. Instead, each stored index indicates the index of the corresponding element of A that has either

  • The j-th smallest value along the specified axis - S3L_grade_detailed_down

  • The j-th largest value along the specified axis - S3L_grade_detailed_up

This means G is an integer array whose rank and extents are the same as those of A.

Repeating the 3 x 3 sample array shown above,

Example 8-106

   _         _
  | 6   2   4 |
  |           |
  | 1   3   8 |
  |           |
  | 9   7   5 |
   -         -

if S3_grade_detailed_down is called from a C program with the axis argument = 0, upon completion, G will contain the following values:

Example 8-107

   _         _
  | 1   2   2 |
  |           |
  | 2   1   0 |
  |           |
  | 0   0   1 |
   -         -

If, instead, axis = 1, G will contain

Example 8-108

   _         _
  | 0   2   1 |
  |           |
  | 2   1   0 |
  |           |
  | 0   1   2 |
   -         -

If S3L_grade_detailed_up is called from a C program with axis = 0, G will contain

Example 8-109

   _         _
  | 1   0   0 |
  |           |
  | 0   1   2 |
  |           |
  | 2   2   1 |
   -         -

If S3L_grade_detailed_up is called from a C program with axis = 1, G will contain

Example 8-110

   _         _
  | 2   0   1 |
  |           |
  | 0   1   2 |
  |           |
  | 2   1   0 |
   -         -

For F77 or F90 calls, each index value in these examples, including the axis argument, would be increased by 1.

Syntax

The C and Fortran syntax for these functions are shown below.

C/C++ Syntax

Example 8-111

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_grade_up(A, grade)
S3L_grade_down(A, grade)
S3L_grade_up_detailed(A, grade, axis)
S3L_grade_down_detailed(A, grade, axis)
    S3L_array_t       A
    S3L_array_t       grade
    S3L_array_t       axis

F77/F90 Syntax

Example 8-112

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_grade_up(A, grade, ier)
S3L_grade_down(A, grade, ier)
S3L_grade_up_detailed(A, grade, axis, ier)
S3L_grade_down_detailed(A, grade, axis, ier)
    integer*8         A
    integer*8         grade
    integer*8         axis
    integer*4         ier

where <type> is real*4 or real*8 for both C/C++ and F77/F90.

Input

• A - S3L internal array handle for the array to be graded. Its type can be real, double, integer, or long integer.

• axis - The axis along which S3L_grade_detailed_down or S3L_grade_detailed_up is to be computed. It may not be used in S3L_grade_down or S3L_grade_up calls.

Output

These functions use the following arguments for output:

• grade - S3L internal array handle for an integer array. Upon successful completion, grade contains the indices of the order of the elements.

• ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, these functions return S3L_SUCCESS.

These functions perform generic checking 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 condition will cause the functions to terminate and return the associated code:

• S3L_ERR_ARG_AXISNUM - The axis argument has an invalid value. The correct values for axis are

  • 0 <= axis < rank of a (C/C++)

  • 0 < axis <= rank of a (F77/F90)

Examples

../examples/s3l/grade/ex_grade.c
../examples/s3l/grade-f/ex_grade.f

Related Functions

S3L_sort(3)
S3L_sort_detailed_up(3)
S3L_sort_detailed_down(3)