Sun S3L 3.0 Programming and Reference Guide

Multidimensional Sort and Grade

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

`S3L_sort`, `S3L_sort_up`, `S3L_sort_down`, `S3L_sort_detailed_up`, `S3L_sort_detailed_down`

Description

The S3L_sort function sorts the elements of a one-dimensional array in ascending order.

S3L_sort_up and S3L_sort_down sort the elements of one-dimensional or multidimensional array in ascending and descending order, respectively.

Note -

S3L_sort is a special case of S3L_sort_up.

When A is one-dimensional, the result is a vector that contains the same elements as A, but arranged in ascending order (S3L_sort or S3L_sort_up) or descending order. For example, if A contains

Example 8-113

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

calling S3L_sort or S3L_sort_up would produce the result

Example 8-114

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

If A is multidimensional, the elements are sorted into an index-based sequence, starting with the first row-column index and progressing through the row indices first before advancing to the next column index position.

For example if A contains

Example 8-115

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

S3L_sort_up would produce the result

Example 8-116

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

and S3L_sort_down would produce the result

Example 8-117

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

S3L_sort_detailed_up and S3L_sort_detailed_down sort the elements of one-dimensional or multidimensional arrays in ascending and descending order along the axis specified by the axis argument.

Note -

The value of the axis argument is language dependent. For C/C++ applications, it must be zero-based and for F77/F90 applications, it must be one-based.

If the array referenced by A contains

Example 8-118

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

and a C program calls S3L_sort_detailed_up with axis = 0, upon completion, A will contain

Example 8-119

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

Or, if a C program calls S3L_sort_detailed_up with axis = 1, upon completion, A will contain

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

If these calls were made from an F77 or F90 program, the axis values would need to be one greater (that is, 1 and 2, respectively) to achieve the same results.

Syntax

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

C/C++ Syntax

Example 8-120

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_sort(A)
S3L_sort_up(A)
S3L_sort_down(A)
S3L_sort_detailed_up(A, axis)
S3L_sort_detailed_down(A, axis)
    S3L_array_t       A
    int               axis

F77/F90 Syntax

Example 8-121

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_sort(A, ier)
S3L_sort_up(A, ier)
S3L_sort_down(A, ier)
S3L_sort_detailed_up(A, axis, ier)
S3L_sort_detailed_down(A, axis, ier)
    integer*8         A
    integer*4         axis
    integer*4         ier

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

Input

A - For S3L_sort, A must be a one-dimensional array. For S3L_sort_up, S3L_sort_down, S3L_sort_detailed_up, and S3L_sort_detailed_down, A can be one-dimensional or multidimensional.
axis - Used with S3L_sort_detailed_up and S3L_sort_detailed_down to specify which axis of A is to be sorted. If A is one-dimensional, axis must be zero (for C/C++) or 1 (for F77/F90). It may not be used in S3L_sort, S3L_sort_up, or S3L_sort_down calls.

Output

These functions use the following arguments for output:

A - On output, A contains the sorted array.

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 all check 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_DTYPE - The type of the array is invalid. It must be one of: S3L_integer, S3L_long_integer, S3L_float or S3L_double.

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/sort/sort1.c
../examples/s3l/sort/ex_sort2.c
../examples/s3l/sort-f/sort1.f

Related Functions

S3L_grade_up(3)
S3L_grade_detailed_down(3)
S3L_grade_detailed_up(3)

Multidimensional Sort and Grade

S3L_grade_down, S3L_grade_up, S3L_grade_down_detailed, S3L_grade_up_detailed

Description

S3L_grade_down and S3L_grade_up

Example 8-102

Example 8-103

Example 8-104

Example 8-105

S3L_grade_detailed_down and S3L_grade_detailed_up

Example 8-106

Example 8-107

Example 8-108

Example 8-109

Example 8-110

Syntax

C/C++ Syntax

Example 8-111

F77/F90 Syntax

Example 8-112

Input

Output

Error Handling

Examples

Related Functions

S3L_sort, S3L_sort_up, S3L_sort_down, S3L_sort_detailed_up, S3L_sort_detailed_down

Description

Example 8-113

Example 8-114

Example 8-115

Example 8-116

Example 8-117

Example 8-118

Example 8-119

Syntax

C/C++ Syntax

Example 8-120

F77/F90 Syntax

Example 8-121

Input

Output

Error Handling

Examples

Related Functions

`S3L_grade_down`, `S3L_grade_up`, `S3L_grade_down_detailed`, `S3L_grade_up_detailed`

`S3L_grade_down` and `S3L_grade_up`

`S3L_grade_detailed_down` and `S3L_grade_detailed_up`

`S3L_sort`, `S3L_sort_up`, `S3L_sort_down`, `S3L_sort_detailed_up`, `S3L_sort_detailed_down`