SLIP_LU/Doc/SLIP_LU_UserGuide.tex

35 \textbf{User Guide for SLIP LU, A Sparse Left-Looking Integer
64 SLIP LU is a software package designed to exactly solve unsymmetric sparse
72 is the Sparse Left-looking Integer-Preserving (SLIP) LU factorization
77 guaranteed to be exact. In addition, SLIP LU provides a wrapper class for the
81 external libraries. SLIP LU is written in ANSI C and is accompanied by a MATLAB
130 Using the SLIP matrix copy function, any matrix in any of the 15 combinations
135 One key advantage of utilizing SLIP LU with floating-point output is that the
139 to machine roundoff (approximately $10^{-16}$) and SLIP LU utilizes higher
207 \noindent \textbf{Required Packages:} SLIP LU requires the installation of AMD
231 Installation of SLIP LU requires the \verb|make| utility in Linux/MacOS, or
233 under the main directory will compile AMD, COLAMD and SLIP LU to the respective
245 If you want to use SLIP LU within MATLAB, from your installation of MATLAB,
257 \section{Managing the SLIP LU environment} \label{s:user:setup}
264 SLIP LU defines the following strings with \verb|#define|. Refer to
282 \cprotect\subsection{\verb|SLIP_info|: status code returned by SLIP LU}
286 Most SLIP LU functions return their status to the caller as their return value,
303     -5& \verb|SLIP_PANIC| & SLIP LU environment error \\
309 must be called prior to using any other SLIP LU function.  \verb|SLIP_finalize|
310 must be called as the last SLIP LU function.
312 Subsequent SLIP LU sessions can be restarted after a call to
331 \verb|SLIP_initialize| initializes the working environment for SLIP LU
332 functions.  SLIP LU utilizes a specialized memory management scheme in order to
335 any other function in the library.  Returns \verb|SLIP_PANIC| if SLIP LU has
357 it allows for a redefinition of custom memory functions that are used for SLIP
373 Returns \verb|SLIP_PANIC| if SLIP LU has already been initialized,
391 \verb|SLIP_finalize| finalizes the working environment for SLIP LU
392 library, and frees any internal workspace created by SLIP LU.  It must be
394 call to \verb|SLIP_initialize*| may be used to start another SLIP LU session.
395 Returns \verb|SLIP_PANIC| if SLIP LU has not been initialized,
403 structures used in SLIP LU.  By default, SLIP LU relies on the SuiteSparse
408 changed by initializing the SLIP LU environment with
433 Returns \verb|NULL| if SLIP LU has not been initialized.
456 Returns \verb|NULL| if SLIP LU has not been initialized.
483 object is returned.  Returns \verb|ok| as \verb|false| if SLIP LU has not been
489 returned as \verb|true|), unless SLIP LU has not been initialized.
544 No action is taken if SLIP LU has not been initialized.
548 parameter settings for SLIP LU} \label{ss:SLIP_options}
552 modified to change the behavior of the SLIP LU functions.  Default values of
562 There are six available pivoting schemes provided in SLIP LU that can be
568 does not lead to any kind of numerical inaccuracy, since SLIP LU is guaranteed
618 The SLIP LU library provides three column ordering schemes: no pre-ordering,
655 functions used in the SLIP LU package. The \verb|SLIP_options* option| struct
680 COLAMD/AMD and SLIP, 3: all, with matrices and results. Default value: 0.
692 of MPFR rounding to be used by SLIP LU. This is a parameter of the MPFR
715 system should be checked. Intended for debugging only; the SLIP LU library is
720 All SLIP LU routines except basic memory management routines in Sections
769 Returns \verb|NULL| if SLIP LU has not been initialized.
775 All matrices for SLIP LU are stored as a \verb|SLIP_matrix| object (a pointer
790 The SLIP LU library provides three available matrix formats: sparse CSC
813 The SLIP LU library provides five data types for matrix entries: \verb|mpz_t|,
952 To simplify the access the entries in \verb|A|, SLIP LU package provides the
970 The SLIP LU package has a set of functions to allocate, copy(convert), query and
971 destroy a SLIP LU matrix, \verb|SLIP_matrix|, as shown in the following table.
1048 Returns \verb|SLIP_PANIC| if SLIP LU has not been initialized.
1103 \verb|SLIP_PANIC| if SLIP LU has not been initialized.
1127 Returns -1 if SLIP LU has not been initialized.
1151 as \verb|NULL|.  Returns \verb|SLIP_PANIC| if SLIP LU has not been initialized.
1190 The SLIP LU package provides the following functions to create and destroy a
1230 \verb|SLIP_LU_analyze| performs the symbolic ordering for SLIP LU. Currently,
1241 error status returned if a failure occurred.  Returns \verb|SLIP_PANIC| if SLIP
1269 Returns \verb|SLIP_PANIC| if SLIP LU has not been initialized.
1295 \verb|SLIP_LU_factorize| performs the SLIP LU factorization. This factorization
1325 Returns \verb|SLIP_PANIC| if SLIP LU has not been initialized.  Otherwise, if
1372 intended for debugging only; the SLIP LU library is guaranteed to return the
1378 Section \ref{s:Using:expert}.  Returns \verb|SLIP_PANIC| if SLIP LU has not
1421 However, this is intended for debugging only; SLIP LU library is guaranteed to
1425 Returns \verb|SLIP_PANIC| if SLIP LU has not been initialized.
1431 \section{SLIP LU wrapper functions for GMP and MPFR}
1434 SLIP LU provides a wrapper class for all GMP and MPFR functions used by SLIP
1437 are used inside all SLIP LU functions, wherever any GMP or MPFR functions are
1442 \verb|mpz_mul| is changed to \verb|SLIP_mpz_mul|. Each SLIP GMP/MPFR function
1444 following table gives a brief list of each currently covered SLIP GMP/MPFR
1702 \cprotect\section{Using SLIP LU in C} \label{s:Using}
1705 Using SLIP LU in C has three steps:
1717 done in one of two ways. If only the solution vector $x$ is required, SLIP LU
1727 \cprotect\subsection{SLIP LU initialization and population of data structures}
1732 structures required for SLIP LU.
1738 SLIP LU is built upon the GNU Multiple Precision Arithmetic (GMP)
1741 functions it uses.  This allows SLIP LU to properly handle memory management
1742 failures, which GMP/MPFR does not handle.  To enable this mechanism, SLIP LU
1744 SLIP LU function:
1759 SLIP LU assumes three specific input options for all functions. These are:
1787 SLIP LU allows the input numerical data for \verb|A| and \verb|b| to come in
1793 is stored as $A ( i[k], j[k]) = x[k]$. SLIP LU stores its dense matrices in
1824 \cprotect\subsection{Simple SLIP LU routines for solving linear systems}
1828 After initializing the necessary data structures, SLIP LU obtains the solution
1829 to $Ax=b$ using the simple interface of SLIP LU, \verb|SLIP_backslash|.  The
1845 \cprotect\subsection{Expert SLIP LU routines}
1849 If the $L$ and $U$ factors from the SLIP LU factorization of the matrix $A$
1851 a sequence of calls to SLIP LU functions:
1867 Using SLIP LU in this form requires the intermediate variables be declared,
1887 \subsubsection{SLIP LU symbolic analysis}
1890 The symbolic analysis phase of SLIP LU computes the column permutation and
1922 and as a verification that SLIP LU is computing its expected result.  This test
1932 a dense \verb|mpq_t| matrix. SLIP LU allows this to be converted into any form
1952 As described in Section \ref{s:user:memmanag}, SLIP LU provides a number
1953 of functions/macros to free SLIP LU objects:
1969 After all usage of the SLIP LU routines is finished, \verb|SLIP_finalize()|
1974 \cprotect\subsection{Examples of using SLIP LU in a C program}
1978 The \verb|SLIP_LU/Demo| folder contains three sample C codes which utilize SLIP
1979 LU. These files demonstrate the usage of SLIP LU as follows:
2003 \cprotect\section{Using SLIP LU in MATLAB}
2008 using the SLIP LU factorization within MATLAB can be done via the
2019 The SLIP LU MATLAB interface includes an \verb|option| struct as in optional
2099 The SLIP LU function expects as input a sparse matrix $A$ and dense set of