\section{High Level Data Interface\label{highlevel_data_inter}}

Setting up the distributed format described in Section~\ref{data_formats} for
the local submatrix on each processor can be quite cumbersome. In particular,
the user must determine a mapping between the global numbering scheme and a
local scheme which facilitates proper communication.  Further, a number of
additional variables must be set for communication and synchronization (see
Section~\ref{advanced_topics}).  In this section we describe a simpler data
format that is used in conjunction with a transformation function to generate
data structures suitable for \Az{}.  The new format allows the user to specify
the rows in a natural order as well as to use global column numbers in the {\it
  bindx} array.  To use the transformation function the user supplies the {\it
  update\/} set and the submatrix for each processor.  Unlike the previous
section, however, the submatrix is specified using the global coordinate
numbering instead of the local numbering required by \Az{}. This procedure
greatly facilitates matrix specification and is the main advantage of the
transformation software.

On a given processor, the {\it update\/} set (i.e.  vector element assignment
to processors) is defined by initializing the array {\it update\/} on each
processor so that it contains the global index of each element assigned to the
processor. The {\it update} array must be sorted in ascending order (i.e. $ i <
j \Rightarrow update[i] < update[j]$). This sorting can be performed using the
\Az{} function {\sf AZ\_sort}. Matrix specification occurs using the arrays
defined in the previous section. However, now the local rows are defined in the
same order as the {\it update} array and column indices (e.g. {\it bindx}) are
given as global column indices.  To illustrate this in more detail, consider
the following example matrix:
\[
A = \pmatrix{ a_{00} & a_{01} &        & a_{03} & a_{04} &        \cr
              a_{10} & a_{11} &        & a_{13} &        &        \cr
                     &        & a_{22} & a_{23} & a_{24} & a_{25} \cr
              a_{30} & a_{31} & a_{32} & a_{33} & a_{34} & a_{35} \cr
              a_{40} &        & a_{42} & a_{43} & a_{44} &        \cr
                     &        & a_{52} & a_{53} &        & a_{55} } .
\]
Figure~\ref{init_input} illustrates the information corresponding to a
particular matrix partitioning that is specified by the user as input to the
data transformation tool.
\begin{figure}[Htbp]
  \shadowbox{
%    \begin{minipage}{\textwidth}
    \begin{minipage}{6.2in}
      \vspace{0.5em}
      {\large \flushleft{\bf Example}} \hrulefill %
      \vspace{0.5em}
%%%
\begin{tabbing}
\tt
\hsp proc 0: \\
\>  \hsp N\_update: \in  3 \\
\>  \>   update:    \>   0 \sp 1  \sp 3 \\
\>  \>   bindx:     \>   4       \>   7       \>   9       \sp 14     \sp 1
                    \sp  3       \sp  4       \sp  0       \sp  3     \sp  0
                    \sp  1       \sh  2       \sh  4       \sh  5\\
\>  \>   val:       \>  $a_{00}$ \>  $a_{11}$ \>  $a_{33}$ \> \hskip .05in -  \> $a_{01}$
                    \>  $a_{03}$ \>  $a_{04}$ \>  $a_{10}$ \> $a_{13}$\>$a_{30}$
                    \>  $a_{31}$ \bb $a_{32}$ \bb $a_{34}$ \bb $a_{35}$\\
\>-----------------------------------------------------------------------------------------------------------\\
\>  proc 1:\\
\>  \>   N\_update: \>   1\\
\>  \>   update:    \>   4\\
\>  \>   bindx:     \>   2 \>   5  \>   0 \>   3  \>  2 \\
\>  \>   val:       \>$a_{44}$\>\hskip .025in -\>$a_{40}$\>$a_{43}$\>$a_{42}$\\
\>-----------------------------------------------------------------------------------------------------------\\
\>  proc 2:\\
\>  \>   N\_update: \>   2\\
\>  \>   update:    \>   2 \>   5\\
\>  \>   bindx:     \>   3 \>   6  \>   8 \>   3  \>  4  \> 5  \> 2  \> 3\\
\>  \>   val:       \>$a_{22}$\>$a_{55}$\>\hskip .025in -\>$a_{23}$\>
                        $a_{24}$\>$a_{25}$\>$a_{52}$\>$a_{53}$
\end{tabbing}
%%%
      \vspace{0.5em}
    \end{minipage}}
  \caption{User input (MSR format) to initialize the sample matrix problem.}
  \label{init_input}
\end{figure}
%It should also be note that though this example
%considers only the sparsity pattern of the matrix, it is possible to
%specify the actual nonzero entries as well at the start of the calculation.
Using this information, {\sf AZ\_transform}
\begin{itemize}
\item determines the sets {\it internal}, {\it border} and
      {\it external}.
\item determines the local numbering:
      {\it update\_index[i]} is the local numbering for
      {\it update[i]} while {\it extern\_index[i]} is the local
      numbering for {\it external[i]}.
\item permutes and renumbers the local submatrix rows and columns so that
      they now correspond to the new ordering.
\item computes additional information
      (e.g. the number of internal, border and external components on this
      processor) and
      stores this in {\it data\_org\/} (see Section~\ref{advanced_topics}).
\end{itemize}
A sample transformation is given in Figure~\ref{init_mv_structs}
%
\begin{figure}[Htbp]
  \shadowbox{
%    \begin{minipage}{\textwidth}
    \begin{minipage}{6.2in}
      \vspace{0.5em}
      {\large \flushleft{\bf Example}} \hrulefill %
      \vspace{0.5em}
%%%
\begin{verbatim}
init_matrix_vector_structures(bindx, val, update, external,
                              update_index, extern_index, data_org);
{
  AZ_read_update(update, N_update);
  create_matrix(bindx, val, update, N_update);
  AZ_transform(bindx, val, update, external, update_index,
               extern_index, data_org, N_update);
}
\end{verbatim}
%%%
      \vspace{0.1em}
    \end{minipage}}
  \caption{{\sf init\_matrix\_vector\_structures}.}\label{init_mv_structs}
\end{figure}
%
and is found in the file \verb'az\_app\_utils.c'.  {\sf AZ\_read\_update} is an
\Az{} utility which reads a file and assigns elements to {\it update\/}.  The
user supplied routine {\sf create\_matrix} creates an MSR or VBR matrix using
the global numbering.  Once transformed the matrix can now be used within
\Az{}.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "az_ug_20"
%%% End:
