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.
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
_ _ | 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.
_ _ | 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).
_ _ | 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.
_ _ | 2 1 2 1 3 1 3 2 3 | | | | 1 2 2 3 3 1 2 3 1 | - - |
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,
_ _ | 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:
_ _ | 1 2 2 | | | | 2 1 0 | | | | 0 0 1 | - - |
If, instead, axis = 1, G will contain
_ _ | 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
_ _ | 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
_ _ | 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.
The C and Fortran syntax for these functions are shown below.
#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 |
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.
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.
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.
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/s3l/grade/ex_grade.c ../examples/s3l/grade-f/ex_grade.f
S3L_sort(3) S3L_sort_detailed_up(3) S3L_sort_detailed_down(3)
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.
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
_ _ | 7 2 4 3 1 8 6 9 5 | - - |
calling S3L_sort or S3L_sort_up would produce the result
_ _ | 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
_ _ | 6 2 7 | | | | 1 4 3 | | | | 9 5 8 | - - |
S3L_sort_up would produce the result
_ _ | 1 4 7 | | | | 2 5 8 | | | | 3 6 9 | - - |
and S3L_sort_down would produce the result
_ _ | 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.
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
_ _ | 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
_ _ | 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.
The C and Fortran syntax for these functions are shown below.
#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 |
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.
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.
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.
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/s3l/sort/sort1.c ../examples/s3l/sort/ex_sort2.c ../examples/s3l/sort-f/sort1.f
S3L_grade_up(3) S3L_grade_detailed_down(3) S3L_grade_detailed_up(3)