\chapter{The Serial Wrapper Object and Driver}
\label{section:serial}
\par
The goal is to solve $AX = Y$ in a serial environment.
Section 1 of the User's Manual presents a listing of the 
{\tt AllInOne.c} driver program for solving $AX =Y$.
There are nine steps, and each requires ``mid-level'' knowledge 
of several objects of the {\bf SPOOLES} library.
To reduce the complexity of using the library, 
(and the complexity rises dramatically in the multithreaded and MPI
environments),
we created the {\tt Bridge} object.
The term ``bridge'' symbolizes spanning the distance between the
{\bf SPOOLES} library and the CSAR-Nastran application code.
The nine steps of the {\tt allInOne.c} driver program is reduced to
three using the {\tt Bridge} object.
\begin{itemize}
\item Initialization and setup step.
\par
Here the {\tt Bridge} object is allocated via a call to {\tt
Bridge\_new()}.
Parameters are set using {\tt Bridge\_set*()} methods.
The setup phase orders the matrix and prepares all the necessary {\bf
SPOOLES} data structures for the factorization and solve that follows.
\item Factorization step.
\par
The matrix is factored via a call to {\tt Bridge\_factor()}.
\item Solution step.
\par
The linear system is solved via a call to {\tt Bridge\_solve()}.
\end{itemize}
\par
The {\tt Bridge} object 
has many parameters that control the ordering of the matrix,
the pivoting tolerance (if pivoting is requested),
the drop tolerance (for an approximate factorization),
and so on.
Rather than burden the user with the knowledge of and setting these
parameters, there are decent default values built into the object.
There are also methods to set various parameters to allow the user
some control over the ordering, factor and solve processes.
\par
Section~\ref{section:Bridge:quick-look-serial-driver} takes a quick
look at the {\tt Bridge} driver program (whose complete listing is
found in Appendix~\ref{chapter:serial_driver}).
Section~\ref{section:Bridge:dataStructure} describes the internal 
data fields of the {\tt Bridge} object.
Section~\ref{section:Bridge:proto} contains the prototypes and
descriptions of all {\tt Bridge} methods.
\par
\section{A quick look at serial driver program}
\label{section:Bridge:quick-look-serial-driver}
\par
The entire listing of this serial driver is found in
Appendix~\ref{chapter:serial_driver}.
We now extract parts of the code.
\begin{itemize}
\item Decode the input.
\par
\begin{verbatim}
msglvl       = atoi(argv[1]) ;
msgFileName  = argv[6] ;
neqns        = atoi(argv[3]) ;
type         = atoi(argv[4]) ;
symmetryflag = atoi(argv[5]) ;
mtxFileName  = argv[6] ;
rhsFileName  = argv[7] ;
solFileName  = argv[8] ;
seed         = atoi(argv[9]) ;
\end{verbatim}
Here is a description of the input parameters.

\begin{itemize}
\item {\tt msglvl} is the message level.
\item {\tt msgFile} is the message file name
\item {\tt neqns} is the number of equations.
\item {\tt type} is the type of entries:
1 ({\tt SPOOLES\_REAL}) or
2 ({\tt SPOOLES\_COMPLEX}).
\item {\tt symmetryflag} is the type of matrix symmetry:
0 ({\tt SPOOLES\_SYMMETRIC}),
1 ({\tt SPOOLES\_HERMITIAN}) or
2 ({\tt SPOOLES\_NONSYMMETRIC}).
\item {\tt mtxFile} is the name of the file from which to read the {\tt
InpMtx} object for $A$.
The file name must have the form {\tt *.inpmtxb} for a binary file or
{\tt *.inpmtxf} for a formatted file.
\item {\tt rhsFile} is the name of the file from which to read the {\tt
DenseMtx} object for the right hand side $Y$.
The file name must have the form {\tt *.densemtxb} for a binary file or
{\tt *.densemtxf} for a formatted file.
\item {\tt solFile} is the name of the file to write the {\tt
DenseMtx} object for the solution $X$.
The file name must have the form {\tt *.densemtxb} for a binary file or
{\tt *.densemtxf} for a formatted file, {\tt "none"} for no output,
or any other name for a human-readable listing.
\item {\tt seed} is a random number seed used in the ordering process.
\end{itemize}
%
\item Read in the {\tt InpMtx} object for $A$.
\begin{verbatim}
mtxA = InpMtx_new() ;
rc = InpMtx_readFromFile(mtxA, mtxFileName) ;
\end{verbatim}
The {\tt rc} parameter is the error return. 
In the driver it is tested for an error, but we omit this from the
present discussion.
%
\item Read in the {\tt DenseMtx} object for $Y$.
\begin{verbatim}
mtxY = DenseMtx_new() ;
rc = DenseMtx_readFromFile(mtxY, mtxFileName) ;
DenseMtx_dimensions(mtxY, &nrow, &nrhs) ;
\end{verbatim}
The {\tt nrhs} parameter contains the number of right hand sides,
or equivalently, the number of columns in $Y$.
%
\item Create and setup the {\tt Bridge} object.
\begin{verbatim}
bridge = Bridge_new() ;
Bridge_setMatrixParams(bridge, neqns, type, symmetryflag) ;
Bridge_setMessageInfo(bridge, msglvl, msgFile) ;
rc = Bridge_setup(bridge, mtxA) ;
\end{verbatim}
The {\tt Bridge} object is allocated by {\tt Bridge\_new()},
and various parameters are set.
The actual ordering of the matrix, symbolic factorization,
and permutation creation are performed inside the {\tt Bridge\_setup()}
method.
%
\item Compute the matrix factorization.
\begin{verbatim}
permuteflag = 1 ;
rc = Bridge_factor(bridge, mtxA, permuteflag, &error) ;
\end{verbatim}
When {\tt permuteflag} is {\tt 1}, it means that the matrix in {\tt
mtxA} has not yet been permuted into the new ordering and so is
done inside the method.
The {\tt error} flag is filled with an error code that tells how far the
factorization was able to proceed.
If {\tt rc = 1}, the factorization completed without any error.
%
\item Solve the linear system.
\begin{verbatim}
mtxX = DenseMtx_new() ;
DenseMtx_init(mtxX, type, 0, 0, neqns, nrhs, 1, neqns) ;
DenseMtx_zero(mtxX) ;
rc = Bridge_solve(bridge, permuteflag, mtxX, mtxY) ;
\end{verbatim}
The {\tt DenseMtx} object {\tt mtxX} is created and initialized to be
the same type and size as {\tt mtxY}.
Its entries are explicitly zeroed (this is not necessary but is a good
idea in general).
The solution is then solved.
Again, note the presence of {\tt permuteflag}.
When {\tt 1}, \texttt{mtxY} needs to be permuted into the new ordering,
and \texttt{mtxX} is returned in the original ordering.
\end{itemize}
\par
\section{The \texttt{Bridge} Data Structure}
\label{section:Bridge:dataStructure}
\par
The {\tt Bridge} structure has the following fields.
\begin{itemize}
%
\item Graph parameters:
\begin{itemize} 
\item
{\tt int neqns} : number of equations, 
i.e., number of vertices in the graph.
\item
{\tt int nedges} : number of edges 
(includes $(u,v)$, $(v,u)$ and $(u,u)$).
\item
{\tt int Neqns} : number of equations in the compressed graph.
\item
{\tt int Nedges} : number of edges in the compressed graph.
\end{itemize}
%
\item Ordering parameters:
\begin{itemize}
\item
{\tt int maxdomainsize} : maximum size of a subgraph to not split any
further during the nested dissection process.
\item
{\tt int maxnzeros} : maximum number of zeros to allow in a front 
during the supernode amalgamation process.
\item
{\tt int maxsize} : maximum size of a front when the fronts are split.
\item
{\tt int seed} : random number seed.
\item
{\tt double compressCutoff} : if the \texttt{Neqns} $<$
\texttt{compressCutoff} $*$ \texttt{neqns}, then the compressed
graph is formed, ordered and used to create the symbolic
factorization.
\end{itemize}
%
\item Matrix parameters:
\begin{itemize}
\item
{\tt int type} : type of entries,
{\tt SPOOLES\_REAL} or {\tt SPOOLES\_COMPLEX},
default value is {\tt SPOOLES\_REAL}.
\item
{\tt int symmetryflag} : type of symmetry for the matrix,
{\tt SPOOLES\_SYMMETRIC}, {\tt SPOOLES\_HERMITIAN}
or {\tt SPOOLES\_NONSYMMETRIC},
default value is {\tt SPOOLES\_SYMMETRIC}.
\end{itemize}
%
\item Factorization parameters:
\begin{itemize}
\item
{\tt int sparsityflag} : 
{\tt SPOOLES\_DENSE\_FRONTS} for a direct factorization,
or {\tt SPOOLES\_SPARSE\_FRONTS} for an approximate factorization,
default value is {\tt SPOOLES\_DENSE\_FRONTS}.
\item
{\tt int pivotingflag} : 
{\tt SPOOLES\_PIVOTING} for pivoting enabled,
or {\tt SPOOLES\_NO\_PIVOTING} for no pivoting,
default value is {\tt SPOOLES\_NO\_PIVOTING}.
\item
{\tt double tau} : used when pivoting is enabled,
all entries in $L$ and $U$ have magnitude less than or equal to
\texttt{tau},
default value is 100.
\item
{\tt double droptol} : used for an approximation,
all entries in $L$ and $U$ that are kept 
have magnitude greater than or equal to \texttt{droptol}.
default value is 0.001.
\item
{\tt PatchAndGoInfo *patchinfo} : pointer to an object that
controls special factorizations for optimization matrices
and singular matrices from structural analysis,
default value is \texttt{NULL} which means no special action is taken.
See the Reference Manual for more information.
\end{itemize}
%
\item Pointers to objects:
\begin{itemize}
\item
{\tt ETree *frontETree} : object that defines the factorizations,
e.g., the number of fronts, the tree they form, the number of
internal and external rows for each front, and the map from
vertices to the front where it is contained.
\item
{\tt IVL *symbfacIVL} : object that contains the symbolic
factorization of the matrix.
\item
{\tt SubMtxManager *mtxmanager} : object that manages the
\texttt{SubMtx} objects that store the factor entries and are used
in the solves.
\item
{\tt FrontMtx *frontmtx} : object that stores the $L$, $D$ and $U$
factor matrices.
\item
{\tt IV *oldToNewIV} : object that stores old-to-new permutation vector.
\item
{\tt IV *newToOldIV} : object that stores new-to-old permutation vector.
\end{itemize}
%
\item Message information, statistics and cpu times:
\begin{itemize}
\item
{\tt int msglvl} : message level for output.
When 0, no output, When 1, just statistics and cpu times.
When greater than 1, more and more output.
\item
{\tt FILE *msgFile} : message file for output.
When \texttt{msglvl} $>$ 0, \texttt{msgFile} must not be \texttt{NULL}.
\item
{\tt int stats[6]} : statistics for the factorization.
\begin{center}
\begin{tabular}{ll}
\texttt{stats[0]} : & \# of pivots \\
\texttt{stats[1]} : & \# of pivot tests \\
\texttt{stats[2]} : & \# of delayed rows and columns
\end{tabular}
\begin{tabular}{ll}
\texttt{stats[3]} : & \# of entries in $D$ \\
\texttt{stats[4]} : & \# of entries in $L$ \\
\texttt{stats[5]} : & \# of entries in $U$
\end{tabular}
\end{center}
\item
{\tt double cpus[14]} : cpus for the different functions.
\begin{center}
\begin{tabular}{ll}
\texttt{cpus[0]} : & time to construct \texttt{Graph} \\
\texttt{cpus[1]} : & time to compress \texttt{Graph} \\
\texttt{cpus[2]} : & time to order \texttt{Graph} \\
\texttt{cpus[3]} : & time for symbolic factorization \\
\texttt{cpus[4]} : & total setup time \\
\texttt{cpus[5]} : & time to permute matrix \\
\texttt{cpus[6]} : & time to initialize front matrix 
\end{tabular}
\begin{tabular}{ll}
\texttt{cpus[7]} : & time to factor matrix \\
\texttt{cpus[8]} : & time to post-process matrix \\
\texttt{cpus[9]} : & total factor time \\
\texttt{cpus[10]} : & time to permute rhs \\
\texttt{cpus[11]} : & time to solve \\
\texttt{cpus[12]} : & time to permute solution \\
\texttt{cpus[13]} : & total solve time
\end{tabular}
\end{center}
\end{itemize}
\end{itemize}
\par
\section{Prototypes and descriptions of \texttt{Bridge} methods}
\label{section:Bridge:proto}
\par
This section contains brief descriptions including prototypes
of all methods that belong to the {\tt Bridge} object.
\par
\subsection{Basic methods}
\label{subsection:Bridge:proto:basics}
\par
As usual, there are four basic methods to support object creation,
setting default fields, clearing any allocated data, and free'ing
the object.
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
Bridge * Bridge_new ( void ) ;
\end{verbatim}
\index{Bridge_new@{\tt Bridge\_new()}}
This method simply allocates storage for the {\tt Bridge} structure 
and then sets the default fields by a call to 
{\tt Bridge\_setDefaultFields()}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_setDefaultFields ( Bridge *bridge ) ;
\end{verbatim}
\index{Bridge_setDefaultFields@{\tt Bridge\_setDefaultFields()}}
The structure's fields are set to default values:
\begin{itemize}
\item
\texttt{neqns} = \texttt{nedges} = \texttt{Neqns} =
\texttt{Nedges} = 0.
\item
\texttt{maxdomainsize} = \texttt{maxnzeros} 
   = \texttt{maxsize} = \texttt{seed} = -1.
\texttt{compressCutoff} = 0.
\item
\texttt{type} = \texttt{SPOOLES\_REAL}.
\item
\texttt{symmetryflag} = \texttt{SPOOLES\_SYMMETRIC}.
\item
\texttt{sparsityflag} = \texttt{SPOOLES\_DENSE\_FRONTS}.
\item
\texttt{pivotingflag} = \texttt{SPOOLES\_NO\_PIVOTING}.
\item
\texttt{tau} = 100., \texttt{droptol} = 0.001.
\item
\texttt{patchinfo} =
\texttt{frontETree} =
\texttt{symbfacIVL} =
\texttt{mtxmanager} =
\texttt{frontmtx} =
\texttt{oldToNewIV} =
\texttt{newToOldIV} = \texttt{NULL}.
\end{itemize}
The \texttt{stats[6]} and \texttt{cpus[14]} vectors are filled 
with zeros.
\par \noindent {\it Return value:}
1 for a normal return, -1 if \texttt{bridge} is \texttt{NULL}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_clearData ( Bridge *bridge ) ;
\end{verbatim}
\index{Bridge_clearData@{\tt Bridge\_clearData()}}
This method clears the object and free's any owned data.
It then calls {\tt Bridge\_setDefaultFields()}.
\par \noindent {\it Return value:}
1 for a normal return, -1 if \texttt{bridge} is \texttt{NULL}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_free ( Bridge *bridge ) ;
\end{verbatim}
\index{Bridge_free@{\tt Bridge\_free()}}
This method releases any storage by a call to
{\tt Bridge\_clearData()} and then free the space for {\tt bridge}.
\par \noindent {\it Return value:}
1 for a normal return, -1 if \texttt{bridge} is \texttt{NULL}.
%-----------------------------------------------------------------------
\end{enumerate}
\par
\subsection{Instance methods}
\label{subsection:Bridge:proto:instance}
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_oldToNewIV ( Bridge *bridge, IV **pobj ) ;
\end{verbatim}
\index{Bridge_oldToNewIV@{\tt Bridge\_oldToNewIV()}}
This method fills \texttt{*pobj} with its \texttt{oldToNewIV} pointer.
\par \noindent {\it Return value:}
1 for a normal return, 
-1 if \texttt{bridge} is \texttt{NULL}.
-2 if \texttt{pobj} is \texttt{NULL}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_newToOldIV ( Bridge *bridge, IV **pobj ) ;
\end{verbatim}
\index{Bridge_newToOldIV@{\tt Bridge\_newToOldIV()}}
This method fills \texttt{*pobj} with its \texttt{newToOldIV} pointer.
\par \noindent {\it Return value:}
1 for a normal return, 
-1 if \texttt{bridge} is \texttt{NULL}.
-2 if \texttt{pobj} is \texttt{NULL}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_frontETree ( Bridge *bridge, ETree **pobj ) ;
\end{verbatim}
\index{Bridge_frontETree@{\tt Bridge\_frontETree()}}
This method fills \texttt{*pobj} with its \texttt{frontETree} pointer.
\par \noindent {\it Return value:}
1 for a normal return, 
-1 if \texttt{bridge} is \texttt{NULL}.
-2 if \texttt{pobj} is \texttt{NULL}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_symbfacIVL ( Bridge *bridge, IVL **pobj ) ;
\end{verbatim}
\index{Bridge_symbfacIVL@{\tt Bridge\_symbfacIVL()}}
This method fills \texttt{*pobj} with its \texttt{symbfacIVL} pointer.
\par \noindent {\it Return value:}
1 for a normal return, 
-1 if \texttt{bridge} is \texttt{NULL}.
-2 if \texttt{pobj} is \texttt{NULL}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_mtxmanager ( Bridge *bridge, SubMtxManager **pobj ) ;
\end{verbatim}
\index{Bridge_mtxmanager@{\tt Bridge\_mtxmanager()}}
This method fills \texttt{*pobj} with its \texttt{mtxmanager} pointer.
\par \noindent {\it Return value:}
1 for a normal return, 
-1 if \texttt{bridge} is \texttt{NULL}.
-2 if \texttt{pobj} is \texttt{NULL}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_frontmtx ( Bridge *bridge, FrontMtx **pobj ) ;
\end{verbatim}
\index{Bridge_frontmtx@{\tt Bridge\_frontmtx()}}
This method fills \texttt{*pobj} with its \texttt{frontmtx} pointer.
\par \noindent {\it Return value:}
1 for a normal return, 
-1 if \texttt{bridge} is \texttt{NULL}.
-2 if \texttt{pobj} is \texttt{NULL}.
%-----------------------------------------------------------------------
\end{enumerate}
\par
\subsection{Parameter methods}
\label{subsection:Bridge:proto:parameters}
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_setMatrixParams ( Bridge *bridge, int neqns, int type, int symmetryflag ) ;
\end{verbatim}
\index{Bridge_setMatrixParams@{\tt Bridge\_setMatrixParams()}}
This method sets the number of equations, type of entries, 
and symmetry type of the matrix.
\par \noindent {\it Return value:}
\begin{center}
\begin{tabular}{ll}
~1 & normal return \\
-1 & \texttt{bridge} is \texttt{NULL} \\
-2 & \texttt{neqns} $\le$ 0
\end{tabular}
\begin{tabular}{ll}
-3 & \texttt{type} is invalid \\
-4 & \texttt{symmetryflag} is invalid \\
-5 & symmetry flag is Hermitian but type is real
\end{tabular}
\end{center}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_setOrderingParams ( Bridge *bridge, int maxdomainsize, int maxnzeros, 
                               int maxsize, int seed, double compressCutoff ) ;
\end{verbatim}
\index{Bridge_setOrderingParams@{\tt Bridge\_setOrderingParams()}}
This method sets parameters needed for the ordering.
\par \noindent {\it Return value:}
\begin{center}
\begin{tabular}{ll}
~1 & normal return \\
-1 & \texttt{bridge} is \texttt{NULL} \\
-2 & \texttt{maxdomainsize} $\le$ 0
\end{tabular}
\begin{tabular}{ll}
-3 & \texttt{maxsize} $\le$ 0 \\
-4 & \texttt{compressCutoff} $>$ 1
\end{tabular}
\end{center}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_setFactorParams ( Bridge *bridge, int sparsityflag, int pivotingflag, 
                             double tau, double droptol, PatchAndGoInfo *patchinfo ) ;
\end{verbatim}
\index{Bridge_setFactorParams@{\tt Bridge\_setFactorParams()}}
This method sets parameters needed for the factorization.
\par \noindent {\it Return value:}
\begin{center}
\begin{tabular}{ll}
~1 & normal return \\
-1 & \texttt{bridge} is \texttt{NULL} \\
-2 & \texttt{sparsityflag} is invalid 
\end{tabular}
\begin{tabular}{ll}
-3 & \texttt{pivotingflag} is invalid  \\
-4 & \texttt{tau} $<$ 2.0 \\
-5 & \texttt{droptol} $<$ 0.0
\end{tabular}
\end{center}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_setMessagesInfo ( Bridge *bridge, int msglvl, FILE *msgFile ) ;
\end{verbatim}
\index{Bridge_setMessagesInfo@{\tt Bridge\_setMessagesInfo()}}
This method sets the message level and file.
\par \noindent {\it Return value:}
1 for a  normal return,
-1 if \texttt{bridge} is \texttt{NULL},
-2 if \texttt{msglvl} $>$ 0 and \texttt{msgFile} is \texttt{NULL}.
%-----------------------------------------------------------------------
\end{enumerate}
\par
\subsection{Setup methods}
\label{subsection:Bridge:proto:setup}
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_setup ( Bridge *bridge, InpMtx *mtxA ) ;
\end{verbatim}
\index{Bridge_setup@{\tt Bridge\_setup()}}
This method orders the graph, generates the front tree, computes
the symbolic factorization, and creates the two permutation vectors.
\par \noindent {\it Return value:}
1 for a  normal return,
-1 if \texttt{bridge} is \texttt{NULL},
-2 if \texttt{mtxA} is \texttt{NULL}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_factorStats ( Bridge *bridge, int type, int symmetryflag, int *pnfront,
      int *pnfactorind, int *pnfactorent, int *pnsolveops, double *pnfactorops ) ;
\end{verbatim}
\index{Bridge_factorStats@{\tt Bridge\_factorStats()}}
This method takes as input the type and symmetry of the matrix,
and fills the pointer fields with the number of fronts, factor
indices, factor entries, forward and back solve operations,
and factor operations.
\par \noindent {\it Return value:}
\begin{center}
\begin{tabular}{ll}
~1 & normal return \\
-1 & \texttt{bridge} is \texttt{NULL} \\
-2 & \texttt{type} is invalid \\
-3 & \texttt{symmetryflag} is invalid \\
-4 & \texttt{type} is real but \texttt{symmetryflag} is Hermitian \\
-5 & front tree is not present
\end{tabular}
\begin{tabular}{ll}
~-6 & \texttt{pnfront} is \texttt{NULL}  \\
~-7 & \texttt{pnfactorind} is \texttt{NULL}  \\
~-8 & \texttt{pnfactorent} is \texttt{NULL}  \\
~-9 & \texttt{pnsolveops} is \texttt{NULL}  \\
-10 & \texttt{pnfactorops} is \texttt{NULL} 
\end{tabular}
\end{center}
%-----------------------------------------------------------------------
\end{enumerate}
\par
\subsection{Factor method}
\label{subsection:Bridge:proto:factor}
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_factor ( Bridge *bridge, InpMtx *mtxA, int permuteflag, int *perror ) ;
\end{verbatim}
\index{Bridge_factor@{\tt Bridge\_factor()}}
This method permutes the matrix into the new ordering (if
\texttt{permuteflag} is 1), factors the matrix, and then
post-processes the factors.
\par \noindent {\it Return value:}
\begin{center}
\begin{tabular}{ll}
~1 & normal return, factorization did complete \\
~0 & factorization did not complete \\
\end{tabular}
\begin{tabular}{ll}
-1 & \texttt{bridge} is \texttt{NULL} \\
-2 & \texttt{mtxA} is \texttt{NULL} \\
-3 & \texttt{perror} is \texttt{NULL} \\
\end{tabular}
\end{center}
%-----------------------------------------------------------------------
\end{enumerate}
\par
\subsection{Solve method}
\label{subsection:Bridge:proto:solve}
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int Bridge_solve ( Bridge *bridge, int permuteflag, DenseMtx *mtxX, DenseMtx *mtxY ) ;
\end{verbatim}
\index{Bridge_solve@{\tt Bridge\_solve()}}
If \texttt{permuteflag} is 1, then \texttt{mtxY} is permuted into
the new ordering.
The linear system $AX = Y$ is solved.
If \texttt{permuteflag} is 1, then \texttt{mtxX} is permuted into
the old ordering.
\par \noindent {\it Return value:}
\begin{center}
\begin{tabular}{ll}
~1 & normal return \\
-1 & \texttt{bridge} is \texttt{NULL} \\
-2 & \texttt{X} is \texttt{NULL} \\
-3 & \texttt{Y} is \texttt{NULL} \\
\end{tabular}
\begin{tabular}{ll}
-4 & \texttt{frontmtx} is \texttt{NULL} \\
-5 & \texttt{mtxmanager} is \texttt{NULL} \\
-6 & \texttt{oldToNewIV} needed, but not available \\
-7 & \texttt{newToOldIV} needed, but not available \\
\end{tabular}
\end{center}
%-----------------------------------------------------------------------
\end{enumerate}