Skip to content

Commit 5b08d68

Browse files
DrTimothyAldenDavisDrTimothyAldenDavis
authored
Merge pull request DrTimothyAldenDavis#775 from clouren/dev2
SPEX User guide update
2 parents 8c59a72 + 370e948 commit 5b08d68

File tree

3 files changed

+94
-22
lines changed

3 files changed

+94
-22
lines changed

‎SPEX/Doc/SPEX_UserGuide.tex

Lines changed: 82 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@
6262
\textbf{User Guide for the SPEX Software Package} \\
6363
\vspace{5mm}
6464

65-
Version 3.0, July 2023 % VERSION
65+
Version 3.1, March, 2024 % VERSION
6666
\vspace{20mm}
6767

6868
Jinhao Chen, Timothy A. Davis, Christopher Lourenco, Lorena Mejia-Domenzain, Erick Moreno-Centeno \\
@@ -109,7 +109,7 @@ \chapter{SPEX Overview}\vspace{-0.75in}
109109
\begin{itemize}
110110
\item GNU GMP \cite{granlund2015gnu} and MPFR \cite{fousse2007mpfr} libraries. Distributed under the LGPL3 and GPL2 and can be acquired and installed from \url{https://gmplib.org/} and \url{http://www.mpfr.org/}, respectively.
111111

112-
\item CMake, available under a BSD 3-clause license. May be independently obtained at \url{https://cmake.org}.
112+
\item CMake \cite{hoffman2003cmake}, available under a BSD 3-clause license. May be independently obtained at \url{https://cmake.org}.
113113

114114
\item AMD \cite{amestoy1996approximate,amestoy2004algorithmamd}, available under a BSD 3-clause license and distributed along with SPEX. May be independently obtained at \url{www.suitesparse.com}
115115

@@ -1518,6 +1518,12 @@ \section{\texttt{SPEX\_gmp}: SPEX wrapper functions for GMP/MPFR}
15181518
\verb|mpfr_init2(x, size)|
15191519
& \verb|SPEX_mpfr_init2(x, size)|
15201520
& Initialize x with size bits \\ \hline
1521+
\verb|mpfr_clear(x)|
1522+
& \verb|SPEX_mpfr_clear(x)|
1523+
& Safely free \verb|mpfr_t| value \\ \hline
1524+
\verb|mpfr_set_null(x)|
1525+
& \verb|SPEX_mpfr_set_null(x)|
1526+
& Initialize the (pointer) contents of a \verb|mpfr_t| value \\ \hline
15211527
\verb|mpfr_set(x, y, rnd)|
15221528
& \verb|SPEX_mpfr_set(x, y, rnd)|
15231529
& $x = y$ \\ \hline
@@ -1579,9 +1585,15 @@ \section{\texttt{SPEX\_gmp}: SPEX wrapper functions for GMP/MPFR}
15791585
\verb|mpz_init2(x, size)|
15801586
& \verb|SPEX_mpz_init2(x, size)|
15811587
& Initialize x to size bits \\ \hline
1588+
\verb|mpz_clear(x)|
1589+
& \verb|SPEX_mpz_clear(x)|
1590+
& Safely free \verb|mpz_t| value \\ \hline
15821591
\verb|mpz_set(x, y)|
15831592
& \verb|SPEX_mpz_set(x, y)|
15841593
& $x = y$ (\verb|mpz_t|) \\ \hline
1594+
\verb|mpz_set_null(x)|
1595+
& \verb|SPEX_mpz_set_null(x)|
1596+
& Initialize the (pointer) contents of a \verb|mpz_t| value \\ \hline
15851597
\verb|mpz_set_ui(x, y)|
15861598
& \verb|SPEX_mpz_set_ui(x, y)|
15871599
& $x = y$ (\verb|uint64_t|) \\ \hline
@@ -1666,6 +1678,12 @@ \section{\texttt{SPEX\_gmp}: SPEX wrapper functions for GMP/MPFR}
16661678
\verb|mpq_init(x)|
16671679
& \verb|SPEX_mpq_init(x)|
16681680
& Initialize x \\ \hline
1681+
\verb|mpq_set_null(x)|
1682+
& \verb|SPEX_mpq_set_null(x)|
1683+
& Initialize the (pointer) contents of a \verb|mpq_t| value \\ \hline
1684+
\verb|mpq_clear(x)|
1685+
& \verb|SPEX_mpq_clear(x)|
1686+
& Safely free \verb|mpq_t| value \\ \hline
16691687
\verb|mpq_set(x, y)|
16701688
& \verb|SPEX_mpq_set(x, y)|
16711689
& $x = y$ \\ \hline
@@ -1807,6 +1825,67 @@ \section{\texttt{SPEX\_gmp}: SPEX wrapper functions for GMP/MPFR}
18071825
\end{verbatim}
18081826
} \end{mdframed}
18091827

1828+
\section{SPEX Helper Macros} \label{ss:SPEX_helper_macros}
1829+
1830+
In addition to the functionality described in this section; SPEX offers several helper macros to increase ease for the end user application. The first two macros are a simple try/catch mechanism which can be used to wrap functions for error handling. The next two give an easy interface to access entries $(i,j)$ in a matrix.
1831+
1832+
\subsection{\texttt{SPEX\_TRY} and
1833+
\texttt{SPEX\_CATCH}}
1834+
1835+
In a robust application, the return values from SPEX should be checked and properly handled in the case an error occurs. SPEX is written in C and thus it cannot rely on the try/catch mechanism of C++. Thus, \verb|SPEX_TRY| and \verb|SPEX_CHECK| aim to achieve this goal. We provide \verb|SPEX_TRY| and leave \verb|SPEX_CATCH| to the user to define.
1836+
1837+
\begin{mdframed}[userdefinedwidth=\textwidth]
1838+
{\footnotesize
1839+
\begin{verbatim}
1840+
#define SPEX_TRY(method) \
1841+
{ \
1842+
SPEX_info info = (method) ; \
1843+
if (info != SPEX_OK) \
1844+
{ \
1845+
SPEX_CATCH (info) ; \
1846+
} \
1847+
}
1848+
\end{verbatim}
1849+
} \end{mdframed}
1850+
1851+
An example definition of a \verb|SPEX_CATCH| is below. This example assumes that the user needs to free a matrix and return an error code.
1852+
\begin{mdframed}[userdefinedwidth=\textwidth]
1853+
{\footnotesize
1854+
\begin{verbatim}
1855+
#define SPEX_CATCH(info) \
1856+
{ \
1857+
SPEX_matrix_free (&A, NULL) ; \
1858+
fprintf (stderr, "SPEX failed: info %d, \
1859+
line %d, file %s\n", \
1860+
info, __LINE__, __FILE__) ; \
1861+
return (info) ; \
1862+
}
1863+
\end{verbatim}
1864+
} \end{mdframed}
1865+
1866+
With this mechanism, the user can safely wrap any SPEX function which returns \verb|SPEX_info| with \verb|SPEX_TRY|. For example, one can wrap.
1867+
1868+
\subsection{\texttt{SPEX\_1D}: Access matrix entries with 1D linear indexing.}
1869+
1870+
\begin{mdframed}[userdefinedwidth=\textwidth]
1871+
{\footnotesize
1872+
\begin{verbatim}
1873+
#define SPEX_1D(A,k,type) ((A)->x.type [k])
1874+
\end{verbatim}
1875+
} \end{mdframed}
1876+
1877+
This allows the $k$th entry of a matrix stored in any kind (CSC, triplet, dense) of any type (mpq, mpz, int64, double, int) to be returned. For example, to return the $n$th entry of a CSC matrix with \verb|mpz_t| data types, one would use \verb|SPEX_1D(A, n, mpz)|.
1878+
1879+
\subsection{\texttt{SPEX\_2D}: Access dense matrix with 2D indexing.}
1880+
1881+
\begin{mdframed}[userdefinedwidth=\textwidth]
1882+
{\footnotesize
1883+
\begin{verbatim}
1884+
#define SPEX_2D(A,i,j,type) SPEX_1D (A, (i)+(j)*((A)->m), type)
1885+
\end{verbatim}
1886+
} \end{mdframed}
1887+
1888+
This allows the $(i,j)$ entry of a dense matrix of any type (mpq, mpz, int64, double, int). For example to return the $(m,n)$ entry of a dense matrix with \verb|mpq_t| data types, one would use \verb|SPEX_2D(A, m, n, mpq)|.
18101889

18111890
%-------------------------------------------------------------------------------
18121891
\chapter{SPEX LU}\vspace{-0.75in} \label{ch:LeftLU}
@@ -2074,7 +2153,7 @@ \subsubsection{Populating data structures}
20742153
corresponding to CSC form, sparse triplet form or dense form, allocate a
20752154
shallow \verb|SPEX_matrix| and assign vectors accordingly, then use
20762155
\verb|SPEX_matrix_copy| to get a \verb|SPEX_matrix| in the desired kind and
2077-
type. For more details, refer to the example programs in \verb|SPEX/SPEX/Demo/*.c|. In a case when
2156+
type. For more details, refer to \verb|SPEX/SPEX/SPEX_Left_LU/Demo/example.c|. In a case when
20782157
\verb|A| is available in format other than CSC \verb|mpz|, and/or \verb|b| is
20792158
available in format other than dense \verb|mpz|, the following code snippet
20802159
shows how to get \verb|A| and \verb|b| in a required format.
@@ -2248,8 +2327,6 @@ \subsubsection{Converting the solution vector to the final desired form}
22482327
which utilize SPEX. These files demonstrate the usage of SPEX as
22492328
follows:
22502329

2251-
{\bf FIXME: description of demos is out of date}
2252-
22532330
\begin{itemize}
22542331
\item \verb|example.c|: This example generates a random dense $50 \times 50$
22552332
matrix and a random dense $50 \times 1$ right hand side vector $b$ and

‎SPEX/Include/SPEX.h

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -183,8 +183,6 @@ SPEX_info SPEX_version
183183
// SPEX_TRY: try a SPEX method and check for errors
184184
//------------------------------------------------------------------------------
185185

186-
// FIXME: add SPEX_TRY and SPEX_CATCH to user guide
187-
188186
// In a robust application, the return values from each call to SPEX should be
189187
// checked, and corrective action should be taken if an error occurs. The
190188
// SPEX_TRY macros assist in this effort.
@@ -460,8 +458,6 @@ typedef SPEX_matrix_struct *SPEX_matrix ;
460458
// SPEX_matrix macros
461459
//------------------------------------------------------------------------------
462460

463-
// FIXME add SPEX_1D and SPEX_2D macros to the user guide (needed by
464-
// SPEX demos)
465461

466462
// These macros simplify the access to entries in a SPEX_matrix.
467463
// The type parameter is one of: mpq, mpz, mpfr, int64, or fp64.
@@ -1017,7 +1013,6 @@ SPEX_info SPEX_mpfr_free_cache (void) ;
10171013

10181014
SPEX_info SPEX_mpfr_free_str (char *str) ;
10191015

1020-
// FIXME: add these 6 functions to the user guide:
10211016
SPEX_info SPEX_mpz_set_null (mpz_t x) ;
10221017
SPEX_info SPEX_mpq_set_null (mpq_t x) ;
10231018
SPEX_info SPEX_mpfr_set_null (mpfr_t x) ;

‎SPEX/TODO.txt

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,18 @@ Chris: User Guide
88

99
Added: (need in user guide)
1010

11-
SPEX_TRY
12-
SPEX_CATCH
13-
SPEX_1D
14-
SPEX_2D
15-
16-
SPEX_mpz_set_null
17-
SPEX_mpq_set_null
18-
SPEX_mpfr_set_null
19-
20-
SPEX_mpz_clear
21-
SPEX_mpq_clear
22-
SPEX_mpfr_clear
11+
(DONE) SPEX_TRY
12+
(DONE) SPEX_CATCH
13+
(DONE) SPEX_1D
14+
(DONE) SPEX_2D
15+
16+
(DONE) SPEX_mpz_set_null
17+
(DONE) SPEX_mpq_set_null
18+
(DONE) SPEX_mpfr_set_null
19+
20+
(DONE) SPEX_mpz_clear
21+
(DONE) SPEX_mpq_clear
22+
(DONE) SPEX_mpfr_clear
2323

2424
Erick: check copyright
2525

0 commit comments

Comments
 (0)