Archive standard solutions to exercises

Author: anyzelman

ALP_Tutorial.tex

@@ -201,7 +201,7 @@ \subsection{Basic Container I/O}
 \end{lstlisting}
 The type \texttt{grb::RC} is the standard return type; ALP primitives\footnote{that are not simple `getters' like \texttt{grb::nnz}} always return an error code, and, if no error is encountered, return \texttt{grb::SUCCESS}. Iterators in ALP may be either \emph{sequential} or \emph{parallel}. Start-end iterator pairs that are sequential, such as retrieved from the parser in the above snippet, iterate over all elements of the underlying container (in this case, all nonzeroes in the sparse matrix file). A parallel iterator, by contrast, only retrieves some subset of elements $V_s$, where $s$ is the process ID. It assumes that there are a total of $p$ subsets $V_i$, where $p$ is the total number of processes. These subsets are pairwise disjoint (i.e., $V_i\cap V_j=\emptyset$ for all $i\neq j, 0\leq i,j<p$), while $\cup V_i$ corresponds to all elements in the underlying container. Parallel iterators are useful when launching an ALP/GraphBLAS program with multiple processes to benefit from distributed-memory parallelisation; in such cases, it would be wasteful if every process iterates over all data elements on data ingestion-- instead, parallel I/O is preferred. ALP primitives that take iterator pairs as input must be aware of the I/O type, which is passed as the last argument to \texttt{grb::buildMatrixUnique} in the above code snippet.
 
-\textbf{Exercise 5.} Use the \texttt{FileMatrixParser} and its iterators to build $A$ from \texttt{west0497.mtx}. Have it print the number of nonzeroes in $A$ after buildMatrixUnique. Then modify the \texttt{main} function to take as the first program argument a path to a .mtx file, pass that path to the ALP/GraphBLAS program. Find and download the west0497 matrix from the SuiteSparse matrix collection, and run the application with the path to the downloaded matrix. If all went well, its output should be something like:
+\noindent \textbf{Exercise 5.} Use the \texttt{FileMatrixParser} and its iterators to build $A$ from \texttt{west0497.mtx}. Have it print the number of nonzeroes in $A$ after buildMatrixUnique. Then modify the \texttt{main} function to take as the first program argument a path to a .mtx file, pass that path to the ALP/GraphBLAS program. Find and download the west0497 matrix from the SuiteSparse matrix collection, and run the application with the path to the downloaded matrix. If all went well, its output should be something like:
 \begin{lstlisting}[keywordstyle=\ttfamily]
 Info: grb::init (reference) called.
 elements in x: 497
@@ -214,6 +214,50 @@ \subsection{Basic Container I/O}
 Info: grb::finalize (reference) called.
 \end{lstlisting}
 
+\noindent \textbf{Bonus question.} Why is there no \texttt{grb::set(matrix,scalar)} primitive?
+
+\subsection{Copying, Masking, and Standard Matrices}
+
+Continuing from the last exercise, the following code would store a copy of $y$ in $x$ and a copy of $A$ in $B$:
+\begin{lstlisting}
+grb::Matrix< double > B( 497, 497 );
+assert( grb::capacity( B ) == 497 );
+grb::RC rc = grb::set( x, y );
+rc = rc ? rc : grb::set( B, A, grb::RESIZE );
+rc = rc ? rc : grb::set( B, A, grb::EXECUTE );
+\end{lstlisting}
+\noindent \textbf{Question.} What does the code pattern \texttt{rc = rc ? rc : <function call>;} achieve?
+
+Note that after instantiation of $B$ (line 1 in the above) it will be allocated with a default capacity of $497$ values maximum (line 2). However, $A$ from the preceding exercise has $1\ 727$ values; therefore, simply executing \texttt{grb::set( B, A )} would return \texttt{grb::ILLEGAL}. Rather than manually having to call \texttt{grb::resize( B, 1727 )} to make the copy work, the above snippet instead first requests ALP/GraphBLAS to figure out the required capacity of $B$ and resize it if necessary (line 4), before then executing the copy (line 5). The execute phase is default-- i.e., the last line could equivalently have read \texttt{rc = rc ? rc : grb::set( B, A );}. Similarly, the vector copy (line 3) could have been broken up in resize-execute phases, however, from the previous exercises we already learned that the default vector capacity guarantees are sufficient to store $y$ and so we call the execute phase immediately.
+
+\noindent \textbf{Question.} $A$ contains $1727$ double-precision elements. Are these $1727$ nonzeroes?
+
+The \texttt{grb::set} primitive may also take a mask argument. The mask determines which outputs are computed and which outputs are discarded. For example, recall that $y$ from the previous exercise is a vector of size $497$ that contains only one value $y_{200}=$\texttt{true}. Then
+\begin{lstlisting}
+grb::RC rc = grb::set( x, y, false );
+\end{lstlisting}
+results in a vector $x$ that has one entry only: $x_{200}=\texttt{false}$. This is because $y$ has no elements anywhere except at position $200$, and hence the mask evaluates \texttt{false} for any $0\leq i<497, i\neq200$, and no entries are generated by the primitive at those positions. At position $200$, however, the mask $y$ does contain an element whose value is \texttt{true}, and hence the \texttt{grb::set} primitive will generate an output entry there. The value of the entry $x_{200}$ is set to the value given to the primitive, which is \texttt{false}. All GraphBLAS primitives with an output container can take mask arguments.
+
+\noindent \textbf{Question.} What would \texttt{grb::set( y, x, true )} return for $y$, assuming it is computed immediately after the preceding code snippet?
+
+We have shown how matrices may be built from input iterators while similarly, vectors may be built from standard iterators through \texttt{grb::buildVectorUnique} as well. Iterator-based ingestion also allows for the construction of vectors and matrices that have regular structures. ALP/GraphBLAS comes with some standard recipes that exploit this, for example to build an $n\times n$ identity matrix:
+\begin{lstlisting}
+...
+#include <graphblas/algorithms/matrix_factory.hpp>
+...
+
+    const grb::Matrix< double > identity = grb::algorithms::matrices< double >::identity( n );
+
+...
+\end{lstlisting}
+\href{http://albert-jan.yzelman.net/alp/v0.8-preview/classgrb_1_1algorithms_1_1matrices.html#a1336accbaf6a61ebd890bef9da4116fc}{Other regular patterns supported} are \emph{eye} (similar to identity but not required to be a square matrix) and \emph{diag} (which takes an optional parameter $k$ to generate offset the diagonal, e.g., to generate a superdiagonal matrix). The class includes a set of constructors that result in dense matrices as well, including \emph{dense}, \emph{full}, \emph{zeros}, and \emph{ones}; note, however, that ALP/GraphBLAS is not optimised to handle dense matrices efficiently and so their use is discouraged\footnote{for similar reasons, actually, there is no primitive \texttt{grb::set(matrix,scalar)} in the GraphBLAS API}. While constructing matrices from standard file formats and through general iterators hence are key features for usability, it is also possible to derive matrices from existing ones via \texttt{grb::set(matrix,mask,value)}.
+
+\noindent \textbf{Exercise 6.} Copy the code from the previous exercise, and modify it to determine whether $A$ holds explicit zeroes; i.e., entries in $A$ that have numerical value zero. \textbf{Hint:} it is possible to complete this exercise using only masking and copiying. For bonus points, consider making use of the \texttt{grb::descriptors::invert\_mask} descriptor described \href{http://albert-jan.yzelman.net/alp/v0.8-preview/namespacegrb_1_1descriptors.html}{here}.
+
+\noindent \textbf{Exercise 7.} Determine how many explicit zeroes exist on the diagonal, superdiagonal, and subdiagonal of $A$; i.e., compute $|\{A_{ij}\ |\ A_{ij}=0, |i-j|\leq1, 0\leq i,j<497\}|$.
+
+\noindent \textbf{Bonus question.} How much memory beyond that which is required to store the $n\times n$ identity matrix will a call to \texttt{matrices< double >::identity( n )} consume? \textbf{Hint:} consider that the iterators passed to \texttt{buildMatrixUnique} iterate over regular index sequences that can easily be systematically enumerated.
+
 \subsection{Semirings and Algebraic Operations}
 
 A key feature of GraphBLAS (and ALP) is that operations are defined over semirings rather than just the conventional arithmetic operations. A semiring consists of a pair of operations (an “addition” and a “multiplication”) along with their identity elements, which generalize the standard arithmetic (+ and $\times$). GraphBLAS allows using different semirings to, for example, perform computations like shortest paths or logical operations by substituting the plus or times operations with min, max, logical OR/AND, etc. In GraphBLAS, matrix multiplication is defined in terms of a semiring: the “add” operation is used to accumulate results, and the “multiply” operation is used when combining elements.

solutions/3-4-5-container-io.cpp

@@ -0,0 +1,98 @@
+
+#include <cstddef>
+#include <cstring>
+
+#include <graphblas.hpp>
+#include <graphblas/utils/parser.hpp>
+
+#include <assert.h>
+
+
+constexpr size_t max_fn_size = 255;
+typedef char Filename[ max_fn_size ];
+
+void hello_world( const Filename &in, int &out ) {
+	grb::Vector< bool > x( 497 ), y( 497, 1 );
+	grb::Matrix< void > A( 497, 497, 1727 );
+
+	grb::RC rc = grb::set( x, false );
+	rc = rc ? rc : grb::setElement( y, true, 200 );
+	if( rc != grb::SUCCESS ) {
+		out = 10;
+		return;
+	}
+
+	std::cout << "elements in x: " << grb::nnz( x ) << "\n";
+	std::cout << "elements in y: " << grb::nnz( y ) << "\n";
+	std::cout << "cacacity of y: " << grb::capacity( y ) << "\n";
+
+	for( const auto &pair : y ) {
+		std::cout << "y[ " << pair.first << " ] = " << pair.second << "\n";
+	}
+
+	size_t x_nnz = 0;
+	for( const auto &pair : x ) {
+		(void) ++x_nnz;
+		if( pair.second ) {
+			std::cerr << "x[ " << pair.first << " ] reads true "
+				<< "but false was expected!\n";
+			out = 20;
+			return;
+		}
+	}
+	if( x_nnz != 497 ) {
+		std::cerr << "Output iterator of x retrieved " << x_nnz << " elements, "
+			<< "expected 497!\n";
+		out = 30;
+		return;
+	}
+
+	grb::utils::MatrixFileReader< double > parser( in, true );
+	if( parser.m() != 497 || parser.n() != 497 ) {
+		std::cerr << in << " corresponds to a matrix of unexpected size\n";
+		out = 40;
+		return;
+	}
+	{
+		const auto iterator = parser.begin();
+		std::cout << "First parsed entry: ( " << iterator.i() << ", " << iterator.j() << " ) = " << iterator.v() << "\n";
+	}
+
+	rc = grb::buildMatrixUnique(
+		A,
+		parser.begin( grb::SEQUENTIAL ), parser.end( grb::SEQUENTIAL ),
+		grb::SEQUENTIAL
+	);
+	if( rc != grb::SUCCESS ) {
+		std::cerr << "Error encountered during reading " << in << "\n";
+		out = 50;
+		return;
+	}
+	std::cout << "nonzeroes in A: " << grb::nnz( A ) << "\n";
+
+	// all OK
+	out = 0;
+}
+
+int main( int argc, char ** argv ) {
+	if( argc < 2 || argc > 2 ) {
+		std::cout << "Usage: " << argv[ 0 ] << " </path/to/west0497.mtx>\n";
+		return 0;
+	}
+
+	// get input
+	Filename fn;
+	(void) std::strncpy( fn, argv[ 1 ], max_fn_size );
+
+	// set up output field
+	int error_code = 100;
+
+	// launch hello world program
+	grb::Launcher< grb::AUTOMATIC > launcher;
+	assert( launcher.exec( &hello_world, fn, error_code, true )
+		== grb::SUCCESS );
+
+	// return with the hello_world error code
+	return error_code;
+}
+

solutions/alp_hw.cpp

@@ -0,0 +1,25 @@
+
+#include <cstddef>
+#include <cstring>
+#include <graphblas.hpp>
+#include <assert.h>
+constexpr size_t max_fn_size = 255;
+typedef char Filename[ max_fn_size ];
+void hello_world( const Filename &in, int &out ) {
+std::cout << "Hello from " << in << std::endl;
+out = 0;
+}
+int main( int argc, char ** argv ) {
+// get input
+Filename fn;
+(void) std::strncpy( fn, argv[ 0 ], max_fn_size );
+// set up output field
+int error_code = 100;
+// launch hello world program
+grb::Launcher< grb::AUTOMATIC > launcher;
+assert( launcher.exec( &hello_world, fn, error_code, true )
+== grb::SUCCESS );
+// return with the hello_world error code
+return error_code;
+}
+