Fixed docs on usage of modules. Taken out sorting routines from user's

guide (for the time being).

docs/pdf/datastruct.tex

@@ -8,9 +8,9 @@ communication descriptors and preconditioners.%%  These data structures
 %% are used for calling PSBLAS routines in Fortran~90 language and will
 %% be used to next chapters containing these callings.  
 
-All the data types and subroutine interfaces are defined in the module
+All the data types and the basic subroutine interfaces are defined in
-\verb|psb_base_mod|; this will have to be included by every user
+the module \verb|psb_base_mod|; this will have to be included by every
-subroutine that makes use of the library. 
+user subroutine that makes use of the library. 
 
 
 

docs/pdf/methods.tex

@@ -2,7 +2,8 @@
 \label{sec:methods}
 
 In this chapter we provide routines for preconditioners and iterative
-methods. 
+methods. The interfaces for Krylov subspace methods are available in
+the module \verb|psb_krylov_mod|.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %

docs/pdf/util.tex

@@ -1,78 +1,81 @@
 \section{Utilities}
 \label{sec:util}
 
-
+We have some utitlities available for input and output of
-\subroutine{}{Sorting utilities}
+sparsematrices; the interfaces to these routines are available in the
-
+module \verb|psb_util_mod|.
-\subroutine*{psb\_msort}{Sorting by the Merge-sort algorithm}
+
-\subroutine*{psb\_qsort}{Sorting by the Quicksort  algorithm}
+%% \subroutine{}{Sorting utilities}
-\syntax{call psb\_msort}{x,ix,dir,flag}
+
-\syntax*{call psb\_qsort}{x,ix,dir,flag}
+%% \subroutine*{psb\_msort}{Sorting by the Merge-sort algorithm}
-
+%% \subroutine*{psb\_qsort}{Sorting by the Quicksort  algorithm}
-These  serial routines sort a sequence $X$ into ascending or
+%% \syntax{call psb\_msort}{x,ix,dir,flag}
-descending  order. The argument meaning is identical for the two
+%% \syntax*{call psb\_qsort}{x,ix,dir,flag}
-calls; the only difference is the algorithm used to accomplish the
+
-task (see Usage Notes below). 
+%% These  serial routines sort a sequence $X$ into ascending or
-\begin{description}
+%% descending  order. The argument meaning is identical for the two
-\item[\bf  On Entry ]
+%% calls; the only difference is the algorithm used to accomplish the
-\item[x] The sequence to be sorted.\\
+%% task (see Usage Notes below). 
-Type:{\bf required}.\\
+%% \begin{description}
-Specified as: an integer array of rank 1.
+%% \item[\bf  On Entry ]
-\item[ix] A vector of indices.\\
+%% \item[x] The sequence to be sorted.\\
-Type:{\bf optional}.\\
+%% Type:{\bf required}.\\
-Specified as: an integer array of (at least) the same size as $X$.
+%% Specified as: an integer array of rank 1.
-\item[dir] The desired ordering.\\
+%% \item[ix] A vector of indices.\\
-Type:{\bf optional}.\\
+%% Type:{\bf optional}.\\
-Specified as: an integer value \verb|psb_sort_up_| or
+%% Specified as: an integer array of (at least) the same size as $X$.
-\verb|psb_sort_down_|; default \verb|psb_sort_up_|.
+%% \item[dir] The desired ordering.\\
-\item[flag] Whether to keep the original values in $IX$.\\
+%% Type:{\bf optional}.\\
-Type:{\bf optional}.\\
+%% Specified as: an integer value \verb|psb_sort_up_| or
-Specified as: an integer value \verb|psb_sort_ovw_idx_| or
+%% \verb|psb_sort_down_|; default \verb|psb_sort_up_|.
-\verb|psb_sort_keep_idx_|; default \verb|psb_sort_ovw_idx_|.
+%% \item[flag] Whether to keep the original values in $IX$.\\
-
+%% Type:{\bf optional}.\\
-\end{description}
+%% Specified as: an integer value \verb|psb_sort_ovw_idx_| or
-
+%% \verb|psb_sort_keep_idx_|; default \verb|psb_sort_ovw_idx_|.
-\begin{description}
+
-\item[\bf On Return]
+%% \end{description}
-\item[x] The sequence of values, in the chosen ordering.\\ 
+
-Type:{\bf required}.\\
+%% \begin{description}
-Specified as: an integer array of rank 1.
+%% \item[\bf On Return]
-\item[ix] A vector of indices.\\
+%% \item[x] The sequence of values, in the chosen ordering.\\ 
-Type: {\bf Optional} \\
+%% Type:{\bf required}.\\
-An integer array of rank 1, whose entries are moved to the same
+%% Specified as: an integer array of rank 1.
-position as the corresponding entries in $x$.
+%% \item[ix] A vector of indices.\\
-\end{description}
+%% Type: {\bf Optional} \\
-\section*{Usage notes}
+%% An integer array of rank 1, whose entries are moved to the same
-\begin{enumerate}
+%% position as the corresponding entries in $x$.
-\item The two routines return the items in the chosen ordering; the
+%% \end{description}
-  only output difference is the handling of  ties (i.e. items with an
+%% \section*{Usage notes}
-  equal   value) in the original input. With the merge-sort algorithm
+%% \begin{enumerate}
-  ties are   preserved in the same order as they had in the original
+%% \item The two routines return the items in the chosen ordering; the
-  sequence,   while this is not guaranteed for quicksort 
+%%   only output difference is the handling of  ties (i.e. items with an
-\item If $flag = psb\_sort\_ovw\_idx\_$ then the entries in $ix(1:n)$
+%%   equal   value) in the original input. With the merge-sort algorithm
-  where $n$ is the size of $x$ are initialized to $ix(i) \leftarrow
+%%   ties are   preserved in the same order as they had in the original
-  i$; thus, upon return from the subroutine, for each
+%%   sequence,   while this is not guaranteed for quicksort 
-  index $i$ we have in $ix(i)$ the position that the item $x(i)$
+%% \item If $flag = psb\_sort\_ovw\_idx\_$ then the entries in $ix(1:n)$
-  occupied in the original data sequence;
+%%   where $n$ is the size of $x$ are initialized to $ix(i) \leftarrow
-\item If $flag = psb\_sort\_keep\_idx\_$  the routine will assume that
+%%   i$; thus, upon return from the subroutine, for each
-  the entries in $ix(:)$ have already been initialized by the user;
+%%   index $i$ we have in $ix(i)$ the position that the item $x(i)$
-\item The two sorting algorithms have a similar $O(n \log n)$ expected
+%%   occupied in the original data sequence;
-  running time; in the average case quicksort will be the
+%% \item If $flag = psb\_sort\_keep\_idx\_$  the routine will assume that
-  fastest. However note that:
+%%   the entries in $ix(:)$ have already been initialized by the user;
-\begin{enumerate}
+%% \item The two sorting algorithms have a similar $O(n \log n)$ expected
-\item The worst case running time for quicksort is $O(n^2)$; the algorithm
+%%   running time; in the average case quicksort will be the
-  implemented here follows the well-known median-of-three heuristics,
+%%   fastest. However note that:
-  but the worst case may still apply;
+%% \begin{enumerate}
-\item The worst case running time for merge-sort is the same as the
+%% \item The worst case running time for quicksort is $O(n^2)$; the algorithm
-  average case;
+%%   implemented here follows the well-known median-of-three heuristics,
-\item The merge-sort algorithm is implemented to take advantage of 
+%%   but the worst case may still apply;
-  subsequences that may be  already in the desired ordering at the
+%% \item The worst case running time for merge-sort is the same as the
-  beginning; this situation is relatively common when dealing with
+%%   average case;
-  indices of sparse matrix entries, thus merge-sort  is the
+%% \item The merge-sort algorithm is implemented to take advantage of 
-  preferred   choice when a sorting is needed by other routines in the
+%%   subsequences that may be  already in the desired ordering at the
-  library. 
+%%   beginning; this situation is relatively common when dealing with
-\end{enumerate}
+%%   indices of sparse matrix entries, thus merge-sort  is the
-\end{enumerate}
+%%   preferred   choice when a sorting is needed by other routines in the
+%%   library. 
+%% \end{enumerate}
+%% \end{enumerate}
 
 
 %\subroutine{PSB\_HBIO\_MOD}{Input/Output in Harwell-Boeing format}