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:

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

Output

These functions use the following arguments for output:

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:

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

Output

These functions use the following arguments for output:

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:

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)