fdurastante
/
psblas3
mirror of https://github.com/sfilippone/psblas3.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merged with documentation modification

Browse Source
pull/28/head
Fabio Durastante 8 months ago
parent 4cd6cf21d0 c916b9224e
commit 6ee08787a5
3 changed files with 1842 additions and 1780 deletions
Show Stats Download Patch File Download Diff File

120
docs/html/userhtmlse6.html
Unescape Escape 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> id="x12-1050006.27"></a>Sorting utilities &#8212; </h4>
<!--l. 1783--><p class="noindent" ><span <!--l. 1783--><p class="noindent" ><span
class="pplb7t-x-x-120">psb</span><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 <!--l. 1786--><p class="noindent" ><span
class="pplb7t-x-x-120">psb</span><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 <!--l. 1789--><p class="noindent" ><span
class="pplb7t-x-x-120">psb</span><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> class="pplb7t-x-x-120">_hsort &#8212; Sorting by the Heapsort algorithm</span>
<pre class="verbatim" id="verbatim-60"> <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_msort(x,ix,dir,flag)
call&#x00A0;psb_qsort(x,ix,dir,flag) call&#x00A0;psb_qsort(x,ix,dir,flag)
call&#x00A0;psb_hsort(x,ix,dir,flag) call&#x00A0;psb_hsort(x,ix,dir,flag)
</pre> </pre>
<!--l. 1794--><p class="nopar" > <!--l. 1798--><p class="nopar" >
<!--l. 1796--><p class="indent" > These serial routines sort a sequence <span <!--l. 1800--><p class="indent" > These serial routines sort a sequence <span
class="zplmr7m-">X </span>into ascending or descending order. The class="zplmr7m-">X </span>into ascending or descending order. The
argument meaning is identical for the three calls; the only difference is the algorithm argument meaning is identical for all calls; the only difference is the algorithm used
used to accomplish the task (see Usage Notes below). to accomplish the task (see Usage Notes below).
<dl class="description"><dt class="description"> <dl class="description"><dt class="description">
<!--l. 1801--><p class="noindent" > <!--l. 1805--><p class="noindent" >
<span <span
class="pplb7t-">Type:</span> </dt><dd class="pplb7t-">Type:</span> </dt><dd
class="description"> class="description">
<!--l. 1801--><p class="noindent" >Asynchronous. <!--l. 1805--><p class="noindent" >Asynchronous.
</dd><dt class="description"> </dd><dt class="description">
<!--l. 1802--><p class="noindent" > <!--l. 1806--><p class="noindent" >
<span <span
class="pplb7t-">On Entry</span> </dt><dd class="pplb7t-">On Entry</span> </dt><dd
class="description"> class="description">
<!--l. 1802--><p class="noindent" > <!--l. 1806--><p class="noindent" >
</dd><dt class="description"> </dd><dt class="description">
<!--l. 1803--><p class="noindent" > <!--l. 1807--><p class="noindent" >
<span <span
class="pplb7t-">x</span> </dt><dd class="pplb7t-">x</span> </dt><dd
class="description"> 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="newline" />Type:<span
class="pplb7t-">required</span>.<br class="pplb7t-">required</span>.<br
class="newline" />Specified as: an integer, real or complex array of rank 1. class="newline" />Specified as: an integer, real or complex array of rank 1.
</dd><dt class="description"> </dd><dt class="description">
<!--l. 1806--><p class="noindent" > <!--l. 1810--><p class="noindent" >
<span <span
class="pplb7t-">ix</span> </dt><dd class="pplb7t-">ix</span> </dt><dd
class="description"> 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="newline" />Type:<span
class="pplb7t-">optional</span>.<br class="pplb7t-">optional</span>.<br
class="newline" />Specified as: an integer array of (at least) the same size as <span class="newline" />Specified as: an integer array of (at least) the same size as <span
class="zplmr7m-">X</span>. class="zplmr7m-">X</span>.
</dd><dt class="description"> </dd><dt class="description">
<!--l. 1809--><p class="noindent" > <!--l. 1813--><p class="noindent" >
<span <span
class="pplb7t-">dir</span> </dt><dd class="pplb7t-">dir</span> </dt><dd
class="description"> 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="newline" />Type:<span
class="pplb7t-">optional</span>.<br class="pplb7t-">optional</span>.<br
class="newline" />Specified as: an integer value: class="newline" />Specified as: an integer value:
<dl class="description"><dt class="description"> <dl class="description"><dt class="description">
<!--l. 1812--><p class="noindent" > <!--l. 1816--><p class="noindent" >
<span <span
class="pplb7t-">Integer and real data:</span> </dt><dd class="pplb7t-">Integer and real data:</span> </dt><dd
class="description"> 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_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_sort_down_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_asort_up_</span></span></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"> </dd><dt class="description">
<!--l. 1815--><p class="noindent" > <!--l. 1819--><p class="noindent" >
<span <span
class="pplb7t-">Complex data:</span> </dt><dd class="pplb7t-">Complex data:</span> </dt><dd
class="description"> 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_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_lsort_down_</span></span></span>, <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_asort_up_</span></span></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_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> class="cmtt-10">psb_lsort_up_</span></span></span>.</dd></dl>
</dd><dt class="description"> </dd><dt class="description">
<!--l. 1819--><p class="noindent" > <!--l. 1823--><p class="noindent" >
<span <span
class="pplb7t-">flag</span> </dt><dd class="pplb7t-">flag</span> </dt><dd
class="description"> 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="zplmr7m-">IX</span>.<br
class="newline" />Type:<span class="newline" />Type:<span
class="pplb7t-">optional</span>.<br 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 default <span class="obeylines-h"><span class="verb"><span
class="cmtt-10">psb_sort_ovw_idx_</span></span></span>. class="cmtt-10">psb_sort_ovw_idx_</span></span></span>.
</dd></dl> </dd></dl>
<!--l. 1826--><p class="indent" > <!--l. 1830--><p class="indent" >
<dl class="description"><dt class="description"> <dl class="description"><dt class="description">
<!--l. 1827--><p class="noindent" > <!--l. 1831--><p class="noindent" >
<span <span
class="pplb7t-">On Return</span> </dt><dd class="pplb7t-">On Return</span> </dt><dd
class="description"> class="description">
<!--l. 1827--><p class="noindent" > <!--l. 1831--><p class="noindent" >
</dd><dt class="description"> </dd><dt class="description">
<!--l. 1828--><p class="noindent" > <!--l. 1832--><p class="noindent" >
<span <span
class="pplb7t-">x</span> </dt><dd class="pplb7t-">x</span> </dt><dd
class="description"> 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="newline" />Type:<span
class="pplb7t-">required</span>.<br class="pplb7t-">required</span>.<br
class="newline" />Specified as: an integer, real or complex array of rank 1. class="newline" />Specified as: an integer, real or complex array of rank 1.
</dd><dt class="description"> </dd><dt class="description">
<!--l. 1831--><p class="noindent" > <!--l. 1835--><p class="noindent" >
<span <span
class="pplb7t-">ix</span> </dt><dd class="pplb7t-">ix</span> </dt><dd
class="description"> 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="newline" />Type: <span
class="pplb7t-">Optional </span><br class="pplb7t-">Optional </span><br
class="newline" />An integer array of rank 1, whose entries are moved to the same position class="newline" />An integer array of rank 1, whose entries are moved to the same position
as the corresponding entries in <span as the corresponding entries in <span
class="zplmr7m-">x</span>.</dd></dl> 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> class="pplb7t-x-x-120">Notes</span>
<ol class="enumerate1" > <ol class="enumerate1" >
<li <li
class="enumerate" id="x12-105002x1"> 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; direction, on the natural or absolute values;
</li> </li>
<li <li
class="enumerate" id="x12-105004x2"> 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 sort on the real part with ties broken according to the imaginary part) or
on the absolute values; on the absolute values;
@ -4020,15 +4024,15 @@ class="pplb7t-x-x-120">Notes</span>
</li> </li>
<li <li
class="enumerate" id="x12-105006x3"> 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 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 original input. With the insertion-sort or merge-sort algorithms ties are
same relative order as they had in the original sequence, while this is not preserved in the same relative order as they had in the original sequence,
guaranteed for quicksort or heapsort; while this is not guaranteed for quicksort or heapsort;
</li> </li>
<li <li
class="enumerate" id="x12-105008x4"> 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="zplmr7m-">flag </span><span
class="zplmr7t-">= </span><span class="zplmr7t-">= </span><span
class="zplmr7m-">psb</span>_<span class="zplmr7m-">psb</span>_<span
@ -4063,7 +4067,7 @@ class="zplmr7t-">) </span>occupied
</li> </li>
<li <li
class="enumerate" id="x12-105010x5"> 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="zplmr7m-">flag </span><span
class="zplmr7t-">= </span><span class="zplmr7t-">= </span><span
class="zplmr7m-">psb</span>_<span class="zplmr7m-">psb</span>_<span
@ -4076,18 +4080,38 @@ class="zplmr7t-">(:) </span>have already been initialized by the user;
</li> </li>
<li <li
class="enumerate" id="x12-105012x6"> 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="zplmr7m-">O</span><span
class="zplmr7t-">(</span><span class="zplmr7t-">(</span><span
class="zplmr7m-">n</span> log <span class="zplmr7m-">n</span> log <span
class="zplmr7m-">n</span><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. in the average case quicksort will be the fastest and merge-sort the slowest.
However note that: However note that:
<ol class="enumerate2" > <ol class="enumerate2" >
<li <li
class="enumerate" id="x12-105014x1"> 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 for quicksort is <span
class="zplmr7m-">O</span><span class="zplmr7m-">O</span><span
class="zplmr7t-">(</span><span class="zplmr7t-">(</span><span
@ -4098,24 +4122,24 @@ class="zplmr7t-">)</span>; the algorithm implemented here follows the
apply; apply;
</li> </li>
<li <li
class="enumerate" id="x12-105016x2"> class="enumerate" id="x12-105018x3">
<!--l. 1864--><p class="noindent" >The worst case running time for merge-sort and heap-sort is <!--l. 1872--><p class="noindent" >The worst case running time for merge-sort and heap-sort is
<span <span
class="zplmr7m-">O</span><span class="zplmr7m-">O</span><span
class="zplmr7t-">(</span><span class="zplmr7t-">(</span><span
class="zplmr7m-">n</span> log <span class="zplmr7m-">n</span> log <span
class="zplmr7m-">n</span><span class="zplmr7m-">n</span><span
class="zplmr7t-">) </span>as the average case; class="zplmr7t-">) </span>as the average case;
</li> </li>
<li <li
class="enumerate" id="x12-105018x3"> class="enumerate" id="x12-105020x4">
<!--l. 1866--><p class="noindent" >The merge-sort algorithm is implemented to take advantage of <!--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 subsequences that may be already in the desired ordering prior to
the subroutine call; this situation is relatively common when dealing the subroutine call; this situation is relatively common when dealing
with groups of indices of sparse matrix entries, thus merge-sort is 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 preferred choice when a sorting is needed by other routines in
the library.</li></ol> the library.</li></ol>
</li></ol> </li></ol>

3482
docs/psblas-3.9.pdf
View File

File diff suppressed because it is too large Load Diff

20
docs/src/toolsrout.tex
Unescape Escape View File

@ -1780,6 +1780,9 @@ Returned as: an \verb|integer(psb_long_int_k_)| number.
\clearpage\subsection{Sorting utilities --- } \clearpage\subsection{Sorting utilities --- }
%\addcontentsline{toc}{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 {\par\noindent\large\bfseries psb\_msort --- Sorting by the Merge-sort
algorithm} 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} {\par\noindent\large\bfseries psb\_hsort --- Sorting by the Heapsort algorithm}
\begin{verbatim} \begin{verbatim}
call psb_isort(x,ix,dir,flag)
call psb_msort(x,ix,dir,flag) call psb_msort(x,ix,dir,flag)
call psb_qsort(x,ix,dir,flag) call psb_qsort(x,ix,dir,flag)
call psb_hsort(x,ix,dir,flag) call psb_hsort(x,ix,dir,flag)
\end{verbatim} \end{verbatim}
These serial routines sort a sequence $X$ into ascending or 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 calls; the only difference is the algorithm used to accomplish the
task (see Usage Notes below). task (see Usage Notes below).
\begin{description} \begin{description}
@ -1843,7 +1847,7 @@ position as the corresponding entries in $x$.
the imaginary part) or on the absolute values; the imaginary part) or on the absolute values;
\item The routines return the items in the chosen ordering; the \item The routines return the items in the chosen ordering; the
output difference is the handling of ties (i.e. items with an 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 ties are preserved in the same relative order as they had in the
original sequence, while this is not guaranteed for quicksort or original sequence, while this is not guaranteed for quicksort or
heapsort; heapsort;
@ -1854,11 +1858,15 @@ position as the corresponding entries in $x$.
occupied in the original data sequence; occupied in the original data sequence;
\item If $flag = psb\_sort\_keep\_idx\_$ the routine will assume that \item If $flag = psb\_sort\_keep\_idx\_$ the routine will assume that
the entries in $ix(:)$ have already been initialized by the user; the entries in $ix(:)$ have already been initialized by the user;
\item The three sorting algorithms have a similar $O(n \log n)$ expected \item Three sorting algorithms have a similar $O(n \log n)$ expected
running time; in the average case quicksort will be the 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: fastest and merge-sort the slowest. However note that:
\begin{enumerate} \begin{enumerate}
\item The worst case running time for quicksort is $O(n^2)$; the algorithm \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, implemented here follows the well-known median-of-three heuristics,
but the worst case may still apply; but the worst case may still apply;
\item The worst case running time for merge-sort and heap-sort is \item The worst case running time for merge-sort and heap-sort is

Write Preview
Loading…
Cancel
Save