fdurastante/psblas3
1
0
Fork 0
mirror of https://github.com/sfilippone/psblas3.git synced 2026-10-06 22:55:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update sorting docs

Browse Source
This commit is contained in:
Salvatore Filippone
2025-09-30 19:09:03 +02:00
parent 25f73d15db
commit 2f514d1959
3 changed files with 2065 additions and 2003 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/html/userhtmlse6.html
+74 -50
View File
@@ -3872,72 +3872,76 @@ class="cmtt-10">integer(psb_long_int_k_)</span></span></span> number.</dd></dl>
id="x12-1050006.27"></a>Sorting utilities &#8212; </h4>
<!--l. 1783--><p class="noindent" ><span
class="pplb7t-x-x-120">psb</span><span
class="pplb7t-x-x-120">_msort &#8212; Sorting by the Merge-sort algorithm</span>
class="pplb7t-x-x-120">_isort &#8212; Sorting by the Insertion-sort algorithm</span>
<!--l. 1786--><p class="noindent" ><span
class="pplb7t-x-x-120">psb</span><span
class="pplb7t-x-x-120">_qsort &#8212; Sorting by the Quicksort algorithm</span>
class="pplb7t-x-x-120">_msort &#8212; Sorting by the Merge-sort algorithm</span>
<!--l. 1789--><p class="noindent" ><span
class="pplb7t-x-x-120">psb</span><span
class="pplb7t-x-x-120">_qsort &#8212; Sorting by the Quicksort algorithm</span>
<!--l. 1792--><p class="noindent" ><span
class="pplb7t-x-x-120">psb</span><span
class="pplb7t-x-x-120">_hsort &#8212; Sorting by the Heapsort algorithm</span>
<pre class="verbatim" id="verbatim-60">
call&#x00A0;psb_isort(x,ix,dir,flag)
call&#x00A0;psb_msort(x,ix,dir,flag)
call&#x00A0;psb_qsort(x,ix,dir,flag)
call&#x00A0;psb_hsort(x,ix,dir,flag)
</pre>
<!--l. 1794--><p class="nopar" >
<!--l. 1796--><p class="indent" > These serial routines sort a sequence <span
<!--l. 1798--><p class="nopar" >
<!--l. 1800--><p class="indent" > These serial routines sort a sequence <span
class="zplmr7m-">X </span>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).
argument meaning is identical for all calls; the only difference is the algorithm used
to accomplish the task (see Usage Notes below).
<dl class="description"><dt class="description">
<!--l. 1801--><p class="noindent" >
<!--l. 1805--><p class="noindent" >
<span
class="pplb7t-">Type:</span> </dt><dd
class="description">
<!--l. 1801--><p class="noindent" >Asynchronous.
<!--l. 1805--><p class="noindent" >Asynchronous.
</dd><dt class="description">
<!--l. 1802--><p class="noindent" >
<!--l. 1806--><p class="noindent" >
<span
class="pplb7t-">On Entry</span> </dt><dd
class="description">
<!--l. 1802--><p class="noindent" >
<!--l. 1806--><p class="noindent" >
</dd><dt class="description">
<!--l. 1803--><p class="noindent" >
<!--l. 1807--><p class="noindent" >
<span
class="pplb7t-">x</span> </dt><dd
class="description">
<!--l. 1803--><p class="noindent" >The sequence to be sorted.<br
<!--l. 1807--><p class="noindent" >The sequence to be sorted.<br
class="newline" />Type:<span
class="pplb7t-">required</span>.<br
class="newline" />Specified as: an integer, real or complex array of rank 1.
</dd><dt class="description">
<!--l. 1806--><p class="noindent" >
<!--l. 1810--><p class="noindent" >
<span
class="pplb7t-">ix</span> </dt><dd
class="description">
<!--l. 1806--><p class="noindent" >A vector of indices.<br
<!--l. 1810--><p class="noindent" >A vector of indices.<br
class="newline" />Type:<span
class="pplb7t-">optional</span>.<br
class="newline" />Specified as: an integer array of (at least) the same size as <span
class="zplmr7m-">X</span>.
</dd><dt class="description">
<!--l. 1809--><p class="noindent" >
<!--l. 1813--><p class="noindent" >
<span
class="pplb7t-">dir</span> </dt><dd
class="description">
<!--l. 1809--><p class="noindent" >The desired ordering.<br
<!--l. 1813--><p class="noindent" >The desired ordering.<br
class="newline" />Type:<span
class="pplb7t-">optional</span>.<br
class="newline" />Specified as: an integer value:
<dl class="description"><dt class="description">
<!--l. 1812--><p class="noindent" >
<!--l. 1816--><p class="noindent" >
<span
class="pplb7t-">Integer and real data:</span> </dt><dd
class="description">
<!--l. 1812--><p class="noindent" ><span class="obeylines-h"><span class="verb"><span
<!--l. 1816--><p class="noindent" ><span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_sort_up_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_sort_down_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_asort_up_</span></span></span>,
@@ -3948,11 +3952,11 @@ class="cmtt-10">psb_sort_up_</span></span></span>.
</dd><dt class="description">
<!--l. 1815--><p class="noindent" >
<!--l. 1819--><p class="noindent" >
<span
class="pplb7t-">Complex data:</span> </dt><dd
class="description">
<!--l. 1815--><p class="noindent" ><span class="obeylines-h"><span class="verb"><span
<!--l. 1819--><p class="noindent" ><span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_lsort_up_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_lsort_down_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_asort_up_</span></span></span>,
@@ -3960,11 +3964,11 @@ class="cmtt-10">psb_asort_up_</span></span></span>,
class="cmtt-10">psb_asort_down_</span></span></span>; default <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_lsort_up_</span></span></span>.</dd></dl>
</dd><dt class="description">
<!--l. 1819--><p class="noindent" >
<!--l. 1823--><p class="noindent" >
<span
class="pplb7t-">flag</span> </dt><dd
class="description">
<!--l. 1819--><p class="noindent" >Whether to keep the original values in <span
<!--l. 1823--><p class="noindent" >Whether to keep the original values in <span
class="zplmr7m-">IX</span>.<br
class="newline" />Type:<span
class="pplb7t-">optional</span>.<br
@@ -3974,44 +3978,44 @@ class="cmtt-10">psb_sort_keep_idx_</span></span></span>;
default <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_sort_ovw_idx_</span></span></span>.
</dd></dl>
<!--l. 1826--><p class="indent" >
<!--l. 1830--><p class="indent" >
<dl class="description"><dt class="description">
<!--l. 1827--><p class="noindent" >
<!--l. 1831--><p class="noindent" >
<span
class="pplb7t-">On Return</span> </dt><dd
class="description">
<!--l. 1827--><p class="noindent" >
<!--l. 1831--><p class="noindent" >
</dd><dt class="description">
<!--l. 1828--><p class="noindent" >
<!--l. 1832--><p class="noindent" >
<span
class="pplb7t-">x</span> </dt><dd
class="description">
<!--l. 1828--><p class="noindent" >The sequence of values, in the chosen ordering.<br
<!--l. 1832--><p class="noindent" >The sequence of values, in the chosen ordering.<br
class="newline" />Type:<span
class="pplb7t-">required</span>.<br
class="newline" />Specified as: an integer, real or complex array of rank 1.
</dd><dt class="description">
<!--l. 1831--><p class="noindent" >
<!--l. 1835--><p class="noindent" >
<span
class="pplb7t-">ix</span> </dt><dd
class="description">
<!--l. 1831--><p class="noindent" >A vector of indices.<br
<!--l. 1835--><p class="noindent" >A vector of indices.<br
class="newline" />Type: <span
class="pplb7t-">Optional </span><br
class="newline" />An integer array of rank 1, whose entries are moved to the same position
as the corresponding entries in <span
class="zplmr7m-">x</span>.</dd></dl>
<!--l. 1837--><p class="noindent" ><span
<!--l. 1841--><p class="noindent" ><span
class="pplb7t-x-x-120">Notes</span>
<ol class="enumerate1" >
<li
class="enumerate" id="x12-105002x1">
<!--l. 1839--><p class="noindent" >For integer or real data the sorting can be performed in the up/down
<!--l. 1843--><p class="noindent" >For integer or real data the sorting can be performed in the up/down
direction, on the natural or absolute values;
</li>
<li
class="enumerate" id="x12-105004x2">
<!--l. 1841--><p class="noindent" >For complex data the sorting can be done in a lexicographic order (i.e.:
<!--l. 1845--><p class="noindent" >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;
@@ -4020,15 +4024,15 @@ class="pplb7t-x-x-120">Notes</span>
</li>
<li
class="enumerate" id="x12-105006x3">
<!--l. 1844--><p class="noindent" >The routines return the items in the chosen ordering; the output
<!--l. 1848--><p class="noindent" >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;
original input. With the insertion-sort or merge-sort algorithms ties are
preserved in the same relative order as they had in the original sequence,
while this is not guaranteed for quicksort or heapsort;
</li>
<li
class="enumerate" id="x12-105008x4">
<!--l. 1850--><p class="noindent" >If <span
<!--l. 1854--><p class="noindent" >If <span
class="zplmr7m-">flag </span><span
class="zplmr7t-">= </span><span
class="zplmr7m-">psb</span>_<span
@@ -4063,7 +4067,7 @@ class="zplmr7t-">) </span>occupied
</li>
<li
class="enumerate" id="x12-105010x5">
<!--l. 1855--><p class="noindent" >If <span
<!--l. 1859--><p class="noindent" >If <span
class="zplmr7m-">flag </span><span
class="zplmr7t-">= </span><span
class="zplmr7m-">psb</span>_<span
@@ -4076,18 +4080,38 @@ class="zplmr7t-">(:) </span>have already been initialized by the user;
</li>
<li
class="enumerate" id="x12-105012x6">
<!--l. 1857--><p class="noindent" >The three sorting algorithms have a similar <span
<!--l. 1861--><p class="noindent" >Three sorting algorithms have a similar <span
class="zplmr7m-">O</span><span
class="zplmr7t-">(</span><span
class="zplmr7m-">n</span> log <span
class="zplmr7m-">n</span><span
class="zplmr7t-">) </span>expected running time;
class="zplmr7t-">) </span>expected running time,
whereas insertion sort has an expected running time <span
class="zplmr7m-">O</span><span
class="zplmr7t-">(</span><span
class="zplmr7m-">n</span><sup><span
class="pplr7t-x-x-76">2</span></sup><span
class="zplmr7t-">)</span>; of the other three,
in the average case quicksort will be the fastest and merge-sort the slowest.
However note that:
<ol class="enumerate2" >
<li
class="enumerate" id="x12-105014x1">
<!--l. 1861--><p class="noindent" >The worst case running time
<!--l. 1866--><p class="noindent" >The the best case running time for insertion sort is <span
class="zplmr7t-">&#x03A9;(</span><span
class="zplmr7m-">n</span><span
class="zplmr7t-">) </span>while the
average and worst case are <span
class="zplmr7m-">O</span><span
class="zplmr7t-">(</span><span
class="zplmr7m-">n</span><sup><span
class="pplr7t-x-x-76">2</span></sup><span
class="zplmr7t-">)</span>; however for very short input
sequences this is likely to be the fastest method;
</li>
<li
class="enumerate" id="x12-105016x2">
<!--l. 1869--><p class="noindent" >The worst case running time
for quicksort is <span
class="zplmr7m-">O</span><span
class="zplmr7t-">(</span><span
@@ -4098,24 +4122,24 @@ class="zplmr7t-">)</span>; the algorithm implemented here follows the
apply;
</li>
<li
class="enumerate" id="x12-105016x2">
<!--l. 1864--><p class="noindent" >The worst case running time for merge-sort and heap-sort is
class="enumerate" id="x12-105018x3">
<!--l. 1872--><p class="noindent" >The worst case running time for merge-sort and heap-sort is
<span
class="zplmr7m-">O</span><span
class="zplmr7t-">(</span><span
class="zplmr7m-">n</span> log <span
class="zplmr7m-">n</span><span
class="zplmr7t-">) </span>as the average case;
</li>
<li
class="enumerate" id="x12-105018x3">
<!--l. 1866--><p class="noindent" >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
</li>
<li
class="enumerate" id="x12-105020x4">
<!--l. 1874--><p class="noindent" >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
the preferred choice when a sorting is needed by other routines in
the library.</li></ol>
</li></ol>
docs/psblas-3.9.pdf
+1977 -1947
View File
File diff suppressed because it is too large Load Diff
docs/src/toolsrout.tex
+14 -6
View File
@@ -1780,6 +1780,9 @@ Returned as: an \verb|integer(psb_long_int_k_)| number.
\clearpage\subsection{Sorting utilities --- }
%\addcontentsline{toc}{subsection}{Sorting utilities}
{\par\noindent\large\bfseries psb\_isort --- Sorting by the Insertion-sort
algorithm}
{\par\noindent\large\bfseries psb\_msort --- Sorting by the Merge-sort
algorithm}
@@ -1788,13 +1791,14 @@ Returned as: an \verb|integer(psb_long_int_k_)| number.
{\par\noindent\large\bfseries psb\_hsort --- Sorting by the Heapsort algorithm}
\begin{verbatim}
call psb_isort(x,ix,dir,flag)
call psb_msort(x,ix,dir,flag)
call psb_qsort(x,ix,dir,flag)
call psb_hsort(x,ix,dir,flag)
\end{verbatim}
These serial routines sort a sequence $X$ into ascending or
descending order. The argument meaning is identical for the three
descending order. The argument meaning is identical for all
calls; the only difference is the algorithm used to accomplish the
task (see Usage Notes below).
\begin{description}
@@ -1843,7 +1847,7 @@ position as the corresponding entries in $x$.
the imaginary part) or on the absolute values;
\item 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
equal value) in the original input. With the insertion-sort or merge-sort algorithms
ties are preserved in the same relative order as they had in the
original sequence, while this is not guaranteed for quicksort or
heapsort;
@@ -1854,11 +1858,15 @@ position as the corresponding entries in $x$.
occupied in the original data sequence;
\item If $flag = psb\_sort\_keep\_idx\_$ the routine will assume that
the entries in $ix(:)$ have already been initialized by the user;
\item The three sorting algorithms have a similar $O(n \log n)$ expected
running time; in the average case quicksort will be the
\item Three sorting algorithms have a similar $O(n \log n)$ expected
running time, whereas insertion sort has an expected running time
$O(n^2)$; of the other three, in the average case quicksort will be the
fastest and merge-sort the slowest. However note that:
\begin{enumerate}
\item The worst case running time for quicksort is $O(n^2)$; the algorithm
\begin{enumerate}
\item The the best case running time for insertion sort is $\Omega(n)$ while the average
and worst case are $O(n^2)$; however for very short input sequences this is
likely to be the fastest method;
\item 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;
\item The worst case running time for merge-sort and heap-sort is