Skip to content

Commit 6ee0878

Browse files
Cirdans-HomeCirdans-Home
committed
Merged with documentation modification
2 parents 4cd6cf2 + c916b92 commit 6ee0878

File tree

3 files changed

+86
-54
lines changed

3 files changed

+86
-54
lines changed

‎docs/html/userhtmlse6.html‎

Lines changed: 72 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -3872,72 +3872,76 @@ <h4 class="subsectionHead"><span class="titlemark">6.27 </span> <a
38723872
id="x12-1050006.27"></a>Sorting utilities &#8212; </h4>
38733873
<!--l. 1783--><p class="noindent" ><span
38743874
class="pplb7t-x-x-120">psb</span><span
3875-
class="pplb7t-x-x-120">_msort &#8212; Sorting by the Merge-sort algorithm</span>
3875+
class="pplb7t-x-x-120">_isort &#8212; Sorting by the Insertion-sort algorithm</span>
38763876
<!--l. 1786--><p class="noindent" ><span
38773877
class="pplb7t-x-x-120">psb</span><span
3878-
class="pplb7t-x-x-120">_qsort &#8212; Sorting by the Quicksort algorithm</span>
3878+
class="pplb7t-x-x-120">_msort &#8212; Sorting by the Merge-sort algorithm</span>
38793879
<!--l. 1789--><p class="noindent" ><span
38803880
class="pplb7t-x-x-120">psb</span><span
3881+
class="pplb7t-x-x-120">_qsort &#8212; Sorting by the Quicksort algorithm</span>
3882+
<!--l. 1792--><p class="noindent" ><span
3883+
class="pplb7t-x-x-120">psb</span><span
38813884
class="pplb7t-x-x-120">_hsort &#8212; Sorting by the Heapsort algorithm</span>
38823885

38833886

38843887

38853888
<pre class="verbatim" id="verbatim-60">
3889+
call&#x00A0;psb_isort(x,ix,dir,flag)
38863890
call&#x00A0;psb_msort(x,ix,dir,flag)
38873891
call&#x00A0;psb_qsort(x,ix,dir,flag)
38883892
call&#x00A0;psb_hsort(x,ix,dir,flag)
38893893
</pre>
3890-
<!--l. 1794--><p class="nopar" >
3891-
<!--l. 1796--><p class="indent" > These serial routines sort a sequence <span
3894+
<!--l. 1798--><p class="nopar" >
3895+
<!--l. 1800--><p class="indent" > These serial routines sort a sequence <span
38923896
class="zplmr7m-">X </span>into ascending or descending order. The
3893-
argument meaning is identical for the three calls; the only difference is the algorithm
3894-
used to accomplish the task (see Usage Notes below).
3897+
argument meaning is identical for all calls; the only difference is the algorithm used
3898+
to accomplish the task (see Usage Notes below).
38953899
<dl class="description"><dt class="description">
3896-
<!--l. 1801--><p class="noindent" >
3900+
<!--l. 1805--><p class="noindent" >
38973901
<span
38983902
class="pplb7t-">Type:</span> </dt><dd
38993903
class="description">
3900-
<!--l. 1801--><p class="noindent" >Asynchronous.
3904+
<!--l. 1805--><p class="noindent" >Asynchronous.
39013905
</dd><dt class="description">
3902-
<!--l. 1802--><p class="noindent" >
3906+
<!--l. 1806--><p class="noindent" >
39033907
<span
39043908
class="pplb7t-">On Entry</span> </dt><dd
39053909
class="description">
3906-
<!--l. 1802--><p class="noindent" >
3910+
<!--l. 1806--><p class="noindent" >
39073911
</dd><dt class="description">
3908-
<!--l. 1803--><p class="noindent" >
3912+
<!--l. 1807--><p class="noindent" >
39093913
<span
39103914
class="pplb7t-">x</span> </dt><dd
39113915
class="description">
3912-
<!--l. 1803--><p class="noindent" >The sequence to be sorted.<br
3916+
<!--l. 1807--><p class="noindent" >The sequence to be sorted.<br
39133917
class="newline" />Type:<span
39143918
class="pplb7t-">required</span>.<br
39153919
class="newline" />Specified as: an integer, real or complex array of rank 1.
39163920
</dd><dt class="description">
3917-
<!--l. 1806--><p class="noindent" >
3921+
<!--l. 1810--><p class="noindent" >
39183922
<span
39193923
class="pplb7t-">ix</span> </dt><dd
39203924
class="description">
3921-
<!--l. 1806--><p class="noindent" >A vector of indices.<br
3925+
<!--l. 1810--><p class="noindent" >A vector of indices.<br
39223926
class="newline" />Type:<span
39233927
class="pplb7t-">optional</span>.<br
39243928
class="newline" />Specified as: an integer array of (at least) the same size as <span
39253929
class="zplmr7m-">X</span>.
39263930
</dd><dt class="description">
3927-
<!--l. 1809--><p class="noindent" >
3931+
<!--l. 1813--><p class="noindent" >
39283932
<span
39293933
class="pplb7t-">dir</span> </dt><dd
39303934
class="description">
3931-
<!--l. 1809--><p class="noindent" >The desired ordering.<br
3935+
<!--l. 1813--><p class="noindent" >The desired ordering.<br
39323936
class="newline" />Type:<span
39333937
class="pplb7t-">optional</span>.<br
39343938
class="newline" />Specified as: an integer value:
39353939
<dl class="description"><dt class="description">
3936-
<!--l. 1812--><p class="noindent" >
3940+
<!--l. 1816--><p class="noindent" >
39373941
<span
39383942
class="pplb7t-">Integer and real data:</span> </dt><dd
39393943
class="description">
3940-
<!--l. 1812--><p class="noindent" ><span class="obeylines-h"><span class="verb"><span
3944+
<!--l. 1816--><p class="noindent" ><span class="obeylines-h"><span class="verb"><span
39413945
class="cmtt-10">psb_sort_up_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
39423946
class="cmtt-10">psb_sort_down_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
39433947
class="cmtt-10">psb_asort_up_</span></span></span>,
@@ -3948,23 +3952,23 @@ <h4 class="subsectionHead"><span class="titlemark">6.27 </span> <a
39483952

39493953

39503954
</dd><dt class="description">
3951-
<!--l. 1815--><p class="noindent" >
3955+
<!--l. 1819--><p class="noindent" >
39523956
<span
39533957
class="pplb7t-">Complex data:</span> </dt><dd
39543958
class="description">
3955-
<!--l. 1815--><p class="noindent" ><span class="obeylines-h"><span class="verb"><span
3959+
<!--l. 1819--><p class="noindent" ><span class="obeylines-h"><span class="verb"><span
39563960
class="cmtt-10">psb_lsort_up_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
39573961
class="cmtt-10">psb_lsort_down_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
39583962
class="cmtt-10">psb_asort_up_</span></span></span>,
39593963
<span class="obeylines-h"><span class="verb"><span
39603964
class="cmtt-10">psb_asort_down_</span></span></span>; default <span class="obeylines-h"><span class="verb"><span
39613965
class="cmtt-10">psb_lsort_up_</span></span></span>.</dd></dl>
39623966
</dd><dt class="description">
3963-
<!--l. 1819--><p class="noindent" >
3967+
<!--l. 1823--><p class="noindent" >
39643968
<span
39653969
class="pplb7t-">flag</span> </dt><dd
39663970
class="description">
3967-
<!--l. 1819--><p class="noindent" >Whether to keep the original values in <span
3971+
<!--l. 1823--><p class="noindent" >Whether to keep the original values in <span
39683972
class="zplmr7m-">IX</span>.<br
39693973
class="newline" />Type:<span
39703974
class="pplb7t-">optional</span>.<br
@@ -3974,44 +3978,44 @@ <h4 class="subsectionHead"><span class="titlemark">6.27 </span> <a
39743978
default <span class="obeylines-h"><span class="verb"><span
39753979
class="cmtt-10">psb_sort_ovw_idx_</span></span></span>.
39763980
</dd></dl>
3977-
<!--l. 1826--><p class="indent" >
3981+
<!--l. 1830--><p class="indent" >
39783982
<dl class="description"><dt class="description">
3979-
<!--l. 1827--><p class="noindent" >
3983+
<!--l. 1831--><p class="noindent" >
39803984
<span
39813985
class="pplb7t-">On Return</span> </dt><dd
39823986
class="description">
3983-
<!--l. 1827--><p class="noindent" >
3987+
<!--l. 1831--><p class="noindent" >
39843988
</dd><dt class="description">
3985-
<!--l. 1828--><p class="noindent" >
3989+
<!--l. 1832--><p class="noindent" >
39863990
<span
39873991
class="pplb7t-">x</span> </dt><dd
39883992
class="description">
3989-
<!--l. 1828--><p class="noindent" >The sequence of values, in the chosen ordering.<br
3993+
<!--l. 1832--><p class="noindent" >The sequence of values, in the chosen ordering.<br
39903994
class="newline" />Type:<span
39913995
class="pplb7t-">required</span>.<br
39923996
class="newline" />Specified as: an integer, real or complex array of rank 1.
39933997
</dd><dt class="description">
3994-
<!--l. 1831--><p class="noindent" >
3998+
<!--l. 1835--><p class="noindent" >
39953999
<span
39964000
class="pplb7t-">ix</span> </dt><dd
39974001
class="description">
3998-
<!--l. 1831--><p class="noindent" >A vector of indices.<br
4002+
<!--l. 1835--><p class="noindent" >A vector of indices.<br
39994003
class="newline" />Type: <span
40004004
class="pplb7t-">Optional </span><br
40014005
class="newline" />An integer array of rank 1, whose entries are moved to the same position
40024006
as the corresponding entries in <span
40034007
class="zplmr7m-">x</span>.</dd></dl>
4004-
<!--l. 1837--><p class="noindent" ><span
4008+
<!--l. 1841--><p class="noindent" ><span
40054009
class="pplb7t-x-x-120">Notes</span>
40064010
<ol class="enumerate1" >
40074011
<li
40084012
class="enumerate" id="x12-105002x1">
4009-
<!--l. 1839--><p class="noindent" >For integer or real data the sorting can be performed in the up/down
4013+
<!--l. 1843--><p class="noindent" >For integer or real data the sorting can be performed in the up/down
40104014
direction, on the natural or absolute values;
40114015
</li>
40124016
<li
40134017
class="enumerate" id="x12-105004x2">
4014-
<!--l. 1841--><p class="noindent" >For complex data the sorting can be done in a lexicographic order (i.e.:
4018+
<!--l. 1845--><p class="noindent" >For complex data the sorting can be done in a lexicographic order (i.e.:
40154019
sort on the real part with ties broken according to the imaginary part) or
40164020
on the absolute values;
40174021

@@ -4020,15 +4024,15 @@ <h4 class="subsectionHead"><span class="titlemark">6.27 </span> <a
40204024
</li>
40214025
<li
40224026
class="enumerate" id="x12-105006x3">
4023-
<!--l. 1844--><p class="noindent" >The routines return the items in the chosen ordering; the output
4027+
<!--l. 1848--><p class="noindent" >The routines return the items in the chosen ordering; the output
40244028
difference is the handling of ties (i.e. items with an equal value) in the
4025-
original input. With the merge-sort algorithm ties are preserved in the
4026-
same relative order as they had in the original sequence, while this is not
4027-
guaranteed for quicksort or heapsort;
4029+
original input. With the insertion-sort or merge-sort algorithms ties are
4030+
preserved in the same relative order as they had in the original sequence,
4031+
while this is not guaranteed for quicksort or heapsort;
40284032
</li>
40294033
<li
40304034
class="enumerate" id="x12-105008x4">
4031-
<!--l. 1850--><p class="noindent" >If <span
4035+
<!--l. 1854--><p class="noindent" >If <span
40324036
class="zplmr7m-">flag </span><span
40334037
class="zplmr7t-">= </span><span
40344038
class="zplmr7m-">psb</span>_<span
@@ -4063,7 +4067,7 @@ <h4 class="subsectionHead"><span class="titlemark">6.27 </span> <a
40634067
</li>
40644068
<li
40654069
class="enumerate" id="x12-105010x5">
4066-
<!--l. 1855--><p class="noindent" >If <span
4070+
<!--l. 1859--><p class="noindent" >If <span
40674071
class="zplmr7m-">flag </span><span
40684072
class="zplmr7t-">= </span><span
40694073
class="zplmr7m-">psb</span>_<span
@@ -4076,18 +4080,38 @@ <h4 class="subsectionHead"><span class="titlemark">6.27 </span> <a
40764080
</li>
40774081
<li
40784082
class="enumerate" id="x12-105012x6">
4079-
<!--l. 1857--><p class="noindent" >The three sorting algorithms have a similar <span
4083+
<!--l. 1861--><p class="noindent" >Three sorting algorithms have a similar <span
40804084
class="zplmr7m-">O</span><span
40814085
class="zplmr7t-">(</span><span
40824086
class="zplmr7m-">n</span> log <span
40834087
class="zplmr7m-">n</span><span
4084-
class="zplmr7t-">) </span>expected running time;
4088+
class="zplmr7t-">) </span>expected running time,
4089+
whereas insertion sort has an expected running time <span
4090+
class="zplmr7m-">O</span><span
4091+
class="zplmr7t-">(</span><span
4092+
class="zplmr7m-">n</span><sup><span
4093+
class="pplr7t-x-x-76">2</span></sup><span
4094+
class="zplmr7t-">)</span>; of the other three,
40854095
in the average case quicksort will be the fastest and merge-sort the slowest.
40864096
However note that:
40874097
<ol class="enumerate2" >
40884098
<li
40894099
class="enumerate" id="x12-105014x1">
4090-
<!--l. 1861--><p class="noindent" >The worst case running time
4100+
<!--l. 1866--><p class="noindent" >The the best case running time for insertion sort is <span
4101+
class="zplmr7t-">&#x03A9;(</span><span
4102+
class="zplmr7m-">n</span><span
4103+
class="zplmr7t-">) </span>while the
4104+
average and worst case are <span
4105+
class="zplmr7m-">O</span><span
4106+
class="zplmr7t-">(</span><span
4107+
class="zplmr7m-">n</span><sup><span
4108+
class="pplr7t-x-x-76">2</span></sup><span
4109+
class="zplmr7t-">)</span>; however for very short input
4110+
sequences this is likely to be the fastest method;
4111+
</li>
4112+
<li
4113+
class="enumerate" id="x12-105016x2">
4114+
<!--l. 1869--><p class="noindent" >The worst case running time
40914115
for quicksort is <span
40924116
class="zplmr7m-">O</span><span
40934117
class="zplmr7t-">(</span><span
@@ -4098,24 +4122,24 @@ <h4 class="subsectionHead"><span class="titlemark">6.27 </span> <a
40984122
apply;
40994123
</li>
41004124
<li
4101-
class="enumerate" id="x12-105016x2">
4102-
<!--l. 1864--><p class="noindent" >The worst case running time for merge-sort and heap-sort is
4125+
class="enumerate" id="x12-105018x3">
4126+
<!--l. 1872--><p class="noindent" >The worst case running time for merge-sort and heap-sort is
41034127
<span
41044128
class="zplmr7m-">O</span><span
41054129
class="zplmr7t-">(</span><span
41064130
class="zplmr7m-">n</span> log <span
41074131
class="zplmr7m-">n</span><span
41084132
class="zplmr7t-">) </span>as the average case;
4133+
4134+
4135+
41094136
</li>
41104137
<li
4111-
class="enumerate" id="x12-105018x3">
4112-
<!--l. 1866--><p class="noindent" >The merge-sort algorithm is implemented to take advantage of
4138+
class="enumerate" id="x12-105020x4">
4139+
<!--l. 1874--><p class="noindent" >The merge-sort algorithm is implemented to take advantage of
41134140
subsequences that may be already in the desired ordering prior to
41144141
the subroutine call; this situation is relatively common when dealing
41154142
with groups of indices of sparse matrix entries, thus merge-sort is
4116-
4117-
4118-
41194143
the preferred choice when a sorting is needed by other routines in
41204144
the library.</li></ol>
41214145
</li></ol>

‎docs/psblas-3.9.pdf‎

2.36 KB
Binary file not shown.

‎docs/src/toolsrout.tex‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1780,6 +1780,9 @@ \subsection{psb\_cdall --- Allocates a communication descriptor}
17801780
\clearpage\subsection{Sorting utilities --- }
17811781
%\addcontentsline{toc}{subsection}{Sorting utilities}
17821782

1783+
{\par\noindent\large\bfseries psb\_isort --- Sorting by the Insertion-sort
1784+
algorithm}
1785+
17831786
{\par\noindent\large\bfseries psb\_msort --- Sorting by the Merge-sort
17841787
algorithm}
17851788

@@ -1788,13 +1791,14 @@ \subsection{psb\_cdall --- Allocates a communication descriptor}
17881791

17891792
{\par\noindent\large\bfseries psb\_hsort --- Sorting by the Heapsort algorithm}
17901793
\begin{verbatim}
1794+
call psb_isort(x,ix,dir,flag)
17911795
call psb_msort(x,ix,dir,flag)
17921796
call psb_qsort(x,ix,dir,flag)
17931797
call psb_hsort(x,ix,dir,flag)
17941798
\end{verbatim}
17951799

17961800
These serial routines sort a sequence $X$ into ascending or
1797-
descending order. The argument meaning is identical for the three
1801+
descending order. The argument meaning is identical for all
17981802
calls; the only difference is the algorithm used to accomplish the
17991803
task (see Usage Notes below).
18001804
\begin{description}
@@ -1843,7 +1847,7 @@ \subsection{psb\_cdall --- Allocates a communication descriptor}
18431847
the imaginary part) or on the absolute values;
18441848
\item The routines return the items in the chosen ordering; the
18451849
output difference is the handling of ties (i.e. items with an
1846-
equal value) in the original input. With the merge-sort algorithm
1850+
equal value) in the original input. With the insertion-sort or merge-sort algorithms
18471851
ties are preserved in the same relative order as they had in the
18481852
original sequence, while this is not guaranteed for quicksort or
18491853
heapsort;
@@ -1854,11 +1858,15 @@ \subsection{psb\_cdall --- Allocates a communication descriptor}
18541858
occupied in the original data sequence;
18551859
\item If $flag = psb\_sort\_keep\_idx\_$ the routine will assume that
18561860
the entries in $ix(:)$ have already been initialized by the user;
1857-
\item The three sorting algorithms have a similar $O(n \log n)$ expected
1858-
running time; in the average case quicksort will be the
1861+
\item Three sorting algorithms have a similar $O(n \log n)$ expected
1862+
running time, whereas insertion sort has an expected running time
1863+
$O(n^2)$; of the other three, in the average case quicksort will be the
18591864
fastest and merge-sort the slowest. However note that:
1860-
\begin{enumerate}
1861-
\item The worst case running time for quicksort is $O(n^2)$; the algorithm
1865+
\begin{enumerate}
1866+
\item The the best case running time for insertion sort is $\Omega(n)$ while the average
1867+
and worst case are $O(n^2)$; however for very short input sequences this is
1868+
likely to be the fastest method;
1869+
\item The worst case running time for quicksort is $O(n^2)$; the algorithm
18621870
implemented here follows the well-known median-of-three heuristics,
18631871
but the worst case may still apply;
18641872
\item The worst case running time for merge-sort and heap-sort is

0 commit comments

Comments
 (0)