Updated documentation with getrow.

Added some comments into realloc module.

base/modules/psb_realloc_mod.F90

@@ -32,6 +32,10 @@ module psb_realloc_mod
   use psb_const_mod
   implicit none
   
+  !
+  ! psb_realloc will reallocate the input array to have exactly 
+  ! the size specified, possibly shortening it. 
+  !
   Interface psb_realloc
     module procedure psb_dreallocate1i
     module procedure psb_dreallocate2i
@@ -58,7 +62,12 @@ module psb_realloc_mod
          & psb_dcpy1d, psb_dcpy2d, psb_zcpy1d, psb_zcpy2d
   end Interface
 
-  Interface psb_ensure_size
+  !
+  ! psb_ensure_size will reallocate the input array if necessary
+  ! to guarantee that its size is at least as large as the 
+  ! value required, usually with some room to spare.
+  !
+  interface psb_ensure_size
     module procedure psb_icksz1d, psb_dcksz1d, psb_zcksz1d
   end Interface
 

base/serial/README.serial

@@ -54,7 +54,7 @@ How do you add a new storage format? Here is your checklist.
 11. You have to provide the query facilities used in PSB_XSPINFO
     (included  in base/modules/psb_spmat_type). 
 12. You have to provide the functionality to extract a block of
-    rows in psb_getrow_mod.f90. This is used in the GETBLK/GETROW/CLIP
+    rows in psb_getrow_mod.f90. This is used in the GETROW/GETBLK/CLIP
     chain; GETROW is (all that is) used by the ILU factorization. 
 13. You have to provide the GETDIAG functionality. 
 14. RWEXTD: what do we do here? Should we switch to/from COO?????

docs/pdf/toolsrout.tex

@@ -1070,6 +1070,83 @@ An integer value; 0 means no error has been detected.
 
 
 
+\subroutine{psb\_sp\_getrow}{Extract row(s) from a sparse matrix}
+
+\syntax{call psb\_sp\_getrow}{row, a, nz, ia, ja, val, info, append,
+  nzin, lrw}
+
+\begin{description}
+\item[\bf On Entry]
+\item[row] The (first) row to be extracted.\\
+Scope:{\bf local}\\
+Type:{\bf required}\\
+Specified as: an integer $>0$.
+\item[a] the matrix from  which to get rows.\\
+Scope:{\bf local}\\
+Type:{\bf required}\\
+Specified as: a structured data of type \spdata.
+\item[append] Whether to append or overwrite existing output.\\
+Scope:{\bf local}\\
+Type:{\bf optional}\\
+Specified as: a logical value default: false (overwrite).
+\item[nzin] Input size to be appended to.\\
+Scope:{\bf local}\\
+Type:{\bf optional}\\
+Specified as: an integer $>0$. When append is true, specifies how many
+entries in the output vectors are already filled. 
+\item[lrw] The last  row to be extracted.\\
+Scope:{\bf local}\\
+Type:{\bf optional}\\
+Specified as: an integer $>0$, default: $row$.
+
+%% \item[is] the starting row on matrix $a$.\\
+%% Scope:{\bf local}.\\
+%% Type:{\bf optional}.\\
+%% Specified as: an integer vaule.
+%% \item[js] the starting column on matrix $a$.\\
+%% Scope:{\bf local}.\\
+%% Type:{\bf optional}\\
+%% Specified as: an integer value
+\end{description}
+
+\begin{description}
+\item[\bf On Return]
+\item[nz] the number of elements returned by this call.\\
+Scope:{\bf local}.\\
+Type:{\bf required}.\\
+Returned  as: an integer scalar.
+\item[ia] the row indices.\\
+Scope:{\bf local}.\\
+Type:{\bf required}.\\
+Specified as: an integer array with the \verb|ALLOCATABLE| attribute.
+\item[ja] the column indices of the elements to be inserted.\\
+Scope:{\bf local}.\\
+Type:{\bf required}.\\
+Specified as: an integer array with the \verb|ALLOCATABLE| attribute.
+\item[val] the elements to be inserted.\\
+Scope:{\bf local}.\\
+Type:{\bf required}.\\
+Specified as: a real  array with the \verb|ALLOCATABLE| attribute.
+\item[info] Error code.\\
+Scope: {\bf local} \\
+Type: {\bf required} \\
+An integer value; 0 means no error has been detected. 
+\end{description}
+
+\section*{Notes}
+\begin{enumerate}
+\item The output $nz$ is always the size of the output generated by
+  the current call; thus, if \verb|append=.true.|, the total output
+  size will be $nzin+nz$, with the newly extracted rows stored in
+  entries \verb|nzin+1:nzin+nz| of the array arguments;
+\item When \verb|append=.true.|  the output arrays are reallocated as
+  necessary;
+\item The row and column indices are returned in the local numbering
+  scheme; if the global numbering is desired, the user may emply the
+  \verb|psb_loc_to_glob| routine.
+\end{enumerate}
+
+
 
 %%% Local Variables: 
 %%% mode: latex

docs/pdf/util.tex

@@ -9,10 +9,10 @@
 \syntax{call psb\_msort}{x,ix,dir,flag}
 \syntax*{call psb\_qsort}{x,ix,dir,flag}
 
-These  serial routines sort a sequence $X$ into an order consistent
+These  serial routines sort a sequence $X$ into ascending or
-with the underlying field from which the values are drawn. The
+descending  order. The argument meaning is identical for the two
-argument meaning is identical; the only difference is the algorithm
+calls; the only difference is the algorithm used to accomplish the
-used to accomplish the task (see Usage Notes below).
+task (see Usage Notes below). 
 \begin{description}
 \item[\bf  On Entry ]
 \item[x] The sequence to be sorted.\\
@@ -45,16 +45,17 @@ position as the corresponding entries in $x$.
 \section*{Usage notes}
 \begin{enumerate}
 \item The two routines return the items in the chosen ordering; the
-  only difference is the handling of  ties (i.e. items with an equal
+  only output difference is the handling of  ties (i.e. items with an
-  value) in the original input. With the merge-sort algorithm ties are
+  equal   value) in the original input. With the merge-sort algorithm
-  preserved in the same order as they had in the original sequence,
+  ties are   preserved in the same order as they had in the original
-  while this is not guaranteed for quicksort
+  sequence,   while this is not guaranteed for quicksort 
 \item 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; otherwise the routine will
+  occupied in the original data sequence;
-  shuffle around whatever data the user chose for its initialization. 
+\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 two sorting algorithms have a similar $O(n \log n)$ expected
   running time; in the average case quicksort will be the
   fastest. However note that:
@@ -64,11 +65,12 @@ position as the corresponding entries in $x$.
   but the worst case may still apply;
 \item The worst case running time for merge-sort is the same as the
   average case;
-\item Our merge-sort is implemented to take advantage of any
+\item The merge-sort algorithm is implemented to take advantage of 
-  subsequence that is already in the desired ordering at the
+  subsequences that may be  already in the desired ordering at the
-  beginning; this situation may be quite common when dealing with
+  beginning; this situation is relatively common when dealing with
-  indices of sparse matrix entries, accordingly it is the preferred
+  indices of sparse matrix entries, thus merge-sort  is the
-  choice when a sorting is needed by other routines in the library.
+  preferred   choice when a sorting is needed by other routines in the
+  library. 
 \end{enumerate}
 \end{enumerate}