Sorting utilities

psb_msort -- Sorting by the Merge-sort algorithm

psb_qsort -- Sorting by the Quicksort algorithm

psb_hsort -- Sorting by the Heapsort algorithm

call psb_msort(x,ix,dir,flag)
call psb_qsort(x,ix,dir,flag)
call psb_hsort(x,ix,dir,flag)

These serial routines sort a sequence $X$ into ascending or descending order. The argument meaning is identical for the three calls; the only difference is the algorithm used to accomplish the task (see Usage Notes below).

Type:

Asynchronous.

On Entry

x

The sequence to be sorted.
Type:required.
Specified as: an integer, real or complex array of rank 1.

ix

A vector of indices.
Type:optional.
Specified as: an integer array of (at least) the same size as $X$.

dir

The desired ordering.
Type:optional.
Specified as: an integer value:

Integer and real data:

psb_sort_up_, psb_sort_down_, psb_asort_up_, psb_asort_down_; default psb_sort_up_.

Complex data:

psb_lsort_up_, psb_lsort_down_, psb_asort_up_, psb_asort_down_; default psb_lsort_up_.

flag

Whether to keep the original values in $IX$.
Type:optional.
Specified as: an integer value psb_sort_ovw_idx_ or psb_sort_keep_idx_; default psb_sort_ovw_idx_.

On Return

x

The sequence of values, in the chosen ordering.
Type:required.
Specified as: an integer, real or complex array of rank 1.

ix

A vector of indices.
Type: Optional
An integer array of rank 1, whose entries are moved to the same position as the corresponding entries in $x$.

Notes

1. For integer or real data the sorting can be performed in the up/down direction, on the natural or absolute values;
2. For complex data the sorting can be done in a lexicographic order (i.e.: sort on the real part with ties broken according to the imaginary part) or on the absolute values;
3. The routines return the items in the chosen ordering; the output difference is the handling of ties (i.e. items with an equal value) in the original input. With the merge-sort algorithm ties are preserved in the same relative order as they had in the original sequence, while this is not guaranteed for quicksort or heapsort;
4. If $flag = psb\_sort\_ovw\_idx\_$ then the entries in $ix(1:n)$ where $n$ is the size of $x$ are initialized to $ix(i) \leftarrow i$; thus, upon return from the subroutine, for each index $i$ we have in $ix(i)$ the position that the item $x(i)$ occupied in the original data sequence;
5. If $flag = psb\_sort\_keep\_idx\_$ the routine will assume that the entries in $ix(:)$ have already been initialized by the user;
6. The three sorting algorithms have a similar $O(n \log n)$ expected running time; in the average case quicksort will be the fastest and merge-sort the slowest. However note that:
   1. The worst case running time for quicksort is $O(n^2)$; the algorithm implemented here follows the well-known median-of-three heuristics, but the worst case may still apply;
   2. The worst case running time for merge-sort and heap-sort is $O(n \log n)$ as the average case;
   3. The merge-sort algorithm is implemented to take advantage of subsequences that may be already in the desired ordering prior to the subroutine call; this situation is relatively common when dealing with groups of indices of sparse matrix entries, thus merge-sort is often the preferred choice when a sorting is needed by other routines in the library.