\documentclass[12pt]{article}
\usepackage{url}
\urlstyle{sf}
\usepackage[svgnames]{xcolor}
\usepackage[colorlinks,linkcolor=Blue,citecolor=Blue,urlcolor=Blue]{hyperref}
\usepackage{amssymb}
\usepackage{amsmath}
\usepackage{framed}
\usepackage{mdframed}
% \usepackage{geometry}
% \usepackage{pdflscape}
\newmdenv[backgroundcolor=white]{spec}
\newmdenv[backgroundcolor=yellow]{specbeta}
\hyphenation{Suite-Sparse}
\hyphenation{Graph-BLAS}
\hyphenation{Suite-Sparse-Graph-BLAS}
\hyphenation{Suite-Sparse-Graph-BLAS}

\newenvironment{packed_itemize}{
\begin{itemize}
  \setlength{\itemsep}{1pt}
  \setlength{\parskip}{0pt}
  \setlength{\parsep}{0pt}
}{\end{itemize}}

\title{User Guide for SuiteSparse:GraphBLAS}

\author{Timothy A. Davis \\
\small
davis@tamu.edu, Texas A\&M University. \\
\small
http://www.suitesparse.com and http://aldenmath.com
}

% version and date are set by cmake (see GraphBLAS/CMakeLists.txt)
\input{GraphBLAS_version.tex}

%-------------------------------------------------------------------------------
\begin{document}
%-------------------------------------------------------------------------------
\maketitle

\begin{abstract}
SuiteSparse:GraphBLAS is a full implementation of the GraphBLAS standard,
which defines a set of sparse matrix operations on an extended algebra of
semirings using an almost unlimited variety of operators and types.  When
applied to sparse adjacency matrices, these algebraic operations are equivalent
to computations on graphs.  GraphBLAS provides a powerful and expressive
framework for creating graph algorithms based on the elegant mathematics of
sparse matrix operations on a semiring.
\end{abstract}

\newpage
{\small
\tableofcontents
}

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{intro}

The GraphBLAS standard defines sparse matrix and vector operations on an
extended algebra of semirings.  The operations are useful for creating a wide
range of graph algorithms.

For example, consider the matrix-matrix multiplication, ${\bf C=AB}$.  Suppose
${\bf A}$ and ${\bf B}$ are sparse $n$-by-$n$ Boolean adjacency matrices of two
undirected graphs.  If the matrix multiplication is redefined to use logical
AND instead of scalar multiply, and if it uses the logical OR instead of add,
then the matrix ${\bf C}$ is the sparse Boolean adjacency matrix of a graph
that has an edge $(i,j)$ if node $i$ in ${\bf A}$ and node $j$ in ${\bf B}$
share any neighbor in common.  The OR-AND pair forms an algebraic semiring, and
many graph operations like this one can be succinctly represented by matrix
operations with different semirings and different numerical types.  GraphBLAS
provides a wide range of built-in types and operators, and allows the user
application to create new types and operators without needing to recompile the
GraphBLAS library.

% API version and date are set by cmake (see GraphBLAS/CMakeLists.txt)

See \cite{Davis18} for a journal article on SuiteSparse:GraphBLAS, and
\cite{Davis18b} for a more recent conference paper.  A full and precise
definition of the GraphBLAS specification is provided in {\em The GraphBLAS C
API Specification} by {Ayd\i n Bulu\c{c}, Timothy Mattson, Scott McMillan,
Jos\'e Moreira, and Carl Yang} \cite{BulucMattsonMcMillanMoreiraYang17,spec},
based on {\em GraphBLAS Mathematics} by Jeremy Kepner \cite{Kepner2017}.  The
GraphBLAS C API Specification is available at \url{http://graphblas.org}.  This
version of SuiteSparse:GraphBLAS fully conforms to Version
\input{GraphBLAS_API_version.tex} of that specification.  In this User Guide,
aspects of the GraphBLAS specification that would be true for any GraphBLAS
implementation are simply called ``GraphBLAS.'' Details unique to this
particular implementation are referred to as SuiteSparse:GraphBLAS. 

\begin{spec}
{\bf SPEC:} See the tag {\bf SPEC:} for SuiteSparse extensions to the spec.
They are also placed in text boxes like this one.  All functions, objects, and
macros with a name of the form \verb'GxB_*' are extensions to the spec.
\end{spec}

\newpage
\subsection{Release Notes:}

\begin{itemize}

\item Version 2.3 (Feb 2019) improves the performance of many GraphBLAS
operations, including an early-exit for monoids.  These changes have a
significant impact on breadth-first-search (a performance bug was also fixed in
the two BFS \verb'Demo' codes).  The matrix and vector import/export functions
were added (Section~\ref{import_export}), in support of the new LAGraph project
(\url{https://github.com/GraphBLAS/LAGraph}, see also Section~\ref{lagraph}).
LAGraph includes a push-pull BFS in GraphBLAS that is faster than two versions
in the \verb'Demo' folder.  \verb'GxB_init' was added to allow the memory
manager functions (\verb'malloc', etc) to be specified.

\item
Version 2.2 (Nov 2018)
adds user-defined objects at compile-time, via user \verb'*.m4' files placed in
\verb'GraphBLAS/User', which use the \verb'GxB_*_define' macros described in
Section~\ref{precompile}.  The default matrix format is now \verb'GxB_BY_ROW'.
% If you want the default format to be by column (the default in Version 2.1 and
% earlier), just compile with \verb'-DBYCOL', or add \newline
% \verb'GxB_set (GxB_FORMAT, GxB_BY_COL) ;'
% after calling \verb'GrB_init'.
Also added are the \verb'GxB_*print' methods for printing the contents of each
GraphBLAS object (Section~\ref{fprint}).   PageRank demos have been added to
the \verb'Demos' folder.
Prior versions required GraphBLAS to be compiled with OpenMP, for it to be
thread-safe.  It can now be compiled with POSIX pthreads.  The \verb'cmake'
script automatically detects if OpenMP and/or POSIX pthreads are available.
Demos have been added to show how GraphBLAS can be called from a multi-threaded
user application.

\item
Version 2.1 (Oct 2018) was
a major update with support for new matrix formats
(by row or column, and hypersparse matrices), and MATLAB-like colon notation
(\verb'I=begin:end' or \verb'I=begin:inc:end').  Some graph algorithms are more
naturally expressed with matrices stored by row, and this version includes the
new \verb'GxB_BY_ROW' format.  The default format in Version 2.1 and
prior versions is by column.
New extensions to GraphBLAS in this version include \verb'GxB_get',
\verb'GxB_set', and \verb'GxB_AxB_METHOD', \verb'GxB_RANGE', \verb'GxB_STRIDE',
and \verb'GxB_BACKWARDS', and their related definitions, described in
Sections~\ref{descriptor},~\ref{options},~and~\ref{colon}.

\item
Version 2.0 (March 2018) addressed changes in the GraphBLAS C API
Specification and added \verb'GxB_kron' and \verb'GxB_resize'.

\item
Version 1.1 (Dec 2017) primarily improved the performance.

\item
Version 1.0 was released on Nov 25, 2017.
\end{itemize}


\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Basic Concepts} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{basic}

Since the {\em GraphBLAS C API Specification} provides a precise definition of
GraphBLAS, not every detail of every function is provided here.  For example,
some error codes returned by GraphBLAS are self-explanatory, but since a
specification must precisely define all possible error codes a function can
return, these are listed in detail in the {\em GraphBLAS C API Specification}.
However, including them here is not essential and the additional information on
the page might detract from a clearer view of the essential features of the
GraphBLAS functions.

This User Guide also assumes the reader is familiar with the MATLAB language,
created by Cleve
Moler.  MATLAB supports only the conventional plus-times semiring on sparse
double and complex matrices, but a MATLAB-like notation easily extends to the
arbitrary semirings used in GraphBLAS.  The matrix multiplication in the
example in the Introduction can be written in MATLAB notation as \verb'C=A*B',
if the Boolean \verb'OR-AND' semiring is understood.  Relying on a MATLAB-like
notation allows the description in this User Guide to be expressive, easy to
understand, and terse at the same time.  {\em The GraphBLAS C API
Specification} also makes use of some MATLAB-like language, such as the colon
notation.

MATLAB notation will always appear here in fixed-width font, such as
\verb'C=A*B(:,j)'.  In standard mathematical notation it would be written as
the matrix-vector multiplication ${\bf C = A b}_j$ where ${\bf b}_j$ is the
$j$th column of the matrix ${\bf B}$.  The GraphBLAS standard is a C API and
SuiteSparse:GraphBLAS is written in C, and so a great deal of C syntax appears
here as well, also in fixed-width font.  This User Guide alternates between all
three styles as needed.

%===============================================================================
\subsection{Graphs and sparse matrices} %=======================================
%===============================================================================
\label{sparse}

Graphs can be huge, with many nodes and edges.  A dense adjacency matrix ${\bf
A}$ for a graph of $n$ nodes takes $O(n^2)$ memory, which is impossible if $n$
is, say, a million.  Most graphs arising in practice are sparse, however, with
only $|{\bf A}|=O(n)$ edges, where $|{\bf A}|$ denotes the number of edges in
the graph, or the number of explicit entries present in the data structure for
the matrix ${\bf A}$.  Sparse graphs with millions of nodes and edges can
easily be created by representing them as sparse matrices, where only explicit
values need to be stored.  Some graphs are {\em hypersparse}, with ${|\bf A}|
<< n$.  SuiteSparse:GraphBLAS supports two kinds of sparse matrix formats: a
regular sparse format, taking $O(n+|{\bf A}|)$ space, and a hypersparse format
taking only $O(|{\bf A}|)$ space.  As a result, creating a sparse matrix of
size $n$-by-$n$ where $n=2^{60}$ (about $10^{18}$) can be done on quite easily
on a commodity laptop, limited only by $|{\bf A}|$.

A sparse matrix data structure only stores a subset of the possible $n^2$
entries, and it assumes the values of entries not stored have some implicit
value.  In conventional linear algebra, this implicit value is zero, but it
differs with different semirings.  Explicit values are called {\em entries} and
they appear in the data structure.  The {\em pattern} of a matrix  defines
where its explicit entries appear.  It will be referenced in one of two
equivalent ways.  It can be viewed as a set of indices $(i,j)$, where $(i,j)$
is in the pattern of a matrix ${\bf A}$ if ${\bf A}(i,j)$ is an explicit value.
It can also be viewed as a Boolean matrix ${\bf S}$ where ${\bf S}(i,j)$ is
true if $(i,j)$ is an explicit entry and false otherwise.  In MATLAB notation,
\verb'S=spones(A)' or \verb'S=(A~=0)', if the implicit value is zero.  The
\verb'(i,j)' pairs, and their values, can also be extracted from the matrix via
the MATLAB expression \verb'[I,J,X]=find(A)', where the \verb'k'th tuple
\verb'(I(k),J(k),X(k))' represents the explicit entry \verb'A(I(k),J(k))', with
numerical value \verb'X(k)' equal to $a_{ij}$, with row index $i$=\verb'I(k)'
and column index $j$=\verb'J(k)'.

The entries in the pattern of ${\bf A}$ can take on any value, including the
implicit value, whatever it happens to be.  This differs slightly from MATLAB,
which always drops all explicit zeros from its sparse matrices.  This is a
minor difference but it cannot be done in GraphBLAS.  For example, in the
max-plus tropical algebra, the implicit value is negative infinity, and zero
has a different meaning.  Here, the MATLAB notation used will assume that no
explicit entries are ever dropped because their explicit value happens to match
the implicit value.

{\em Graph Algorithms in the Language on Linear Algebra}, Kepner and Gilbert,
eds., provides a framework for understanding how graph algorithms can be
expressed as matrix computations \cite{KepnerGilbert2011}.  For additional
background on sparse matrix algorithms, see also \cite{Davis06book} and
\cite{DavisRajamanickamSidLakhdar16}.

%===============================================================================
\subsection{Overview of GraphBLAS methods and operations} %=====================
%===============================================================================
\label{overview}

GraphBLAS provides a collection of {\em methods} to create, query, and free its
of objects: sparse matrices, sparse vectors, types, operators, monoids,
semirings, and a descriptor object used for parameter settings.  Details are
given in Section~\ref{objects}.  Once these objects are created they can be
used in mathematical {\em operations} (not to be confused with the how the term
{\em operator} is used in GraphBLAS).  A short summary of these operations and
their nearest MATLAB analog is given in the table below.

% \vspace{0.1in}
\begin{tabular}{ll}
operation                           & approximate MATLAB analog \\
\hline
matrix multiplication               & \verb'C=A*B' \\
element-wise operations             & \verb'C=A+B' and \verb'C=A.*B' \\
reduction to a vector or scalar     & \verb's=sum(A)' \\
apply unary operator                & \verb'C=-A' \\
transpose                           & \verb"C=A'" \\
submatrix extraction                & \verb'C=A(I,J)' \\
submatrix assignment                & \verb'C(I,J)=A' \\
\hline
\end{tabular}
\vspace{0.1in}

GraphBLAS can do far more than what MATLAB can do in these rough analogs, but
the list provides a first step in describing what GraphBLAS can do.  Details of
each GraphBLAS operation are given in Section~\ref{operations}.  With this
brief overview, the full scope of GraphBLAS extensions of these operations can
now be described.

GraphBLAS has 11 built-in scalar types: Boolean, single and double precision
floating-point, and 8, 16, 32, and 64-bit signed and unsigned integers.  In
addition, user-defined scalar types can be created from nearly any C
\verb'typedef', as long as the entire type fits in a fixed-size contiguous
block of memory (of arbitrary size).  All of these types can be used to create
GraphBLAS sparse matrices or vectors.

The scalar addition of conventional matrix multiplication is replaced with a
{\em monoid}.  A monoid is an associative and commutative binary operator
\verb'z=f(x,y)' where all three domains are the same (the types of \verb'x',
\verb'y', and \verb'z'), and where the operator has an identity value \verb'id'
such that \verb'f(x,id)=f(id,x)=x'.  Performing matrix multiplication with a
semiring uses a monoid in place of the ``add'' operator, scalar addition being
just one of many possible monoids.  The identity value of addition is zero,
since $x+0=0+x=x$.   GraphBLAS includes eight built-in operators suitable for
use as a monoid: min (with an identity value of positive infinity), max (whose
identity is negative infinity), add (identity is zero) multiply (with an
identity of one), and four logical operators: AND, OR, exclusive-OR, and
Boolean equality.  User-created monoids can be defined with any associative and
commutative operator that has an identity value.

Finally, a semiring can use any built-in or user-defined binary operator
\verb'z=f(x,y)' as its ``multiply'' operator, as long as the type of its
output, \verb'z' matches the type of the semiring's monoid.
The user application can create any semiring based on any types, monoids,
and multiply operators, as long these few rules are followed.

Just considering built-in types and operators, GraphBLAS can perform
\verb'C=A*B' in 960 unique semirings.  With typecasting, any of these 960
semirings can be applied to matrices \verb'C', \verb'A', and \verb'B' of any of
the 11 types, in any combination.  This gives $960 \times 11^3 = 1,277,760$
possible kinds of sparse matrix multiplication supported by GraphBLAS, and this
is counting just built-in types and operators.  By contrast, MATLAB provides
just two semirings for its sparse matrix multiplication \verb'C=A*B':
plus-times-double and plus-times-complex, not counting the typecasting that
MATLAB does when multiplying a real matrix times a complex matrix.  All of the
1.3 million forms of matrix multiplication methods in SuiteSparse:GraphBLAS are
typically just as fast as computing \verb'C=A*B' in MATLAB using its own native
sparse matrix multiplication methods, and sometimes faster.

A monoid can also be used in a reduction operation, like \verb's=sum(A)' in
MATLAB.  MATLAB provides the plus, times, min, and max reductions of a real or
complex sparse matrix as \verb's=sum(A)',  \verb's=prod(A)', \verb's=min(A)',
and \verb's=max(A)', respectively.  In GraphBLAS, any monoid can be used (min,
max, plus, times, AND, OR, exclusive-OR, equality, or any user-defined monoid,
on any user-defined type).

Element-wise operations are also expanded from what can be done in MATLAB.
Consider matrix addition, \verb'C=A+B' in MATLAB.  The pattern of the result is
the set union of the pattern of \verb'A' and \verb'B'.  In GraphBLAS, any
binary operator can be used in this set-union ``addition.''  The operator is
applied to entries in the intersection.  Entries in \verb'A' but not \verb'B',
or visa-versa, are copied directly into \verb'C', without any application of
the binary operator.  The accumulator operation for ${\bf Z = C \odot T}$
described in Section~\ref{accummask} is one example of this set-union
application of an arbitrary binary operator.

Consider element-wise multiplication, \verb'C=A.*B' in MATLAB.  The operator
(multiply in this case) is applied to entries in the set intersection, and the
pattern of \verb'C' just this set intersection.  Entries in \verb'A' but not
\verb'B', or visa-versa, do not appear in \verb'C'.  In GraphBLAS, any binary
operator can be used in this manner, not just scalar multiplication.  The
difference between element-wise ``add'' and ``multiply'' is not the operators,
but whether or not the pattern of the result is the set union or the set
intersection.  In both cases, the operator is only applied to the set
intersection.

Finally, GraphBLAS includes a {\em non-blocking} mode where operations can be
left pending, and saved for later.  This is very useful for submatrix
assignment (\verb'C(I,J)=A' where \verb'I' and \verb'J' are integer vectors),
or scalar assignment (\verb'C(i,j)=x' where \verb'i' and \verb'j' are scalar
integers).  Because of how MATLAB stores its matrices, adding and deleting
individual entries is very costly.  For example, this is very slow in MATLAB,
taking $O(nz^2)$ time:

    \begin{mdframed}
    {\footnotesize
    \begin{verbatim}
    A = sparse (m,n) ;   % an empty sparse matrix
    for k = 1:nz
        compute a value x, row index i, and column index j
        A (i,j) = x ;
    end\end{verbatim}}\end{mdframed}

The above code is very easy read and simple to write, but exceedingly slow.  In
MATLAB, the method below is preferred and is far faster, taking only $O(|{\bf
A}|)$ time.  It can easily be a million times faster than the method above.
Unfortunately the second method below is a little harder to read and a little
less natural to write:

    \begin{mdframed}
    {\footnotesize
    \begin{verbatim}
    I = zeros (nz,1) ;
    J = zeros (nz,1) ;
    X = zeros (nz,1) ;
    for k = 1:nz
        compute a value x, row index i, and column index j
        I (k) = i ;
        J (k) = j ;
        X (k) = x ;
    end
    A = sparse (I,J,X,m,n) ;   \end{verbatim}} \end{mdframed}

GraphBLAS can do both methods.  SuiteSparse:GraphBLAS stores its matrices in a
format that allows for pending computations, which are done later in bulk, and
as a result it can do both methods above equally as fast as the MATLAB
\verb'sparse' function, allowing the user to write simpler code.

%===============================================================================
\subsection{The accumulator and the mask} %=====================================
%===============================================================================
\label{accummask}

Most GraphBLAS operations can be modified via transposing input matrices, using
an accumulator operator, applying a mask or its complement, and by clear all
entries the matrix \verb'C' after using it in the accumulator operator but
before the final results are written back into it.  All of these steps are
optional, and are controlled by a descriptor object that holds parameter
settings (see Section~\ref{descriptor}) that control the following options:

\begin{itemize}
\item the input matrices \verb'A' and/or \verb'B' can be transposed first.

\item an accumulator operator can be used, like the plus in the statement
    \verb'C=C+A*B'.  The accumulator operator can be any binary operator, and
    an element-wise ``add'' (set union) is performed using the operator.

\item an optional {\em mask} can be used to selectively write the results to
    the output.  The mask is a sparse Boolean matrix \verb'Mask' whose size is
    the same size as the result.  If \verb'Mask(i,j)' is true, then the
    corresponding entry in the output can be modified by the computation.  If
    \verb'Mask(i,j)' is false, then the corresponding in the output is
    protected and cannot be modified by the computation.  The \verb'Mask'
    matrix acts exactly like logical matrix indexing in MATLAB, with one
    minor difference: in GraphBLAS notation, the mask operation is $\bf C
    \langle M \rangle = Z$, where the mask $\bf M$ appears only on the
    left-hand side.  In MATLAB, it would appear on both sides as
    \verb'C(Mask)=Z(Mask)'.  If no mask is provided, the \verb'Mask' matrix is
    implicitly all true.  This is indicated by passing the value
    \verb'GrB_NULL' in place of the \verb'Mask' argument in GraphBLAS
    operations.

\end{itemize}

\noindent
This process can be described in mathematical notation as:
    \vspace{-0.2in}
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> ${\bf A = A}^{\sf T}$, if requested via descriptor (first input option) \\
    \> ${\bf B = B}^{\sf T}$, if requested via descriptor (second input option) \\
    \> ${\bf T}$ is computed according to the specific operation  \\
    \> ${\bf C \langle M \rangle = C \odot T}$,
        accumulating and writing the results back via the mask
    \end{tabbing} }
\noindent
The application of the mask and the accumulator operator is written as
${\bf C \langle M \rangle = C \odot T}$ where ${\bf Z = C \odot T}$ denotes the
application of the accumulator operator, and
${\bf C \langle M \rangle = Z}$
denotes the mask operator via the Boolean matrix ${\bf M}$.  The Accumulator
Phase, ${\bf Z = C \odot T}$, is performed as follows:
    \vspace{-0.2in}
    % accum: Z = C odot T
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> {\bf Accumulator Phase}: compute ${\bf Z = C \odot T}$: \\
    \> \> if \verb'accum' is \verb'NULL' \\
    \> \>\>    ${\bf Z = T}$ \\
    \> \> else \\
    \> \>\>    ${\bf Z = C \odot T}$
    \end{tabbing}}
The accumulator operator is $\odot$ in GraphBLAS notation, or \verb'accum'
in the code.  The pattern of ${\bf C \odot T}$ is the set union of the
patterns of ${\bf C}$ and ${\bf T}$, and the operator is applied only on the
set intersection of ${\bf C}$ and ${\bf T}$.  Entries in neither the pattern
of ${\bf C}$ nor ${\bf T}$ do not appear in the pattern of ${\bf Z}$.  That is:
    \newpage % \vspace{-0.2in}
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> for all entries $(i,j)$ in ${\bf C \cap T}$
    (that is, entries in both ${\bf C}$ and ${\bf T}$) \\
    \> \> $z_{ij} = c_{ij} \odot t_{ij}$ \\
    \> for all entries $(i,j)$ in ${\bf C \setminus T}$
    (that is, entries in ${\bf C}$ but not ${\bf T}$) \\
    \> \> $z_{ij} = c_{ij}$ \\
    \> for all entries $(i,j)$ in ${\bf T \setminus C}$
    (that is, entries in ${\bf T}$ but not ${\bf C}$) \\
    \> \> $z_{ij} = t_{ij}$
    \end{tabbing} }
The Accumulator Phase is followed by the Mask/Replace Phase, ${\bf C \langle M \rangle = Z}$
as controlled by the \verb'GrB_REPLACE' and \verb'GrB_SCMP' descriptor options:
    \vspace{-0.2in}
    % mask/replace/scmp: C<M> = Z
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \>{\bf Mask/Replace Phase}: compute ${\bf C \langle M \rangle = Z}$: \\
    \> \> if (\verb'GrB_REPLACE') delete all entries in ${\bf C}$ \\
    \> \> if \verb'Mask' is \verb'NULL' \\
    \> \>\>    if (\verb'GrB_SCMP') \\
    \> \>\>\>      ${\bf C}$ is not modified \\
    \> \>\>    else \\
    \> \>\>\>      ${\bf C = Z}$ \\
    \> \> else \\
    \> \>\>    if (\verb'GrB_SCMP') \\
    \> \>\>\>      ${\bf C \langle \neg M \rangle  = Z}$ \\
    \> \>\>    else \\
    \> \>\>\>      ${\bf C \langle M \rangle  = Z}$
    \end{tabbing} }
Both phases of the accum/mask process are illustrated in MATLAB notation in
Figure~\ref{fig_accummask}.  A GraphBLAS operation starts with its primary
computation, producing a result \verb'T'; for matrix multiply, \verb'T=A*B', or
if \verb'A' is transposed first, \verb"T=A'*B", for example.  Applying the
accumulator, mask (or its complement) to obtain the final result matrix
\verb'C' can be expressed in the MATLAB \verb'accum_mask' function shown in the
figure.  This function is an exact, fully functional, and nearly-complete
description of the GraphBLAS accumulator/mask operation.  The only aspects it
does not consider are typecasting (see Section~\ref{typecasting}), and the
value of the implicit identity (for those, see another version in the
\verb'Test' folder).

\begin{figure}
\begin{mdframed}[leftmargin=-0.4in,userdefinedwidth=5.8in]
{\footnotesize
\begin{verbatim}
function C = accum_mask (C, Mask, accum, T, C_replace, Mask_complement)
[m n] = size (C.matrix) ;
Z.matrix  = zeros (m, n) ;
Z.pattern = false (m, n) ;

if (isempty (accum))
   Z = T ;     % no accum operator
else
   % Z = accum (C,T), like Z=C+T but with an binary operator, accum
   p =  C.pattern &  T.pattern ; Z.matrix (p) = accum (C.matrix (p), T.matrix (p));
   p =  C.pattern & ~T.pattern ; Z.matrix (p) = C.matrix (p) ;
   p = ~C.pattern &  T.pattern ; Z.matrix (p) = T.matrix (p) ;
   Z.pattern = C.pattern | T.pattern ;
end

% apply the mask to the values and pattern
C.matrix  = mask (C.matrix,  Mask, Z.matrix,  C_replace, Mask_complement) ;
C.pattern = mask (C.pattern, Mask, Z.pattern, C_replace, Mask_complement) ;
end

function C = mask (C, Mask, Z, C_replace, Mask_complement)
% replace C if requested
if (C_replace)
   C (:,:) = 0 ;
end
if (isempty (Mask))             % if empty, Mask is implicit ones(m,n)
   % implicitly, Mask = ones (size (C))
   if (~Mask_complement)
      C = Z ;                   % this is the default
   else
      C = C ;                   % Z need never have been computed
   end
else
   % apply the mask
   if (~Mask_complement)
      C (Mask) = Z (Mask) ;
   else
      C (~Mask) = Z (~Mask) ;
   end
end
end \end{verbatim} }
\end{mdframed}
\caption{Applying the mask and accumulator, ${\bf C \langle M \rangle = C \odot T}$\label{fig_accummask}}
\end{figure}

One aspect of GraphBLAS cannot be as easily expressed in a MATLAB sparse
matrix: namely, what is the implicit value of entries not in the pattern?  To
accommodate this difference in the \verb'accum_mask' MATLAB function, each
sparse matrix \verb'A' is represented with its values \verb'A.matrix' and its
pattern, \verb'A.pattern'.  The latter could be expressed as the sparse matrix
\verb'A.pattern=spones(A)' or \verb'A.pattern=(A~=0)' in MATLAB, if the
implicit value is zero.  With different semirings, entries not in the pattern
can be \verb'1', \verb'+Inf', \verb'-Inf', or whatever is the identity value of
the monoid.  As a result, Figure~\ref{fig_accummask} performs its computations
on two MATLAB matrices: the values in \verb'A.matrix' and the pattern in the
logical matrix \verb'A.pattern'.  Implicit values are untouched.

The final computation in Figure~\ref{fig_accummask}  with a complemented
\verb'Mask' is easily expressed in MATLAB as \verb'C(~Mask)=Z(~Mask)' but this
is costly if \verb'Mask' is very sparse (the typical case).  It can be computed
much faster in MATLAB without complementing the sparse \verb'Mask' via:

        {\footnotesize
        \begin{verbatim}
        R = Z ; R (Mask) = C (Mask) ; C = R ; \end{verbatim} }

A set of MATLAB functions that precisely compute the ${\bf C \langle M \rangle
= C \odot T}$ operation according to the full GraphBLAS specification is
provided in SuiteSparse:GraphBLAS as \verb'GB_spec_accum.m', which computes
${\bf Z=C\odot T}$, and \verb'GB_spec_mask.m', which computes ${\bf C \langle M
\rangle = Z}$.  SuiteSparse:GraphBLAS includes a complete list of
\verb'GB_spec_*' functions that illustrate every GraphBLAS operation;
these are discussed in in Section~\ref{spec}.

The methods in Figure~\ref{fig_accummask} rely heavily on MATLAB's logical
matrix indexing.  For those unfamiliar with logical indexing in MATLAB, here is
short summary.  Logical matrix indexing in MATLAB is written as \verb'A(Mask)'
where \verb'A' is any matrix and \verb'Mask' is a logical matrix the same size
as \verb'A'.  The expression \verb'x=A(Mask)' produces a column vector \verb'x'
consisting of the entries of \verb'A' where \verb'Mask' is true.  On the
left-hand side, logical submatrix assignment \verb'A(Mask)=x' does the
opposite, copying the components of the vector \verb'x' into the places in
\verb'A' where \verb'Mask' is true.  For example, to negate all values greater
than 10 using logical indexing in MATLAB:

    \begin{mdframed}
    {\footnotesize
    \begin{verbatim}
    >> A = magic (4)
    A =
        16     2     3    13
         5    11    10     8
         9     7     6    12
         4    14    15     1
    >> A (A>10) = - A (A>10) 
    A =
       -16     2     3   -13
         5   -11    10     8
         9     7     6   -12
         4   -14   -15     1 \end{verbatim} } \end{mdframed}

In MATLAB, logical indexing with a sparse matrix \verb'A' and sparse logical
matrix \verb'Mask' is very efficient since MATLAB supports sparse logical
matrices.  The Mask operator in GraphBLAS works identically as sparse logical
indexing in MATLAB, and is equally as fast (or faster) in SuiteSparse:GraphBLAS.

%===============================================================================
\subsection{Typecasting} %======================================================
%===============================================================================
\label{typecasting}

If an operator \verb'z=f(x)' or \verb'z=f(x,y)' is used with inputs that do not
match its inputs \verb'x' or \verb'y', or if its result \verb'z' does not match
the type of the matrix it is being stored into, then the values are typecasted.
Typecasting in GraphBLAS extends beyond just operators.  Almost all GraphBLAS
methods and operations are able to typecast their results, as needed.

If one type can be typecasted into the other, they are said to be {\em
compatible}.  All built-in types are compatible with each other.  GraphBLAS
cannot typecast user-defined types thus any user-defined type is only
compatible with itself.  When GraphBLAS requires inputs of a specific type, or
when one type cannot be typecast to another, the GraphBLAS function returns an
error code, \verb'GrB_DOMAIN_MISMATCH' (refer to Section~\ref{error} for a
complete list of error codes).  Typecasting can only be done between built-in
types, and it follows the rules of the ANSI C language (not MATLAB) wherever
the rules of ANSI C are well-defined.   In particular, a large integer outside
the range of a smaller one is wrapped, modulo style.  This differs from MATLAB.

However, unlike MATLAB, the C language specification states that the results of
typecasting a \verb'float' or \verb'double' to an integer type is not always
defined.  In SuiteSparse:GraphBLAS, whenever C leaves the result undefined the
rules used in MATLAB are followed.  In particular \verb'+Inf' converts to the
largest integer value, \verb'-Inf' converts to the smallest (zero for unsigned
integers), and \verb'NaN' converts to zero.  Other than these special cases,
SuiteSparse:GraphBLAS trusts the C compiler for the rest of its typecasting.

Typecasting to \verb'bool' is fully defined in the C language specification,
even for \verb'NaN'.  The result is \verb'false' if the value compares equal to
zero, and true otherwise.  Thus \verb'NaN' converts to \verb'true'.

\begin{spec}
{\bf SPEC:} the GraphBLAS API states that typecasting follows the rules of ANSI
C.  Yet C leaves some typecasting undefined.  SuiteSparse:GraphBLAS provides a
precise definition for all typecasting as an extension to the spec.
\end{spec}

%===============================================================================
\subsection{Notation and list of GraphBLAS operations} %========================
%===============================================================================
\label{list}

As a summary of what GraphBLAS can do, the following table lists all GraphBLAS
operations (where \verb'GxB_*' are in SuiteSparse:GraphBLAS only).  Upper case
letters denote a matrix, lower case letters are vectors, and ${\bf AB}$
denote the multiplication of two matrices over a semiring.

\vspace{0.05in}
{\footnotesize
\begin{tabular}{lll}
\hline
\verb'GrB_mxm'       & matrix-matrix multiply  & ${\bf C \langle M \rangle = C \odot AB}$ \\
\verb'GrB_vxm'       & vector-matrix multiply  & ${\bf w^{\sf T}\langle m^{\sf T}\rangle = w^{\sf T}\odot u^{\sf T}A}$ \\
\verb'GrB_mxv'       & matrix-vector multiply  & ${\bf w \langle m \rangle = w \odot Au}$ \\
\hline
\verb'GrB_eWiseMult' & element-wise,           & ${\bf C \langle M \rangle = C \odot (A \otimes B)}$ \\
                     & set union               & ${\bf w \langle m \rangle = w \odot (u \otimes v)}$ \\
\hline
\verb'GrB_eWiseAdd'  & element-wise,           & ${\bf C \langle M \rangle = C \odot (A \oplus  B)}$ \\
                     & set intersection        & ${\bf w \langle m \rangle = w \odot (u \oplus  v)}$ \\
\hline
\verb'GrB_extract'   & extract submatrix       & ${\bf C \langle M \rangle = C \odot A(I,J)}$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot u(i)}$ \\
\hline
\verb'GxB_subassign' & assign submatrix        & ${\bf C (I,J) \langle M \rangle = C(I,J) \odot A}$ \\
                     & (with submask for ${\bf C(I,J)}$)
                                               & ${\bf w (i)   \langle m \rangle = w(i)   \odot u}$ \\
\hline
\verb'GrB_assign'    & assign submatrix        & ${\bf C \langle M \rangle (I,J) = C(I,J) \odot A}$ \\
                     & (with mask for ${\bf C}$)
                                               & ${\bf w \langle m \rangle (i)   = w(i)   \odot u}$ \\
\hline
\verb'GrB_apply'     & apply unary operator    & ${\bf C \langle M \rangle = C \odot} f{\bf (A)}$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f{\bf (u)}$ \\
\hline
\verb'GxB_select'    & apply select operator   & ${\bf C \langle M \rangle = C \odot} f{\bf (A,k)}$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f{\bf (u,k)}$ \\
\hline
\verb'GrB_reduce'    & reduce to vector        & ${\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]$ \\
                     & reduce to scalar        & $s = s \odot [{\oplus}_{ij}  {\bf A}(I,J)]$ \\
\hline
\verb'GrB_transpose' & transpose               & ${\bf C \langle M \rangle = C \odot A^{\sf T}}$ \\
\hline
\verb'GxB_kron'      & Kronecker product       & ${\bf C \langle M \rangle = C \odot \mbox{kron}(A, B)}$ \\
\hline
\end{tabular}
}
\vspace{0.05in}

Each operation takes an optional \verb'GrB_Descriptor' argument that modifies
the operation.  The input matrices ${\bf A}$ and ${\bf B}$ can be optionally
transposed, the mask ${\bf M}$ can be complemented, and ${\bf C}$ can be
cleared of its entries after it is used in ${\bf Z = C \odot T}$ but before
the ${\bf C \langle M \rangle = Z}$ assignment.
Vectors are never transposed via the descriptor.

Let ${\bf A \oplus B}$ denote the element-wise operator that produces a set
union pattern (like \verb'A+B' in MATLAB).  Any binary operator can be used
this way in GraphBLAS, not just plus.  Let ${\bf A \otimes B}$ denote the
element-wise operator that produces a set intersection pattern (like
\verb'A.*B' in MATLAB); any binary operator can be used this way, not just
times.

Reduction of a matrix ${\bf A}$ to a vector reduces the $i$th row of ${\bf A}$
to a scalar $w_i$.  This is like \verb"w=sum(A')" since by default, MATLAB
reduces down the columns, not across the rows.
% Since the input matrix can be
% optionally transposed, selecting this option obtains the behavior of \verb'sum'
% in MATLAB.

% Further details of each operation are given in Section~\ref{operations}.



\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{GraphBLAS Context and Sequence} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{context}

A user application that directly relies on GraphBLAS must include the
\verb'GraphBLAS.h' header file:

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
    #include "GraphBLAS.h"
\end{verbatim}
} \end{mdframed}

The \verb'GraphBLAS.h' file defines functions, types, and macros prefixed with
\verb'GrB_' and \verb'GxB_' that may be used in user applications.  The prefix
\verb'GrB_' denote items that appear in the official {\em GraphBLAS C API
Specification}.  The prefix \verb'GxB_' refers to SuiteSparse-specific
extensions to the GraphBLAS API.  Both may be used in user applications but be
aware that items with prefixes \verb'GxB_' will not appear in other
implementations of the GraphBLAS standard.

% There are a few functions and objects prefixed with \verb'GB_' that also
% appear in \verb'GraphBLAS.h', but all names with this prefix are internal to
% SuiteSparse:GraphBLAS and must not be referenced by user applications.  They
% are not documented in this User Guide, and no guarantee at all is made about
% them in future versions of this package.  They can change or even be removed
% without notice.  In addition, no contents of any GraphBLAS object (\verb'A',
% say) should be dereferenced with \verb'A->whatever'.  This content is opaque
% to end user applications and can change without notice in future versions of
% this package.  These names and content are technically visible to end-user
% applications, but this is only to enable the creation and use of polymorphic
% functions via the \verb'_Generic' keyword in ANSI C11.

\begin{spec}
{\bf SPEC:} The following macros are extensions to the spec.
\end{spec}

The \verb'GraphBLAS.h' file includes all the definitions required to use
GraphBLAS, including the following macros that can assist a user application in
compiling and using GraphBLAS.

There are two version numbers associated with SuiteSparse:GraphBLAS:
the version of the {\em GraphBLAS C API Specification} it
conforms to, and the version of the implementation itself.  These can
be used in the following manner in a user application:

{\footnotesize
\begin{verbatim}
    #if GxB >= GxB_VERSION (2,0,3)
    ... use features in GraphBLAS specification 2.0.3 ...
    #else
    ... only use features in early specifications
    #endif

    #if GxB_IMPLEMENTATION > GxB_VERSION (1,4,0)
    ... use features from version 1.4.0 of a specific GraphBLAS implementation
    #endif \end{verbatim}}


SuiteSparse:GraphBLAS also defines the following strings with \verb'#define'.
Refer to the \verb'GraphBLAS.h' file for details.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
Macro                & purpose                                      \\
\hline
\verb'GxB_ABOUT'        & this particular implementation, copyright, and URL \\
\verb'GxB_DATE'         & the date of this implementation \\
\verb'GxB_SPEC'         & the GraphBLAS specification for this implementation \\
\verb'GxB_SPEC_DATE'    & the date of the GraphBLAS specification \\
\verb'GxB_LICENSE'      & the license for this particular implementation \\
\hline
\end{tabular}
}
\vspace{0.2in}

Finally, SuiteSparse:GraphBLAS gives itself a unique name of the form
\verb'GxB_SUITESPARSE_GRAPHBLAS' that the user application can use in \verb'#ifdef'
tests. This is helpful in case a particular implementation provides
non-standard features that extend the GraphBLAS specification, such as
additional predefined built-in operators, or if a GraphBLAS implementation does
not yet fully implement all of the GraphBLAS specification.  The
SuiteSparse:GraphBLAS name is provided in its \verb'GraphBLAS.h' file as:

    {\footnotesize
    \begin{verbatim}
    #define GxB_SUITESPARSE_GRAPHBLAS \end{verbatim}}

For example, SuiteSparse:GraphBLAS predefines additional built-in operators not
in the specification.  If the user application wishes to use these in any
GraphBLAS implementation, an \verb'#ifdef' can control when they are used.
Refer to the examples in the \verb'GraphBLAS/Demo' folder.

As another example, the GraphBLAS API states that an
implementation need not define the order in which \verb'GrB_Matrix_build'
assembles duplicate tuples in its \verb'[I,J,X]' input arrays.  As a result, no
particular ordering should be relied upon in general.  However,
SuiteSparse:GraphBLAS does guarantee an ordering, and this guarantee will be
kept in future versions of SuiteSparse:GraphBLAS as well.  Since not all
implementations will ensure a particular ordering, the following can be used to
exploit the ordering returned by SuiteSparse:GraphBLAS.

    {\footnotesize
    \begin{verbatim}
    #ifdef GxB_SUITESPARSE_GRAPHBLAS
    // duplicates in I, J, X assembled in a specific order;
    // results are well-defined even if op is not associative.
    GrB_Matrix_build (C, I, J, X, nvals, op) ;
    #else
    // duplicates in I, J, X assembled in no particular order;
    // results are undefined if op is not associative.
    GrB_Matrix_build (C, I, J, X, nvals, op) ;
    #endif \end{verbatim}}

The remainder of this section describes GraphBLAS functions that create,
modify, and destroy the GraphBLAS context, or provide utility methods for
dealing with errors:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_init'      & start up GraphBLAS                           & \ref{init} \\
\verb'GxB_init'      & start up GraphBLAS with different \verb'malloc'
                                                                & \ref{xinit} \\
\verb'GrB_wait'      & force completion of pending operations       & \ref{wait}\\
\verb'GrB_Info'      & status code returned by GraphBLAS functions  & \ref{info} \\
\verb'GrB_error'     & get more details on the last error           & \ref{error} \\
\verb'GrB_finalize'  & finish GraphBLAS                             & \ref{finalize} \\
\hline
\end{tabular}
}
\vspace{0.2in}

%===============================================================================
\subsection{{\sf GrB\_init:} initialize GraphBLAS} %============================
%===============================================================================
\label{init}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
typedef enum
{
    GrB_NONBLOCKING = 0,    // methods may return with pending computations
    GrB_BLOCKING = 1        // no computations are ever left pending
}
GrB_Mode ;
\end{verbatim}
}\end{mdframed}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_init           // start up GraphBLAS
(
    const GrB_Mode mode     // blocking or non-blocking mode
) ;
\end{verbatim}
}\end{mdframed}

\hypertarget{link:init}{\mbox{ }}%
\verb'GrB_init' must be called before any other GraphBLAS operation.  It
defines the mode that GraphBLAS will use:  blocking or non-blocking.  With
blocking mode, all operations finish before returning to the user application.
With non-blocking mode, operations can be left pending, and are computed only
when needed.  Non-blocking mode can be much faster than blocking mode, by many
orders of magnitude in extreme cases.  Blocking mode should be used only when
debugging a user application.  The mode cannot be changed once it is set by
\verb'GrB_init'.

GraphBLAS objects are opaque to the user application.  This allows GraphBLAS to
postpone operations and then do them later in a more efficient manner by
rearranging them and grouping them together.  In non-blocking mode, the
computations required to construct an opaque GraphBLAS object might not be
finished when the GraphBLAS method or operation returns to the user.  However,
user-provided arrays are not opaque, and GraphBLAS methods and operations that
read them (such as \verb'GrB_Matrix_build') or write to them (such as
\verb'GrB_Matrix_extractTuples') always finish reading them, or creating them,
when the method or operation returns to the user application.

In addition, all methods and operations that extract values from a GraphBLAS
object and return them into non-opaque user arrays always ensure that the
computations for that object are completed when the method returns, namely:
\verb'GrB_*_nvals', \verb'GrB_*_extractElement', \verb'GrB_*_extractTuples',
and \verb'GrB_*_reduce' (to scalar).  These methods only ensure that the
computations for a single object are completed.  Use \verb'GrB_wait'
to ensure that all computations are completed (see Section~\ref{wait}).

SuiteSparse:GraphBLAS is not yet multithreaded, but it is safe to use in a
multithreaded user application.  SuiteSparse:GraphBLAS must be compiled for
each specific user threading model; see Section~\ref{sec:install} for details.

User threads must not operate on the same matrices at the same time, with one
exception.  Multiple threads can use the same matrices or vectors as read-only
inputs to GraphBLAS operations or methods, but only if they have no pending
operations (use \verb'GrB_Matrix_nvals' or \verb'GrB_wait' first).  User
threads cannot simultaneously modify a matrix or vector via any GraphBLAS
operation or method.

With multiple user threads, exactly one user thread must call \verb'GrB_init'
before any user thread may call any \verb'GrB_*' or \verb'GxB_*' function.
When the user application is finished, exactly one user thread 
must call \verb'GrB_finalize', after which no user thread may call
any \verb'GrB_*' or \verb'GxB_*' function.

You can query the mode of a GraphBLAS session with the following
(see Section~\ref{options}), which returns the \verb'mode' passed to
\verb'GrB_init':

{\footnotesize
\begin{verbatim}
    GrB_mode mode ;
    GxB_get (GxB_MODE, &mode) ; \end{verbatim} }

%===============================================================================
\subsection{{\sf GxB\_init:} initialize GraphBLAS with alternate malloc} %======
%===============================================================================
\label{xinit}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_init           // start up GraphBLAS and also define malloc, etc
(
    const GrB_Mode mode,    // blocking or non-blocking mode

    // pointers to memory management functions.
    void * (* user_malloc_function  ) (size_t),
    void * (* user_calloc_function  ) (size_t, size_t),
    void * (* user_realloc_function ) (void *, size_t),
    void   (* user_free_function    ) (void *)
)
\end{verbatim}
}\end{mdframed}

\verb'GxB_init' is identical to \verb'GrB_init', except that it also redefines
the memory management functions that SuiteSparse:GraphBLAS will use.  Giving
the user application control over this is particularly important when using the
\verb'GxB_*import' and \verb'GxB_*export' functions described in
Section~\ref{import_export}, since they require the user application and
GraphBLAS to use the same memory manager.

These
functions can only be set once, when GraphBLAS starts.   Either \verb'GrB_init'
or \verb'GxB_init' must be called before any other GraphBLAS operation, but
not both.

The following usage is identical to \verb'GrB_init(mode)':

    {\footnotesize
    \begin{verbatim}
    GxB_init (mode, malloc, calloc, realloc, free) ; \end{verbatim}}

SuiteSparse:GraphBLAS can be compiled as normal (outside of MATLAB) and then
linked into a MATLAB \verb'mexFunction'.  However, a \verb'mexFunction' should
use the MATLAB memory managers.  To do this, use the following instead of
\verb'GrB_init(mode)' in a MATLAB \verb'mexFunction'.

    {\footnotesize
    \begin{verbatim}
    #include "mex.h"
    #include "GraphBLAS.h"
    ...
    GxB_init (mode, mxMalloc, mxCalloc, mxRealloc, mxFree) ; \end{verbatim}}

As another example, the scalable TBB memory manager can be used:

    {\footnotesize
    \begin{verbatim}
    #include "tbb/scalable_allocator.h"
    #include "GraphBLAS.h"
    ...
    GxB_init (mode, scalable_malloc, scalable_calloc, scalable_realloc,
        scalable_free) ; \end{verbatim}}

\begin{spec}
{\bf SPEC:} \verb'GxB_init' is an extension to the spec.
\end{spec}

\newpage
%===============================================================================
\subsection{{\sf GrB\_wait:} wait for pending operations to finish} %===========
%===============================================================================
\label{wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait ( ) ;     // finish all pending computations
\end{verbatim}
}\end{mdframed}

\verb'GrB_wait' forces all pending operations to complete.
Blocking mode acts as if \verb'GrB_wait' is called whenever a GraphBLAS
method or operation returns to the user application.

Unless specific rules are followed, non-blocking mode can be unpredictable if
user-defined functions have side effects or if they rely on global variables
not under the control of GraphBLAS.  Suppose the user application creates a
user-defined operator that accesses a global variable.  That operator is then
used in a GraphBLAS operation, which is left pending.  If the user application
then changes the global variable before pending operations complete, the
pending operations will be eventually computed with this different value.

Worse yet, a user-defined operator might be freed before it is needed to finish
a pending operation.  This causes undefined behavior.

For best results with GraphBLAS, user-defined functions should not have side
effects, nor should they access global variables outside the control of
GraphBLAS.  This allows the non-blocking mode to be used at its fullest level
of performance.  However, both of these features can safely be used in
user-defined functions if the following specific rules are followed.

\begin{itemize}

\item User-defined functions may be called in any order when used in a
    GraphBLAS operation.  This order may change in non-obvious ways, even in
    the same GraphBLAS operation.  For example, SuiteSparse:\-GraphBLAS relies
    on multiple algorithms for matrix multiplication, and selects between them
    automatically.  The methods will call user-defined multiply and add
    operators in the semiring, in different order.  The user application should
    not rely on any particular order used in a specific implementation of
    GraphBLAS.

\item User-defined functions are permitted to access global variables.
    However, if they do so, the global variables they rely on should not be
    changed if any GraphBLAS methods or operations are still pending, assuming
    GraphBLAS is executing in non-blocking mode (see Section~\ref{init}).  To
    ensure this, the user application must call \verb'GrB_wait' before changing
    any global variables relied upon by user-defined functions.  Alternatively,
    computations can be forced to complete on selected matrices and vectors via
    \verb'GrB_*_nvals', \verb'GrB_*_extractElement',
    \verb'GrB_*_extractTuples', and \verb'GrB_*_reduce' (to scalar) applied to
    selected matrices and vectors.  The \verb'GrB_*_nvals' function is
    particularly well-suited for this purpose since it is otherwise an
    extremely light-weight computation in SuiteSparse:GraphBLAS.

\item If any GraphBLAS methods or operations are still pending, freeing
    user-defined types, operators, monoids, semirings, vectors, matrices, or
    descriptors leads to undefined behavior.  A user application must call
    \verb'GrB_wait' before freeing any user-defined object, if a pending
    operation relies on it, or by selective completion via, say,
    \verb'GrB_*_nvals'.  Alternatively, if the user application is about to
    terminate GraphBLAS (see \verb'GrB_finalize' below), then all GraphBLAS
    objects may be freed in any order, without calling \verb'GrB_wait'.
    Pending computations will simply be abandoned.

\end{itemize}

\verb'GrB_wait' ensures that all computations are completed for all objects.
For specific objects, \verb'GrB_*_nvals', \verb'GrB_*_extractElement',
\verb'GrB_*_extractTuples', and \verb'GrB_*_reduce' (to scalar) ensure that the
pending operations are completed just for the matrix or vector they operate on.
No other GraphBLAS method or operation guarantees the completion of pending
computations, even though they may happen to do so in any particular
implementation.  In the current version, SuiteSparse:GraphBLAS exploits the
non-blocking mode in the \verb'GrB_*_setElement' methods and the
\verb'GrB_assign' and \verb'GxB_subassign' operations.  Future versions of
SuiteSparse:GraphBLAS may extend this to other methods and operations.  Refer
to the example at the end of Section~\ref{overview}.

If multiple user threads have created matrices or vectors, and those have
pending operations, then a single call by one thread to \verb'GrB_wait' causes
all pending operations left by all threads to be completed.  If other user
threads are working on any of those matrices, this would result in a race
condition.  Therefore, \verb'GrB_wait' should be called only when no other user
thread is operating on any other matrix.  Functions that cause a specific
matrix to be finalized (\verb'GrB_*_nvals', \verb'GrB_*_extractElement',
\verb'GrB_*_extractTuples', and \verb'GrB_*_reduce' (to scalar)) can be safely
called by multiple user threads on different matrices.

\newpage
%===============================================================================
\subsection{{\sf GrB\_Info:} status code returned by GraphBLAS} %===============
%===============================================================================
\label{info}

Each GraphBLAS method and operation returns its status to the caller as its
return value, an enumerated type (an \verb'enum') called \verb'GrB_Info'.  The
first two values in the following table denote a successful status, the rest
are error codes.

\vspace{0.2in}
\noindent
{\small
\begin{tabular}{llp{2.8in}}
\hline
\verb'GrB_SUCCESS'              & 0 & the method or operation was successful \\
\verb'GrB_NO_VALUE'             & 1 & \verb'A(i,j)' requested but not there.
                                  Its value is implicit. \\
\hline
\verb'GrB_UNINITIALIZED_OBJECT' & 2 & object has not been initialized \\
\verb'GrB_INVALID_OBJECT'       & 3 & object is corrupted \\
\verb'GrB_NULL_POINTER'         & 4 & input pointer is \verb'NULL' \\
\verb'GrB_INVALID_VALUE'        & 5 & generic error code; some value is bad \\
\verb'GrB_INVALID_INDEX'        & 6 & a row or column index is out of bounds;
                                for indices passed as scalars, not in a list. \\
\verb'GrB_DOMAIN_MISMATCH'      & 7 & object domains are not compatible \\
\verb'GrB_DIMENSION_MISMATCH'   & 8 & matrix dimensions do not match \\
\verb'GrB_OUTPUT_NOT_EMPTY'     & 9 & output matrix already has values in it \\
\hline
\verb'GrB_OUT_OF_MEMORY'        & 10 & out of memory \\
\verb'GrB_INSUFFICIENT_SPACE'   & 11 & output array not large enough \\
\verb'GrB_INDEX_OUT_OF_BOUNDS'  & 12 & a row or column index is out of bounds;
                                  for indices in a list of indices. \\
\hline
\verb'GrB_PANIC'                & 13 & unrecoverable error.
\\
\hline
\end{tabular}
\vspace{0.2in}
}

Not all GraphBLAS methods or operations can return all status codes.  Any
GraphBLAS method or operation can return an out-of-memory condition,
\verb'GrB_OUT_OF_MEMORY', or a panic, \verb'GrB_PANIC'.  These two errors, and
the \verb'GrB_INDEX_OUT_OF_BOUNDS' error, are called {\em execution errors}.
The other errors are called {\em API} errors.  An API error is detecting
immediately, regardless of the blocking mode.  The detection of an execution
error may be deferred until the pending operations complete.

In the discussions of each method and operation in this User Guide, most of the
obvious error code returns are not discussed.  For example, if a required input
is a \verb'NULL' pointer, then \verb'GrB_NULL_POINTER' is returned.  Only error
codes specific to the method or that require elaboration are discussed here.
For a full list of the status codes that each GraphBLAS function can return,
refer to {\em The GraphBLAS C API Specification} \cite{spec}.

\newpage
%===============================================================================
\subsection{{\sf GrB\_error:} get more details on the last error} %=============
%===============================================================================
\label{error}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
const char *GrB_error ( ) ;     // return a string describing the last error
\end{verbatim}
}\end{mdframed}

Each GraphBLAS method and operation returns a \verb'GrB_Info' error code.  The
\verb'GrB_error' function returns additional information on the error in a
thread-safe null-terminated string.  The string returned by \verb'GrB_error' is
allocated in thread local storage and must not be freed or modified.
Each user thread has its own error status.
The simplest way to use it is just to print it out, such as:

    {\footnotesize
    \begin{verbatim}
    info = GrB_some_method_here (...) ;
    if (! (info == GrB_SUCCESS || info == GrB_NO_VALUE))
    {
        printf ("info: %d error: %s\n", info, GrB_error ( )) ;
    } \end{verbatim}}

SuiteSparse:GraphBLAS reports many helpful details via \verb'GrB_error'.  For
example, if a row or column index is out of bounds, the report will state what
those bounds are.  If a matrix dimension is incorrect, the mismatching
dimensions will be provided.  \verb'GrB_BinaryOp_new', \verb'GrB_UnaryOp_new',
and \verb'GxB_SelectOp_new' record the name the function passed to them, and
\verb'GrB_Type_new' records the name of its type parameter, and these are
printed if the user-defined types and operators are used incorrectly.  Refer to
the output of the example programs in the \verb'Demo' folder, which
intentionally generate errors to illustrate the use of \verb'GrB_error'.

Successful GraphBLAS methods do not modify the last error message recorded.  If
a GraphBLAS method fails and then subsequent GraphBLAS method succeeds, the
error message is not modified from the last failure.  Only a subsequent failure
will cause \verb'GrB_error' to return a different error message.

Note that \verb'GrB_NO_VALUE' is an not error, but an informational status.
\verb'GrB_*_extractElment(&x,A,i,j)', which does \verb'x=A(i,j)', returns this
value to indicate that \verb'A(i,j)' is not present in the matrix.

In SuiteSparse:GraphBLAS, some failures cannot be safely recorded for
\verb'GrB_error' to print.  These include \verb'GrB_PANIC' and errors in
\verb'GrB_init' and \verb'GxB_init'.

\newpage
%===============================================================================
\subsection{{\sf GrB\_finalize:} finish GraphBLAS} %============================
%===============================================================================
\label{finalize}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_finalize ( ) ;     // finish GraphBLAS
\end{verbatim}
}\end{mdframed}

\verb'GrB_finalize' must be called as the last GraphBLAS operation, even after
all calls to \verb'GrB_free'.  All GraphBLAS objects created by the user
application should be freed first, before calling \verb'GrB_finalize' since
\verb'GrB_finalize' will not free those objects.  In non-blocking mode,
GraphBLAS may leave some computations as pending.  These computations can be
safely abandoned if the user application frees all GraphBLAS objects it has
created and then calls \verb'GrB_finalize'.  There is no need to call
\verb'GrB_wait' in this case.  When the user application is finished, exactly
one user thread must call \verb'GrB_finalize'.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{GraphBLAS Objects and their Methods} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{objects}

GraphBLAS defines eight different objects to represent matrices and vectors,
their scalar data type (or domain), binary and unary operators on scalar types,
monoids, semirings, and a {\em descriptor} object used to specify optional
parameters that modify the behavior of a GraphBLAS operation.
SuiteSparse:GraphBLAS adds an operator for selecting entries from a matrix or
vector.

The GraphBLAS API makes a distinction between {\em methods} and {\em
operations}.  A method is a function that works on a GraphBLAS object, creating
it, destroying it, or querying its contents.  An operation (not to be confused
with an operator) acts on matrices and/or vectors in a semiring.

\vspace{0.1in}
\noindent
{\small
\begin{tabular}{ll}
\hline
\verb'GrB_Type'     & a scalar data type \\
\verb'GrB_UnaryOp'  & a unary operator $z=f(x)$,
                        where $z$ and $x$ are scalars\\
\verb'GrB_BinaryOp' & a binary operator $z=f(x,y)$,
                        where $z$, $x$, and $y$ are scalars\\
\verb'GxB_SelectOp' & a select operator \\
\verb'GrB_Monoid'   & an associative and commutative binary operator  \\
                    & and its identity value \\
\verb'GrB_Semiring' & a monoid that defines the ``plus'' and a binary operator\\
                    & that defines the ``multiply'' for an algebraic semiring \\
\verb'GrB_Matrix'   & a 2D sparse matrix of any type \\
\verb'GrB_Vector'   & a 1D sparse column vector of any type \\
\verb'GrB_Descriptor'& a collection of parameters that modify an operation \\
\hline
\end{tabular}
}
\vspace{0.1in}

Each of these objects is implemented in C as an opaque handle, which is a
pointer to a data structure held by GraphBLAS.  User applications may not
examine the content of the object directly; instead, they can pass the handle
back to GraphBLAS which will do the work.  Assigning one handle to another
is valid but it does not make a copy of the underlying object.

GraphBLAS provides 11 built-in types and 157 built-in operators;
SuiteSparse:GraphBLAS adds 99 additional built-in operators.  With these,
44 unique monoids and 960 unique semirings can be constructed.

\begin{spec}
{\bf SPEC:} SuiteSparse:GraphBLAS predefines all unique monoids and semirings
that can be constructed from built-in types and operators, as an extension to
the spec.  They appear in \verb'GraphBLAS.h'.  The \verb'GxB_SelectOp' object
is an extension to GraphBLAS.
\end{spec}

\newpage
%===============================================================================
\subsection{The GraphBLAS type: {\sf GrB\_Type}} %==============================
%===============================================================================
\label{type}

A GraphBLAS \verb'GrB_Type' defines the type of scalar values that a matrix or
vector contains, and the type of scalar operands for a unary or binary
operator.  There are eleven built-in types, and a user application can define
any types of its own as well.  The built-in types correspond to built-in types
in C (\verb'#include <stdbool.h>' and \verb'#include <stdint.h>'), and the
classes in MATLAB, as listed in the following table.

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lllll}
\hline
GraphBLAS         & C type           & MATLAB         & description              & range \\
type              &                  & class          &                          & \\
\hline
\verb'GrB_BOOL'   & \verb'bool'      & \verb'logical' & Boolean                  & true (1), false (0) \\
\hline
\verb'GrB_INT8'   & \verb'int8_t'    & \verb'int8'    & 8-bit signed integer     & -128 to 127 \\
\verb'GrB_UINT8'  & \verb'uint8_t'   & \verb'uint8'   & 8-bit unsigned integer   & 0 to 255 \\
\hline
\verb'GrB_INT16'  & \verb'int16_t'   & \verb'int16'   & 16-bit integer           & $-2^{15}$ to $2^{15}-1$ \\
\verb'GrB_UINT16' & \verb'uint16_t'  & \verb'uint16'  & 16-bit unsigned integer  & 0 to $2^{16}-1$ \\
\hline
\verb'GrB_INT32'  & \verb'int32_t'   & \verb'int32'   & 32-bit integer           & $-2^{31}$ to $2^{31}-1$ \\
\verb'GrB_UINT32' & \verb'uint32_t'  & \verb'uint32'  & 32-bit unsigned integer  & 0 to $2^{32}-1$ \\
\hline
\verb'GrB_INT64'  & \verb'int64_t'   & \verb'int64'   & 64-bit integer           & $-2^{63}$ to $2^{63}-1$ \\
\verb'GrB_UINT64' & \verb'uint64_t'  & \verb'uint64'  & 64-bit unsigned integer  & 0 to $2^{64}-1$ \\
\hline
\verb'GrB_FP32'   & \verb'float'     & \verb'single'  & 32-bit IEEE 754          & \verb'-Inf' to \verb'+Inf'\\
\verb'GrB_FP64'   & \verb'double'    & \verb'double'  & 64-bit IEEE 754          & \verb'-Inf' to \verb'+Inf'\\
\hline
\end{tabular}
}
\vspace{0.2in}

The user application can also define new types based on any \verb'typedef' in
the C language whose values are held in a contiguous region of memory.  For
example, a user-defined \verb'GrB_Type' could be created to hold any C
\verb'struct' whose content is self-contained.  A C \verb'struct' containing
pointers might be problematic because GraphBLAS would not know to dereference
the pointers to traverse the entire ``scalar'' entry, but this can be done if
the objects referenced by these pointers are not moved.  A user-defined complex
type with real and imaginary types can be defined, or even a ``scalar'' type
containing a fixed-sized dense matrix (see Section~\ref{type_new}).  The
possibilities are endless.  GraphBLAS can create and operate on sparse matrices
and vectors in any of these types, including any user-defined ones.  For
user-defined types, GraphBLAS simply moves the data around itself (via
\verb'memcpy'), and then passes the values back to user-defined functions when
it needs to do any computations on the type.  The next sections describe the
methods for the \verb'GrB_Type' object:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GrB_Type_new'      & create a user-defined type \\
\verb'GxB_Type_size'     & return the size of a type \\
\verb'GrB_Type_free'     & free a user-defined type \\
\hline
\end{tabular}
}
\vspace{0.2in}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Type\_new:} create a user-defined type}
%-------------------------------------------------------------------------------
\label{type_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Type_new           // create a new GraphBLAS type
(
    GrB_Type *type,             // handle of user type to create
    size_t sizeof_ctype         // size = sizeof (ctype) of the C type
) ;
\end{verbatim}
}\end{mdframed}

\verb'GrB_Type_new' creates a new user-defined type.  The \verb'type' is a
handle, or a pointer to an opaque object.  The handle itself must not be
\verb'NULL' on input, but the content of the handle can be undefined.  On
output, the handle contains a pointer to a newly created type.
The \verb'ctype' is the type in C that will be used to construct the new
GraphBLAS type.  It can be either a built-in C type, or defined by a
\verb'typedef'.
The second parameter should be passed as \verb'sizeof(ctype)'.  The only
requirement on the C type is that \verb'sizeof(ctype)' is valid in C, and
that the type reside in a contiguous block of memory so that it can be moved
with \verb'memcpy'.  For example, to create a user-defined type called
\verb'Complex' for double-precision complex values using the ANSI C11
\verb'double complex' type, the following can be used.  A complete example can
be found in the \verb'usercomplex.c' and \verb'usercomplex.h' files in the
\verb'Demo' folder.

    {\footnotesize
    \begin{verbatim}
    #include <math.h>
    #include <complex.h>
    GrB_Type Complex ;
    GrB_Type_new (&Complex, sizeof (double complex)) ;    \end{verbatim} }

To demonstrate the flexibility of the \verb'GrB_Type', consider a ``scalar''
consisting of 4-by-4 floating-point matrix and a string.  This type might be
useful for the 4-by-4 translation/rotation/scaling matrices that arise in
computer graphics, along with a string containing a description or even a
regular expression that can be parsed and executed in a user-defined operator.
All that is required is a fixed-size type, where \verb'sizeof(ctype)' is
a constant.

    {\footnotesize
    \begin{verbatim}
    typedef struct
    {
        float stuff [4][4] ;
        char whatstuff [64] ;
    }
    wildtype ;
    GrB_Type WildType ;
    GrB_Type_new (&WildType, sizeof (wildtype)) ; \end{verbatim} }

With this type a sparse matrix can be created in which each entry consists of a
4-by-4 dense matrix \verb'stuff' and a 64-character string \verb'whatstuff'.
GraphBLAS treats this 4-by-4 as a ``scalar.'' Any GraphBLAS method or operation
that simply moves data can be used with this type without any further
information from the user application.  For example, entries of this type can
be assigned to and extracted from a matrix or vector, and matrices containing
this type can be transposed.  A working example (\verb'wildtype.c'
in the \verb'Demo' folder) creates matrices and multiplies them with
a user-defined semiring with this type.

Performing arithmetic on matrices and vectors with user-defined types requires
operators to be defined.  For example, the user application can define its own
type for complex numbers, but then transposing the matrix with GraphBLAS will
not compute the complex conjugate transpose.  This corresponds to the array
transpose in MATLAB (\verb"C=A.'") instead of the complex conjugate transpose
(\verb"C=A'").  To compute the complex conjugate transpose, the application
would need to create a user-defined unary operator to conjugate a user-defined
complex scalar, and then apply it to the matrix before or after the transpose,
via \verb'GrB_apply'.  An extensive set of complex operators are provided in
the \verb'usercomplex.c' example in the \verb'Demo' folder, along with an
include file, \verb'usercomplex.h', that is suitable for inclusion in any user
application.  Thus, while GraphBLAS does not include any complex types or
operators, SuiteSparse:GraphBLAS provides them in two simple ``user'' files in
the \verb'Demo' folder.
Refer to Section~\ref{user} for more details on these two example user-defined
types.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Type\_size:} return the size of a type}
%-------------------------------------------------------------------------------

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Type_size          // determine the size of the type
(
    size_t *size,               // the sizeof the type
    GrB_Type type               // type to determine the sizeof
) ;
\end{verbatim}
}\end{mdframed}

This function acts just like \verb'sizeof(type)' in the C language.  For
example \verb'GxB_Type_size (&s, GrB_INT32)' sets \verb's' to 4, the same as
\verb'sizeof(int32_t)'. 

\begin{spec}
{\bf SPEC:} \verb'GxB_Type_size' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Type\_free:} free a user-defined type}
%-------------------------------------------------------------------------------
\label{type_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_free               // free a user-defined type
(
    GrB_Type *type              // handle of user-defined type to free
) ;
\end{verbatim}
}\end{mdframed}

\verb'GrB_Type_free' frees a user-defined type.
Either usage:

    {\small
    \begin{verbatim}
    GrB_Type_free (&type) ;
    GrB_free (&type) ; \end{verbatim}}

\noindent
frees the user-defined \verb'type' and
sets \verb'type' to \verb'NULL'.
It safely does nothing if passed a \verb'NULL'
handle, or if \verb'type == NULL' on input.

It is safe to attempt to free a built-in type.  SuiteSparse:GraphBLAS silently
ignores the request and returns \verb'GrB_SUCCESS'.  A user-defined type should
not be freed until all operations using the type are completed.
SuiteSparse:GraphBLAS attempts to detect this condition but it must query a
freed object in its attempt.  This is hazardous and not recommended.
Operations on such objects whose type has been freed leads to undefined
behavior.

It is safe to first free a type, and then a matrix of that type, but after the
type is freed the matrix can no longer be used.  The only safe thing that can
be done with such a matrix is to free it.

Note the function signature of \verb'GrB_Type_free', above.  It is illustrated
with the generic name, \verb'GrB_free'.  Any GraphBLAS object can be freed with
the single function, \verb'GrB_free'.  Refer to Section~\ref{free} for more
details.

GraphBLAS includes many such generic functions.  When describing a specific
variation, a function is described with its specific name in this User Guide
(such as \verb'GrB_Type_free').  When discussing features applicable to all
specific forms, the generic name is used instead (such as \verb'GrB_free').

\newpage
%===============================================================================
\subsection{GraphBLAS unary operators: {\sf GrB\_UnaryOp}, $z=f(x)$} %==========
%===============================================================================
\label{unaryop}

A unary operator is a scalar function of the form $z=f(x)$.  The domain (type)
of $z$ and $x$ need not be the same.

There are six kinds of built-in unary operators: one, identity,
additive inverse, absolute value,
multiplicative inverse, and logical negation.  In the notation in the table
below, $T$ is any of the 11 built-in types and is a place-holder for
\verb'BOOL', \verb'INT8', \verb'UINT8', ...  \verb'FP32', or \verb'FP64'.   For
example, \verb'GrB_AINV_INT32' is a unary operator that computes \verb'z=-x'
for two values \verb'x' and \verb'z' of type \verb'GrB_INT32'.

The logical negation operator \verb'GrB_LNOT' only works on Boolean types.  The
\verb'GxB_LNOT_'$T$ functions operate on inputs of type $T$, implicitly
typecasting their input to Boolean and returning result of type $T$, with a
value 1 for true and 0 for false.  The operators \verb'GxB_LNOT_BOOL' and
\verb'GrB_LNOT' are identical.
Considering all combinations, there are thus 67 built-in unary operators
((6 kinds of operators) $\times$ (11 types), and \verb'GrB_LNOT').

\vspace{0.2in}
{\footnotesize
\begin{tabular}{llll}
\hline
GraphBLAS name          & types (domains)   & expression    & description \\
                        &                   & $z=f(x)$      & \\
\hline
\verb'GxB_ONE_'$T$      & $T \rightarrow T$ & $z = 1$       & one \\
\verb'GrB_IDENTITY_'$T$ & $T \rightarrow T$ & $z = x$       & identity \\
\verb'GrB_AINV_'$T$     & $T \rightarrow T$ & $z = -x$      & additive inverse \\
\verb'GxB_ABS_'$T$      & $T \rightarrow T$ & $z = |x|$     & absolute value \\
\verb'GrB_MINV_'$T$     & $T \rightarrow T$ & $z = 1/x$     & multiplicative inverse \\
\verb'GxB_LNOT_'$T$     & $T \rightarrow T$ & $z = \lnot (x \ne 0)$ & logical negation \\
\hline
\verb'GrB_LNOT'         & \verb'bool'
                          $\rightarrow$
                          \verb'bool'       & $z = \lnot x$ & logical negation \\
\hline
\end{tabular}
}
\vspace{0.2in}

\begin{spec}
{\bf SPEC:} \verb'GxB_ONE_'$T$, \verb'GxB_ABS_'$T$ and \verb'GxB_LNOT_'$T$ are extensions to the spec.
\end{spec}

Integer division by zero normally terminates an application, but this is
avoided in SuiteSparse:GraphBLAS.  For details, see the binary
\verb'GrB_DIV_'$T$ operators.

\begin{spec}
{\bf SPEC:} The definition of integer division by zero is an extension to the spec.
\end{spec}

The next sections define the following methods for the \verb'GrB_UnaryOp'
object:

\vspace{0.1in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GrB_UnaryOp_new'   & create a user-defined unary operator  \\
\verb'GxB_UnaryOp_ztype' & return the type of the output $z$ for $z=f(x)$\\
\verb'GxB_UnaryOp_xtype' & return the type of the input $x$ for $z=f(x)$\\
\verb'GrB_UnaryOp_free'  & free a user-defined unary operator  \\
\hline
\end{tabular}
}
\vspace{0.1in}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_UnaryOp\_new:} create a user-defined unary operator}
%-------------------------------------------------------------------------------
\label{unaryop_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_UnaryOp_new            // create a new user-defined unary operator
(
    GrB_UnaryOp *unaryop,           // handle for the new unary operator
    void *function,                 // pointer to the unary function
    const GrB_Type ztype,           // type of output z
    const GrB_Type xtype            // type of input x
) ;
\end{verbatim} }\end{mdframed}

\verb'GrB_UnaryOp_new' creates a new unary operator.  The new operator is
returned in the \verb'unaryop' handle, which must not be \verb'NULL' on input.
On output, its contents contains a pointer to the new unary operator.

The two types \verb'xtype' and \verb'ztype' are the GraphBLAS types of the
input $x$ and output $z$ of the user-defined function $z=f(x)$.  These types
may be built-in types or user-defined types, in any combination.  The two types
need not be the same, but they must be previously defined before passing them
to \verb'GrB_UnaryOp_new'.

The \verb'function' argument to \verb'GrB_UnaryOp_new' is a pointer to a
user-defined function with the following signature:

    {\footnotesize
    \begin{verbatim}
    void (*f) (void *z, const void *x) ; \end{verbatim} }

When the function \verb'f' is called, the arguments \verb'z' and \verb'x' are
passed as \verb'(void *)' pointers, but they will be pointers to values of the
correct type, defined by \verb'ztype' and \verb'xtype', respectively, when the
operator was created.
% V2.1 and later:
{\bf NOTE:}
Currently, the pointers will be unique.  That is, the user function is not
called with pointers that point to the same space.  Future versions of
SuiteSparse:GraphBLAS may call the function with the pointers \verb'z' and
\verb'x' equal to one another, in which case \verb'z=f(z)' should be computed. 

% SPEC: the spec is silent on aliasing in user-defined functions

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_UnaryOp\_ztype:} return the type of $z$} 
%-------------------------------------------------------------------------------
\label{unaryop_ztype}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_UnaryOp_ztype          // return the type of z
(
    GrB_Type *ztype,                // return type of output z
    const GrB_UnaryOp unaryop       // unary operator
) ;
\end{verbatim}
}\end{mdframed}

\verb'GxB_UnaryOp_ztype' returns the \verb'ztype' of the unary operator, which
is the type of $z$ in the function $z=f(x)$.

\begin{spec}
{\bf SPEC:} \verb'GxB_UnaryOp_ztype' is an extension to the spec.
\end{spec}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_UnaryOp\_xtype:} return the type of $x$} 
%-------------------------------------------------------------------------------
\label{unaryop_xtype}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_UnaryOp_xtype          // return the type of x
(
    GrB_Type *xtype,                // return type of input x
    const GrB_UnaryOp unaryop       // unary operator
) ;
\end{verbatim}
}\end{mdframed}

\verb'GxB_UnaryOp_xtype' returns the \verb'xtype' of the unary operator, which
is the type of $x$ in the function $z=f(x)$.

\begin{spec}
{\bf SPEC:} \verb'GxB_UnaryOp_xtype' is an extension to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_UnaryOp\_free:} free a user-defined unary operator}
%-------------------------------------------------------------------------------
\label{unaryop_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_free                   // free a user-created unary operator
(
    GrB_UnaryOp *unaryop            // handle of unary operator to free
) ;
\end{verbatim}
}\end{mdframed}

\verb'GrB_UnaryOp_free' frees a user-defined unary operator.
Either usage:

    {\small
    \begin{verbatim}
    GrB_UnaryOp_free (&unaryop) ;
    GrB_free (&unaryop) ; \end{verbatim}}

\noindent
frees the \verb'unaryop' and sets \verb'unaryop' to \verb'NULL'. 
It safely does nothing if passed a \verb'NULL'
handle, or if \verb'unaryop == NULL' on input.
It does nothing at all if passed a built-in unary operator.

\newpage
%===============================================================================
\subsection{GraphBLAS binary operators: {\sf GrB\_BinaryOp}, $z=f(x,y)$} %======
%===============================================================================
\label{binaryop}

A binary operator is a scalar function of the form $z=f(x,y)$.  The types of
$z$, $x$, and $y$ need not be the same.

SuiteSparse:GraphBLAS has 17 kinds of built-in binary operators of the form $T
\times T \rightarrow T$ that work on all 11 of the built-in types, $T$, for a
total of 187 binary operators of this form.  These are listed in the table
below.  For each of these operators, all domains (types) of the three operands
are the same.  The six comparison operators and three logical operators all
return a result one for true and zero for false, in the same domain $T$ as
their inputs.  These six comparison operators are useful as ``multiply''
operators for creating semirings with non-Boolean monoids.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{llll}
\hline
GraphBLAS             & types (domains)            & expression      & description \\
name                  &                            & $z=f(x,y)$      & \\
\hline
% 8 numeric TxT->T
\verb'GrB_FIRST_'$T$  & $T \times T \rightarrow T$ & $z = x$         & first argument \\
\verb'GrB_SECOND_'$T$ & $T \times T \rightarrow T$ & $z = y$         & second argument \\
\verb'GrB_MIN_'$T$    & $T \times T \rightarrow T$ & $z = \min(x,y)$ & minimum \\
\verb'GrB_MAX_'$T$    & $T \times T \rightarrow T$ & $z = \max(x,y)$ & maximum \\
\verb'GrB_PLUS_'$T$   & $T \times T \rightarrow T$ & $z = x+y$       & addition \\
\verb'GrB_MINUS_'$T$  & $T \times T \rightarrow T$ & $z = x-y$       & subtraction \\
\verb'GrB_TIMES_'$T$  & $T \times T \rightarrow T$ & $z = xy$        & multiplication \\
\verb'GrB_DIV_'$T$    & $T \times T \rightarrow T$ & $z = x/y$       & division \\
\hline
% 6 new TxT->T comparison
\verb'GxB_ISEQ_'$T$   & $T \times T \rightarrow T$ & $z = (x == y)$  & equal \\
\verb'GxB_ISNE_'$T$   & $T \times T \rightarrow T$ & $z = (x \ne y)$ & not equal \\
\verb'GxB_ISGT_'$T$   & $T \times T \rightarrow T$ & $z = (x >   y)$ & greater than \\
\verb'GxB_ISLT_'$T$   & $T \times T \rightarrow T$ & $z = (x <   y)$ & less than  \\
\verb'GxB_ISGE_'$T$   & $T \times T \rightarrow T$ & $z = (x \ge y)$ & greater than or equal \\
\verb'GxB_ISLE_'$T$   & $T \times T \rightarrow T$ & $z = (x \le y)$ & less than or equal  \\
\hline
% 3 TxT->T logical
\verb'GxB_LOR_'$T$    & $T \times T \rightarrow T$ & $z = (x \ne 0) \vee    (y \ne 0) $ & logical OR \\
\verb'GxB_LAND_'$T$   & $T \times T \rightarrow T$ & $z = (x \ne 0) \wedge  (y \ne 0) $ & logical AND \\
\verb'GxB_LXOR_'$T$   & $T \times T \rightarrow T$ & $z = (x \ne 0) \veebar (y \ne 0) $ & logical XOR \\
\hline
\end{tabular}
}
\vspace{0.2in}

\begin{spec}
{\bf SPEC:} The \verb'GxB_IS*_'$T$ operators and the Boolean \verb'GxB_L*_'$T$ are extensions to the spec.
\end{spec}

Another set of six kinds of built-in comparison operators have the form $T
\times T \rightarrow $\verb'bool'.  They are defined for all eleven built-in
types, for a total of 66 binary operators.  Note that when $T$ is \verb'bool',
the six operators give the same results as the six \verb'GxB_IS*_BOOL'
operators in the table above.  These six comparison operators are useful as
``multiply'' operators for creating semirings with Boolean monoids.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{llll}
\hline
GraphBLAS             & types (domains)            & expression      & description \\
name                  &                            & $z=f(x,y)$      & \\
\hline
% 6 TxT->bool comparison
\verb'GrB_EQ_'$T$     & $T \times T \rightarrow $\verb'bool' & $z = (x == y)$  & equal \\
\verb'GrB_NE_'$T$     & $T \times T \rightarrow $\verb'bool' & $z = (x \ne y)$ & not equal \\
\verb'GrB_GT_'$T$     & $T \times T \rightarrow $\verb'bool' & $z = (x >   y)$ & greater than \\
\verb'GrB_LT_'$T$     & $T \times T \rightarrow $\verb'bool' & $z = (x <   y)$ & less than  \\
\verb'GrB_GE_'$T$     & $T \times T \rightarrow $\verb'bool' & $z = (x \ge y)$ & greater than or equal \\
\verb'GrB_LE_'$T$     & $T \times T \rightarrow $\verb'bool' & $z = (x \le y)$ & less than or equal  \\
\hline
\end{tabular}
}
\vspace{0.2in}

Finally, GraphBLAS has three built-in binary operators that operate purely in
the Boolean domain.  These three are identical to the \verb'GxB_L*_BOOL'
operators described above, just with a shorter name.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{llll}
\hline
GraphBLAS             & types (domains)            & expression      & description \\
name                  &                            & $z=f(x,y)$      & \\
\hline
% 3 bool x bool -> bool
\verb'GrB_LOR'        & \verb'bool'
                        $\times$ \verb'bool'
                        $\rightarrow$ \verb'bool'  & $z = x \vee    y $ & logical OR \\
\verb'GrB_LAND'       & \verb'bool'
                        $\times$ \verb'bool'
                        $\rightarrow$ \verb'bool'  & $z = x \wedge  y $ & logical AND \\
\verb'GrB_LXOR'       & \verb'bool'
                        $\times$ \verb'bool'
                        $\rightarrow$ \verb'bool'  & $z = x \veebar y $ & logical XOR \\
\hline
\end{tabular}
}
\vspace{0.2in}

This gives a total of 256 built-in binary operators listed in the tables above:
187 of the form $T \times T \rightarrow T$, 66 of the form $T \times T
\rightarrow $ \verb'bool', and three purely Boolean.  There are 240 unique
operators since 16 of the 26 Boolean operators are redundant.

There are two sets of built-in comparison operators in SuiteSparse:Graph\-BLAS,
but they are not redundant.  They are identical except for the type (domain) of
their output, $z$.  The \verb'GrB_EQ_'$T$ and related operators compare their
inputs of type $T$ and produce a Boolean result of true or false.  The
\verb'GxB_ISEQ_'$T$ and related operators do the same comparison and produce a
result with same type $T$ as their input operands, returning one for true or
zero for false.  The \verb'IS*' comparison operators are useful when combining
comparisons with other non-Boolean operators.  For example, a \verb'PLUS-ISEQ'
semiring counts how many terms of the comparison are true.  With this semiring,
matrix multiplication ${\bf C=AB}$ for two weighted undirected graphs ${\bf A}$
and ${\bf B}$ computes $c_{ij}$ as the number of edges node $i$ and $j$ have in
common that have identical edge weights.  Since the output type of the
``multiplier'' operator in a semiring must match the type of its monoid, the
Boolean \verb'EQ' cannot be combined with a non-Boolean \verb'PLUS' monoid to
perform this operation.

Likewise, SuiteSparse:GraphBLAS has two sets of logical OR, AND, and XOR
operators.  Without the \verb'_'$T$ suffix, the three operators \verb'GrB_LOR',
\verb'GrB_LAND', and \verb'GrB_LXOR' operate purely in the Boolean domain,
where all input and output types are \verb'GrB_BOOL'.  The second set
(\verb'GxB_LOR_'$T$ \verb'GxB_LAND_'$T$ and \verb'GxB_LXOR_'$T$) provides
Boolean operators to all 11 domains, implicitly typecasting their inputs from
type $T$ to Boolean and returning a value of type $T$ that is 1 for true or
zero for false.  The set of \verb'GxB_L*_'$T$ operators are useful since they
can be combined with non-Boolean monoids in a semiring.

\begin{spec}
{\bf SPEC:} The definition of integer division by zero is an extension to the spec.
\end{spec}

Floating-point operations follow the IEEE 754 standard.  Thus, computing $x/0$
for a floating-point $x$ results in \verb'+Inf' if $x$ is positive, \verb'-Inf'
if $x$ is negative, and \verb'NaN' if $x$ is zero.  The application is not
terminated.  However, integer division by zero normally terminates an
application.  SuiteSparse:GraphBLAS avoids this by adopting the same rules as
MATLAB, which are analogous to how the IEEE standard handles floating-point
division by zero.  For integers, when $x$ is positive, $x/0$ is the largest
positive integer, for negative $x$ it is the minimum integer, and 0/0 results
in zero.  For example, for an integer $x$ of type \verb'GrB_INT32', 1/0 is
$2^{31}-1$ and (-1)/0 is $-2^{31}$.  Refer to Section~\ref{type} for a list of
integer ranges.

The next sections define the following methods for the \verb'GrB_BinaryOp'
object:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GrB_BinaryOp_new'   & create a user-defined binary operator \\
\verb'GxB_BinaryOp_ztype' & return the type of the output $z$ for $z=f(x,y)$\\
\verb'GxB_BinaryOp_xtype' & return the type of the input $x$ for $z=f(x,y)$\\
\verb'GxB_BinaryOp_ytype' & return the type of the input $y$ for $z=f(x,y)$\\
\verb'GrB_BinaryOp_free'  & free a user-defined binary operator \\
\hline
\end{tabular}
}
\vspace{0.2in}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_BinaryOp\_new:} create a user-defined binary operator}
%-------------------------------------------------------------------------------
\label{binaryop_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_BinaryOp_new
(
    GrB_BinaryOp *binaryop,         // handle for the new binary operator
    void *function,                 // pointer to the binary function
    const GrB_Type ztype,           // type of output z
    const GrB_Type xtype,           // type of input x
    const GrB_Type ytype            // type of input y
) ;
\end{verbatim}
}\end{mdframed}

\verb'GrB_BinaryOp_new' creates a new binary operator.  The new operator is
returned in the \verb'binaryop' handle, which must not be \verb'NULL' on input.
On output, its contents contains a pointer to the new binary operator.

The three types \verb'xtype', \verb'ytype', and \verb'ztype' are the GraphBLAS
types of the inputs $x$ and $y$, and output $z$ of the user-defined function
$z=f(x,y)$.  These types may be built-in types or user-defined types, in any
combination.  The three types need not be the same, but they must be previously
defined before passing them to \verb'GrB_BinaryOp_new'.

The final argument to \verb'GrB_BinaryOp_new' is a pointer to a user-defined
function with the following signature:

    {\footnotesize
    \begin{verbatim}
    void (*f) (void *z, const void *x, const void *y) ; \end{verbatim} }

When the function \verb'f' is called, the arguments \verb'z', \verb'x', and
\verb'y' are passed as \verb'(void *)' pointers, but they will be pointers to
values of the correct type, defined by \verb'ztype', \verb'xtype', and
\verb'ytype', respectively, when the operator was created.
% V2.1 and later:
{\bf NOTE:} SuiteSparse:GraphBLAS may call the function with the pointers
\verb'z' and \verb'x' equal to one another, in which case \verb'z=f(z,y)'
should be computed.  Future versions may use additional pointer aliasing.

% V2.0.3 and earlier:
% The pointers will be unique.  That is, the user function is never called with
% pointers that point to the same space.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_BinaryOp\_ztype:} return the type of $z$} 
%-------------------------------------------------------------------------------
\label{binaryop_ztype}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_ztype         // return the type of z
(
    GrB_Type *ztype,                // return type of output z
    const GrB_BinaryOp binaryop     // binary operator to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_BinaryOp_ztype'
returns the \verb'ztype' of the binary operator, which is the
type of $z$ in the function $z=f(x,y)$.

\begin{spec}
{\bf SPEC:} \verb'GxB_BinaryOp_ztype' is an extension to the spec.
\end{spec}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_BinaryOp\_xtype:} return the type of $x$} 
%-------------------------------------------------------------------------------
\label{binaryop_xtype}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_xtype         // return the type of x
(
    GrB_Type *xtype,                // return type of input x
    const GrB_BinaryOp binaryop     // binary operator to query
) ;
\end{verbatim}
}\end{mdframed}

\verb'GxB_BinaryOp_xtype'
returns the \verb'xtype' of the binary operator, which is the
type of $x$ in the function $z=f(x,y)$.

\begin{spec}
{\bf SPEC:} \verb'GxB_BinaryOp_xtype' is an extension to the spec.
\end{spec}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_BinaryOp\_ytype:} return the type of $y$} 
%-------------------------------------------------------------------------------
\label{binaryop_ytype}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_ytype         // return the type of y
(
    GrB_Type *ytype,                // return type of input y
    const GrB_BinaryOp binaryop     // binary operator to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_BinaryOp_ytype'
returns the \verb'ytype' of the binary operator, which is the
type of $y$ in the function $z=f(x,y)$.

\begin{spec}
{\bf SPEC:} \verb'GxB_BinaryOp_ytype' is an extension to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_BinaryOp\_free:} free a user-defined binary operator}
%-------------------------------------------------------------------------------
\label{binaryop_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_free                   // free a user-created binary operator
(
    GrB_BinaryOp *binaryop          // handle of binary operator to free
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_BinaryOp_free' frees a user-defined binary operator.
Either usage:

    {\small
    \begin{verbatim}
    GrB_BinaryOp_free (&op) ;
    GrB_free (&op) ; \end{verbatim}}

\noindent
frees the \verb'op' and sets \verb'op' to \verb'NULL'. 
It safely does nothing if passed a \verb'NULL'
handle, or if \verb'op == NULL' on input.
It does nothing at all if passed a built-in binary operator.

\newpage
%===============================================================================
\subsection{SuiteSparse:GraphBLAS select operators: {\sf GxB\_SelectOp}} %======
%===============================================================================
\label{selectop}

A select operator is a scalar function of the form
$z=f(i,j,m,n,a_{ij},\mbox{thunk})$ that is applied to the entries $a_{ij}$ of
an $m$-by-$n$ matrix.  The domain (type) of $z$ is always boolean.  The domain
(type) of $a_{ij}$ can be any built-in or user-defined type, or it can be
\verb'GrB_NULL' if the operator is type-generic.

The \verb'GxB_SelectOp' operator is used by \verb'GxB_select' (see Section
\ref{select}) to select entries from a matrix.  Each entry \verb'A(i,j)' is
evaluated with the operator, which returns true if the entry is to be kept in
the output, or false if it is not to appear in the output.  The signature of
the select function \verb'f' is as follows:

{\footnotesize
\begin{verbatim}
bool f                      // returns true if A(i,j) is kept
(
    const GrB_Index i,      // row index of A(i,j)
    const GrB_Index j,      // column index of A(i,j)
    const GrB_Index nrows,  // number of rows of A
    const GrB_Index ncols,  // number of columns of A
    const void *x,          // value of A(i,j), or NULL if f is type-generic
    const void *thunk       // user-defined auxiliary data
) ; \end{verbatim}}

There are five built-in select operators listed in the table below.  For the
first four operators, \verb'thunk' is a pointer to a single scalar of type
\verb'int64_t', which holds the value of \verb'k'.  Each operator can be used
on any type, including user-defined types.  User-defined select operators can
also be created.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS name          & MATLAB            & description \\
                        & analog            & \\
\hline
\verb'GxB_TRIL'         & \verb'C=tril(A,k)'   & true for \verb'A(i,j)' if \verb'(j-i) <= k' \\
\verb'GxB_TRIU'         & \verb'C=triu(A,k)'   & true for \verb'A(i,j)' if \verb'(j-i) >= k' \\
\verb'GxB_DIAG'         & \verb'C=diag(A,k)'   & true for \verb'A(i,j)' if \verb'(j-i) == k' \\
\verb'GxB_OFFDIAG'      & \verb'C=A-diag(A,k)' & true for \verb'A(i,j)' if \verb'(j-i) != k' \\
\verb'GxB_NONZERO'      & \verb'C=A(A~=0)'     & true if \verb'A(i,j)' is nonzero\\
\hline
\end{tabular}
}
\vspace{0.2in}

\begin{spec}
{\bf SPEC:} \verb'GxB_SelectOp' and the table above
are extensions to the spec.
\end{spec}

The built-in \verb'GxB_NONZERO' select operator is unique in that it is a
function of the value of the entry $a_{ij}$, but it is still type-generic.  It
does this by simply returning false if all bits in the value are zero, or true
otherwise.  This gives the proper result for any built-in type, since integer
and floating-point zeros are represented this way.  For user-defined types, the
function returns the same thing.  This action is well-defined but its
suitability for any particular user-defined type must be determined according
to how the user application defines the type, and what a value with all bits
zero means for this type.  Whatever it means, if the bits of a value with a
user-defined type are all zero, the function returns false, and if any bit is
one, the \verb'GxB_NONZERO' function returns true.

The following methods operate on the \verb'GxB_SelectOp' object:

\vspace{0.1in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GxB_SelectOp_new'   & create a user-defined select operator  \\
\verb'GxB_SelectOp_xtype' & return the type of the input $x$ \\
\verb'GxB_SelectOp_free'  & free a user-defined select operator  \\
\hline
\end{tabular}
}
\vspace{0.1in}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_SelectOp\_new:} create a user-defined select operator}
%-------------------------------------------------------------------------------
\label{selectop_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_SelectOp_new       // create a new user-defined select operator
(
    GxB_SelectOp *selectop,     // handle for the new select operator
    void *function,             // pointer to the select function
    const GrB_Type xtype        // type of input x, or NULL if type-generic
) ;
\end{verbatim} }\end{mdframed}

\verb'GxB_SelectOp_new' creates a new select operator.  The new operator is
returned in the \verb'selectop' handle, which must not be \verb'NULL' on input.
On output, its contents contains a pointer to the new select operator.

The \verb'function' argument to \verb'GxB_SelectOp_new' is a pointer to a
user-defined function whose signature is given at the beginning of
Section~\ref{selectop}.  Given the properties of an entry $a_{ij}$ in an
$m$-by-$n$ matrix, the \verb'function' should return \verb'true' if the entry
should be kept in the output of \verb'GxB_select', or \verb'false' if it should
not appear in the output.

The type \verb'xtype' is the GraphBLAS type of the input $x$ of the
user-defined function $z=f(i,j,m,n,x,\mbox{thunk})$.  The type may be built-in
or user-defined, or it may even be \verb'GrB_NULL'.  If the \verb'xtype' is
\verb'GrB_NULL', then the \verb'selectop' is type-generic.  The
\verb'GxB_select' operation does not pass the value of $x=a_{ij}$ to the select
function, but passes \verb'GrB_NULL' for the input \verb'x' to the user-defined
select \verb'function'.

For example, to delete all entries in a matrix equal to the additive identity
of a monoid, create a user-defined \verb'GxB_SelectOp' with a function that
compares its input value \verb'x' with the value of the identity, passed in to
it via the \verb'thunk' parameter of type \verb'void *'.  The user-defined
function should return \verb'false' if \verb'x' is equal the value
\verb'(*thunk)', and \verb'true' otherwise.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_SelectOp\_xtype:} return the type of $x$} 
%-------------------------------------------------------------------------------
\label{selectop_xtype}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_SelectOp_xtype     // return the type of x
(
    GrB_Type *xtype,            // return type of input x
    const GxB_SelectOp selectop // select operator
) ;

\end{verbatim}
}\end{mdframed}

\verb'GxB_SelectOp_xtype' returns the \verb'xtype' of the select operator,
which is the type of $x$ in the function $z=f(i,j,m,n,x,\mbox{thunk})$.  If the
select operator is type-generic, \verb'xtype' is returned as \verb'GrB_NULL'.
This is not an error condition, but simply indicates that the
\verb'GxB_SelectOp' is type-generic.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_SelectOp\_free:} free a user-defined select operator}
%-------------------------------------------------------------------------------
\label{selectop_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_free               // free a user-created select operator
(
    GxB_SelectOp *selectop      // handle of select operator to free
) ;
\end{verbatim}
}\end{mdframed}

\verb'GxB_SelectOp_free' frees a user-defined select operator.  Either usage:

    {\small
    \begin{verbatim}
    GxB_SelectOp_free (&selectop) ;
    GrB_free (&selectop) ; \end{verbatim}}

\noindent
frees the \verb'selectop' and sets \verb'selectop' to \verb'NULL'.  It safely
does nothing if passed a \verb'NULL' handle, or if \verb'selectop == NULL' on
input.  It does nothing at all if passed a built-in select operator.

\newpage
%===============================================================================
\subsection{GraphBLAS monoids: {\sf GrB\_Monoid}} %=============================
%===============================================================================
\label{monoid}

A {\em monoid} is defined on a single domain (that is, a single type), $T$.  It
consists of an associative binary operator $z=f(x,y)$ whose three operands $x$,
$y$, and $z$ are all in this same domain $T$ (that is $T \times T \rightarrow
T$).  The associative operator must also have an identity element, or ``zero''
in this domain, such that $f(x,0)=f(0,x)=0$.  Recall that an associative
operator $f(x,y)$ is one for which the condition $f(a, f(b,c)) = f(f (a,b),c)$
always holds.  That is, operator can be applied in any order and the results
remain the same.

Four kinds of built-in operators (\verb'MIN', \verb'MAX', \verb'PLUS',
\verb'TIMES') can be used to form monoids for each of the ten non-Boolean
built-in types, and 12 can be used for Boolean monoids, all of which are listed
in the table below.  This is a total of 52 valid monoids that can be
constructed from built-in types and operators, although 8 of the 12 Boolean
monoids are redundant (the four remaining being \verb'OR', \verb'AND',
\verb'XOR', and \verb'EQ').  There are thus a total of 44 unique monoids that
can be constructed using built-in binary operators.  Since the built-in monoids
are also commutative, all of them can be used to create a semiring.  Recall
that a commutative operator $f(x,y)$ is one for which the condition
$f(a,b)=f(b,a)$ always holds.  That is, the two operands can be swapped and the
results remain the same.  One of the components of a semiring is a commutative
monoid.

% All 44 monoids are defined in \verb'GraphBLAS.h' file.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lllll}
\hline
GraphBLAS             & types (domains)            & expression      & identity  & terminal \\
operator              &                            & $z=f(x,y)$      &           & \\
\hline
% 8 numeric TxT->T
\verb'GrB_MIN_'$T$    & $T \times T \rightarrow T$ & $z = \min(x,y)$ & $+\infty$ & $-\infty$ \\
\verb'GrB_MAX_'$T$    & $T \times T \rightarrow T$ & $z = \max(x,y)$ & $-\infty$ & $+\infty$ \\
\verb'GrB_PLUS_'$T$   & $T \times T \rightarrow T$ & $z = x+y$       & 0         & none \\
\verb'GrB_TIMES_'$T$  & $T \times T \rightarrow T$ & $z = xy$        & 1         & 0 (not fp) \\
\hline
% 4 bool x bool -> bool
\verb'GrB_LOR'        & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \vee    y $ & false & true  \\
\verb'GrB_LAND'       & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \wedge  y $ & true  & false \\
\verb'GrB_LXOR'       & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \veebar y $ & false & none \\
\verb'GrB_EQ_BOOL'    & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z =(x ==      y)$ & true  & none \\
\hline
\end{tabular}
}
\vspace{0.2in}

The above table lists the GraphBLAS operator, its type, expression, identity
value, and {\em terminal} value (if any).  For these built-in operators, the
terminal values are the {\em annihilators} of the function, which is the value
$z$ so that $z=f(z,y)$ regardless of the value of $y$.  For example
$\min(-\infty,y) = -\infty$ for any $y$.  For integer domains, $+\infty$ and
$-\infty$ are the largest and smallest integer in their range.  With unsigned
integers, the smallest value is zero, and thus \verb'GrB_MIN_UINT8' has an
identity of 255 and a terminal value of 0.

When computing with a monoid, the computation can terminate early if the
terminal value arises.  No further work is needed since the result will not
change.  This value is called the terminal value instead of the annihilator,
since a user-defined operator can be created with a terminal value that is not
an annihilator.  See Section~\ref{monoid_terminal_new} for an example.

The \verb'GrB_TIMES_FP*' operators do not have a terminal value of zero, since
they comply with the IEEE 754 standard, and \verb'0*NaN' is not zero, but
\verb'NaN'.  Technically, their terminal value is \verb'NaN', but this value is
rare in practice and thus the terminal condition is not worth checking.

SuiteSparse:GraphBLAS predefines each of the 44 unique monoids that can be
constructed with built-in types and operators, with the naming convention
\verb'GxB_op_type_MONOID'.  For the first 40, \verb'op' is \verb'MIN',
\verb'MAX', \verb'PLUS', or \verb'TIMES', and \verb'type' is all but
\verb'BOOL'.  The four Booolean monoids are \verb'GxB_LOR_BOOL_MONOID',
\verb'GxB_LAND_BOOL_MONOID', \verb'GxB_LXOR_BOOL_MONOID', and
\verb'GxB_EQ_BOOL_MONOID'.

The next sections define the following methods for the \verb'GrB_Monoid'
object:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GrB_Monoid_new'       & create a monoid \\
\verb'GxB_Monoid_terminal_new'  & create a monoid that has a terminal value\\
\verb'GxB_Monoid_operator'  & return the monoid operator \\
\verb'GxB_Monoid_identity'  & return the monoid identity value \\
\verb'GxB_Monoid_terminal'  & return the monoid terminal value (if any) \\
\verb'GrB_Monoid_free'      & free a monoid \\
\hline
\end{tabular}
}
\vspace{0.2in}

\begin{spec}
{\bf SPEC:} The predefined monoids are an extension to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Monoid\_new:} create a monoid}
%-------------------------------------------------------------------------------
\label{monoid_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Monoid_new             // create a monoid
(
    GrB_Monoid *monoid,             // handle of monoid to create
    const GrB_BinaryOp op,          // binary operator of the monoid
    const <type> identity           // identity value of the monoid
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Monoid_new' creates a monoid.  The operator, \verb'op', must be an
associative binary operator, either built-in or user-defined.

In the definition above, \verb'<type>' is a place-holder for the specific type
of the monoid.  For built-in types, it is the C type corresponding to the
built-in type (see Section~\ref{type}), such as \verb'bool', \verb'int32_t',
\verb'float', or \verb'double'.  In this case, \verb'identity' is a
\verb'const' scalar value of the particular type, not a pointer.  For
user-defined types, \verb'<type>' is \verb'void *', and thus \verb'identity' is
a not a scalar itself but a \verb'void *' pointer to a memory location
containing the identity value of the user-defined operator, \verb'op'.

If \verb'op' is a built-in operator with a known identity value, then the
\verb'identity' parameter is ignored, and its known identity value is used
instead.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Monoid\_terminal\_new:} create a monoid with terminal}
%-------------------------------------------------------------------------------
\label{monoid_terminal_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Monoid_terminal_new    // create a monoid that has a terminal value
(
    GrB_Monoid *monoid,             // handle of monoid to create
    const GrB_BinaryOp op,          // binary operator of the monoid
    const <type> identity,          // identity value of the monoid
    const <type> terminal           // terminal value of the monoid
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Monoid_terminal_new' is identical to \verb'GrB_Monoid_new', except
that it allows for the specification of a {\em terminal value}.  The
\verb'<type>' of the terminal value is the same as the \verb'identity'
parameter; see Section~\ref{monoid_new} for details.

The terminal value of a monoid is the value $z$ for which $z=f(z,y)$ for any
$y$, where $z=f(x,y)$ is the binary operator of the monoid.  This is also
called the {\em annihilator}, but the term {\em terminal value} is used here.
This is because all annihilators are terminal values, but a terminal value need
not be an annihilator, as described in the \verb'MIN' example below.

If the terminal value is encountered during computation, the rest of the
computations can be skipped.  This can greatly improve the performance of
\verb'GrB_reduce', and matrix multiply in specific cases (when a dot product
method is used).  For example, using \verb'GrB_reduce' to compute the sum of
all entries in a \verb'GrB_FP32' matrix with $e$ entries takes $O(e)$ time,
since a monoid based on \verb'GrB_PLUS_FP32' has no terminal value.  By
contrast, a reduction using \verb'GrB_LOR' on a \verb'GrB_BOOL' matrix can take
as little as $O(1)$ time, if a \verb'true' value is found in the matrix very
early.

Monoids based on the built-in \verb'GrB_MIN_*' and \verb'GrB_MAX_*' operators
(for any type), the boolean \verb'GrB_LOR', and the boolean \verb'GrB_LAND'
operators all have terminal values.  For example, the identity value of
\verb'GrB_LOR' is \verb'false', and its terminal value is \verb'true'.  When
computing a reduction of a set of boolean values to a single value, once a
\verb'true' is seen, the computation can exit early since the result is now
known.

If \verb'op' is a built-in operator with known identity and terminal values,
then the \verb'identity' and \verb'terminal' parameters are ignored, and its
known identity and terminal values are used instead.

There may be cases in which the user application needs to use a non-standard
terminal value for a built-in operator.  For example, suppose the matrix has
type \verb'GrB_FP32', but all values in the matrix are known to be
non-negative.  The annihilator value of \verb'MIN' is \verb'-INFINITY', but
this will never be seen.  However, the computation could could terminate when
finding the value zero.  This is an example of using a terminal value that is
not actually an annihilator, but it functions like one since the monoid will
operate stricly on non-negative values.  In this case, a monoid created with
\verb'GrB_MIN_FP32' will not terminate early.  To create a monoid that can
terminate early, create a user-defined operator that computes the same thing as
\verb'GrB_MIN_FP32', and then create a monoid based on this user-defined
operator with a terminal value of zero and an identity of \verb'+INFINITY'.

\begin{spec}
{\bf SPEC:} \verb'GxB_Monoid_terminal_new' is an extension to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Monoid\_operator:} return the monoid operator}
%-------------------------------------------------------------------------------
\label{monoid_operator}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Monoid_operator        // return the monoid operator
(
    GrB_BinaryOp *op,               // returns the binary op of the monoid
    const GrB_Monoid monoid         // monoid to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Monoid_operator' returns the binary operator of the monoid.

\begin{spec}
{\bf SPEC:} \verb'GxB_Monoid_operator' is an extension to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Monoid\_identity:} return the monoid identity}
%-------------------------------------------------------------------------------

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Monoid_identity        // return the monoid identity
(
    void *identity,                 // returns the identity of the monoid
    const GrB_Monoid monoid         // monoid to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Monoid_identity' returns the identity value of the monoid.  The
\verb'void *' pointer, \verb'identity', must be non-\verb'NULL' and must point
to a memory space of size at least equal to the size of the type of the
\verb'monoid'.  The type size can be obtained via \verb'GxB_Monoid_operator' to
return the monoid additive operator, then \verb'GxB_BinaryOp_ztype' to obtain
the \verb'ztype', followed by \verb'GxB_Type_size' to get its size.

\begin{spec}
{\bf SPEC:} \verb'GxB_Monoid_identity' is an extension to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Monoid\_terminal:} return the monoid terminal value}
%-------------------------------------------------------------------------------

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Monoid_terminal        // return the monoid terminal
(
    bool *has_terminal,             // true if the monoid has a terminal value
    void *terminal,                 // returns the terminal of the monoid
    const GrB_Monoid monoid         // monoid to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Monoid_terminal' returns the terminal value of the monoid (if any).
The \verb'void *' pointer, \verb'terminal', must be non-\verb'NULL' and must
point to a memory space of size at least equal to the size of the type of the
\verb'monoid'.  The type size can be obtained via \verb'GxB_Monoid_operator' to
return the monoid additive operator, then \verb'GxB_BinaryOp_ztype' to obtain
the \verb'ztype', followed by \verb'GxB_Type_size' to get its size.

If the monoid has a terminal value, then \verb'has_terminal' is \verb'true',
and its value is returned in the \verb'terminal' parameter.  If it has no
terminal value, then \verb'has_terminal' is \verb'false', and the
\verb'terminal' parameter is not modified.

\begin{spec}
{\bf SPEC:} \verb'GxB_Monoid_terminal' is an extension to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Monoid\_free:} free a monoid}
%-------------------------------------------------------------------------------
\label{monoid_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_free                   // free a user-created monoid
(
    GrB_Monoid *monoid              // handle of monoid to free
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Monoid_frees' frees a monoid.  Either usage:

    {\small
    \begin{verbatim}
    GrB_Monoid_free (&monoid) ;
    GrB_free (&monoid) ; \end{verbatim}}

\noindent
frees the \verb'monoid' and sets \verb'monoid' to \verb'NULL'.  It safely does
nothing if passed a \verb'NULL' handle, or if \verb'monoid == NULL' on input.
It does nothing at all if passed a built-in monoid.

\newpage
%===============================================================================
\subsection{GraphBLAS semirings: {\sf GrB\_Semiring}} %=========================
%===============================================================================
\label{semiring}

A {\em semiring} defines all the operators required to define the
multiplication of two sparse matrices in GraphBLAS, ${\bf C=AB}$.  The ``add''
operator is a commutative and associative monoid, and the binary ``multiply''
operator defines a function $z=fmult(x,y)$ where the type of $z$ matches the
exactly with the monoid type.  SuiteSparse:GraphBLAS includes 960
predefined built-in semirings, which are all those that can be constructed
from built-in types and operators.  The next sections define the following
methods for the \verb'GrB_Semiring' object:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GrB_Semiring_new'       & create a semiring \\
\verb'GxB_Semiring_add'       & return the additive monoid of a semiring \\
\verb'GxB_Semiring_multiply'  & return the binary operator of a semiring \\
\verb'GrB_Semiring_free'      & free a semiring \\
\hline
\end{tabular}
}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Semiring\_new:} create a semiring}
%-------------------------------------------------------------------------------
\label{semiring_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Semiring_new           // create a semiring
(
    GrB_Semiring *semiring,         // handle of semiring to create
    const GrB_Monoid add,           // add monoid of the semiring
    const GrB_BinaryOp multiply     // multiply operator of the semiring
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Semiring_new' creates a new semiring, with \verb'add' being the
additive monoid and \verb'multiply' being the binary ``multiply'' operator.  In
addition to the standard error cases, the function returns
\verb'GrB_DOMAIN_MISMATCH' if the output (\verb'ztype') domain of
\verb'multiply' does not match the domain of the \verb'add' monoid.  Using
built-in types and operators, 960 unique semirings can be built.  This count
excludes redundant Boolean operators (for example \verb'GrB_TIMES_BOOL' and
\verb'GrB_LAND' are different operators but they are redundant since they
always return the same result).

\vspace{-0.05in}
\begin{itemize}
\item 680 semirings with a multiplier $T \times T \rightarrow T$ where $T$ is
    non-Boolean, from the complete cross product of:

    \vspace{-0.05in}
    \begin{itemize}
    \item 4 add monoids (\verb'MIN', \verb'MAX', \verb'PLUS', \verb'TIMES')
    \item 17 multiply operators
    (\verb'FIRST', \verb'SECOND', \verb'MIN', \verb'MAX',
    \verb'PLUS', \verb'MINUS', \verb'TIMES', \verb'DIV',
    \verb'ISEQ', \verb'ISNE', \verb'ISGT',
    \verb'ISLT', \verb'ISGE', \verb'ISLE',
    \verb'LOR', \verb'LAND', \verb'LXOR').
    \item 10 non-Boolean types, $T$
    \end{itemize}

\item 240 semirings with a comparison operator $T \times T \rightarrow$
    \verb'bool', where $T$ is non-Boolean, from the complete cross product of:

    \vspace{-0.05in}
    \begin{itemize}
    \item 4 Boolean add monoids
    (\verb'LAND', \verb'LOR', \verb'LXOR', \verb'EQ')
    \item 6 multiply operators
    (\verb'EQ', \verb'NE', \verb'GT', \verb'LT', \verb'GE', \verb'LE')
    \item 10 non-Boolean types, $T$
    \end{itemize}

\item 40 semirings with purely Boolean types, \verb'bool' $\times$ \verb'bool'
    $\rightarrow$ \verb'bool', from the complete cross product of:

    \vspace{-0.05in}
    \begin{itemize}
    \item 4 Boolean add monoids
    (\verb'LAND', \verb'LOR', \verb'LXOR', \verb'EQ')
    \item 10 multiply operators
    (\verb'FIRST', \verb'SECOND', \verb'LOR', \verb'LAND', \verb'LXOR',
    \verb'EQ', \verb'GT', \verb'LT', \verb'GE', \verb'LE')
    \end{itemize}

\end{itemize}

\vspace{-0.05in}
SuiteSparse:GraphBLAS pre-defines all 960 unique semirings that can be
constructed from built-in types and operators, as an extension to the spec.
The naming convention is \verb'GxB_add_mult_type', where \verb'add' is the
operator of the addititive monoid, \verb'mult' is the multiply operator, and
\verb'type' is the type of inputs to the multiply operator.  The name of the
domain for the addititve monoid does not appear, since it always matches the
type of the output of the \verb'mult' operator.  For example
\verb'GxB_LAND_EQ_FP32' uses the \verb'GxB_LAND_BOOL_MONOID' as its additive
monoid, and the \verb'GrB_EQ_FP32' as the binary multiplicative operator.

\begin{spec}
{\bf SPEC:} Predefined semirings are an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Semiring\_add:} return the additive monoid of a semiring}
%-------------------------------------------------------------------------------
\label{semiring_add}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Semiring_add           // return the add monoid of a semiring
(
    GrB_Monoid *add,                // returns add monoid of the semiring
    const GrB_Semiring semiring     // semiring to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Semiring_add' returns the additive monoid of a semiring.

\begin{spec}
{\bf SPEC:} \verb'GxB_Semiring_add' is an extension to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Semiring\_multiply:} return multiply operator of a semiring}
%-------------------------------------------------------------------------------
\label{semiring_multiply}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Semiring_multiply      // return multiply operator of a semiring
(
    GrB_BinaryOp *multiply,         // returns multiply operator of the semiring
    const GrB_Semiring semiring     // semiring to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Semiring_multiply' returns the binary multiplicative operator of a
semiring.

\begin{spec}
{\bf SPEC:} \verb'GxB_Semiring_multiply' is an extension to the spec.
\end{spec}


%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Semiring\_free:} free a semiring}
%-------------------------------------------------------------------------------
\label{semiring_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_free                   // free a user-created semiring
(
    GrB_Semiring *semiring          // handle of semiring to free
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Semiring_free' frees a semiring.  Either usage:

    {\small
    \begin{verbatim}
    GrB_Semiring_free (&semiring) ;
    GrB_free (&semiring) ; \end{verbatim}}

\noindent
frees the \verb'semiring' and sets \verb'semiring' to \verb'NULL'.  It safely
does nothing if passed a \verb'NULL' handle, or if \verb'semiring == NULL' on
input.  It does nothing at all if passed a built-in semiring.

\newpage
%===============================================================================
\subsection{GraphBLAS vectors: {\sf GrB\_Vector}} %=============================
%===============================================================================
\label{vector}

Many of the methods for GraphBLAS vectors require a row index or a size.  Many
methods for matrices require both a row and column index, or a row and column
dimension.  These are all integers of a specific type, \verb'GrB_Index',
which is defined in \verb'GraphBLAS.h' as

    {\footnotesize
    \begin{verbatim}
    typedef uint64_t GrB_Index ; \end{verbatim}}

Row and column indices of an \verb'nrows'-by-\verb'ncols' matrix range from
zero to the \verb'nrows-1' for the rows, and zero to \verb'ncols-1' for the
columns.  Indices are zero-based, like C, and not one-based, like MATLAB.  In
SuiteSparse:GraphBLAS, the largest size permitted for any integer of
\verb'GrB_Index' is $2^{60}$.  The largest \verb'GrB_Matrix' that
SuiteSparse:GraphBLAS can construct is thus $2^{60}$-by-$2^{60}$.  An
$n$-by-$n$ matrix $A$ that size can easily be constructed in practice with
$O(|{\bf A}|)$ memory requirements, where $|{\bf A}|$ denotes the number of
entries that explicitly appear in the pattern of ${\bf A}$.  The time and
memory required to construct a matrix that large does not depend on $n$, since
SuiteSparse:GraphBLAS can represent ${\bf A}$ in hypersparse form (see
Section~\ref{hypersparse}).  The largest \verb'GrB_Vector' that can be
constructed is $2^{60}$-by-1.

This section describes a set of methods that create, modify, query,
and destroy a GraphBLAS sparse vector, \verb'GrB_Vector':

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GrB_Vector_new'            & create a vector \\
\verb'GrB_Vector_dup'            & copy a vector \\
\verb'GrB_Vector_clear'          & clear a vector of all entries \\
\verb'GrB_Vector_size'           & return the size of a vector \\
\verb'GrB_Vector_nvals'          & return the number of entries in a vector \\
\verb'GxB_Vector_type'           & return the type of a vector \\
\verb'GrB_Vector_build'          & build a vector from a set of tuples \\
\verb'GrB_Vector_setElement'     & add a single entry to a vector \\
\verb'GrB_Vector_extractElement' & get a single entry from a vector \\
\verb'GrB_Vector_extractTuples'  & get all entries from a vector \\
\verb'GxB_Vector_resize'         & resize a vector \\
\verb'GrB_Vector_free'           & free a vector \\
\hline
\verb'GxB_Vector_import'         & import a vector
                                    (see Section~\ref{import_export})\\
\verb'GxB_Vector_export'         & export a vector
                                    (see Section~\ref{import_export})\\
\hline
\end{tabular}
}


\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_new:}           create a vector}
%-------------------------------------------------------------------------------
\label{vector_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_new     // create a new vector with no entries
(
    GrB_Vector *v,          // handle of vector to create
    const GrB_Type type,    // type of vector to create
    const GrB_Index n       // vector dimension is n-by-1
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Vector_new' creates a new \verb'n'-by-\verb'1' sparse vector with no
entries in it, of the given type.  This is analogous to MATLAB statement
\verb'v = sparse (n,1)', except that GraphBLAS can create sparse vectors any
type.  The pattern of the new vector is empty.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_dup:}           copy a vector}
%-------------------------------------------------------------------------------
\label{vector_dup}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_dup     // make an exact copy of a vector
(
    GrB_Vector *w,          // handle of output vector to create
    const GrB_Vector u      // input vector to copy
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Vector_dup' makes a deep copy of a sparse vector, like \verb'w=u' in
MATLAB.  In GraphBLAS, it is possible, and valid, to write the following:

    {\footnotesize
    \begin{verbatim}
    GrB_Vector u, w ;
    GrB_Vector_new (&u, GrB_FP64, n) ;
    w = u ;                         // w is a shallow copy of u  \end{verbatim}}

Then \verb'w' and \verb'u' can be used interchangeably.  However, only a pointer
reference is made, and modifying one of them modifies both, and freeing one of
them leaves the other as a dangling handle that should not be used.
If two different vectors are needed, then this should be used instead:

    {\footnotesize
    \begin{verbatim}
    GrB_Vector u, w ;
    GrB_Vector_new (&u, GrB_FP64, n) ;
    GrB_Vector_dup (&w, u) ;        // like w = u, but making a deep copy \end{verbatim}}

Then \verb'w' and \verb'u' are two different vectors that currently have the
same set of values, but they do not depend on each other.  Modifying one has
no effect on the other.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_clear:}         clear a vector of all entries}
%-------------------------------------------------------------------------------
\label{vector_clear}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_clear   // clear a vector of all entries;
(                           // type and dimension remain unchanged.
    GrB_Vector v            // vector to clear
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Vector_clear' clears all entries from a vector.  All values
\verb'v(i)' are now equal to the implicit value, depending on what semiring
ring is used to perform computations on the vector.  The pattern of \verb'v' is
empty, just as if it were created fresh with \verb'GrB_Vector_new'.  Analogous
with \verb'v (:) = 0' in MATLAB.  The type and dimension of \verb'v' do not
change.  In SuiteSparse:GraphBLAS, any pending updates to the vector are
discarded.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_size:}          return the size of a vector}
%-------------------------------------------------------------------------------
\label{vector_size}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_size    // get the dimension of a vector
(
    GrB_Index *n,           // vector dimension is n-by-1
    const GrB_Vector v      // vector to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Vector_size' returns the size of a vector (the number of rows).
Analogous to \verb'n = length(v)' or \verb'n = size(v,1)' in MATLAB.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_nvals:}         return the number of entries in a vector}
%-------------------------------------------------------------------------------
\label{vector_nvals}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_nvals   // get the number of entries in a vector
(
    GrB_Index *nvals,       // vector has nvals entries
    const GrB_Vector v      // vector to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Vector_nvals' returns the number of entries in a vector.  Roughly
analogous to \verb'nvals = nnz(v)' in MATLAB, except that the implicit value in
GraphBLAS need not be zero and \verb'nnz' (short for ``number of nonzeros'') in
MATLAB is better described as ``number of entries'' in GraphBLAS.

\paragraph{Forced completion:}
All computations for the vector \verb'v' are guaranteed to be finished when
\verb'GrB_Vector_nvals' method returns.
%
That is, it acts like an object-specific \verb'GrB_wait' for just this
particular vector \verb'v', which is a side-effect useful in its own right.
For example, suppose the computations required for \verb'v' rely upon a
user-defined operator that accesses a user-controlled global variable outside
the scope or control of GraphBLAS.  If the user-application needs to modify or
free the variable, \verb'GrB_Vector_nvals' can be used to force all pending
operations for this vector \verb'v' to complete.  The user application can then
safely modify the global variable.  A call to \verb'GrB_Vector_nvals(&nvals,v)'
only ensures that the computations require to compute \verb'v' are finished;
other pending computations for other objects may remain.  To ensure that all
pending computations are complete for all GraphBLAS objects, use
\verb'GrB_wait' instead.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_type:}          return the type of a vector}
%-------------------------------------------------------------------------------
\label{vector_type}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_type    // get the type of a vector
(
    GrB_Type *type,         // returns the type of the vector
    const GrB_Vector v      // vector to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Vector_type' returns the type of a vector.  Analogous to
\verb'type = class (v)' in MATLAB.

\begin{spec}
{\bf SPEC:} \verb'GxB_Vector_type' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_build:}         build a vector from a set of tuples}
%-------------------------------------------------------------------------------
\label{vector_build}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_build           // build a vector from (I,X) tuples
(
    GrB_Vector w,                   // vector to build
    const GrB_Index *I,             // array of row indices of tuples
    const <type> *X,                // array of values of tuples
    const GrB_Index nvals,          // number of tuples
    const GrB_BinaryOp dup          // binary function to assemble duplicates
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Vector_build' constructs a sparse vector \verb'w' from a set of
tuples, \verb'I' and \verb'X', each of length \verb'nvals'.  The vector
\verb'w' must have already been initialized with \verb'GrB_Vector_new', and it
must have no entries in it before calling \verb'GrB_Vector_build'.

This function is just like \verb'GrB_Matrix_build' (see
Section~\ref{matrix_build}), except that it builds a sparse vector instead of a
sparse matrix.  For a description of what \verb'GrB_Vector_build' does, refer
to \verb'GrB_Matrix_build'.  For a vector, the list of column indices \verb'J'
in \verb'GrB_Matrix_build' is implicitly a vector of length \verb'nvals' all
equal to zero.  Otherwise the methods are identical.

\begin{spec}
{\bf SPEC:} As an extension to the spec, results are defined even if \verb'dup' is non-associative.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_setElement:}    add a single entry to a vector}
%-------------------------------------------------------------------------------
\label{vector_setElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_setElement          // w(i) = x
(
    GrB_Vector w,                       // vector to modify
    const <type> x,                     // scalar to assign to w(i)
    const GrB_Index i                   // row index
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_setElement' sets a single entry in a vector, \verb'w(i) = x'.
The operation is exactly like setting a single entry in an \verb'n'-by-1
matrix, \verb'A(i,0) = x', where the column index for a vector is implicitly
\verb'j=0'.  For further details of this function, see
\verb'GrB_Matrix_setElement' in Section~\ref{matrix_setElement}. 

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_extractElement:} get a single entry from a vector}
%-------------------------------------------------------------------------------
\label{vector_extractElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_extractElement  // x = v(i)
(
    <type> *x,                      // scalar extracted
    const GrB_Vector v,             // vector to extract an entry from
    const GrB_Index i               // row index
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_extractElement' extracts a single entry from a vector,
\verb'x = v(i)'.  The method is identical to extracting a single entry
\verb'x = A(i,0)' from an \verb'n'-by-1 matrix, so further details of this
method are discussed in Section~\ref{matrix_extractElement}, which discusses
\verb'GrB_Matrix_extractElement'.  In this case, the column index is implicitly
\verb'j=0'.
{\bf NOTE: }  if no entry is present at \verb'v(i)', then
\verb'x' is not modified, and the return value of 
\verb'GrB_Vector_extractElement' is \verb'GrB_NO_VALUE'.

\paragraph{Forced completion:}
All computations for the vector \verb'v' are
guaranteed to be finished when the method returns.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_extractTuples:} get all entries from a vector}
%-------------------------------------------------------------------------------
\label{vector_extractTuples}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_extractTuples           // [I,~,X] = find (v)
(
    GrB_Index *I,               // array for returning row indices of tuples
    <type> *X,                  // array for returning values of tuples
    GrB_Index *nvals,           // I, X size on input; # tuples on output
    const GrB_Vector v          // vector to extract tuples from
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_extractTuples' extracts all tuples from a sparse vector,
analogous to \verb'[I,~,X] = find(v)' in MATLAB.  This function is identical to
its \verb'GrB_Matrix_extractTuples' counterpart, except that the array of
column indices \verb'J' does not appear in this function.  Refer to
Section~\ref{matrix_extractTuples} where further details of this function are
described.

\paragraph{Forced completion:}
All computations for the vector \verb'v' are
guaranteed to be finished when the method returns.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_resize:}          resize a vector}
%-------------------------------------------------------------------------------
\label{vector_resize}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_resize      // change the size of a vector
(
    GrB_Vector u,               // vector to modify
    const GrB_Index nrows_new   // new number of rows in vector
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_resize' changes the size of a vector.  If the dimension
decreases, entries that fall outside the resized vector are deleted.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_free:}          free a vector}
%-------------------------------------------------------------------------------
\label{vector_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_free           // free a vector
(
    GrB_Vector *v           // handle of vector to free
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Vector_free' frees a vector.  Either usage:

    {\small
    \begin{verbatim}
    GrB_Vector_free (&v) ;
    GrB_free (&v) ; \end{verbatim}}

\noindent
frees the vector \verb'v' and sets \verb'v' to \verb'NULL'.  It safely does
nothing if passed a \verb'NULL' handle, or if \verb'v == NULL' on input.
In SuiteSparse:GraphBLAS, any pending updates to the vector are abandoned.


\newpage
%===============================================================================
\subsection{GraphBLAS matrices: {\sf GrB\_Matrix}} %============================
%===============================================================================
\label{matrix}

This section describes a set of methods that create, modify, query,
and destroy a GraphBLAS sparse matrix, \verb'GrB_Matrix':

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GrB_Matrix_new'           & create a matrix \\
\verb'GrB_Matrix_dup'           & copy a matrix \\
\verb'GrB_Matrix_clear'         & clear a matrix of all entries \\
\verb'GrB_Matrix_nrows'         & return the number of rows of a matrix \\
\verb'GrB_Matrix_ncols'         & return the number of columns of a matrix \\
\verb'GrB_Matrix_nvals'         & return the number of entries in a matrix \\
\verb'GxB_Matrix_type'          & return the type of a matrix \\
\verb'GrB_Matrix_build'         & build a matrix from a set of tuples \\
\verb'GrB_Matrix_setElement'    & add a single entry to a matrix \\
\verb'GrB_Matrix_extractElement'& get a single entry from a matrix \\
\verb'GrB_Matrix_extractTuples' & get all entries from a matrix \\
\verb'GxB_Matrix_resize'        & resize a matrix \\
\verb'GrB_Matrix_free'          & free a matrix \\
\hline
\verb'GxB_Matrix_import_CSR'            & import a matrix in CSR form
                                          (see Section~\ref{import_export})\\
\verb'GxB_Matrix_import_CSC'            & import a matrix in CSC form
                                          (see Section~\ref{import_export})\\
\verb'GxB_Matrix_import_HyperCSR'       & import a matrix in HyperCSR form
                                          (see Section~\ref{import_export})\\
\verb'GxB_Matrix_import_HyperCSC'       & import a matrix in HyperCSC form
                                          (see Section~\ref{import_export})\\
\verb'GxB_Matrix_export_CSR'            & export a matrix in CSR form
                                          (see Section~\ref{import_export})\\
\verb'GxB_Matrix_export_CSC'            & export a matrix in CSC form
                                          (see Section~\ref{import_export})\\
\verb'GxB_Matrix_export_HyperCSR'       & export a matrix in HyperCSR form
                                          (see Section~\ref{import_export})\\
\verb'GxB_Matrix_export_HyperCSC'       & export a matrix in HyperCSC form
                                          (see Section~\ref{import_export})\\
\hline
\end{tabular}
}
\vspace{0.2in}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_new:}          create a matrix}
%-------------------------------------------------------------------------------
\label{matrix_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_new     // create a new matrix with no entries
(
    GrB_Matrix *A,          // handle of matrix to create
    const GrB_Type type,    // type of matrix to create
    const GrB_Index nrows,  // matrix dimension is nrows-by-ncols
    const GrB_Index ncols
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_new' creates a new \verb'nrows'-by-\verb'ncols' sparse matrix
with no entries in it, of the given type.  This is analogous to the MATLAB
statement \verb'A = sparse (nrows, ncols)', except that GraphBLAS can create
sparse matrices of any type.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_dup:}          copy a matrix}
%-------------------------------------------------------------------------------
\label{matrix_dup}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_dup     // make an exact copy of a matrix
(
    GrB_Matrix *C,          // handle of output matrix to create
    const GrB_Matrix A      // input matrix to copy
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_dup' makes a deep copy of a sparse matrix, like \verb'C=A' in
MATLAB.  In GraphBLAS, it is possible, and valid, to write the following:

    {\footnotesize
    \begin{verbatim}
    GrB_Matrix A, C ;
    GrB_Matrix_new (&A, GrB_FP64, n) ;
    C = A ;                         // C is a shallow copy of A  \end{verbatim}}

Then \verb'C' and \verb'A' can be used interchangeably.  However, only a
pointer reference is made, and modifying one of them modifies both, and freeing
one of them leaves the other as a dangling handle that should not be used.  If
two different matrices are needed, then this should be used instead:

    {\footnotesize
    \begin{verbatim}
    GrB_Matrix A, C ;
    GrB_Matrix_new (&A, GrB_FP64, n) ;
    GrB_Matrix_dup (&C, A) ;        // like C = A, but making a deep copy \end{verbatim}}

Then \verb'C' and \verb'A' are two different matrices that currently have the
same set of values, but they do not depend on each other.  Modifying one has
no effect on the other.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_clear:}        clear a matrix of all entries}
%-------------------------------------------------------------------------------
\label{matrix_clear}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_clear   // clear a matrix of all entries;
(                           // type and dimensions remain unchanged
    GrB_Matrix A            // matrix to clear
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_clear' clears all entries from a matrix.  All values
\verb'A(i,j)' are now equal to the implicit value, depending on what semiring
ring is used to perform computations on the matrix.  The pattern of \verb'A' is
empty, just as if it were created fresh with \verb'GrB_Matrix_new'.  Analogous
with \verb'A (:,:) = 0' in MATLAB.  The type and dimensions of \verb'A' do not
change.  In SuiteSparse:Graph\-BLAS, any pending updates to the matrix are
discarded.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_nrows:}        return the number of rows of a matrix}
%-------------------------------------------------------------------------------
\label{matrix_nrows}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_nrows   // get the number of rows of a matrix
(
    GrB_Index *nrows,       // matrix has nrows rows
    const GrB_Matrix A      // matrix to query
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_nrows' returns the number of rows of a matrix
(\verb'nrow=size(A,1)' in MATLAB).

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_ncols:}        return the number of columns of a matrix}
%-------------------------------------------------------------------------------
\label{matrix_ncols}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_ncols   // get the number of columns of a matrix
(
    GrB_Index *ncols,       // matrix has ncols columns
    const GrB_Matrix A      // matrix to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Matrix_ncols' returns the number of columns of a matrix
(\verb'ncols=size(A,2)' in MATLAB).

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_nvals:}        return the number of entries in a matrix}
%-------------------------------------------------------------------------------
\label{matrix_nvals}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_nvals   // get the number of entries in a matrix
(
    GrB_Index *nvals,       // matrix has nvals entries
    const GrB_Matrix A      // matrix to query
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_nvals' returns the number of entries in a matrix.  Roughly
analogous to \verb'nvals = nnz(A)' in MATLAB, except that the implicit value in
GraphBLAS need not be zero and \verb'nnz' (short for ``number of nonzeros'') in
MATLAB is better described as ``number of entries'' in GraphBLAS.

\paragraph{Forced completion:}
All computations for the matrix \verb'A' are guaranteed to be finished when
\verb'GrB_Matrix_nvals' returns.  That is, it acts like an object-specific
\verb'GrB_wait' for just this particular matrix \verb'A'.  Other pending
computations for other objects may remain.  To ensure that all pending
computations are complete for all GraphBLAS objects, used \verb'GrB_wait'
instead.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_type:}         return the type of a matrix}
%-------------------------------------------------------------------------------
\label{matrix_type}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_type    // get the type of a matrix
(
    GrB_Type *type,         // returns the type of the matrix
    const GrB_Matrix A      // matrix to query
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_type' returns the type of a matrix, like \verb'type=class(A)'
in MATLAB.

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_type' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_build:} build a matrix from a set of tuples}
%-------------------------------------------------------------------------------
\label{matrix_build}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_build           // build a matrix from (I,J,X) tuples
(
    GrB_Matrix C,                   // matrix to build
    const GrB_Index *I,             // array of row indices of tuples
    const GrB_Index *J,             // array of column indices of tuples
    const <type> *X,                // array of values of tuples
    const GrB_Index nvals,          // number of tuples
    const GrB_BinaryOp dup          // binary function to assemble duplicates
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_build' constructs a sparse matrix \verb'C' from a set of
tuples, \verb'I', \verb'J', and \verb'X', each of length \verb'nvals'.  The
matrix \verb'C' must have already been initialized with \verb'GrB_Matrix_new',
and it must have no entries in it before calling \verb'GrB_Matrix_build'.  Thus
the dimensions and type of \verb'C' are not changed by this function, but are
inherited from the prior call to \verb'GrB_Matrix_new' or
\verb'GrB_matrix_dup'.

An error is returned (\verb'GrB_INDEX_OUT_OF_BOUNDS') if any row index in
\verb'I' is greater than or equal to the number of rows of \verb'C', or if any
column index in \verb'J' is greater than or equal to the number of columns of
\verb'C'

Any duplicate entries with identical indices are assembled using the binary
\verb'dup' operator provided on input.  All three types (\verb'x', \verb'y',
\verb'z' for \verb'z=dup(x,y)') must be identical.  The types of \verb'dup',
\verb'C' and \verb'X' must all be compatible.  See Section~\ref{typecasting}
regarding typecasting and compatibility.  The values in \verb'X' are
typecasted, if needed, into the type of \verb'dup'.  Duplicates are then
assembled into a matrix \verb'T' of the same type as \verb'dup', using
\verb'T(i,j) = dup (T (i,j), X (k))'.  After \verb'T' is constructed, it is
typecasted into the result \verb'C'.  That is, typecasting does not occur at
the same time as the assembly of duplicates.

\begin{spec}
{\bf SPEC:} As an extension to the spec, results are defined even if \verb'dup' is non-associative.
\end{spec}

The GraphBLAS API requires \verb'dup' to be associative so
that entries can be assembled in any order, and states that the result is
undefined if \verb'dup' is not associative.  However, SuiteSparse:GraphBLAS
guarantees a well-defined order of assembly.  Entries in the tuples
\verb'[I,J,X]' are first sorted in increasing order of row and column index,
with ties broken by the position of the tuple in the \verb'[I,J,X]' list.  If
duplicates appear, they are assembled in the order they appear in the
\verb'[I,J,X]' input.  That is, if the same indices \verb'i' and \verb'j'
appear in positions \verb'k1', \verb'k2', \verb'k3', and \verb'k4' in
\verb'[I,J,X]', where \verb'k1 < k2 < k3 < k4', then the following operations
will occur in order:

    {\footnotesize
    \begin{verbatim}
    T (i,j) = X (k1) ;
    T (i,j) = dup (T (i,j), X (k2)) ;
    T (i,j) = dup (T (i,j), X (k3)) ;
    T (i,j) = dup (T (i,j), X (k4)) ; \end{verbatim}}

This is a well-defined order but the user should not depend upon it when using
other GraphBLAS implementations since the GraphBLAS API does not
require this ordering.

However, SuiteSparse:GraphBLAS guarantees this ordering, and with this
well-defined order, several operators become very useful.  In particular, the
\verb'SECOND' operator results in the last tuple overwriting the earlier ones.
The \verb'FIRST' operator means the value of the first tuple is used and the
others are discarded.

The acronym \verb'dup' is used here for the name of binary function used for
assembling duplicates, but this should not be confused with the \verb'_dup'
suffix in the name of the function \verb'GrB_Matrix_dup'.  The latter function
does not apply any operator at all, nor any typecasting, but simply makes a
pure deep copy of a matrix.

The parameter \verb'X' is a pointer to any C equivalent built-in type, or a
\verb'void *' pointer.  The \verb'GrB_Matrix_build' function uses the
\verb'_Generic' feature of ANSI C11 to detect the type of pointer passed as the
parameter \verb'X'.  If \verb'X' is a pointer to a built-in type, then the
function can do the right typecasting.  If \verb'X' is a \verb'void *' pointer,
then it can only assume \verb'X' to be a pointer to a user-defined type that is
the same user-defined type of \verb'C' and \verb'dup'.  This function has no
way of checking this condition that the \verb'void * X' pointer points to an
array of the correct user-defined type, so behavior is undefined if the user
breaks this condition.

The \verb'GrB_Matrix_build' method is analogous to \verb'C = sparse (I,J,X)' in
MATLAB, with several important extensions that go beyond that which MATLAB can
do.  In particular, the MATLAB \verb'sparse' function only provides one option
for assembling duplicates (summation), and it can only build double, double
complex, and logical sparse matrices.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_setElement:}   add a single entry to a matrix}
%-------------------------------------------------------------------------------
\label{matrix_setElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_setElement          // C (i,j) = x
(
    GrB_Matrix C,                       // matrix to modify
    const <type> x,                     // scalar to assign to C(i,j)
    const GrB_Index i,                  // row index
    const GrB_Index j                   // column index
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_setElement' sets a single entry in a matrix, \verb'C(i,j)=x'.
If the entry is already present in the pattern of \verb'C', it is overwritten
with the new value.  If the entry is not present, it is added to \verb'C'.  In
either case, no entry is ever deleted by this function.  Passing in a value of
\verb'x=0' simply creates an explicit entry at position \verb'(i,j)' whose
value is zero, even if the implicit value is assumed to be zero.

An error is returned (\verb'GrB_INVALID_INDEX') if the row index \verb'i' is
greater than or equal to the number of rows of \verb'C', or if the column index
\verb'j' is greater than or equal to the number of columns of \verb'C'.  Note
that this error code differs from the same kind of condition in
\verb'GrB_Matrix_build', which returns \verb'GrB_INDEX_OUT_OF_BOUNDS'.  This is
because \verb'GrB_INVALID_INDEX' is an API error, and is caught immediately
even in non-blocking mode, whereas \verb'GrB_INDEX_OUT_OF_BOUNDS' is an
execution error whose detection may wait until the computation completes
sometime later. 

The scalar \verb'x' is typecasted into the type of \verb'C'.  Any value can be
passed to this function and its type will be detected, via the \verb'_Generic'
feature of ANSI C11.  For a user-defined type, \verb'x' is a \verb'void *'
pointer that points to a memory space holding a single entry of this
user-defined type.  This user-defined type must exactly match the user-defined
type of \verb'C' since no typecasting is done between user-defined types.

\paragraph{\bf Performance considerations:} % BLOCKING: setElement, *assign
SuiteSparse:GraphBLAS exploits the non-blocking mode to greatly improve the
performance of this method.  Refer to the example shown in
Section~\ref{overview}.  If the entry exists in the pattern already, it is
updated right away and the work is not left pending.  Otherwise, it is placed
in a list of pending updates, and the later on the updates are done all at
once, using the same algorithm used for \verb'GrB_Matrix_build'.  In other
words, \verb'setElement' in SuiteSparse:GraphBLAS builds its own internal list
of tuples \verb'[I,J,X]', and then calls \verb'GrB_Matrix_build' whenever the
matrix is needed in another computation, or whenever \verb'GrB_wait' is called.

As a result, if calls to \verb'setElement' are mixed with calls to most other
methods and operations (even \verb'extractElement') then the pending updates
are assembled right away, which will be slow.  Performance will be good if many
\verb'setElement' updates are left pending, and performance will be poor if the
updates are assembled frequently.

A few methods and operations can be intermixed with \verb'setElement', in
particular, some forms of the \verb'GrB_assign' and \verb'GxB_subassign'
operations are compatible with the pending updates from \verb'setElement'.
Sections~\ref{compare_assign} gives more details on which \verb'GxB_subassign'
and \verb'GrB_assign' operations can be interleaved with calls to
\verb'setElement' without forcing updates to be assembled.  Other methods that
do not access the existing entries may also be done without forcing the updates
to be assembled, namely \verb'GrB_Matrix_clear' (which erases all pending
updates), \verb'GrB_Matrix_free', \verb'GrB_Matrix_ncols',
\verb'GrB_Matrix_nrows', \verb'GxB_Matrix_type', and of course
\verb'GrB_Matrix_setElement' itself.  All other methods and operations cause
the updates to be assembled.  Future versions of SuiteSparse:GraphBLAS may
extend this list.

See Section~\ref{random} for an example of how to use
\verb'GrB_Matrix_setElement'.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_extractElement:} get a single entry from a matrix}
%-------------------------------------------------------------------------------
\label{matrix_extractElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_extractElement      // x = A(i,j)
(
    <type> *x,                          // extracted scalar
    const GrB_Matrix A,                 // matrix to extract a scalar from
    const GrB_Index i,                  // row index
    const GrB_Index j                   // column index
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_extractElement' extracts a single entry from a matrix
\verb'x=A(i,j)'.

An error is returned (\verb'GrB_INVALID_INDEX') if the row index \verb'i' is
greater than or equal to the number of rows of \verb'C', or if column index
\verb'j' is greater than or equal to the number of columns of \verb'C'.

{\bf NOTE: }  if no entry is present at \verb'A(i,j)', then
\verb'x' is not modified, and the return value of 
\verb'GrB_Matrix_extractElement' is \verb'GrB_NO_VALUE'.

If the entry is not present then GraphBLAS does not know its value, since its
value depends on the implicit value, which is the identity value of the
additive monoid of the semiring.  It is not a characteristic of the matrix
itself, but of the semiring it is used in.  A matrix can be used in any
compatible semiring, and even a mixture of semirings, so the implicit value can
change as the semiring changes.

As a result, if the entry is present, \verb'x=A(i,j)' is performed and the
scalar \verb'x' is returned with this value.  The method returns
\verb'GrB_SUCCESS'.  If the entry is not present, \verb'x' is not modified, and
\verb'GrB_NO_VALUE' is returned to the caller.  What this means is up to the
caller.

The function knows the type of the pointer \verb'x', so it can do typecasting
as needed, from the type of \verb'A' into the type of \verb'x'.  User-defined
types cannot be typecasted, so if \verb'A' has a user-defined type then
\verb'x' must be a \verb'void *' pointer that points to a memory space the same
size as a single scalar of the type of \verb'A'.

\paragraph{Forced completion:}
All computations for the matrix \verb'A' are
guaranteed to be finished when the method returns.
%
In particular, this method causes all pending updates from
\verb'GrB_setElement', \verb'GrB_assign', or \verb'GxB_subassign' to be
assembled, so its use can have performance implications.  Calls to this
function should not be arbitrarily intermixed with calls to these other two
functions.  Everything will work correctly and results will be predictable, it
will just be slow.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_extractTuples:}get all entries from a matrix}
%-------------------------------------------------------------------------------
\label{matrix_extractTuples}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_extractTuples           // [I,J,X] = find (A)
(
    GrB_Index *I,               // array for returning row indices of tuples
    GrB_Index *J,               // array for returning col indices of tuples
    <type> *X,                  // array for returning values of tuples
    GrB_Index *nvals,           // I,J,X size on input; # tuples on output
    const GrB_Matrix A          // matrix to extract tuples from
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_extractTuples' extracts all the entries from the matrix
\verb'A', returning them as a list of tuples, analogous to
\verb'[I,J,X]=find(A)' in MATLAB.  Entries in the tuples \verb'[I,J,X]' are
unique.  No pair of row and column indices \verb'(i,j)' appears more than once.

The GraphBLAS API states the tuples can be returned in any order.
SuiteSparse:GraphBLAS chooses to always return them in sorted order, depending
on whether the matrix is stored by row or by column.

The number of tuples in the matrix \verb'A' is given by
\verb'GrB_Matrix_nvals(&anvals,A)'.  If \verb'anvals' is larger than the size
of the arrays (\verb'nvals' in the parameter list), an error
\verb'GrB_INSUFFICIENT_SIZE' is returned, and no tuples are extracted.  If
\verb'nvals' is larger than \verb'anvals', then only the first \verb'anvals'
entries in the arrays \verb'I' \verb'J', and \verb'X' are modified, containing
all the tuples of \verb'A', and the rest of \verb'I' \verb'J', and \verb'X' are
left unchanged.  On output, \verb'nvals' contains the number of tuples
extracted.

\paragraph{Forced completion:}
All computations for the matrix \verb'A' are
guaranteed to be finished when the method returns.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_resize:}          resize a matrix}
%-------------------------------------------------------------------------------
\label{matrix_resize}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_resize      // change the size of a matrix
(
    GrB_Matrix A,               // matrix to modify
    const GrB_Index nrows_new,  // new number of rows in matrix
    const GrB_Index ncols_new   // new number of columns in matrix
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_resize' changes the size of a matrix.
If the dimensions decrease, entries that fall outside the resized 
matrix are deleted.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_free:} free a matrix}
%-------------------------------------------------------------------------------
\label{matrix_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_free           // free a matrix
(
    GrB_Matrix *A           // handle of matrix to free
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_free' frees a matrix.  Either usage:

    {\small
    \begin{verbatim}
    GrB_Matrix_free (&A) ;
    GrB_free (&A) ; \end{verbatim}}

\noindent
frees the matrix \verb'A' and sets \verb'A' to \verb'NULL'.  It safely does
nothing if passed a \verb'NULL' handle, or if \verb'A == NULL' on input.
In SuiteSparse:GraphBLAS, any pending updates to the matrix are abandoned.




\newpage
%===============================================================================
\subsection{GraphBLAS matrix and vector import/export} %========================
%===============================================================================
\label{import_export}

The import/export functions allow the user application to create a
\verb'GrB_Matrix' or \verb'GrB_Vector' object, and to extract its contents,
faster and with less memory overhead than the \verb'GrB_*_build' and
\verb'GrB_*_extractTuples' functions.

The semantics of import/export are the same as the {\em move constructor} in
C++.  On import, the user provides a set of arrays that have been previously
allocated via the ANSI C \verb'malloc', \verb'calloc', or \verb'realloc'
functions (by default), or by the corresponding functions passed to
\verb'GxB_init'.  The arrays define the content of the matrix or vector.
Unlike \verb'GrB_*_build', the GraphBLAS library then takes ownership of the
user's input arrays and may either:

\begin{enumerate}
\item incorporate them
into its internal data structure for the new \verb'GrB_Matrix' or
\verb'GrB_Vector', potentially creating the \verb'GrB_Matrix' or
\verb'GrB_Vector' in constant time with no memory copying performed, or
\item if
the library does not support the import format directly, then it may convert
the input to its internal format, and then free the user's input arrays.
\item A
GraphBLAS implementation may also choose to use a mix of the two strategies.
\end{enumerate}

SuiteSparse:GraphBLAS takes the first approach, and so the import functions
always take $O(1)$ time, and require $O(1)$ memory space to be allocated.

Regardless of the method chosen, as listed above, the input arrays are no
longer owned by the user application.  If \verb'A' is a \verb'GrB_Matrix'
created by an import, the user input arrays are freed no later than
\verb'GrB_free(&A)', and may be freed earlier, at the discretion of the
GraphBLAS library.  The data structure of the \verb'GrB_Matrix' and
\verb'GrB_Vector' remain opaque.

The export of a \verb'GrB_Matrix' or \verb'GrB_Vector' is symmetric with the
import operation.  The export changes the ownership of the arrays, where the
\verb'GrB_Matrix' or \verb'GrB_Vector' no longer exists when the export
completes, and instead the user is returned several arrays that contain the
matrix or vector in the requested format.  Ownership of these arrays is given
to the user application, which is then responsible for freeing them via the
ANSI C \verb'free' function (by default), or by the \verb'free_function' that
was passed in to \verb'GxB_init'.  Alternatively, these arrays can be
re-imported into a \verb'GrB_Matrix' or \verb'GrB_Vector', at which point they
again become the responsibility of GraphBLAS.

For a matrix export, if the output format matches the current internal format
of the matrix then these arrays are returned to the user application in $O(1)$
time and with no memory copying performed.  Otherwise, the \verb'GrB_Matrix' is
first converted into the requested format, and then exported.

The vector import/export methods use a single format for a \verb'GrB_Vector'.
Four different formats are provided for the import/export of a
\verb'GrB_Matrix'.  For each format, the \verb'Ax' array has a C type
corresponding to one of the 11 built-in types in GraphBLAS (\verb'bool',
\verb'int*_t', \verb'uint*_t', \verb'float', and \verb'double'), or that
corresponds with the user-defined type.  No typecasting is done on import or
export.

The table below lists the methods presented in this section.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
method & purpose & Section \\
\hline
\verb'GxB_Vector_import'         & import a vector &
                                    \ref{vector_import} \\
\verb'GxB_Vector_export'         & export a vector &
                                    \ref{vector_export} \\
\hline
\verb'GxB_Matrix_import_CSR'            & import a matrix in CSR form &
                                          \ref{matrix_import_csr} \\
\verb'GxB_Matrix_import_CSC'            & import a matrix in CSC form &
                                          \ref{matrix_import_csc} \\
\verb'GxB_Matrix_import_HyperCSR'       & import a matrix in HyperCSR form &
                                          \ref{matrix_import_hypercsr} \\
\verb'GxB_Matrix_import_HyperCSC'       & import a matrix in HyperCSC form &
                                          \ref{matrix_import_hypercsc} \\
\verb'GxB_Matrix_export_CSR'            & export a matrix in CSR form &
                                          \ref{matrix_export_csr} \\
\verb'GxB_Matrix_export_CSC'            & export a matrix in CSC form &
                                          \ref{matrix_export_csc} \\
\verb'GxB_Matrix_export_HyperCSR'       & export a matrix in HyperCSR form &
                                          \ref{matrix_export_hypercsr} \\
\verb'GxB_Matrix_export_HyperCSC'       & export a matrix in HyperCSC form &
                                          \ref{matrix_export_hypercsc} \\
\hline
\end{tabular}
}
\vspace{0.2in}

\begin{spec}
{\bf SPEC:} The import/export methods are extensions to the spec.  However,
they have been implemented in SuiteSparse:GraphBLAS at the request of the
GraphBLAS C API Committee, as a prototype for future consideration for
inclusion in a future specification.  Their calling sequence may change if
these functions are added to the specification as \verb'GrB_*' functions.  A
GraphBLAS library need not implement these methods in constant time and memory.
On import, a library may choose to copy the content of the user arrays into its
internal data structure and then \verb'free' the user arrays.  On export, it
may chose to \verb'malloc' the output arrays, fill them with the requested
data, and then \verb'GrB_free' the GraphBLAS object being exported.  The
semantics of these options are the same as a move constructor; they just take
more time and memory.  The choice is up to the GraphBLAS implementation since
the internal data structure is opaque to the user application.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_import:}        import a vector}
%-------------------------------------------------------------------------------
\label{vector_import}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_import  // import a vector in CSC format
(
    GrB_Vector *v,          // vector to create
    const GrB_Type type,    // type of vector to create
    GrB_Index n,            // vector length
    GrB_Index nvals,        // number of entries in the vector
    GrB_Index **vi,         // indices, size nvals (in sorted order)
    void      **vx,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

The \verb'GxB_Vector_import' function is a fast way to construct a
\verb'GrB_Vector', always taking just $O(1)$ time.  Calling
\verb'GxB_Vector_import' with:

{\footnotesize
\begin{verbatim}
    GxB_Vector_import (&v, type, n, nvals, &vi, &vx, desc) ;
\end{verbatim}}

is identical to the following:

{\footnotesize
\begin{verbatim}
    int64_t *Ap = calloc (2, sizeof (int64_t)) ;
    Ap [1] = nvals ;
    GxB_Matrix_import_CSC (&A, type, n, 1, nvals, -1, &Ap, &vi, &vx, desc) ;
\end{verbatim}}

\noindent
except that the latter creates an \verb'n'-by-1 matrix instead.  For the vector
import, described here, the first argument is a \verb'GrB_Vector'.  The
arguments \verb'vi' and \verb'vx' take the place of \verb'Ai' and \verb'Ax',
and the \verb'Ap' array for the CSC matrix import is not provided for a vector
import.  Refer to the description of \verb'GxB_Matrix_import_CSC' for details
(Section~\ref{matrix_import_csc}).

If successful, \verb'v' is created as a \verb'n'-by-1 vector.  Its entries are
the row indices given by \verb'vi', with the corresponding values in \verb'vx'.
The two pointers \verb'vi' and \verb'vx' are returned as \verb'NULL', which
denotes that they are no longer owned by the user application.  They have
instead been moved into the new vector \verb'v'.  The row indices in \verb'vi'
must appear in sorted order, and no duplicates can appear.  These conditions
are not checked, so results are undefined if they are not met exactly.  The
user application can check the resulting vector \verb'v' with \verb'GxB_print',
if desired, which will determine if these conditions hold.

If not successful, \verb'v' is returned as \verb'NULL' and \verb'vi' and
\verb'vx' are not modified.

\begin{spec}
{\bf SPEC:} \verb'GxB_Vector_import' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_export:}        export a vector}
%-------------------------------------------------------------------------------
\label{vector_export}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_export  // export and free a vector
(
    GrB_Vector *v,          // vector to export and free
    GrB_Type *type,         // type of matrix exported
    GrB_Index *n,           // length of the vector
    GrB_Index *nvals,       // number of entries in the vector
    GrB_Index **vi,         // indices, size nvals
    void      **vx,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

The \verb'GxB_Vector_export' function is a fast way to extract the contents of
a \verb'GrB_Vector', always taking just $O(1)$ time.  Using
\verb'GxB_Vector_export' with:

{\footnotesize
\begin{verbatim}
    GxB_Vector_export (&v, &type, &n, &nvals, &vi, &vx, desc) ;
\end{verbatim}}

is analogous to:

{\footnotesize
\begin{verbatim}
    GxB_Matrix_export_CSC (&A, &type, &n, &one, &nvals, &nonempty,
        &Ap, &Ai, &Ax, desc)
\end{verbatim}}

\noindent
if \verb'A' were an \verb'n'-by-1 matrix.  For the vector export, described
here, the first argument is a \verb'GrB_Vector'.  The arguments \verb'vi' and
\verb'vx' take the place of \verb'Ai' and \verb'Ax', and the \verb'Ap' array
for the CSC matrix export is not returned from a vector export.  Refer to the
description of \verb'GxB_Matrix_export_CSC' for details.
(Section~\ref{matrix_import_csr}).

Exporting a vector forces completion of any pending operations on the vector.

If successful, \verb'v' is returned as \verb'NULL', and its contents are
returned to the user, with its \verb'type', dimension \verb'n', and number of
entries \verb'nvals'.  A sorted list of row indices of entries that were in
\verb'v' is returned in \verb'vi', and the corresponding numerical values are
returned in \verb'vx'.  If \verb'nvals' is zero, the \verb'vi' and \verb'vx'
arrays are returned as \verb'NULL'; this is not an error condition.

If not successful, \verb'v' is unmodified and \verb'vi' and \verb'vx' are
not modified.  

\begin{spec}
{\bf SPEC:} \verb'GxB_Vector_export' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_import\_CSR:} import a CSR matrix}
%-------------------------------------------------------------------------------
\label{matrix_import_csr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_import_CSR      // import a CSR matrix
(
    GrB_Matrix *A,          // handle of matrix to create
    const GrB_Type type,    // type of matrix to create
    GrB_Index nrows,        // matrix dimension is nrows-by-ncols
    GrB_Index ncols,
    GrB_Index nvals,        // number of entries in the matrix
    // CSR format:
    int64_t nonempty,       // number of rows with at least one entry:
                            // either < 0 if not known, or >= 0 if exact
    GrB_Index **Ap,         // row "pointers", size nrows+1
    GrB_Index **Aj,         // column indices, size nvals
    void      **Ax,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_import_CSR' imports a matrix from 3 user arrays in CSR format.
In the resulting \verb'GrB_Matrix A', the \verb'CSR' format is a matrix with a
format (\verb'GxB_FORMAT') of \verb'GxB_BY_ROW', in standard for instead of
hypersparse form (See Section~\ref{hypersparse}).

The first four arguments of \verb'GxB_Matrix_import_CSR' are the same as
all four arguments of \verb'GrB_Matrix_new', because this function is similar.
It creates a new \verb'GrB_Matrix A', with the given type and dimensions.
The \verb'GrB_Matrix A' does not exist on input.

Unlike \verb'GrB_Matrix_new', this function also populates the new matrix
\verb'A' with the three arrays \verb'Ap', \verb'Aj' and \verb'Ax', provided by
the user, all of which must have been created with the ANSI C \verb'malloc',
\verb'calloc', or \verb'realloc' functions (by default), or by the
corresponding \verb'malloc_function', \verb'calloc_function', or
\verb'realloc_function' provided to \verb'GxB_init'.  These arrays define the
pattern and values of the new matrix \verb'A':

\begin{itemize}
\item \verb'GrB_Index Ap [nrows+1] ;'  The \verb'Ap' array is the row
``pointer'' array.  It does not actual contain pointers.  More precisely, it is
an integer array that defines where the column indices and values appear in
\verb'Aj' and \verb'Ax', for each row.  The number of entries in row \verb'i'
is given by the expression \verb'Ap [i+1] - Ap [i]'.

\item \verb'GrB_Index Aj [nvals] ;'  The \verb'Aj' array defines the
column indices of entries in each row.

\item \verb'ctype Aj [nvals] ;'  The \verb'Ax' array defines the values of
entries in each row.  It is passed in as a \verb'(void *)' pointer, but it must
point to an array of size \verb'nvals' values, each of size
\verb'sizeof(ctype)', where \verb'ctype' is the exact type in C that corresponds
to the \verb'GrB_Type type' parameter.  That is, if \verb'type' is
\verb'GrB_INT32', then \verb'ctype' is \verb'int32_t'.  User types
may be used, just the same as built-in types.
\end{itemize}

The content of the three arrays \verb'Ap' \verb'Aj', and \verb'Ax' is very
specific.  This content is not checked, since this function takes only
$O(1)$ time.  Results are undefined if the following specification is not
followed exactly.

The column indices of entries in the ith row of the matrix are held in
\verb'Aj [Ap [i] ... Ap[i+1]]', and the corresponding values are held in the
same positions in \verb'Ax'.  Column indices must be in the range 0 to
\verb'ncols'-1, and must appear in sorted order within each row.  No duplicate
column indices may appear in any row.  \verb'Ap [0]' must equal zero, and
\verb'Ap [nrows]' must equal nvals.  The \verb'Ap' array must be of size
\verb'nrows'+1 (or larger), and the \verb'Aj' and \verb'Ax' arrays must have
size at least \verb'nvals'.

If \verb'nvals' is zero, then the content of the \verb'Aj' and \verb'Ax' arrays
is not accessed and they may be \verb'NULL' on input (if not \verb'NULL', they
are still freed and returned as \verb'NULL', if the method is successful).

The \verb'nonempty' parameter is optional.  It states the number of rows
that have at least one entry: if not known, use -1;
if $\ge 0$, it must be exact.

An example of the CSR format is shown below.  Consider the following
matrix with 10 nonzero entries, and suppose the zeros are not stored.

    \begin{equation}
    \label{eqn:Aexample}
    A = \left[
    \begin{array}{cccc}
    4.5 &   0 & 3.2 &   0 \\
    3.1 & 2.9 &  0  & 0.9 \\
     0  & 1.7 & 3.0 &   0 \\
    3.5 & 0.4 &  0  & 1.0 \\
    \end{array}
    \right]
    \end{equation}

The \verb'Ap' array has length 5, since the matrix is 4-by-4.  The first entry
must always zero, and \verb'Ap [5] = 10' is the number of entries.
The content of the arrays is shown below:

{\footnotesize
\begin{verbatim}
    int64_t Ap [ ] = { 0,        2,             5,        7,            10 } ;
    int64_t Aj [ ] = { 0,   2,   0,   1,   3,   1,   2,   0,   1,   3   } ;
    double  Ax [ ] = { 4.5, 3.2, 3.1, 2.9, 0.9, 1.7, 3.0, 3.5, 0.4, 1.0 } ; \end{verbatim} }

Spaces have been added to the \verb'Ap' array, just for illustration.  Row zero
is in \verb'Aj [0..1]' (column indices) and \verb'Ax [0..1]' (values), starting
at \verb'Ap [0] = 0' and ending at \verb'Ap [0+1]-1 = 1'.  The list of column
indices of row one is at \verb'Aj [2..4]' and row two is in \verb'Aj [5..6]'.
The last row (three) appears \verb'Aj [7..9]', because \verb'Ap [3] = 7' and
\verb'Ap [4]-1 = 10-1 = 9'.  The corresponding numerical values appear in the
same positions in \verb'Ax'.

To iterate over the rows and entries of this matrix, the following code can be
used:

    {\footnotesize
    \begin{verbatim}
    int64_t nvals = Ap [nrows] ;
    for (int64_t i = 0 ; i < nrows ; i++)
    {
        // get A(i,:)
        for (int64_t p = Ap [i] ; p < Ap [i+1] ; p++)
        {
            // get A(i,j)
            int64_t  j = Aj [p] ;           // column index
            double aij = Ax [p] ;           // numerical value
        }
    } \end{verbatim}}

On successful creation of \verb'A', the three pointers \verb'Ap', \verb'Aj',
and \verb'Ax' are set to \verb'NULL' on output.  This denotes to the user
application that it is no longer responsible for freeing these arrays.
Internally, GraphBLAS has moved these arrays into its internal data structure.
They will eventually be freed no later than when the user does
\verb'GrB_free(&A)', but they may be freed or resized later, if the matrix
changes.

If the matrix \verb'A' is later exported in CSR form, and GraphBLAS has not yet
reallocated these arrays, then these same three arrays are returned to the user
by \verb'GxB_Matrix_export_CSR' (see Section~\ref{matrix_export_csr}).  If an
export is performed, the freeing of these three arrays again becomes the
responsibility of the user application.

The \verb'GxB_Matrix_import_CSR' function will rarely fail, since it allocates
just $O(1)$ space.  If it does fail, it returns \verb'GrB_OUT_OF_MEMORY',
and it leaves the three user arrays unmodified.  They are still owned by
the user application, which is eventually responsible for freeing them with
\verb'free(Ap)', etc.

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_import_CSR' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_import\_CSC:} import a CSC matrix}
%-------------------------------------------------------------------------------
\label{matrix_import_csc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_import_CSC      // import a CSC matrix
(
    GrB_Matrix *A,          // handle of matrix to create
    const GrB_Type type,    // type of matrix to create
    GrB_Index nrows,        // matrix dimension is nrows-by-ncols
    GrB_Index ncols,
    GrB_Index nvals,        // number of entries in the matrix
    // CSC format:
    int64_t nonempty,       // number of columns with at least one entry:
                            // either < 0 if not known, or >= 0 if exact
    GrB_Index **Ap,         // column "pointers", size ncols+1
    GrB_Index **Ai,         // row indices, size nvals
    void      **Ax,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_import_CSC' imports a matrix from 3 user arrays in CSC format.
The \verb'GrB_Matrix A' is created in the \verb'CSC' format, which is a
\verb'GxB_FORMAT' of \verb'GxB_BY_COL'.  The arguments are identical to
\verb'GxB_Matrix_import_CSR', except for how the 3 user arrays are
interpreted.  The column ``pointer'' array has size \verb'ncols+1'.  The row
indices of the columns are in \verb'Ai', and must appear in ascending order in
each column.  The corresponding numerical values are held in \verb'Ax'.  The
row indices of column \verb'j' are held in \verb'Ai [Ap [j]...Ap [j+1]-1',
and the corresponding numerical values are in the same locations in \verb'Ax'.

The \verb'nonempty' parameter is optional.  It states the number of columns
that have at least one entry: if not known, use -1;
if $\ge 0$, it must be exact.

The same matrix from Equation~\ref{eqn:Aexample}in
the last section (repeated here):

    \begin{equation}
    A = \left[
    \begin{array}{cccc}
    4.5 &   0 & 3.2 &   0 \\
    3.1 & 2.9 &  0  & 0.9 \\
     0  & 1.7 & 3.0 &   0 \\
    3.5 & 0.4 &  0  & 1.0 \\
    \end{array}
    \right]
    \end{equation}

is held in CSC form as follows:

{\footnotesize
\begin{verbatim}
    int64_t Ap [ ] = { 0,             3,             6,        8,       10 } ;
    int64_t Ai [ ] = { 0,   1,   3,   1,   2,   3,   0,   2,   1,   3   } ;
    double  Ax [ ] = { 4.5, 3.1, 3.5, 2.9, 1.7, 0.4, 3.2, 3.0, 0.9, 1.0 } ; \end{verbatim} }

That is, the row indices of column 1 (the second column) are in
\verb'Ai [3..5]', and the values in the same place in \verb'Ax',
since \verb'Ap [1] = 3' and \verb'Ap [2]-1 = 5'.

To iterate over the columns and entries of this matrix, the following code can
be used:

    {\footnotesize
    \begin{verbatim}
    int64_t nvals = Ap [ncols] ;
    for (int64_t j = 0 ; j < ncols ; j++)
    {
        // get A(:,j)
        for (int64_t p = Ap [j] ; p < Ap [j+1] ; p++)
        {
            // get A(i,j)
            int64_t  i = Ai [p] ;           // row index
            double aij = Ax [p] ;           // numerical value
        }
    } \end{verbatim}}

The method is identical to \verb'GxB_Matrix_import_CSR'; just the format is
different.  That is, if the method is successful, the 3 user arrays are
imported into the new \verb'GrB_Matrix A', with the given type and dimensions,
and returned as \verb'NULL' pointers to the user application.

If \verb'nvals' is zero, then the content of the \verb'Ai' and \verb'Ax' arrays
is not accessed and they may be \verb'NULL' on input (if not \verb'NULL', they
are still freed and returned as \verb'NULL', if the method is successful).

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_import_CSC' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_import\_HyperCSR:} import a HyperCSR matrix}
%-------------------------------------------------------------------------------
\label{matrix_import_hypercsr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_import_HyperCSR     // import a hypersparse CSR matrix
(
    GrB_Matrix *A,          // handle of matrix to create
    const GrB_Type type,    // type of matrix to create
    GrB_Index nrows,        // matrix dimension is nrows-by-ncols
    GrB_Index ncols,
    GrB_Index nvals,        // number of entries in the matrix
    // hypersparse CSR format:
    int64_t nonempty,       // number of rows in Ah with at least one entry,
                            // either < 0 if not known, or >= 0 if exact
    GrB_Index nvec,         // number of rows in Ah list
    GrB_Index **Ah,         // list of size nvec of rows that appear in A
    GrB_Index **Ap,         // row "pointers", size nvec+1
    GrB_Index **Aj,         // column indices, size nvals
    void      **Ax,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_import_HyperCSR' imports a matrix in hypersparse CSR format in
$O(1)$ time.  In the hypersparse format, the \verb'Ap' array itself becomes
sparse, if the matrix has rows that are completely empty.  An array \verb'Ah'
of size \verb'nvec' provides a list of rows that appear in the data structure.
For example, consider Equation~\ref{eqn:Ahyper}, which is a sparser version of
the matrix in Equation~\ref{eqn:Aexample}.  Row 2 and column 1 of this matrix
are all zero.

    \begin{equation}
    \label{eqn:Ahyper}
    A = \left[
    \begin{array}{cccc}
    4.5 &   0 & 3.2 &   0 \\
    3.1 &   0 &  0  & 0.9 \\
     0  &   0 &  0  &   0 \\
    3.5 &   0 &  0  & 1.0 \\
    \end{array}
    \right]
    \end{equation}

The conventional CSR format would appear as follows.  Since the third row (row
2) is all zero, accessing \verb'Ai [Ap [2] ... Ap [3]-1]' gives an empty set
(\verb'[2..1]'), and the number of entries in this row is
\verb'Ap [i+1] - Ap [i]' \verb'= Ap [3] - Ap [2] = 0'.

{\footnotesize
\begin{verbatim}
    int64_t Ap [ ] = { 0,        2,2,      4,       5 } ;
    int64_t Aj [ ] = { 0,   2,   0,   3,   0    3   }
    double  Ax [ ] = { 4.5, 3.2, 3.1, 0.9, 3.5, 1.0 } ; \end{verbatim} }

A hypersparse CSR format for this same matrix would discard
these duplicate integers in \verb'Ap'.  Doing so requires
another array, \verb'Ah', that keeps track of the rows that appear
in the data structure.

\newpage
{\footnotesize
\begin{verbatim}
    int64_t nvec = 3 ;
    int64_t Ah [ ] = { 0,        1,        3        } ;
    int64_t Ap [ ] = { 0,        2,        4,       5 } ;
    int64_t Aj [ ] = { 0,   2,   0,   3,   0    3   }
    double  Ax [ ] = { 4.5, 3.2, 3.1, 0.9, 3.5, 1.0 } ; \end{verbatim} }

Note that the \verb'Aj' and \verb'Ax' arrays are the same in the standard and
hypersparse CSR formats.  The row indices in \verb'Ah' must appear in ascending
order, and no duplicates can appear.  To iterate over this data structure:

    {\footnotesize
    \begin{verbatim}
    int64_t nvals = Ap [nvec] ;
    for (int64_t k = 0 ; k < nvec ; k++)
    {
        int64_t i = Ah [k] ;                // row index
        // get A(i,:)
        for (int64_t p = Ap [k] ; p < Ap [k+1] ; p++)
        {
            // get A(i,j)
            int64_t  j = Aj [p] ;           // column index
            double aij = Ax [p] ;           // numerical value
        }
    } \end{verbatim}}

\vspace{-0.05in}
This is more complex than the standard CSR format, but it requires at most
$O(e)$ space, where $A$ is $m$-by-$n$ with $e$ = \verb'nvals' entries.  The
standard CSR format requires $O(m+e)$ space.  If $e << m$, then the size $m+1$
of \verb'Ap' can dominate the memory required.  In the hypersparse form,
\verb'Ap' takes on size \verb'nvec+1', and \verb'Ah' has size \verb'nvec',
where \verb'nvec' is the number of rows that appear in the data structure.
The standard CSR format can be viewed as a dense array (of size \verb'nrows')
of sparse row vectors.   By contrast, the hypersparse CSR format is a sparse
array (of size \verb'nvec') of sparse row vectors.

The import takes $O(1)$ time.  If successful, the four arrays \verb'Ah',
\verb'Ap', \verb'Aj', and \verb'Ax' are returned as \verb'NULL', and the
hypersparse \verb'GrB_Matrix A' is created.

If \verb'nvals' is zero, then the content of the \verb'Aj' and \verb'Ax' arrays
is not accessed and they may be \verb'NULL' on input (if not \verb'NULL', they
are still freed and returned as \verb'NULL', if the method is successful).
The \verb'nonempty' parameter is optional.  It states the number of rows
that have at least one entry: if not known, use -1;
if $\ge 0$, it must be exact.

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_import_HyperCSR' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_import\_HyperCSC:} import a HyperCSC matrix}
%-------------------------------------------------------------------------------
\label{matrix_import_hypercsc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_import_HyperCSC     // import a hypersparse CSC matrix
(
    GrB_Matrix *A,          // handle of matrix to create
    const GrB_Type type,    // type of matrix to create
    GrB_Index nrows,        // matrix dimension is nrows-by-ncols
    GrB_Index ncols,
    GrB_Index nvals,        // number of entries in the matrix
    // hypersparse CSC format:
    int64_t nonempty,       // number of columns in Ah with at least one entry,
                            // either < 0 if not known, or >= 0 if exact
    GrB_Index nvec,         // number of columns in Ah list
    GrB_Index **Ah,         // list of size nvec of columns that appear in A
    GrB_Index **Ap,         // column "pointers", size nvec+1
    GrB_Index **Ai,         // row indices, size nvals
    void      **Ax,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_import_HyperCSC' imports a matrix in hypersparse CSC format in
$O(1)$ time.  It is identical to \verb'GxB_Matrix_import_HyperCSR', except for
the data structure defined by the four arrays \verb'Ah', \verb'Ap', \verb'Ai',
and \verb'Ax'.  It is a sparse array of size \verb'nvec' of sparse column
vectors.  The following code iterates over the matrix:

    \vspace{-0.10in}
    {\footnotesize
    \begin{verbatim}
    int64_t nvals = Ap [nvec] ;
    for (int64_t k = 0 ; k < nvec ; k++)
    {
        int64_t j = Ah [k] ;                // column index
        // get A(:,j)
        for (int64_t p = Ap [k] ; p < Ap [k+1] ; p++)
        {
            // get A(i,j)
            int64_t  i = Ai [p] ;           // row index
            double aij = Ax [p] ;           // numerical value
        }
    } \end{verbatim}}

\vspace{-0.12in}
The \verb'nonempty' parameter is optional.  It states the number of columns
that have at least one entry: if not known, use -1;
if $\ge 0$, it must be exact.

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_import_HyperCSC' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_export\_CSR:} export a CSR matrix}
%-------------------------------------------------------------------------------
\label{matrix_export_csr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_export_CSR  // export and free a CSR matrix
(
    GrB_Matrix *A,          // handle of matrix to export and free
    GrB_Type *type,         // type of matrix exported
    GrB_Index *nrows,       // matrix dimension is nrows-by-ncols
    GrB_Index *ncols,
    GrB_Index *nvals,       // number of entries in the matrix
    // CSR format:
    int64_t *nonempty,      // number of rows with at least one entry
    GrB_Index **Ap,         // row "pointers", size nrows+1
    GrB_Index **Aj,         // column indices, size nvals
    void      **Ax,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_export_CSR' exports a matrix in CSR form:

{\footnotesize
\begin{verbatim}
GxB_Matrix_export_CSR (&A, &type, &nrows, &ncols, &nvals, &nonempty,
                       &Ap, &Aj, &Ax, desc) ;
\end{verbatim}}

On successful output, the \verb'GrB_Matrix A' is freed, and \verb'A' is
returned as \verb'NULL'.  Its type is returned in the \verb'type' parameter,
its dimensions in \verb'nrows' and \verb'ncols', its number of entries in
\verb'nvals', and the CSR format is in the three arrays \verb'Ap', \verb'Aj',
and \verb'Ax'.  If \verb'nvals' is zero, the \verb'Aj' and \verb'Ax' arrays are
returned as \verb'NULL'; this is not an error, and \verb'GxB_Matrix_import_CSR'
also allows these two arrays to be \verb'NULL' on input when \verb'nvals' is
zero.  After a successful export, the user application is responsible for
freeing these three arrays via \verb'free' (or the \verb'free' function passed to \verb'GxB_init').  The CSR format is
described in Section~\ref{matrix_import_csr}.

This method takes $O(1)$ time if the matrix is already in standard
(non-hypersparse) CSR format internally.  If it is in hypersparse CSR form, the
export must first convert the matrix to standard CSR form, taking $O(m)$ time
and memory, where $m$ = \verb'nrows'.  If the matrix is in CSC format, it is
first transposed to convert it to CSR format, and then exported.  This takes
$O(m+n+e)$ or $O(m+e \log e)$ time and memory, whichever is less, where $n=$
\verb'ncols' and $e=$ \verb'nvals'.

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_export_CSR' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_export\_CSC:} export a CSC matrix}
%-------------------------------------------------------------------------------
\label{matrix_export_csc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_export_CSC  // export and free a CSC matrix
(
    GrB_Matrix *A,          // handle of matrix to export and free
    GrB_Type *type,         // type of matrix exported
    GrB_Index *nrows,       // matrix dimension is nrows-by-ncols
    GrB_Index *ncols,
    GrB_Index *nvals,       // number of entries in the matrix
    // CSC format:
    int64_t *nonempty,      // number of columns with at least one entry
    GrB_Index **Ap,         // column "pointers", size ncols+1
    GrB_Index **Ai,         // row indices, size nvals
    void      **Ax,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_export_CSC' exports a matrix in CSC form:

{\footnotesize
\begin{verbatim}
GxB_Matrix_export_CSC (&A, &type, &nrows, &ncols, &nvals, &nonempty,
                       &Ap, &Ai, &Ax, desc) ;
\end{verbatim}}

On successful output, the \verb'GrB_Matrix A' is freed, and \verb'A' is
returned as \verb'NULL'.  Its type is returned in the \verb'type' parameter,
its dimensions in \verb'nrows' and \verb'ncols', its number of entries in
\verb'nvals', and the CSC format is in the three arrays \verb'Ap', \verb'Ai',
and \verb'Ax'.  If \verb'nvals' is zero, the \verb'Ai' and \verb'Ax' arrays are
returned as \verb'NULL'; this is not an error, and \verb'GxB_Matrix_import_CSC'
also allows these two arrays to be \verb'NULL' on input when \verb'nvals' is
zero.  After a successful export, the user application is responsible for
freeing these three arrays via \verb'free' (or the \verb'free' function passed to \verb'GxB_init').  The CSC format is
described in Section~\ref{matrix_import_csc}.

This method takes $O(1)$ time if the matrix is already in standard
(non-hypersparse) CSC format internally.  If it is in hypersparse CSC form, the
export must first convert the matrix to standard CSC form, taking $O(n)$ time
and memory, where $n$ = \verb'ncols'.  If the matrix is in CSR
format, it is first transposed to convert it to CSC format, and then exported.
This takes $O(m+n+e)$ or $O(n+e \log e)$ time and memory, whichever is less,
where $m=$ \verb'nrows' and $e=$ \verb'nvals'.

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_export_CSC' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_export\_HyperCSR:} export a HyperCSR matrix}
%-------------------------------------------------------------------------------
\label{matrix_export_hypercsr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_export_HyperCSR  // export and free a hypersparse CSR matrix
(
    GrB_Matrix *A,          // handle of matrix to export and free
    GrB_Type *type,         // type of matrix exported
    GrB_Index *nrows,       // matrix dimension is nrows-by-ncols
    GrB_Index *ncols,
    GrB_Index *nvals,       // number of entries in the matrix
    // hypersparse CSR format:
    int64_t *nonempty,      // number of rows in Ah with at least one entry
    GrB_Index *nvec,        // number of rows in Ah list
    GrB_Index **Ah,         // list of size nvec of rows that appear in A
    GrB_Index **Ap,         // row "pointers", size nvec+1
    GrB_Index **Aj,         // column indices, size nvals
    void      **Ax,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_export_HyperCSR' exports a matrix in CSR form:

\vspace{-0.05in}
{\footnotesize
\begin{verbatim}
GxB_Matrix_export_HyperCSR (&A, &type, &nrows, &ncols, &nvals, &nonempty,
                            &nvec, &Ah, &Ap, &Aj, &Ax, desc) ; \end{verbatim}}

\vspace{-0.10in}
On successful output, the \verb'GrB_Matrix A' is freed, and \verb'A' is
returned as \verb'NULL'.  Its type is returned in the \verb'type' parameter,
its dimensions in \verb'nrows' and \verb'ncols', its number of entries in
\verb'nvals', and the number of non-empty rows in \verb'nvec'.  The hypersparse
CSR format is in the four arrays \verb'Ah', \verb'Ap', \verb'Aj', and
\verb'Ax'.  If \verb'nvals' is zero, the \verb'Aj' and \verb'Ax' arrays are
returned as \verb'NULL'; this is not an error.  After a successful export, the
user application is responsible for freeing these three arrays via
\verb'free' (or the \verb'free' function passed to \verb'GxB_init').  The hypersparse CSR format is described in
Section~\ref{matrix_import_hypercsr}.

This method takes $O(1)$ time if the matrix is already in hypersparse CSR
format internally.  If it is in standard CSR form, the export must first
convert the matrix to hypersparse CSR form, taking $O(m)$ time and memory,
where $m$ = \verb'nrows'.  If the matrix is in CSC format, it is first
transposed to convert it to hypersparse CSR format, and then exported.  If in
standard CSC form, the transpose takes $O(m+n+e)$ or $O(n + e \log e)$ time and
memory, whichever is less.  If in hypersparse CSC format, it takes $O(e \log
e)$ time.

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_export_HyperCSR' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_export\_HyperCSC:} export a HyperCSC matrix}
%-------------------------------------------------------------------------------
\label{matrix_export_hypercsc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_export_HyperCSC  // export and free a hypersparse CSC matrix
(
    GrB_Matrix *A,          // handle of matrix to export and free
    GrB_Type *type,         // type of matrix exported
    GrB_Index *nrows,       // matrix dimension is nrows-by-ncols
    GrB_Index *ncols,
    GrB_Index *nvals,       // number of entries in the matrix
    // hypersparse CSC format:
    int64_t *nonempty,      // number of columns in Ah with at least one entry
    GrB_Index *nvec,        // number of columns in Ah list
    GrB_Index **Ah,         // list of size nvec of columns that appear in A
    GrB_Index **Ap,         // columns "pointers", size nvec+1
    GrB_Index **Ai,         // row indices, size nvals
    void      **Ax,         // values, size nvals
    const GrB_Descriptor desc       // currently unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_export_HyperCSC' exports a matrix in CSC form:

{\footnotesize
\begin{verbatim}
GxB_Matrix_export_HyperCSC (&A, &type, &nrows, &ncols, &nvals, &nonempty,
                            &nvec, &Ah, &Ap, &Ai, &Ax, desc) ; \end{verbatim}}

\vspace{-0.05in}
On successful output, the \verb'GrB_Matrix A' is freed, and \verb'A' is
returned as \verb'NULL'.  Its type is returned in the \verb'type' parameter,
its dimensions in \verb'nrows' and \verb'ncols', its number of entries in
\verb'nvals', and the number of non-empty rows in \verb'nvec'.  The hypersparse
CSC format is in the four arrays \verb'Ah', \verb'Ap', \verb'Ai', and
\verb'Ax'.  If \verb'nvals' is zero, the \verb'Ai' and \verb'Ax' arrays are
returned as \verb'NULL'; this is not an error.  After a successful export, the
user application is responsible for freeing these three arrays via
\verb'free' (or the \verb'free' function passed to \verb'GxB_init').  The hypersparse CSC format is described in
Section~\ref{matrix_import_hypercsc}.

This method takes $O(1)$ time if the matrix is already in hypersparse CSR
format internally.  If it is in standard CSR form, the export must first
convert the matrix to hypersparse CSR form, taking $O(m)$ time and memory,
where $m$ = \verb'nrows'.  If the matrix is in CSC format, it is first
transposed to convert it to hypersparse CSR format, and then exported.  If in
standard CSC form, the transpose takes $O(m+n+e)$ or $O(n + e \log e)$ time and
memory, whichever is less.  If in hypersparse CSC format, it takes $O(e \log
e)$ time.

\begin{spec}
{\bf SPEC:} \verb'GxB_Matrix_export_HyperCSC' is an extension to the spec.
\end{spec}

\newpage
%===============================================================================
\subsection{GraphBLAS descriptors: {\sf GrB\_Descriptor}} %=====================
%===============================================================================
\label{descriptor}

A GraphBLAS {\em descriptor} modifies the behavior of a GraphBLAS operation.
% (not a operator). 
% GraphBLAS operations are described in
% Section~\ref{operations}, and all of them have a final parameter of a
% descriptor.
If the descriptor is \verb'GrB_NULL', defaults are used.
% No GraphBLAS method (Section~\ref{objects}) is modified by a descriptor, and
% neither are any unary or binary operators.

\begin{spec}
{\bf SPEC:} \verb'GxB_DEFAULT', \verb'GxB_NTHRADS', \verb'GxB_AxB_METHOD', and \verb'GxB_AxB_*'
are extensions to the spec.
\end{spec}

The access to these parameters and their values is governed
by two \verb'enum' types, \verb'GrB_Desc_Field' and \verb'GrB_Desc_Value':

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
#define GxB_NTHREADS 5  // for both GrB_Desc_field and GxB_Option_field
typedef enum
{
    GrB_OUTP = 0,   // descriptor for output of a method
    GrB_MASK = 1,   // descriptor for the mask input of a method
    GrB_INP0 = 2,   // descriptor for the first input of a method
    GrB_INP1 = 3,   // descriptor for the second input of a method
    GxB_DESCRIPTOR_NTHREADS = GxB_NTHREADS,   // number of threads to use
    GxB_AxB_METHOD = 1000, // descriptor for selecting C=A*B algorithm
}
GrB_Desc_Field ;
\end{verbatim} } \end{mdframed}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
typedef enum
{
    // for all GrB_Descriptor fields:
    GxB_DEFAULT = 0,    // default behavior of the method
    // for GrB_OUTP only:
    GrB_REPLACE = 1,    // clear the output before assigning new values to it
    // for GrB_MASK only:
    GrB_SCMP = 2,       // use the structural complement of the input
    // for GrB_INP0 and GrB_INP1 only:
    GrB_TRAN = 3,       // use the transpose of the input

    // for GxB_AxB_METHOD only:
    GxB_AxB_GUSTAVSON = 1001,   // gather-scatter saxpy method
    GxB_AxB_HEAP      = 1002,   // heap-based saxpy method
    GxB_AxB_DOT       = 1003    // dot product
}
GrB_Desc_Value ;
\end{verbatim} } \end{mdframed}

\newpage
The internal representation is opaque to the user, but in this User Guide the
five descriptor fields of a descriptor \verb'desc' are illustrated as an array
of five items, as described in the list below.  The underlying implementation
need not be an array:

\begin{itemize}
\item \verb'desc [GrB_OUTP]' is a parameter that modifies the output of a
    GraphBLAS operation.  Currently, there are two possible settings.  In the
    default case, the output is not cleared, and ${\bf C \langle M \rangle = Z
    = C \odot T}$ is computed as-is, where ${\bf T}$ is the results of the
    particular GraphBLAS operation.

    In the non-default case, ${\bf Z = C \odot T}$ is first computed, using the
    results of ${\bf T}$ and the accumulator $\odot$.  After this is done, if
    the \verb'GrB_OUTP' descriptor field is set to \verb'GrB_REPLACE', then the
    output is cleared of its entries.  Next, the assignment ${\bf C \langle M
    \rangle = Z}$ is performed.

\item \verb'desc [GrB_MASK]' is a parameter that modifies the \verb'Mask',
    even if the mask is not present.

    If this parameter is set to its default value, and if the mask is not
    present (\verb'Mask==NULL') then implicitly \verb'Mask(i,j)=1' for all
    \verb'i' and \verb'j'.  If the mask is present then \verb'Mask(i,j)=1'
    means that \verb'C(i,j)' is to be modified by the ${\bf C \langle M \rangle
    = Z}$ update.  Otherwise, if \verb'Mask(i,j)=0', then \verb'C(i,j)' is not
    modified, even if \verb'Z(i,j)' is an entry with a different value; that
    value is simply discarded.

    If the \verb'desc [GrB_MASK]' parameter is set to \verb'GrB_SCMP', then the
    use of the mask is complemented.  In this case, if the mask is not present
    (\verb'Mask==NULL') then implicitly \verb'Mask(i,j)=0' for all \verb'i' and
    \verb'j'.  This means that none of ${\bf C}$ is modified and the entire
    computation of ${\bf Z}$ might as well have been skipped.  That is, a
    complemented empty mask means no modifications are made to the output
    object at all, except perhaps to clear it in accordance with the
    \verb'GrB_OUTP' descriptor.  With a complemented mask, if the mask is
    present then \verb'Mask(i,j)=0' means that \verb'C(i,j)' is to be modified
    by the ${\bf C \langle M \rangle = Z}$ update.  Otherwise, if
    \verb'Mask(i,j)=1', then \verb'C(i,j)' is not modified, even if
    \verb'Z(i,j)' is an entry with a different value; that value is simply
    discarded.

    Using a parameter to complement the \verb'Mask' is very useful because
    constructing the actual complement of a very sparse mask is impossible
    since it has too many entries.  If the number of places in \verb'C'
    that should be modified is very small, then use a sparse mask without
    complementing it.  If the number of places in \verb'C' that should
    be protected from modification is very small, then use a sparse mask
    to indicate those places, and use a descriptor \verb'GrB_MASK' that
    complements the use of the mask.

\item \verb'desc [GrB_INP0]' and \verb'desc [GrB_INP1]' modify the use of the
    first and second input matrices \verb'A' and \verb'B' of the GraphBLAS
    operation.

    If the \verb'desc [GrB_INP0]' is set to \verb'GrB_TRAN', then \verb'A' is
    transposed before using it in the operation.  Likewise, if
    \verb'desc [GrB_INP1]' is set to \verb'GrB_TRAN', then the second input,
    typically called \verb'B', is transposed.

    Vectors are never transposed via the descriptor.  If a method's first
    parameter is a matrix and the second a vector, then \verb'desc [GrB_INP0]'
    modifies the matrix parameter and \verb'desc [GrB_INP1]' is ignored.  If a
    method's first parameter is a vector and the second a matrix, then
    \verb'desc [GrB_INP1]' modifies the matrix parameter and
    \verb'desc [GrB_INP0]' is ignored.

    To clarify this in each function, the inputs are labeled as
    \verb'first input:' and \verb'second input:' in the function signatures.

\item \verb'desc [GxB_AxB_METHOD]' suggests the method that should be
    used to compute \verb'C=A*B'.  All the methods compute the same result,
    except they may have different floating-point roundoff errors.  This
    descriptor should be considered as a hint; SuiteSparse:GraphBLAS is
    free to ignore it.  The current version always follows the hint, however.

    \begin{itemize}

    \item \verb'GxB_DEFAULT' means that a method is selected automatically.

    \item \verb'GxB_AxB_GUSTAVSON':  an extended version of Gustavson's method
    \cite{Gustavson78}, which is a very good general-purpose method, but
    sometimes the workspace can be too large.  Assuming all matrices are stored
    by column, it computes \verb'C(:,j)=A*B(:,j)' with a sequence of {\em
    saxpy} operations (\verb'C(:,j)+=A(:,k)*B(k:,j)' for each nonzero
    \verb'B(k,j)').  It requires workspace of size $m$, to the number of rows
    of \verb'C', which is not suitable if the matrices are extremely sparse.

    \item \verb'GxB_AxB_HEAP': a heap-based method, computing
    \verb'C(:,j)=A*B(:,j)' via a heap of size equal to the maximum number of
    entries in any column of \verb'B'.  The method is very good for hypersparse
    matrices, particularly when $|{\bf B}|$ is less than the number of rows of
    \verb'C'.  The method used is similar to Algorithm II in
    \cite{BulucGilbert08} (see also \cite{BulucGilbert12}).  It computes
    \verb'C' in the same order as Gustavson's method, using a heap instead of a
    large gather/scatter workspace.  The heap has size $b$, equal to the
    maximum number of entries in any one vector of \verb'B'.

    \item \verb'GxB_AxB_DOT': computes \verb"C(i,j)=A(:,i)'*B(:,j)", for each
    entry \verb'C(i,j)'.  If the mask is present and not complemented, only
    entries for which \verb'M(i,j)=1' are computed.  This is a very specialized
    method that works well only if the mask is present, very sparse, and not
    complemented, or when \verb'C' is tiny.  For example, it works very well
    when \verb'A' and \verb'B' are tall and thin, and \verb"C<M>=A'*B" or
    \verb"C=A'*B" are computed.  It is impossibly slow if \verb'C' is large and
    the mask is not present, since it takes $\Omega(mn)$ time if \verb'C' is
    $m$-by-$n$ in that case.  It can work either without any workspace at all,
    or with workspace of size $O(k)$, where $k$ is the inner dimension (the
    number of rows of \verb'B' if the matrices are stored by column). 
    It does not need any workspace at all if \verb'A' or \verb'B' are
    completely dense, and is the fastest method in this case.  Otherwise, the
    method is faster if it has access to workspace, and thus it uses $O(k)$
    workspace if $k < (|{\bf A}|+|{\bf B}|)$.  If this condition does not hold,
    then the workspace could dominate the memory usage, so it foregoes the use
    of any workspace.  Since it uses no workspace if $k \ge (|{\bf A}|+|{\bf
    B}|)$, it can work very well for extremely sparse or hypersparse matrices,
    when the mask is present and not complemented.

    \end{itemize}

\end{itemize}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Descriptor\_new:}  create a new descriptor}
%-------------------------------------------------------------------------------
\label{descriptor_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Descriptor_new     // create a new descriptor
(
    GrB_Descriptor *descriptor  // handle of descriptor to create
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Descriptor_new' creates a new descriptor, with all fields set to
their defaults (output is not replaced, mask is not complemented, neither
input matrix is transposed, and the method used in \verb'C=A*B' is
selected automatically).

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Descriptor\_set:}  set a parameter in a descriptor}
%-------------------------------------------------------------------------------
\label{descriptor_set}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Descriptor_set     // set a parameter in a descriptor
(
    GrB_Descriptor desc,        // descriptor to modify
    const GrB_Desc_Field field, // parameter to change
    const GrB_Desc_Value val    // value to change it to
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Descriptor_set' sets a descriptor field (\verb'GrB_OUTP',
\verb'GrB_MASK', \verb'GrB_INP0', \verb'GrB_INP1', or \verb'GxB_AxB_METHOD') to
a particular value (\verb'GxB_DEFAULT', \verb'GrB_SCMP', \verb'GrB_TRAN',
\verb'GrB_REPLACE', \verb'GxB_AxB_GUSTAVSON', \verb'GxB_AxB_HEAP', or
\verb'GxB_AxB_DOT').

\vspace{0.2in}
\noindent
{\small
\begin{tabular}{|l|p{2.4in}|p{2.2in}|}
\hline
Descriptor & Default   & Non-default \\
field      & &  \\
\hline

\verb'GrB_OUTP'
    & \verb'GxB_DEFAULT':
    The output matrix is not cleared.  The operation computes
    ${\bf C \langle M \rangle = C \odot T}$.
    & \verb'GrB_REPLACE':
    After computing ${\bf Z=C\odot T}$,
    the output {\bf C} is cleared of all entries.
    Then ${\bf C \langle M \rangle = Z}$ is performed. \\

\hline

\verb'GrB_MASK'
    & \verb'GxB_DEFAULT':
    The Mask is not complemented.  \verb'Mask(i,j)=1' means the value $C_{ij}$
    can be modified by the operation, while \verb'Mask(i,j)=0' means the value
    $C_{ij}$ shall not be modified by the operation.
    & \verb'GrB_SCMP':
    The Mask is complemented.  \verb'Mask(i,j)=0' means the value $C_{ij}$
    can be modified by the operation, while \verb'Mask(i,j)=1' means the value
    $C_{ij}$ shall not be modified by the operation. \\

\hline

\verb'GrB_INP0'
    & \verb'GxB_DEFAULT':
    The first input is not transposed prior to using it in the operation.
    & \verb'GrB_TRAN':
    The first input is transposed prior to using it in the operation.  Only
    matrices are transposed, never vectors. \\

\hline

\verb'GrB_INP1'
    & \verb'GxB_DEFAULT':
    The second input is not transposed prior to using it in the operation.
    & \verb'GrB_TRAN':
    The second input is transposed prior to using it in the operation.  Only
    matrices are transposed, never vectors. \\

\hline

\verb'GrB_AxB_METHOD'
    & \verb'GxB_DEFAULT':
    The method used for computing \verb'C=A*B' is selected automatically.
    & \verb'GxB_AxB_'{\em method}: The selected method is used to compute
    \verb'C=A*B'.  \\

\hline
\end{tabular}
}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Desc\_set:}  set a parameter in a descriptor}
%-------------------------------------------------------------------------------
\label{desc_set}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Desc_set           // set a parameter in a descriptor
(
    GrB_Descriptor desc,        // descriptor to modify
    const GrB_Desc_Field field, // parameter to change
    ...                         // value to change it to
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Desc_set' is identical to \verb'GrB_Descriptor_set', except that the
type of the third parameter can vary with the field.  All descriptor fields are
currently of type \verb'GrB_Desc_Value', so currently this function is
identical in all ways to \verb'GrB_Descriptor_set', except for the name of the
function.  Future versions of this function will allow for arbitrary types of
the third parameter, depending on the field.  For a simpler-to-use alternative,
see \verb'GxB_set' described in Section~\ref{options}.

\begin{spec}
{\bf SPEC:} \verb'GxB_Desc_set' is an extension to the spec.
\end{spec}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Desc\_get:}  get a parameter from a descriptor}
%-------------------------------------------------------------------------------
\label{desc_get}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Desc_get           // get a parameter from a descriptor
(
    const GrB_Descriptor desc,  // descriptor to query; NULL means defaults
    const GrB_Desc_Field field, // parameter to query
    ...                         // value of the parameter
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Desc_get' returns the value of a single field in a descriptor.  The
type of the third parameter is a pointer to a variable type, whose type depends
on the field.  Currently, all descriptor values are of type
\verb'GrB_Desc_Value', so this third parameter is a pointer to a scalar value of
type \verb'GrB_Desc_Value'.  For a simpler-to-use alternative, see
\verb'GxB_get' described in Section~\ref{options}.

\begin{spec}
{\bf SPEC:} \verb'GxB_Desc_get' is an extension to the spec.
\end{spec}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Descriptor\_free:} free a descriptor}
%-------------------------------------------------------------------------------
\label{descriptor_free}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_free               // free a descriptor
(
    GrB_Descriptor *descriptor  // handle of descriptor to free
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Descriptor_free' frees a descriptor.
Either usage:

    {\small
    \begin{verbatim}
    GrB_Descriptor_free (&descriptor) ;
    GrB_free (&descriptor) ; \end{verbatim}}

\noindent
frees the \verb'descriptor' and sets \verb'descriptor' to \verb'NULL'.  It
safely does nothing if passed a \verb'NULL' handle, or if
\verb'descriptor == NULL' on input.

There are currently no predefined descriptors, but if these are added in the
future, this function will do nothing if passed a built-in descriptor.

\newpage
%===============================================================================
\subsection{{\sf GrB\_free:} free any GraphBLAS object} %=======================
%===============================================================================
\label{free}

Each of the nine objects has \verb'GrB_*_new' and \verb'GrB_*_free' methods
that are specific to each object.  They can also be accessed by a generic
function, \verb'GrB_free', that works for all nine objects.  If \verb'G' is any
of the nine objects, the statement

    {\footnotesize
    \begin{verbatim}
    GrB_free (&G) ; \end{verbatim} }

\noindent
frees the object and sets the variable \verb'G' to \verb'NULL'.  It is safe to
pass in a \verb'NULL' handle, or to free an object twice:

    {\footnotesize
    \begin{verbatim}
    GrB_free (NULL) ;       // SuiteSparse:GraphBLAS safely does nothing
    GrB_free (&G) ;         // the object G is freed and G set to NULL
    GrB_free (&G) ;         // SuiteSparse:GraphBLAS safely does nothing \end{verbatim} }

\noindent
However, the following sequence of operations is not safe.  The first two are
valid but the last statement will lead to undefined behavior.

    {\footnotesize
    \begin{verbatim}
    H = G ;                 // valid; creates a 2nd handle of the same object
    GrB_free (&G) ;         // valid; G is freed and set to NULL; H now undefined
    GrB_some_method (H) ;   // not valid; H is undefined \end{verbatim}}

Some objects are predefined, such as the built-in types.  If a user application
attempts to free a built-in object, SuiteSparse:GraphBLAS will safely do
nothing.  In all cases, the \verb'GrB_free' function in SuiteSparse:GraphBLAS
always returns \verb'GrB_SUCCESS'.




\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{SuiteSparse:GraphBLAS Options} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{options}

\begin{spec}
{\bf SPEC:} {\sf GxB\_set} and {\sf GxB\_get} are extensions to the
specification.
\end{spec}

SuiteSparse:GraphBLAS includes two type-generic methods, \verb'GxB_set' and
\verb'GxB_get', that set and query various options and parameters settings,
including a generic way to set values in the \verb'GrB_Descriptor' object.
Using these methods, the user application can provide hints to
SuiteSparse:GraphBLAS on how it should store and operate on its matrices.
These hints have no effect on the results of any GraphBLAS operation (except
perhaps floating-point roundoff differences), but they can have a great impact
on the amount of time or memory taken.

\begin{itemize}

\item \verb'GxB_set (field, value)' provides hints to
    SuiteSparse:GraphBLAS on how it should store all matrices created after
    calling this function:  by row, by column, and whether or not to use a {\em
    hypersparse} format \cite{BulucGilbert08,BulucGilbert12}.  These are global
    options that modify all matrices created after calling this method.

\item \verb'GxB_set (GrB_Matrix A, field, value)' provides hints to
    SuiteSparse: GraphBLAS on how to store a particular matrix.  This method
    allows SuiteSparse:GraphBLAS to transform a specific matrix from one format
    to another.  The format has no effect on the result computed by GraphBLAS;
    it only affects the time and memory taken to do the computations.

\item \verb'GxB_set (GrB_Descriptor desc, field, value)' is another way to
    set the value of a field in a \verb'GrB_Descriptor'.  It is identical to \\
    \verb'GrB_Descriptor_set', just with a generic name.  Except for
    \verb'GxB_AxB_METHOD', the descriptor settings are not hints but are always
    implemented by GraphBLAS, since they affect the results of any GraphBLAS
    operation.

\end{itemize}

The \verb'GxB_get' method queries a \verb'GrB_Descriptor', a \verb'GrB_Matrix',
or the global options.

\begin{itemize}

\item \verb'GxB_get (field, &value)' retrieves the current value of
    a global option.

\item \verb'GxB_get (GrB_Matrix A, field, &value)' retrieves the current
    value of an option from a particular matrix \verb'A'.

\item \verb'GxB_get (GrB_Descriptor desc, field, &value)' retrieves the value
    of a field in a descriptor.

\end{itemize}

%-------------------------------------------------------------------------------
\subsection{Storing a matrix by row or by column}
%-------------------------------------------------------------------------------

The GraphBLAS \verb'GrB_Matrix' is entirely opaque to the user application, and
the GraphBLAS API does not specify how the matrix should be stored.  However,
choices made in how the matrix is represented in a particular implementation,
such as SuiteSparse:GraphBLAS, can have a large impact on performance.

Many graph algorithms are just as fast in any format, but some algorithms are
much faster in one format or the other.  For example, suppose the user
application stores a directed graph as a matrix \verb'A', with the edge $(i,j)$
represented as the value \verb'A(i,j)', and the application makes many accesses
to the $i$th row of the matrix, with \verb'GrB_Col_extract'
\verb'(w,...,A,GrB_ALL,...,i,desc)' with the transposed descriptor
(\verb'GrB_INP0' set to \verb'GrB_TRAN').  If the matrix is stored by column
this can be extremely slow, just like the expression \verb'w=A(i,:)' in MATLAB,
where \verb'i' is a scalar.  Since this is a typical use-case in graph
algorithms, the default format in SuiteSparse:GraphBLAS is to store its
matrices by row, in Compressed Sparse Row format (CSR).

MATLAB stores its sparse matrices by column, in ``non-hypersparse'' format, in
what is called the Compressed Sparse Column format, or CSC for short.  An
\verb'm'-by-\verb'n' matrix in MATLAB is represented as a set of \verb'n'
column vectors, each with a sorted list of row indices and values of the
nonzero entries in that column.  As a result, \verb'w=A(:,j)' is very fast,
since the result is already held in the data structure a single list, the $j$th
column vector.  However, \verb'w=A(i,:)' is very slow in MATLAB, since every
column in the matrix has to be searched to see if it contains row \verb'i'.  In
MATLAB, if many such accesses are made, it is much better to transpose the
matrix (say \verb"AT=A'") and then use \verb"w=AT(:,i)" instead.  This can have
a dramatic impact on the performance of MATLAB.

Likewise, if \verb'u' is a very sparse column vector and \verb'A' is stored by
column, then \verb"w=u'*A" (via \verb'GrB_vxm') is slower than \verb'w=A*u'
(via \verb'GrB_mxv').  The opposite is true if the matrix is stored by row.

An example of this can be found in Section B.1 of Version 1.2 of the GraphBLAS
API Specification, where the breadth-first search \verb'BFS' uses
\verb'GrB_vxm' to compute \verb"q'=q'*A".  This method is not fast if the
matrix \verb'A' is stored by column.  The \verb'bfs5' and \verb'bfs6' examples
in the \verb'Demo/' folder of SuiteSparse:GraphBLAS use \verb'GrB_vxm',
which is fast since the matrices are assumed to be stored in their
default format, by row.

SuiteSparse:GraphBLAS stores its sparse matrices by row, by default.  In
Versions 2.1 and earlier, the matrices were stored by column, by default.
However, it can also be instructed to store any selected matrices, or all
matrices, by column instead (just like MATLAB), so that \verb'w=A(:,j)' (via
\verb'GrB_Col_extract') is very fast.  The change in data format has no effect
on the result, just the time and memory usage.  To use a column-oriented format
by default, the following can be done in a user application that tends to
access its matrices by column.

    {\footnotesize
    \begin{verbatim}
    GrB_init (...) ;
    // just after GrB_init: do the following:
    #ifdef GxB_SUITESPARSE_GRAPHBLAS
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
    #endif \end{verbatim} }

If this is done, and no other \verb'GxB_set' calls are made with
\verb'GxB_FORMAT', all matrices will be stored by column.  Alternatively,
SuiteSparse:GraphBLAS can be compiled with \verb'-DBYCOL', which changes the
default format to \verb'GxB_BY_COL', with no calls to any \verb'GxB_*'
function. {\bf NOTE: the default format is now \verb'GxB_BY_ROW' in this
release; the default in Versions 2.1 and earlier was \verb'GxB_BY_COL'.}

%-------------------------------------------------------------------------------
\subsection{Hypersparse matrices}
\label{hypersparse}
%-------------------------------------------------------------------------------

MATLAB can store an \verb'm'-by-\verb'n' matrix with a very large value of
\verb'm', since a CSC data structure takes $O(n+|{\bf A}|)$ memory, independent
of \verb'm', where $|{\bf A}|$ is the number of nonzeros in the matrix.  It
cannot store a matrix with a huge \verb'n', and this structure is also
inefficient when $|{\bf A}|$ is much smaller than \verb'n'.  In contrast,
SuiteSparse:GraphBLAS can store its matrices in {\em hypersparse} format,
taking only $O(|{\bf A}|)$ memory, independent of how it is stored (by row or
by column) and independent of both \verb'm' and \verb'n'
\cite{BulucGilbert08,BulucGilbert12}.

In both the CSR and CSC formats, the matrix is held as a set of sparse vectors.
In non-hypersparse format, the set of sparse vectors is itself dense; all
vectors are present, even if they are empty.  For example, an
\verb'm'-by-\verb'n' matrix in non-hypersparse CSC format contains \verb'n'
sparse vectors.  Each column vector takes at least one integer to represent,
even for a column with no entries.  This allows for quick lookup for a
particular vector, but the memory required is $O(n+|{\bf A}|)$.  With a
hypersparse CSC format, the set of vectors itself is sparse, and columns with
no entries take no memory at all.  The drawback of the hypersparse format is
that finding an arbitrary column vector \verb'j', such as for the computation
\verb'C=A(:,j)', takes $O(\log k)$ time if there $k \le n$ vectors in the data
structure.  One advantage of the hypersparse structure is the memory required
for an \verb'm'-by-\verb'n' hypersparse CSC matrix is only $O(|{\bf A}|)$,
independent of \verb'm' and \verb'n'.  Algorithms that must visit all non-empty
columns of a matrix are much faster when working with hypersparse matrices,
since empty columns can be skipped.

The \verb'hyper_ratio' parameter controls the hypersparsity of the internal
data structure for a matrix.  The parameter is typically in the range 0 to 1.
The default is \verb'hyper_ratio' = \verb'GxB_HYPER_DEFAULT', which is an
\verb'extern' \verb'const' \verb'double' value, currently set to 0.0625.  This
default ratio may change in the future.

The \verb'hyper_ratio' determines how the matrix is converted between the
hypersparse and non-hypersparse formats.  Let $n$ be the number of columns of a
CSC matrix, or the number of rows of a CSR matrix.  The matrix can have at most
$n$ non-empty vectors.

Let $k$ be the actual number of non-empty vectors.  That is, for the CSC
format, $k \le n$ is the number of columns that have at least one entry.  Let
$h$ be the value of \verb'hyper_ratio'.

If a matrix is currently hypersparse, it can be converted to non-hypersparse if
the either condition $n \le 1$ or $k > 2nh$ holds, or both.  Otherwise, it
stays hypersparse.  Note that if $n \le 1$ the matrix is always stored as
non-hypersparse.

If currently non-hypersparse, it can be converted to hypersparse if
both conditions $n > 1$ and $k \le nh$ hold.  Otherwise, it stays
non-hypersparse.  Note that if $n \le 1$ the matrix always remains
non-hypersparse.

The default value of \verb'hyper_ratio' is assigned at startup by
\verb'GrB_init', and can then be modified globally with \verb'GxB_set'.  All
new matrices are created with the same \verb'hyper_ratio', determined by the
global value.  Once a particular matrix \verb'A' has been constructed, its
hypersparsity ratio can be modified from the default with:

    {\footnotesize
    \begin{verbatim}
    double hyper_ratio = 0.2 ;
    GxB_set (A, GxB_HYPER, hyper_ratio) ; \end{verbatim}}

To force a matrix to always be non-hypersparse, use \verb'hyper_ratio' equal to
\verb'GxB_NEVER_HYPER'.  To force a matrix to always stay hypersparse, set
\verb'hyper_ratio' to \verb'GxB_ALWAYS_HYPER'.

A \verb'GrB_Matrix' can thus be held in one of four formats: any combination of
hyper/non-hyper and CSR/CSC.  All \verb'GrB_Vector' objects are always stored
in non-hypersparse CSC format.

A new matrix created via \verb'GrB_Matrix_new' starts with $k=0$ and is created
in hypersparse form by default unless $n \le 1$ or if $h<0$, where $h$ is the
global \verb'hyper_ratio' value.  The matrix is created in in either
\verb'GxB_BY_ROW' or \verb'GxB_BY_COL' format, as determined by the last call
to \verb'GxB_set(GxB_FORMAT,...)' or \verb'GrB_init'.

A new matrix \verb'C' created via \verb'GrB_dup (&C,A)' inherits the CSR/CSC
format, hypersparsity format, and \verb'hyper_ratio' from \verb'A'.

%-------------------------------------------------------------------------------
{\bf Parameter types:}
%-------------------------------------------------------------------------------
The \verb'GxB_Option_Field' enumerated type gives the type of the \verb'field'
parameter for the second argument of \verb'GxB_set' and \verb'GxB_get',
for setting global options or matrix options.

{\footnotesize
\begin{verbatim}
typedef enum
{
    GxB_HYPER = 0,      // defines switch to hypersparse format (double value)
    GxB_FORMAT = 1,     // defines CSR/CSC format: GxB_BY_ROW or GxB_BY_COL
    GxB_MODE = 2,       // mode passed to GrB_init (blocking or non-blocking)
    GxB_THREAD_SAFETY = 3,  // thread library for thread safety
    GxB_THREADING = 4,      // currently none (in progress)
    GxB_GLOBAL_NTHREADS = GxB_NTHREADS, // max number of threads to use
    GxB_IS_HYPER = 6     // query a matrix to see if it hypersparse or not
                         // (GxB_Matrix_Option_get only)
}
GxB_Option_Field ;
\end{verbatim} }

The \verb'GxB_FORMAT' field can be by row or by column, set to a value
with the type \verb'GxB_Format_Value':

{\footnotesize
\begin{verbatim}
typedef enum
{
    GxB_BY_ROW = 0,     // CSR: compressed sparse row format
    GxB_BY_COL = 1      // CSC: compressed sparse column format
}
GxB_Format_Value ;
\end{verbatim} }

The default format (in SuiteSparse:GraphBLAS Version 2.2 and later) is by row.
The format in SuiteSparse:GraphBLAS Version 2.1 and earlier was by column,
just like MATLAB.

The default format is given by the predefined value \verb'GxB_FORMAT_DEFAULT',
which is equal to \verb'GxB_BY_ROW' if default compile-time options are used.
To change the default at compile time to \verb'GxB_BY_COL', compile the
SuiteSparse: GraphBLAS library with \verb'-DBYCOL'.  This changes
\verb'GxB_FORMAT_DEFAULT' to \verb'GxB_BY_COL'.  The default hypersparsity
ratio is 0.0625 (1/16), but this value may change in the future.

Setting the \verb'GxB_HYPER' field to \verb'GxB_ALWAYS_HYPER' ensures a matrix
always stays hypersparse.  If set to \verb'GxB_NEVER_HYPER', it always stays
non-hypersparse.  At startup, \verb'GrB_init' defines the following initial
settings:

{\footnotesize
\begin{verbatim}
    GxB_set (GxB_HYPER, GxB_HYPER_DEFAULT) ;
    GxB_set (GxB_FORMAT, GxB_FORMAT_DEFAULT) ;
\end{verbatim} }

That is, by default, all new matrices are held by column in CSR format, unless
\verb'-DBYCOL' is used at compile time, in which case the default is to store
all new matrices by row in CSC format.  If a matrix has fewer than $n/16$
columns, it can be converted to hypersparse format.  If it has more than $n/8$
columns, it can be converted to non-hypersparse format.  These options can be
changed for all future matrices with \verb'GxB_set'.  For example, to change
all future matrices to be in non-hypersparse CSC when created, use:

{\footnotesize
\begin{verbatim}
    GxB_set (GxB_HYPER, GxB_NEVER_HYPER) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
\end{verbatim} }

Then if a particular matrix needs a different format, then (as an example):

{\footnotesize
\begin{verbatim}
    GxB_set (A, GxB_HYPER, 0.1) ;
    GxB_set (A, GxB_FORMAT, GxB_BY_ROW) ;
\end{verbatim} }

This changes the matrix \verb'A' so that it is stored by row, and it is
converted from non-hypersparse to hypersparse format if it has fewer than 10\%
non-empty columns.  If it is hypersparse, it is a candidate for conversion to
non-hypersparse if has 20\% or more non-empty columns.  If it has between 10\%
and 20\% non-empty columns, it remains in whatever format it is currently in.

MATLAB only supports a non-hypersparse CSC format.  The format in
SuiteSparse:GraphBLAS that is equivalent to the MATLAB format is given below:

{\footnotesize
\begin{verbatim}
    GrB_init (...) ;
    GxB_set (GxB_HYPER, GxB_NEVER_HYPER) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
    // no subsequent use of GxB_HYPER or GxB_FORMAT
\end{verbatim} }

The \verb'GxB_HYPER' and \verb'GxB_FORMAT' options should be considered as
suggestions from the user application as to how SuiteSparse:GraphBLAS can
obtain the best performance for a particular application.
SuiteSparse:GraphBLAS is free to ignore any of these suggestions, both now and
in the future, and the available options and formats may be augmented in the
future.  Any prior options no longer needed in future versions of
SuiteSparse:GraphBLAS will be silently ignored, so the use these options is
safe for future updates.

The hypersparse status of a matrix can be queried with the following usage:

{\footnotesize
\begin{verbatim}
    bool is_hyper ;
    GxB_get (A, GxB_IS_HYPER, &is_hyper) ;
    printf (is_hyper ? "A is hypersparse" : "A is standard sparse") ; \end{verbatim}}

%-------------------------------------------------------------------------------
\subsection{Other global options}
%-------------------------------------------------------------------------------

\verb'GxB_MODE', \verb'GxB_THREAD_SAFETY', and \verb'GxB_THREADING' can only be
queried by \verb'GxB_get'; they cannot be modified by \verb'GxB_set'.  The mode
is the value passed to \verb'GrB_init' (blocking or non-blocking).  The
\verb'GxB_THREAD*' options are returned as an \verb'enum' type with one of the
following options:

{\footnotesize
\begin{verbatim}
    typedef enum
    {
        GxB_THREAD_NONE = 0,    // no threading
        GxB_THREAD_OPENMP = 1,  // OpenMP
        GxB_THREAD_POSIX = 2,   // POSIX pthreads
        GxB_THREAD_WINDOWS = 3, // Windows threads
        GxB_THREAD_ANSI = 4     // ANSI C11 threads
    }
    GxB_Thread_Model ; \end{verbatim} }

SuiteSparse:GraphBLAS is not yet multi-threaded, but it is thread-safe if it is
compiled with OpenMP or POSIX pthreads, and if the user application threads do
not operate on the same matrices at the same time.  Output matrices and vectors
used by different threads must be different, and input matrices and vectors can
be safely used only if any pending computations on them have finished, via
\verb'GrB_wait' or the per-matrix methods, \verb'GrB_*_nvals',
\verb'GrB_*_extractElement', \verb'GrB_*_extractTuples', and reduction to a
scalar via \verb'GrB_*_reduce'.

The \verb'GxB_THREAD_SAFETY' option returns the threading model used internally
to synchronize user threads.  This is determine during installation (see
Section~\ref{sec:threads}).  Since \verb'GxB_THREAD_NONE' is zero, the
following can be used:

{\footnotesize
\begin{verbatim}
    GxB_Thread_Model safe ;
    GxB_get (GxB_THREAD_SAFETY, &safe) ;
    if (safe)
    {
        printf ("GraphBLAS is thread-safe\n") ;
    }
    else
    {
        // neither OpenMP, POSIX pthreads, nor any other threading model
        // was available at compile-time
        printf ("GraphBLAS is not thread-safe!\n") ;
    }
\end{verbatim} }

The \verb'GxB_THREADING' option currently returns \verb'GxB_THREAD_NONE', but
this will change when SuiteSparse:GraphBLAS exploits OpenMP for internal
parallelism.  In this case, the \verb'GxB_THREADING' option will return either
\verb'GxB_THREAD_NONE' (if OpenMP is not available) or \verb'GxB_THREAD_OPENMP'
otherwise.

All threads in the same user application share the same global options,
including hypersparsity and CSR/CSC format determined by \verb'GxB_set', the
blocking mode determined by \verb'GrB_init', and the threading options.
Specific format and hypersparsity parameters of each matrix are specific to
that matrix and can be independently changed.

\newpage
%===============================================================================
\subsection{{\sf GxB\_Global\_Option\_set:} set a global option}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_set                    // set a global default option
(
    const GxB_Option_Field field,   // option to change
    ...                             // value to change it to
) ;
\end{verbatim} } \end{mdframed}

This usage of \verb'GxB_set' sets the value of a global option.
The \verb'field' parameter can be \verb'GxB_HYPER' or \verb'GxB_FORMAT'.

For example, the following usage sets the global hypersparsity ratio to 0.2,
and the format of future matrices to \verb'GxB_BY_COL'. 
No existing matrices are changed.

{\footnotesize
\begin{verbatim}
    GxB_set (GxB_HYPER, 0.2) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
\end{verbatim} }

%===============================================================================
\subsection{{\sf GxB\_Matrix\_Option\_set:} set a matrix option}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_set                    // set an option in a matrix
(
    GrB_Matrix A,                   // matrix to modify
    const GxB_Option_Field field,   // option to change
    ...                             // value to change it to
) ;
\end{verbatim} } \end{mdframed}

This usage of \verb'GxB_set' sets the value of a matrix option, for a
particular matrix.
The \verb'field' parameter can be \verb'GxB_HYPER' or \verb'GxB_FORMAT'.

For example, the following usage sets the hypersparsity
ratio to 0.2, and the format of \verb'GxB_BY_COL', for a particular matrix
\verb'A'.  SuiteSparse:GraphBLAS currently applies these changes immediately,
but since they are simply hints, future versions of SuiteSparse:GraphBLAS may
delay the change in format if it can obtain better performance.

For performance, the matrix option should be set as soon as it is created with
\verb'GrB_Matrix_new', so the internal transformation takes less time.

{\footnotesize
\begin{verbatim}
    GxB_set (A, GxB_HYPER, 0.2) ;
    GxB_set (A, GxB_FORMAT, GxB_BY_COL) ;
\end{verbatim} }

\newpage
%===============================================================================
\subsection{{\sf GxB\_Desc\_set:} set a {\sf GrB\_Descriptor} value}
%===============================================================================
\label{gxbset}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_set                // set a parameter in a descriptor
(
    GrB_Descriptor desc,        // descriptor to modify
    const GrB_Desc_Field field, // parameter to change
    ...                         // value to change it to
) ;
\end{verbatim} } \end{mdframed}

This usage is identical to \verb'GrB_Descriptor_set', just with a name that is
consistent with the other usages of this generic function.  Unlike
\verb'GrB_Descriptor_set', Future versions of \verb'GxB_Desc_set' will allow
for different types for the third parameter.  Refer to
Sections~\ref{descriptor_set}~and~\ref{desc_set} for details.

%===============================================================================
\subsection{{\sf GxB\_Global\_Option\_get:} retrieve a global option}
%===============================================================================
\label{gxbget}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_get                    // gets the current global default option
(
    const GxB_Option_Field field,   // option to query
    ...                             // return value of the global option
) ;
\end{verbatim} } \end{mdframed}

This usage of \verb'GxB_get' retrieves the value of a global option.  The
\verb'field' parameter can be \verb'GxB_HYPER', \verb'GxB_FORMAT'.
\verb'GxB_MODE', \verb'GxB_THREAD_SAFETY', or \verb'GxB_THREADING'.  For
example:

{\footnotesize
\begin{verbatim}
    double h ;
    GxB_get (GxB_HYPER, &h) ;
    printf ("hyper_ratio = %g for all new matrices\n", h) ;

    GxB_Format_Value s ;
    GxB_get (GxB_FORMAT, &s) ;
    if (s == GxB_BY_COL) printf ("all new matrices are stored by column\n") :
    else printf ("all new matrices are stored by row\n") ;

    GrB_mode mode ;
    GxB_get (GxB_MODE, &mode) ;
    if (mode == GrB_BLOCKING) printf ("GrB_init(GrB_BLOCKING) was called.\n") :
    else printf ("GrB_init(GrB_NONBLOCK) was called.\n") ;

    // see Demo/Program/pthread_demo.c and openmp_demo.c for examples:
    GxB_Threading_Model thread_safety, threading ;
    GxB_get (GxB_THREAD_SAFETY, &thread_safey) ;
    GxB_get (GxB_THREADING, &threading) ; \end{verbatim} }

\newpage
%===============================================================================
\subsection{{\sf GxB\_Matrix\_Option\_get:} retrieve a matrix option}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_get                    // gets the current option of a matrix
(
    const GrB_Matrix A,             // matrix to query
    const GxB_Option_Field field,   // option to query
    ...                             // return value of the matrix option
) ;
\end{verbatim} } \end{mdframed}

This usage of \verb'GxB_get' retrieves the value of a matrix option.
The \verb'field' parameter can be \verb'GxB_HYPER' or \verb'GxB_FORMAT'.
For example:

{\footnotesize
\begin{verbatim}
    double h ;
    GxB_get (A, GxB_HYPER, &h) ;
    printf ("matrix A has hyper_ratio = %g\n", h) ;

    GxB_Format_Value s ;
    GxB_get (A, GxB_FORMAT, &s) ;
    if (s == GxB_BY_COL) printf ("matrix A is stored by column\n") :
    else printf ("matrix A is stored by row\n") ; \end{verbatim} }

%===============================================================================
\subsection{{\sf GxB\_Desc\_get:} retrieve a {\sf GrB\_Descriptor} value}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_get                // get a parameter from a descriptor
(
    const GrB_Descriptor desc,  // descriptor to query; NULL means defaults
    const GrB_Desc_Field field, // parameter to query
    ...                         // value of the parameter
) ;
\end{verbatim} } \end{mdframed}

This usage is the same as \verb'GxB_Desc_get'.  The \verb'field' parameter can
be \verb'GrB_OUTP', \verb'GrB_MASK', \verb'GrB_INP0', \verb'GrB_INP1' or
\verb'GxB_AxB_METHOD'.  Refer to Section~\ref{desc_get} for details.

%===============================================================================
\newpage
\subsection{Summary of usage of {\sf GxB\_set} and {\sf GxB\_get}}
%===============================================================================

The different usages of \verb'GxB_set' and \verb'GxB_get' are summarized below.

\noindent
To set/get the global options:

    {\footnotesize
    \begin{verbatim}
    GxB_set (GxB_HYPER, double h) ;
    GxB_set (GxB_HYPER, GxB_ALWAYS_HYPER) ;
    GxB_set (GxB_HYPER, GxB_NEVER_HYPER) ;
    GxB_get (GxB_HYPER, double *h) ;

    GxB_set (GxB_FORMAT, GxB_BY_ROW) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
    GxB_get (GxB_FORMAT, GxB_Format_Value *s) ; \end{verbatim} }

\noindent
To get global options that can be queried but not modified:

    {\footnotesize
    \begin{verbatim}
    GxB_get (GxB_MODE,          GrB_Mode *mode) ;
    GxB_get (GxB_THREAD_SAFETY, GxB_Thread_Model *thread_safety) ;
    GxB_get (GxB_THREADING,     GxB_Thread_Model *threading) ; \end{verbatim} }

\noindent
To set/get a matrix option:

    {\footnotesize
    \begin{verbatim}
    GxB_set (GrB_Matrix A, GxB_HYPER, double h) ;
    GxB_set (GrB_Matrix A, GxB_HYPER, GxB_ALWAYS_HYPER) ;
    GxB_set (GrB_Matrix A, GxB_HYPER, GxB_NEVER_HYPER) ;
    GxB_get (GrB_Matrix A, GxB_HYPER, double *h) ;

    GxB_set (GrB_Matrix A, GxB_FORMAT, GxB_BY_ROW) ;
    GxB_set (GrB_Matrix A, GxB_FORMAT, GxB_BY_COL) ;
    GxB_get (GrB_Matrix A, GxB_FORMAT, GxB_Format_Value *s) ; \end{verbatim} }

\noindent
To get the hypersparse status of a matrix:

    {\footnotesize
    \begin{verbatim}
    GxB_get (GrB_Matrix A, GxB_IS_HYPER, bool *is_hyper) ; \end{verbatim} }

\noindent
To set/get a descriptor field:

    {\footnotesize
    \begin{verbatim}
    GxB_set (GrB_Descriptor d, GrB_OUTP, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GrB_OUTP, GrB_REPLACE) ;

    GxB_set (GrB_Descriptor d, GrB_MASK, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GrB_MASK, GrB_SCMP) ;

    GxB_set (GrB_Descriptor d, GrB_INP0, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GrB_INP0, GrB_TRAN) ;

    GxB_set (GrB_Descriptor d, GrB_INP1, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GrB_INP1, GrB_TRAN);

    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_GUSTAVSON) ;
    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_HEAP) ;
    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_DOT) ;

    GxB_get (GrB_Descriptor d, GrB_Desc_Field f, GrB_Desc_Value *v) ; \end{verbatim} }

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{SuiteSparse:GraphBLAS Colon and Index Notation} %%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{colon}

MATLAB uses a colon notation to index into matrices, such as
\verb'C=A(2:4,3:8)', which extracts \verb'C' as 3-by-6 submatrix from \verb'A',
from rows 2 through 4 and columns 3 to 8 of the matrix \verb'A'.  A single
colon is used to denote all rows, \verb'C=A(:,9)', or all columns,
\verb'C=A(12,:)', which refers to the 9th column and 12th row of \verb'A',
respectively.  An arbitrary integer list can be given as well, such as the
MATLAB statements:

    {\footnotesize
    \begin{verbatim}
    I = [2 1 4] ;
    J = [3 5] ;
    C = A (I,J) ; \end{verbatim} }
\noindent
which creates the 3-by-2 matrix \verb'C' as follows:
\[
C =
\left[
\begin{array}{cc}
a_{2,3} & a_{2,5} \\
a_{1,3} & a_{1,5} \\
a_{4,3} & a_{4,5} \\
\end{array}
\right]
\]

The GraphBLAS API can do the equivalent of \verb'C=A(I,J)',
\verb'C=A(:,J)', \verb'C=A(I,:)', and \verb'C=A(:,:)', by passing a parameter
\verb'const GrB_Index *I' as either an array of size \verb'ni', or as the
special value \verb'GrB_ALL', which corresponds to the stand-alone colon
\verb'C=A(:,J)', and the same can be done for \verb'J'..  To compute
\verb'C=A(2:4,3:8)' in GraphBLAS requires the user application to create two
explicit integer arrays \verb'I' and \verb'J' of size 3 and 5, respectively,
and then fill them with the explicit values \verb'[2,3,4]' and
\verb'[3,4,5,6,7,8]'.  This works well if the lists are small, or if the matrix
has more entries than rows or columns.

However, particularly with hypersparse matrices, the size of the explicit
arrays \verb'I' and \verb'J' can vastly exceed the number of entries in the
matrix.  When using its hypersparse format, SuiteSparse:GraphBLAS allows the
user application to create a \verb'GrB_Matrix' with dimensions up to $2^{60}$,
with no memory constraints.  The only constraint on memory usage in a
hypersparse matrix is the number of entries in the matrix.

For example, creating a $n$-by-$n$ matrix \verb'A' of type \verb'GrB_FP64' with
$n=2^{60}$ and one million entries is trivial to do in Version 2.1 (and later)
of SuiteSparse:GraphBLAS, taking at most 24MB of space.  SuiteSparse:GraphBLAS
Version 2.1 (or later) could do this on an old smartphone.  However, using just
the pure GraphBLAS API, constructing \verb'C=A(0:(n/2),0:(n/2))'
in SuiteSparse Version 2.0 would require the creation of an integer array
\verb'I' of size $2^{59}$, containing the sequence 0, 1, 2, 3, ...., requiring
about 4 ExaBytes of memory (4 million terabytes).  This is roughly 1000 times
larger than the memory size of the world's largest computer in 2018.

SuiteSparse:GraphBLAS Version 2.1 and later extends the GraphBLAS API with a
full implementation of the MATLAB colon notation for integers,
\verb'I=begin:inc:end'.  This extension allows the construction of the matrix
\verb'C=A(0:(n/2),0:(n/2))' in this example, with dimension $2^{59}$, probably
taking just milliseconds on an old smartphone.

The \verb'GrB_extract', \verb'GrB_assign', and \verb'GrB_subassign' operations
(described in the Section~\ref{operations}) each have parameters that define a
list of integer indices, using two parameters:

    {\footnotesize
    \begin{verbatim}
    const GrB_Index *I ;    // an array, or a special value GrB_ALL
    GrB_Index ni ;          // the size of I, or a special value \end{verbatim}}

These two parameters define five kinds of index lists, which can be used to
specify either an explicit or implicit list of row indices and/or column
indices.  The length of the list of indices is denoted \verb'|I|'.  This
discussion applies equally to the row indices \verb'I' and the column indices
\verb'J'.  The five kinds are listed below.

\begin{enumerate}
\item
    An explicit list of indices, such as \verb'I = [2 1 4 7 2]' in MATLAB
    notation, is handled by passing in \verb'I' as a pointer to an array of
    size 5, and passing \verb'ni=5' as the size of the list.
    The length of the explicit list is \verb'ni=|I|'.
    Duplicates may appear.

\item To specify all rows of a matrix, use \verb'I = GrB_ALL'.  The
    parameter \verb'ni' is ignored.  This is equivalent to \verb'C=A(:,J)'
    in MATLAB.  In GraphBLAS, this is the sequence \verb'0:(m-1)' if \verb'A'
    has \verb'm' rows, with length \verb'|I|=m'.  If \verb'J' is used the
    columns of an \verb'm'-by-\verb'n' matrix, then \verb'J=GrB_ALL' refers to
    all columns, and is the sequence \verb'0:(n-1)', of length \verb'|J|=n'.

\item To specify a contiguous range of indices, such as \verb'I=10:20'
    in MATLAB, the array \verb'I' has size 2, and \verb'ni' is passed to
    SuiteSparse:GraphBLAS as the special value \verb'ni = GxB_RANGE'.  The
    beginning index is \verb'I[GxB_BEGIN]' and the ending index is
    \verb'I[GxB_END]'.   Both values must be non-negative since
    \verb'GrB_Index' is an unsigned integer (\verb'uint64_t').  The value of
    \verb'I[GxB_INC]' is ignored.

    {\footnotesize
    \begin{verbatim}
    // to specify I = 10:20
    GrB_Index I [2], ni = GxB_RANGE ;
    I [GxB_BEGIN] = 10 ;      // the start of the sequence
    I [GxB_END  ] = 20 ;      // the end of the sequence \end{verbatim}}

    Let $b$ = \verb'I[GxB_BEGIN]', let $e$ = \verb'I[GxB_END]',
    The sequence has length zero if $b > e$; otherwise the length is
    $|I| = (e-b) + 1$.

\item To specify a strided range of indices with a non-negative stride,
    such as \verb'I=3:2:10', the array \verb'I' has size 3, and \verb'ni' has
    the special value \verb'GxB_STRIDE'.  This is the sequence 3, 5, 7, 9, of
    length 4.  Note that 10 does not appear in the list.  The end point need
    not appear if the increment goes past it.

    {\footnotesize
    \begin{verbatim}
    // to specify I = 3:2:10
    GrB_Index I [3], ni = GxB_STRIDE ;
    I [GxB_BEGIN ] = 3 ;      // the start of the sequence
    I [GxB_INC   ] = 2 ;      // the increment
    I [GxB_END   ] = 10 ;     // the end of the sequence \end{verbatim}}

    The \verb'GxB_STRIDE' sequence is the same as the \verb'List' generated by
    the following for loop:

    {\footnotesize
    \begin{verbatim}
    int64_t k = 0 ;
    GrB_Index *List = (a pointer to an array of large enough size)
    for (int64_t i = I [GxB_BEGIN] ; i <= I [GxB_END] ; i += I [GxB_INC])
    {
        // i is the kth entry in the sequence
        List [k++] = i ;
    } \end{verbatim}}

    Then passing the explicit array \verb'List' and its length \verb'ni=k' has
    the same effect as passing in the array \verb'I' of size 3, with
    \verb'ni=GxB_STRIDE'.  The latter is simply much faster to produce, and
    much more efficient for SuiteSparse:GraphBLAS to process.

    Let $b$ = \verb'I[GxB_BEGIN]', let $e$ = \verb'I[GxB_END]', and let
    $\Delta$ = \verb'I[GxB_INC]'.  The sequence has length zero if $b > e$ or
    $\Delta=0$.  Otherwise, the length of the sequence is
    \[
    |I| = \Bigl\lfloor\dfrac{e-b}{\Delta}\Bigr\rfloor + 1
    \]

\item
    In MATLAB notation, if the stride is negative, the sequence is decreasing.
    For example, \verb'10:-2:1' is the sequence 10, 8, 6, 4, 2, in that order.
    In SuiteSparse:GraphBLAS, use \verb'ni = GxB_BACKWARDS', with an array
    \verb'I' of size 3.  The following example specifies defines the equivalent
    of the MATLAB expression \verb'10:-2:1' in SuiteSparse:GraphBLAS:

    \vspace{-0.1in}
    {\footnotesize
    \begin{verbatim}
    // to specify I = 10:-2:1
    GrB_Index I [3], ni = GxB_BACKWARDS ;
    I [GxB_BEGIN ] = 10 ;     // the start of the sequence
    I [GxB_INC   ] = 2 ;      // the magnitude of the increment
    I [GxB_END   ] = 1 ;      // the end of the sequence \end{verbatim}}

    \vspace{-0.1in}
    The value -2 cannot be assigned to the \verb'GrB_Index' array \verb'I',
    since that is an unsigned type.  The signed increment is represented
    instead with the special value \verb'ni = GxB_BACKWARDS'.
    The \verb'GxB_BACKWARDS' sequence is the same as generated by the following
    for loop:

    \vspace{-0.1in}
    {\footnotesize
    \begin{verbatim}
    int64_t k = 0 ;
    GrB_Index *List = (a pointer to an array of large enough size)
    for (int64_t i = I [GxB_BEGIN] ; i >= I [GxB_END] ; i -= I [GxB_INC])
    {
        // i is the kth entry in the sequence
        List [k++] = i ;
    } \end{verbatim}}

    \vspace{-0.1in}
    Let $b$ = \verb'I[GxB_BEGIN]', let $e$ = \verb'I[GxB_END]', and let
    $\Delta$ = \verb'I[GxB_INC]' (note that $\Delta$ is not negative).  The
    sequence has length zero if $b < e$ or $\Delta=0$.  Otherwise, the length
    of the sequence is
    \[
    |I| = \Bigl\lfloor\dfrac{b-e}{\Delta}\Bigr\rfloor + 1
    \]

\end{enumerate}

Since \verb'GrB_Index' is an unsigned integer, all three values
\verb'I[GxB_BEGIN]', \verb'I[GxB_INC]', and \verb'I[GxB_END]' must
be non-negative.

Just as in MATLAB, it is valid to specify an empty sequence of length zero.
For example, \verb'I = 5:3' has length zero in MATLAB and the same is
true for a \verb'GxB_RANGE' sequence in SuiteSparse:GraphBLAS, with
\verb'I[GxB_BEGIN]=5' and \verb'I[GxB_END]=3'.  This has the same
effect as array \verb'I' with \verb'ni=0'.

\begin{spec}
{\bf SPEC:} \verb'GxB_RANGE', \verb'GxB_STRIDE', and \verb'GxB_BACKWARDS'
are extensions to the specification.
\end{spec}

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{GraphBLAS Operations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{operations}

The next sections define each of the GraphBLAS operations, also listed in the
table below.  SuiteSparse:GraphBLAS extensions (\verb'GxB_subassign',
\verb'GxB_select' and \verb'GxB_kron') are included in the table.

\vspace{0.2in}
{\small
\begin{tabular}{lll}
\hline
\verb'GrB_mxm'       & matrix-matrix multiply  & ${\bf C \langle M \rangle = C \odot AB}$ \\
\verb'GrB_vxm'       & vector-matrix multiply  & ${\bf w^{\sf T}\langle m^{\sf T}\rangle = w^{\sf T}\odot u^{\sf T}A}$ \\
\verb'GrB_mxv'       & matrix-vector multiply  & ${\bf w \langle m \rangle = w \odot Au}$ \\
\hline
\verb'GrB_eWiseMult' & element-wise,           & ${\bf C \langle M \rangle = C \odot (A \otimes B)}$ \\
                     & set union               & ${\bf w \langle m \rangle = w \odot (u \otimes v)}$ \\
\hline
\verb'GrB_eWiseAdd'  & element-wise,           & ${\bf C \langle M \rangle = C \odot (A \oplus  B)}$ \\
                     & set intersection        & ${\bf w \langle m \rangle = w \odot (u \oplus  v)}$ \\
\hline
\verb'GrB_extract'   & extract submatrix       & ${\bf C \langle M \rangle = C \odot A(I,J)}$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot u(i)}$ \\
\hline
\verb'GxB_subassign' & assign submatrix,       & ${\bf C (I,J) \langle M \rangle = C(I,J) \odot A}$ \\
                     & with submask for ${\bf C(I,J)}$
                                               & ${\bf w (i)   \langle m \rangle = w(i)   \odot u}$ \\
\hline
\verb'GrB_assign'    & assign submatrix        & ${\bf C \langle M \rangle (I,J) = C(I,J) \odot A}$ \\
                     & with submask for ${\bf C}$
                                               & ${\bf w \langle m \rangle (i)   = w(i)   \odot u}$ \\
\hline
\verb'GrB_apply'     & apply unary operator    & ${\bf C \langle M \rangle = C \odot} f{\bf (A)}$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f{\bf (u)}$ \\
\hline
\verb'GxB_select'    & apply select operator   & ${\bf C \langle M \rangle = C \odot} f{\bf (A,k)}$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f{\bf (u,k)}$ \\
\hline
\verb'GrB_reduce'    & reduce to vector        & ${\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]$ \\
                     & reduce to scalar        & $s = s \odot [{\oplus}_{ij}  {\bf A}(I,J)]$ \\
\hline
\verb'GrB_transpose' & transpose               & ${\bf C \langle M \rangle = C \odot A^{\sf T}}$ \\
\hline
\verb'GxB_kron'      & Kronecker product       & ${\bf C \langle M \rangle = C \odot \mbox{kron}(A, B)}$ \\
\hline
\end{tabular}
}
\vspace{0.2in}




\newpage
%===============================================================================
\subsection{The GraphBLAS specification in {MATLAB}} %==========================
%===============================================================================
\label{spec}

SuiteSparse:GraphBLAS includes a MATLAB implementation of nearly the entire
GraphBLAS specification, including all built-in types and operators.  The
typecasting rules and integer operator rules from GraphBLAS are implemented in
MATLAB via \verb'mexFunctions' that call the GraphBLAS routines in C.  All
other functions are written purely in MATLAB \verb'M'-files, and are given
names of the form \verb'GB_spec_*'.  All of these MATLAB interfaces and
\verb'M'-file functions they are provided in the software distribution of
SuiteSparse:GraphBLAS.  The purpose of this is two-fold:

\begin{itemize}

\item {\bf Illustration and documentation:}  MATLAB is so expressive, and so
    beautiful to read and write, that the \verb'GB_spec_*' functions read
    almost like the exact specifications from the GraphBLAS API.
    Excerpts and condensed versions of these functions have
    already been used to this point in the User Guide, such as
    Figure~\ref{fig_accummask}, and the subsequent sections rely on them as
    well.  This is why the discussion here is not just relegated to an Appendix
    on testing; the reader can benefit from studying the \verb'GB_spec_*'
    functions to understand what a GraphBLAS operation is computing.  For
    example, \verb'GrB_mxm' (Section~\ref{mxm}) includes a condensed and
    simplified version of \verb'GB_spec_mxm'.

\item {\bf Testing:} Testing the C interface to SuiteSparse:GraphBLAS is a
    significant challenge since it supports so many different kinds of
    operations on a vast range of semirings.  It is difficult to tell from
    looking at the result from a C function in GraphBLAS if the result is
    correct.  Thus, each function has been written twice: once in a
    highly-optimized function in C, and again in a simple and elegant MATLAB
    function.  The latter is almost a direct translation of all the mathematics
    behind the GraphBLAS API, so it is much easier to visually
    inspect the \verb'GB_spec_*' version in MATLAB to ensure the correct
    mathematics are being computed.

\end{itemize}

The following functions are included in the SuiteSparse:GraphBLAS software
distribution.  Each has a name of the form \verb'GB_spec_*', and each of them
is a ``mimic'' of a corresponding C function in GraphBLAS.  Not all functions
in the C API have a corresponding mimic; in particular, many of the vector
functions can be computed directly with the corresponding matrix version in the
MATLAB implementations.  A list of these files is shown below:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
MATLAB \verb'GB_spec' function          & corresponding GraphBLAS           & Section \\
                                        & function or  method               & \\
\hline
\verb'GB_spec_accum.m'                  & ${\bf Z = C \odot T}$                     & \ref{accummask} \\
\verb'GB_spec_mask.m'                   & ${\bf C \langle M \rangle = Z}$           & \ref{accummask} \\
\verb'GB_spec_accum_mask.m'             & ${\bf C \langle M \rangle = C \odot T}$   & \ref{accummask} \\
\hline
\verb'GB_spec_Vector_extractElement.m'  & \verb'GrB_Vector_extractElement'  & \ref{vector_extractElement} \\
\hline
\verb'GB_spec_build.m'                  & \verb'GrB_Matrix_build'           & \ref{matrix_build} \\
\verb'GB_spec_Matrix_extractElement.m'  & \verb'GrB_Matrix_extractElement'  & \ref{matrix_extractElement} \\
\verb'GB_spec_extractTuples.m'          & \verb'GrB_Matrix_extractTuples'   & \ref{matrix_extractTuples} \\
\hline
\verb'GB_spec_mxm.m'                    & \verb'GrB_mxm'                    & \ref{mxm} \\
\verb'GB_spec_vxm.m'                    & \verb'GrB_vxm'                    & \ref{vxm} \\
\verb'GB_spec_mxv.m'                    & \verb'GrB_mxv'                    & \ref{mxv} \\
\hline
\verb'GB_spec_eWiseMult_Vector.m'       & \verb'GrB_eWiseMult_Vector'       & \ref{eWiseMult} \\
\verb'GB_spec_eWiseMult_Matrix.m'       & \verb'GrB_eWiseMult_Matrix'       & \ref{eWiseMult} \\
\verb'GB_spec_eWiseAdd_Vector.m'        & \verb'GrB_eWiseAdd_Vector'        & \ref{eWiseAdd} \\
\verb'GB_spec_eWiseAdd_Matrix.m'        & \verb'GrB_eWiseAdd_Matrix'        & \ref{eWiseAdd} \\
\hline
\verb'GB_spec_Vector_extract.m'         & \verb'GrB_Vector_extract'         & \ref{extract_vector} \\
\verb'GB_spec_Matrix_extract.m'         & \verb'GrB_Matrix_extract'         & \ref{extract_matrix} \\
\verb'GB_spec_Col_extract.m'            & \verb'GrB_Col_extract'            & \ref{extract_column} \\
\hline
\verb'GB_spec_subassign.m'              & \verb'GxB_subassign'              & \ref{subassign} \\
\verb'GB_spec_assign.m'                 & \verb'GrB_assign'                 & \ref{assign} \\
\hline
\verb'GB_spec_apply.m'                  & \verb'GrB_apply'                  & \ref{apply} \\
\hline
\verb'GB_spec_select.m'                 & \verb'GxB_select'                 & \ref{select} \\
\hline
\verb'GB_spec_reduce_to_vector.m'       & \verb'GrB_reduce' (to vector)     & \ref{reduce_to_vector} \\
\verb'GB_spec_reduce_to_scalar.m'       & \verb'GrB_reduce' (to scalar)     & \ref{reduce_matrix_to_scalar} \\
\hline
\verb'GB_spec_transpose.m'              & \verb'GrB_transpose'              & \ref{transpose} \\
\hline
\verb'GB_spec_kron.m'                   & \verb'GxB_kron'                   & \ref{kron} \\
\hline
\end{tabular}
}
\vspace{0.2in}

Additional files are included for creating test problems and providing
inputs to the above files, or supporting functions:

\vspace{0.1in}
{\footnotesize
\begin{tabular}{ll}
MATLAB \verb'GB_spec' function  & purpose \\
\hline
\verb'GB_spec_compare.m'        & Compares output of C and MATLAB functions \\
\verb'GB_spec_random.m'         & Generates a random matrix \\
\verb'GB_spec_op.m'             & MATLAB mimic of built-in operators \\
\verb'GB_spec_operator.m'       & Like \verb'GrB_*Op_new' \\
\verb'GB_spec_opsall.m'         & List operators, types, and semirings \\
\verb'GB_spec_semiring.m'       & Like \verb'GrB_Semiring_new' \\
\verb'GB_spec_descriptor.m'     & mimics a GraphBLAS descriptor \\
\verb'GB_spec_identity.m'       & returns the identity of a monoid \\
\verb'GB_spec_matrix.m'         & conforms a MATLAB sparse matrix to GraphBLAS \\
\verb'GB_define*.m'             & creates draft of \verb'GraphBLAS.h' \\
\hline
\end{tabular}
}

\newpage
An intensive test suite has been written that generates test graphs in MATLAB,
then computes the result in both the C version of the SuiteSparse:GraphBLAS and
in the MATLAB \verb'GB_spec_*' functions.  Each C function in GraphBLAS has
a direct \verb'mexFunction' interface that allow the test suite in MATLAB
to call both functions.

This approach has its limitations:

\begin{itemize}
\item {\bf matrix classes:} MATLAB only supports sparse double, sparse double
    complex, and sparse logical matrices.  MATLAB can represent dense matrices
    in all eleven built-in GraphBLAS data types, so in all these specification
    \verb'M'-files, the matrices are either in dense format in the
    corresponding MATLAB class, or they are held as sparse double or sparse
    logical, and the actual GraphBLAS type is held with it as a string member
    of a MATLAB \verb'struct'.  To ensure the correct typecasting is computed,
    most of the MATLAB scripts work on dense matrices, not sparse ones.  As a
    result, the MATLAB \verb'GB_spec_*' function are not meant for production
    use, but just for testing and illustration.

\item {\bf integer operations:}  MATLAB and GraphBLAS handle integer operations
    differently.  In MATLAB, an integer result outside the range of the integer
    is set to maximum or minimum integer.  For example, \verb'int8(127)+1' is
    \verb'127'.  This is useful for many computations such as image processing,
    but GraphBLAS follows the C rules instead, where integer values wrap,
    modulo style.  For example, in GraphBLAS and in C, incrementing
    \verb'(int8_t) 127' by one results in \verb'-128'.  Of course, an
    alternative would be for a MATLAB interface to create its own integer
    operators, each of which would follow the MATLAB integer rules of
    arithmetic.  However, this would obscure the purpose of these
    \verb'GB_spec_*' and \verb'GB_mex_*' test functions, which is to test the C
    API of GraphBLAS.  When the \verb'GB_spec_*' functions need to perform
    integer computations and typecasting, they call GraphBLAS to do the work,
    instead doing the work in MATLAB.  This ensures that the \verb'GB_spec_*'
    functions obtain the same results as their GraphBLAS counterparts.

\item {\bf elegance:}  to simplify testing, each MATLAB \verb'mexFunction'
    interface a GraphBLAS function is a direct translation of the C API.  For
    example, \verb'GB_mex_mxm' is a direct interface to the GraphBLAS
    \verb'GrB_mxm', even down the order of parameters.  This approach
    abandons some of the potential features of MATLAB for creating elegant
    \verb'M'-file interfaces in a highly usable form, such as the ability to
    provide fewer parameters when optional parameters are not in use.  These
    \verb'mexFunctions', as written, are not meant to be usable in a user
    application.  They are not highly documented.  They are meant to be fast,
    and direct, to accomplish the goal of testing SuiteSparse:GraphBLAS in
    MATLAB and comparing their results with the corresponding \verb'GB_spec_*'
    function.  They are not recommended for use in general applications in
    MATLAB.

\item {\bf generality:} the MATLAB \verb'mexFunction' interface needs to
    test the C API directly, so it must access content of SuiteSparse:GraphBLAS
    objects that are normally opaque to an end user application.  As a result,
    these \verb'mexFunctions' do not serve as a general interface to any
    conforming GraphBLAS implementation, but only to SuiteSparse:GraphBLAS.

\end{itemize}

In the MATLAB mimic functions, \verb'GB_spec_*', a GraphBLAS matrix \verb'A' is
represented as a MATLAB \verb'struct' with the following components:

\begin{itemize}
\item \verb'A.matrix':  the values of the matrix.  If \verb'A.matrix' is a
    sparse double matrix, it holds a typecasted copy of the values of a
    GraphBLAS matrix, unless the GraphBLAS matrix is also double
    (\verb'GrB_FP64').

\item \verb'A.pattern': a logical matrix holding the pattern;
    \verb'A.pattern(i,j)=true' if \verb'(i,j)' is in the pattern of \verb'A',
    and \verb'false' otherwise.

\item \verb'A.class': the MATLAB class of the matrix corresponding to one of
    the eleven built-in types.  Normally this is simply \verb'class(A.matrix)'.

\item \verb'A.values': most of the GraphBLAS test \verb'mexFunctions' return
    their result as a MATLAB sparse matrix, in the \verb'double' class.  This
    works well for all types except for the 64-bit integer types, since a
    double has about 54 bits of mantissa which is less than the 64 bits
    available in a long integer.  To ensure no bits are lots, these values are
    also returned as a vector.  This enables \verb'GB_spec_compare' to ensure
    the test results are identical down to the very last bit, and not just to
    within roundoff error.  Nearly all tests, even in double precision, check
    for perfect equality, not just for results accurate to within round-off
    error.

\end{itemize}

\newpage
%===============================================================================
\subsection{{\sf GrB\_mxm:} matrix-matrix multiply} %===========================
%===============================================================================
\label{mxm}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_mxm                    // C<Mask> = accum (C, A*B)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const GrB_Semiring semiring,    // defines '+' and '*' for A*B
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Matrix B,             // second input: matrix B
    const GrB_Descriptor desc       // descriptor for C, Mask, A, and B
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_mxm' multiplies two sparse matrices \verb'A' and \verb'B' using the
\verb'semiring'.  The input matrices \verb'A' and \verb'B' may be transposed
according to the descriptor, \verb'desc' (which may be \verb'NULL') and then
typecasted to match the multiply operator of the \verb'semiring'.  Next,
\verb'T=A*B' is computed on the \verb'semiring', precisely defined in the
\verb'GB_spec_mxm.m' script.  The actual algorithm exploits sparsity and does
not take $O(n^3)$ time, but what computes is the following: 

{\footnotesize
\begin{verbatim}
[m s] = size (A.matrix) ;
[s n] = size (B.matrix) ;
T.matrix  = zeros (m, n, multiply.ztype) ;
T.pattern = zeros (m, n, 'logical') ;
T.matrix (:,:) = identity ;             % the identity of the semiring's monoid
T.class = multiply.ztype ;              % the ztype of the semiring's multiply op
A = cast (A.matrix, multiply.xtype) ;   % the xtype of the semiring's multiply op
B = cast (B.matrix, multiply.ytype) ;   % the ytype of the semiring's multiply op
for j = 1:n
    for i = 1:m
        for k = 1:s
            % T (i,j) += A (i,k) * B (k,j), using the semiring
            if (A.pattern (i,k) && B.pattern (k,j))
                z = multiply (A (i,k), B (k,j)) ;
                T.matrix  (i,j) = add (T.matrix (i,j),  z) ;
                T.pattern (i,j) = true ;
            end
        end
    end
end \end{verbatim}}

Finally, \verb'T' is typecasted into the type of \verb'C', and the results are
written back into \verb'C' via the \verb'accum' and \verb'Mask', ${\bf C
\langle M \rangle  = C \odot T}$.  The latter step is reflected in the MATLAB
function \verb'GB_spec_accum_mask.m', discussed in Section~\ref{accummask}.

\paragraph{\bf Performance considerations:}
Suppose all matrices are in \verb'GxB_BY_COL' format, and \verb'B' is extremely
sparse but \verb'A' is not as sparse.  Then computing \verb'C=A*B' is very
fast, and much faster then when \verb'A' is extremely sparse.  For example, if
\verb'A' is square and \verb'B' is a column vector that is all nonzero except
for one entry \verb'B(j,0)=1', then \verb'C=A*B' is the same as extracting
column \verb'A(:,j)'.  This is very fast if \verb'A' is stored by column but
slow if \verb'A' is stored by row.  If \verb'A' is a sparse row with a single
entry \verb'A(0,i)=1', then \verb'C=A*B' is the same as extracting row
\verb'B(i,:)'.  This is fast if \verb'B' is stored by row but slow if \verb'B'
is stored by column.

If the user application needs to repeatedly extract rows and columns from a
matrix, whether by matrix multiplication or by \verb'GrB_extract', then keep
two copies: one stored by row, and other by column, and use the copy that
results in the fastest computation.

%===============================================================================
\subsection{Meta-algorithm for sparse matrix multiplication}
\label{meta}
%===============================================================================

SuiteSparse:GraphBLAS includes three different
methods for computing \verb'C<M>=A*B', and more may be added in the future.
It uses a meta-algorithm to select between the methods, described below.
The default behavior depends on the CSR/CSC format of each matrix (any
combination can be used for the four matrices), whether or not the mask
\verb'M' is present, and the descriptor values for transposing \verb'A' and
\verb'B'.  This gives a large number of possible combinations, so the
meta-algorithm that selects the method starts by reducing this space of
combinations.

A matrix stored by row but not transposed has the same data structure as a
matrix stored by column and transposed.  To make all matrices uniform
all matrices are viewed as if stored by column, by negating the transpose
descriptors if they are stored by row.  No data movement takes place.

{\footnotesize
\begin{verbatim}
    A_transpose = true if transposed by INP0, false otherwise
    B_transpose = true if transposed by INP1, false otherwise
    if (A is stored by row)
        A_transpose = !A_transpose
    if (B is stored by row)
        B_transpose = !B_transpose
    if (C is stored by row)
        C_transpose = true
    else
        C_transpose = false
    if (M is present and stored by row)
        M_transpose = true
    else
        M_transpose = false \end{verbatim}}

Now all matrices are treated as if stored by column.  The next phase applies
the default {\em swap rule}, which removes the transpose of \verb'C' via the
linear algebraic property $A^{\sf T} B^{\sf T}=(BA)^{\sf T}$.

{\footnotesize
\begin{verbatim}
    swap_rule = C_transpose 
    if (swap_rule)
        swap the matrices A and B
        A_transpose = !B_transpose
        B_transpose = !A_transpose
        C_transpose = !C_transpose
        M_transpose = !M_transpose \end{verbatim}}

With this default swap rule, \verb'C_transpose' is now false.  All transposes
below are now explicit, requiring data movement.  Next, the mask is explicitly
transposed.

{\footnotesize
\begin{verbatim}
    if (M_transpose)
        M = M' (an explicit transpose)
        M_transpose = false \end{verbatim}}

There are now four cases to handle:

\begin{enumerate} 

\item If computing \verb"C<M> = A'*B'":   the matrix \verb'B' is
    explicitly transposed and then rule (2) below is applied.

\item If computing \verb"C<M> = A'*B"

{\footnotesize
\begin{verbatim}
if default method:
    if M is present, or if A or B have a single column, or if B or A are dense:
        use the dot method
    else
        select the heap or Gustavson method (see below)
if dot method:
    compute C<M>=A'*B
else if heap or Gustavon's method:
    A=A' ;
    compute C<M>=A*B \end{verbatim}}

\item If computing \verb"C<M> = A*B'"

{\footnotesize
\begin{verbatim}
if default method:
    select the heap or Gustavson method (see below)
if dot method (not selected automatically):
    A=A' ; B=B' ;
    compute C<M>=A'*B
else if heap or Gustavon's method:
    B=B' ;
    compute C<M>=A*B \end{verbatim}}

\item If computing \verb"C<M> = A*B"

{\footnotesize
\begin{verbatim}
if default method:
    select the heap or Gustavson method (see below)
if dot method (not selected automatically):
    A=A' ;
    compute C<M>=A'*B
else if heap or Gustavon's method:
    compute C<M>=A*B \end{verbatim}}

\end{enumerate}

The \verb'GrB_vxm' and \verb'GrB_mxv' operations described in
Sections~\ref{vxm}~and~\ref{mxv} use the same method above, where the vectors
\verb'w', \verb'mask', and \verb'u' are treated as \verb'n'-by-1 matrices,
stored by column.

The default automatic selection between the heap method or Gustavson's method
for \verb'C<M>=A*B' depends on the sparsity of \verb'A' and \verb'B'.  Let $b$
be the largest number of entries in any column of \verb'B'.  Let $m$-by-$n$ be
the dimensions of \verb'C'.  Let $k$ be the inner dimension, so that \verb'A'
is $m$-by-$k$ and \verb'B' is $k$-by-$n$ (and thus $b \le k$).

The workspace required by the heap method is $5b$ integers, or $40b$ bytes.
Gustavson's method requires $(s+1)m$ bytes of workspace where $s$ is the number
of bytes required for the data type of \verb'C' ($s=8$ if \verb'C' is
\verb'GrB_FP64', for example).  The workspace of Gustavson's method can be
prohibitive if the matrices are extremely sparse since $m >> b$ or even $m >>
|{\bf B}|$ is possible.

When the \verb'GxB_AxB_METHOD' is \verb'GxB_DEFAULT' and the \verb'GxB_AxB_DOT'
method has not been chosen (see above), then the following rules are used to
select between the heap method and Gustavson's method.

\begin{itemize}

\item {\bf Rule (1):} If $b<2$ use the heap method.  The heap will be at most 2
in size, which makes the heap method very fast.  It is typically faster than
Gustavson's method in this case.  Example \verb'B' matrices that fit Rule (1)
include diagonal matrices, permutation matrices, or upper/lower bidiagonal
matrices.

\item {\bf Rule (2):}
    If $|{\bf B}| \le 3k$, or $|{\bf B}| \le m$,  or if $|{\bf A}| \le
    \min(k,m)$ then the heap method is used if its memory requirements are much
    less than Gustavson's method.  The heap method can be slow if $b$ is large,
    however, since modifying the heap after each operation can take as much as
    $O(\log b)$ time.  So the heap selection is penalized by a $4 \log_2 b$
    factor.  Thus, the heap method is used if the condition
    \[
        (40b) 4 \log_2 b < (s+1)m
    \]
    holds; otherwise Gustavson's method is used.  Rules (1) and (2) mean that
    the heap rule is used for computing $C=PAQ$ where $P$ and $Q$ are
    permutation matrices or diagonal scaling matrices, which are common use
    cases.  The heap method uses very little memory and is faster than
    Gustavson's method for these cases.

\item {\bf Rule (3):}
    Otherwise, Gustavson's method is used.  Rules (1) and (2) ensure that the
    workspace requirement for Gustavson's method will not be prohibitive.

\end{itemize}

The automatic selection applies to any mixture of the format of the
four matrices (CSR or CSC, and hypersparse or non-hypersparse), and any
combination of the input descriptors that transpose \verb'A' and \verb'B'.
If all matrices are CSR format, \verb'C<M>=A*B' does not explicitly
transpose any matrix.

\paragraph{\bf Performance considerations:}
With such a large space of combinations, the default meta-algorithm may not
select the fastest method, which is why the method can be selected via the
\verb'GxB_AxB_METHOD' field of the descriptor.

The meta-algorithm never transposes the final result (\verb"C=A'*B'" is never
converted into \verb"C=(B*A)'"), although that strategy can lead to better
performance. 
% A different \verb'swap_rule' would allow for the output matrix to
% be transposed (with \verb"C=(B*A)'" being computed); a user descriptor may be
% added in the future to allow for this selection. 
The user application can do this by computing \verb"C'=B*A", and then
transposing the result via \verb'GrB_transpose' to obtain
\verb"C=(B*A)'=A'*B'".  This can be faster in some cases, depending on the size
and sparsity of the three or four matrices (\verb'C', \verb'A', \verb'B', and
\verb'M' if present).

\newpage
%===============================================================================
\subsection{{\sf GrB\_vxm:} vector-matrix multiply} %===========================
%===============================================================================
\label{vxm}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_vxm                    // w'<mask> = accum (w, u'*A)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_Semiring semiring,    // defines '+' and '*' for u'*A
    const GrB_Vector u,             // first input:  vector u
    const GrB_Matrix A,             // second input: matrix A
    const GrB_Descriptor desc       // descriptor for w, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_vxm' multiplies a row vector \verb"u'" times a matrix \verb'A'.  The
matrix \verb'A' may be first transposed according to \verb'desc' (as the second
input, \verb'GrB_INP1'); the column vector \verb'u' is never transposed via the
descriptor.  The inputs \verb'u' and \verb'A' are typecasted to match the
\verb'xtype' and \verb'ytype' inputs, respectively, of the multiply operator of
the \verb'semiring'.  Next, an intermediate column vector \verb"t=A'*u" is
computed on the \verb'semiring' using the same method as \verb'GrB_mxm'.
Finally, the column vector \verb't' is typecasted from the \verb'ztype' of the
multiply operator of the \verb'semiring' into the type of \verb'w', and the
results are written back into \verb'w' using the optional accumulator
\verb'accum' and \verb'mask'.

The last step is ${\bf w \langle m \rangle  = w \odot t}$, as described
in Section~\ref{accummask}, except that all the
terms are column vectors instead of matrices.

\paragraph{\bf Performance considerations:} % u'=u'*A
If the \verb'GxB_FORMAT' of \verb'A' is \verb'GxB_BY_ROW', and the default
descriptor is used (\verb'A' is not transposed), then \verb'GrB_vxm' is faster
than than \verb'GrB_mxv' with its default descriptor, when the vector \verb'u'
is very sparse.
However, if the \verb'GxB_FORMAT' of \verb'A' is \verb'GxB_BY_COL', then
\verb'GrB_mxv' with its default descriptor is faster than \verb'GrB_vxm' with
its default descriptor, when the vector \verb'u' is very sparse.
Using the non-default \verb'GrB_TRAN' descriptor for \verb'A' makes the
\verb'GrB_vxm' operation equivalent to \verb'GrB_mxv' with its default
descriptor (with the operands reversed in the multiplier, as well).  The
reverse is true as well; \verb'GrB_mxv' with \verb'GrB_TRAN' is the same as
\verb'GrB_vxm' with a default descriptor.

The breadth-first search presented in Section~\ref{bfs} of this User Guide uses
\verb'GrB_vxm' instead of \verb'GrB_mxv', since the default format in
SuiteSparse:GraphBLAS is \verb'GxB_BY_ROW'.  If the matrix is stored by column,
then use \verb'GrB_mxv' instead.

\newpage
%===============================================================================
\subsection{{\sf GrB\_mxv:} matrix-vector multiply} %===========================
%===============================================================================
\label{mxv}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_mxv                    // w<mask> = accum (w, A*u)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_Semiring semiring,    // defines '+' and '*' for A*B
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Vector u,             // second input: vector u
    const GrB_Descriptor desc       // descriptor for w, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_mxv' multiplies a matrix \verb'A' times a column vector \verb'u'.
The matrix \verb'A' may be first transposed according to \verb'desc' (as the
first input); the column vector \verb'u' is never transposed via the
descriptor.  The inputs \verb'A' and \verb'u' are typecasted to match the
\verb'xtype' and \verb'ytype' inputs, respectively, of the multiply operator of
the \verb'semiring'. Next, an intermediate column vector \verb't=A*u' is
computed on the \verb'semiring' using the same method as \verb'GrB_mxm'.
Finally, the column vector \verb't' is typecasted from the \verb'ztype' of the
multiply operator of the \verb'semiring' into the type of \verb'w', and the
results are written back into \verb'w' using the optional accumulator
\verb'accum' and \verb'mask'.

The last step is ${\bf w \langle m \rangle  = w \odot t}$, as described
in Section~\ref{accummask}, except that all the terms are column vectors instead
of matrices.

\paragraph{\bf Performance considerations:} % u=A*u
Refer to the discussion of \verb'GrB_vxm'.  In SuiteSparse:GraphBLAS,
\verb'GrB_mxv' is very efficient when \verb'u' is sparse or dense, when the
default descriptor is used, and when the matrix is \verb'GxB_BY_COL'.  When
\verb'u' is very sparse and \verb'GrB_INP0' is set to its non-default
\verb'GrB_TRAN', then this method is not efficient if the matrix is in
\verb'GxB_BY_COL' format.  If an application needs to perform \verb"A'*u"
repeatedly where \verb'u' is very sparse, then use the \verb'GxB_BY_ROW' format
for \verb'A' instead.

\newpage
%===============================================================================
\subsection{{\sf GrB\_eWiseMult:} element-wise operations, set intersection} %==
%===============================================================================
\label{eWiseMult}

Element-wise ``multiplication'' is shorthand for applying a binary operator
element-wise on two matrices or vectors \verb'A' and \verb'B', for all entries
that appear in the set intersection of the patterns of \verb'A' and \verb'B'.
This is like \verb'A.*B' for two sparse matrices in MATLAB, except that in
GraphBLAS any binary operator can be used, not just multiplication.

The pattern of the result of the element-wise ``multiplication'' is exactly
this set intersection.  Entries in \verb'A' but not \verb'B', or visa versa, do
not appear in the result.

Let $\otimes$ denote the binary operator to be used.  The computation ${\bf T =
A \otimes B}$ is given below.  Entries not in the intersection of ${\bf A}$ and
${\bf B}$ do not appear in the pattern of ${\bf T}$.  That is:
    \vspace{-0.2in}
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> for all entries $(i,j)$ in ${\bf A \cap B}$ \\
    \> \> $t_{ij} = a_{ij} \otimes b_{ij}$ \\
    \end{tabbing} }
    \vspace{-0.2in}

Depending on what kind of operator is used and what the implicit value is
assumed to be, this can give the Hadamard product.  This is the case for
\verb'A.*B' in MATLAB since the implicit value is zero.  However, computing a
Hadamard product is not necessarily the goal of the \verb'eWiseMult' operation.
It simply applies any binary operator, built-in or user-defined, to the set
intersection of \verb'A' and \verb'B', and discards any entry outside this
intersection.  Its usefulness in a user's application does not depend upon it
computing a Hadamard product in all cases.  The operator need not be
associative, commutative, nor have any particular property except for type
compatibility with \verb'A' and \verb'B', and the output matrix \verb'C'.

The generic name for this operation is \verb'GrB_eWiseMult', which can be used
for both matrices and vectors.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_eWiseMult\_Vector:} element-wise vector multiply}
%-------------------------------------------------------------------------------
\label{eWiseMult_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_eWiseMult              // w<mask> = accum (w, u.*v)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const <operator> multiply,      // defines '.*' for t=u.*v
    const GrB_Vector u,             // first input:  vector u
    const GrB_Vector v,             // second input: vector v
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_eWiseMult_Vector' computes the element-wise ``multiplication'' of two
vectors \verb'u' and \verb'v', element-wise using any binary operator (not just
times).  The vectors are not transposed via the descriptor.  The vectors
\verb'u' and \verb'v' are first typecasted into the first and second inputs of
the \verb'multiply' operator.  Next, a column vector \verb't' is computed,
denoted ${\bf t = u \otimes v}$.  The pattern of \verb't' is the set
intersection of \verb'u' and \verb'v'.  The result \verb't' has the type of the
output \verb'ztype' of the \verb'multiply' operator.

The \verb'operator' is typically a \verb'GrB_BinaryOp', but the method is
type-generic for this parameter.  If given a monoid (\verb'GrB_Monoid'), the
additive operator of the monoid is used as the \verb'multiply' binary operator.
If given a semiring (\verb'GrB_Semiring'), the multiply operator of the
semiring is used as the \verb'multiply' binary operator.

The next and final step is ${\bf w \langle m \rangle  = w \odot t}$, as
described in Section~\ref{accummask}, except that all the terms are column
vectors instead of matrices.  Note for all GraphBLAS operations, including this
one, the accumulator ${\bf w \odot t}$ is always applied in a set union manner,
even though ${\bf t = u \otimes v}$ for this operation is applied in a set
intersection manner.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_eWiseMult\_Matrix:} element-wise matrix multiply}
%-------------------------------------------------------------------------------
\label{eWiseMult_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_eWiseMult              // C<Mask> = accum (C, A.*B)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const <operator> multiply,      // defines '.*' for T=A.*B
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Matrix B,             // second input: matrix B
    const GrB_Descriptor desc       // descriptor for C, Mask, A, and B
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_eWiseMult_Matrix' computes the element-wise ``multiplication'' of two
matrices \verb'A' and \verb'B', element-wise using any binary operator (not
just times).  The input matrices may be transposed first, according to the
descriptor \verb'desc'.  They are then typecasted into the first and second
inputs of the \verb'multiply' operator.  Next, a matrix \verb'T' is computed,
denoted ${\bf T = A \otimes B}$.  The pattern of \verb'T' is the set
intersection of \verb'A' and \verb'B'.  The result \verb'T' has the type of the
output \verb'ztype' of the \verb'multiply' operator.

The \verb'multiply' operator is typically a \verb'GrB_BinaryOp', but the method
is type-generic for this parameter.  If given a monoid (\verb'GrB_Monoid'), the
additive operator of the monoid is used as the \verb'multiply' binary operator.
If given a semiring (\verb'GrB_Semiring'), the multiply operator of the
semiring is used as the \verb'multiply' binary operator.

\vspace{0.05in}
The operation can be expressed in MATLAB notation as:
    {\footnotesize
    \begin{verbatim}
    [nrows, ncols] = size (A.matrix) ;
    T.matrix = zeros (nrows, ncols, multiply.ztype) ;
    T.class = multiply.ztype ;
    p = A.pattern & B.pattern ;
    A = cast (A.matrix (p), multiply.xtype) ;
    B = cast (B.matrix (p), multiply.ytype) ;
    T.matrix (p) = multiply (A, B) ;
    T.pattern = p ; \end{verbatim} }

The final step is ${\bf C \langle M \rangle  = C \odot T}$, as described in
Section~\ref{accummask}.  Note for all GraphBLAS operations, including this
one, the accumulator ${\bf C \odot T}$ is always applied in a set union manner,
even though ${\bf T = A \otimes B}$ for this operation is applied in a set
intersection manner.

\newpage
%===============================================================================
\subsection{{\sf GrB\_eWiseAdd:} element-wise operations, set union} %==========
%===============================================================================
\label{eWiseAdd}

Element-wise ``addition'' is shorthand for applying a binary operator
element-wise on two matrices or vectors \verb'A' and \verb'B', for all entries
that appear in the set intersection of the patterns of \verb'A' and \verb'B'.
This is like \verb'A+B' for two sparse matrices in MATLAB, except that in
GraphBLAS any binary operator can be used, not just addition.  The pattern of
the result of the element-wise ``addition'' is the set union of the pattern of
\verb'A' and \verb'B'.  Entries in neither in \verb'A' nor in \verb'B' do
not appear in the result.

Let $\oplus$ denote the binary operator to be used.  The computation ${\bf T =
A \oplus B}$ is exactly the same as the computation with accumulator operator
as described in Section~\ref{accummask}.  It acts like a sparse matrix
addition, except that any operator can be used.  The pattern of ${\bf A \oplus
B}$ is the set union of the patterns of ${\bf A}$ and ${\bf B}$, and the
operator is applied only on the set intersection of ${\bf A}$ and ${\bf B}$.
Entries not in either the pattern of ${\bf A}$ or ${\bf B}$ do not appear in
the pattern of ${\bf T}$.  That is:
    \vspace{-0.2in}
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> for all entries $(i,j)$ in ${\bf A \cap B}$ \\
    \> \> $t_{ij} = a_{ij} \oplus b_{ij}$ \\
    \> for all entries $(i,j)$ in ${\bf A \setminus B}$ \\
    \> \> $t_{ij} = a_{ij}$ \\
    \> for all entries $(i,j)$ in ${\bf B \setminus A}$ \\
    \> \> $t_{ij} = b_{ij}$
    \end{tabbing}
    }

The only difference between element-wise ``multiplication'' (${\bf T =A \otimes
B}$) and ``addition'' (${\bf T = A \oplus B}$) is the pattern of the result,
and what happens to entries outside the intersection.  With $\otimes$ the
pattern of ${\bf T}$ is the intersection; with $\oplus$ it is the set union.
Entries outside the set intersection are dropped for $\otimes$, and kept for
$\oplus$; in both cases the operator is only applied to those (and only those)
entries in the intersection.  Any binary operator can be used interchangeably
for either operation.

Element-wise operations do not operate on the implicit values, even implicitly,
since the operations make no assumption about the semiring.  As a result, the
results can be different from MATLAB, which can always assume the implicit
value is zero.  For example, \verb'C=A-B' is the conventional matrix
subtraction in MATLAB.  Computing \verb'A-B' in GraphBLAS with \verb'eWiseAdd'
will apply the \verb'MINUS' operator to the intersection, entries in \verb'A'
but not \verb'B' will be unchanged and appear in \verb'C', and entries in
neither \verb'A' nor \verb'B' do not appear in \verb'C'.  For these cases, the
results matches the MATLAB \verb'C=A-B'.  Entries in \verb'B' but not \verb'A'
do appear in \verb'C' but they are not negated; they cannot be subtracted from
an implicit value in \verb'A'.  This is by design.  If conventional matrix
subtraction of two sparse matrices is required, and the implicit value is known
to be zero, use \verb'GrB_apply' to negate the values in \verb'B', and then
use \verb'eWiseAdd' with the \verb'PLUS' operator, to compute \verb'A+(-B)'.

The generic name for this operation is \verb'GrB_eWiseAdd', which can be used
for both matrices and vectors.

There is another minor difference in two variants of the element-wise
functions.  If given a \verb'semiring', the \verb'eWiseAdd' functions use the
binary operator of the semiring's monoid, while the \verb'eWiseMult' functions
use the multiplicative operator of the semiring.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_eWiseAdd\_Vector:} element-wise vector addition}
%-------------------------------------------------------------------------------
\label{eWiseAdd_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_eWiseAdd               // w<mask> = accum (w, u+v)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const <operator> add,           // defines '+' for t=u+v
    const GrB_Vector u,             // first input:  vector u
    const GrB_Vector v,             // second input: vector v
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_eWiseAdd_Vector' computes the element-wise ``addition'' of two
vectors \verb'u' and \verb'v', element-wise using any binary operator (not just
plus).  The vectors are not transposed via the descriptor.  Entries in the
intersection of \verb'u' and \verb'v' are first typecasted into the first and
second inputs of the \verb'add' operator.  Next, a column vector \verb't' is
computed, denoted ${\bf t = u \oplus v}$.  The pattern of \verb't' is the set
union of \verb'u' and \verb'v'.  The result \verb't' has the type of the output
\verb'ztype' of the \verb'add' operator.

The \verb'add' operator is typically a \verb'GrB_BinaryOp', but the method is
type-generic for this parameter.  If given a monoid (\verb'GrB_Monoid'), the
additive operator of the monoid is used as the \verb'add' binary operator.  If
given a semiring (\verb'GrB_Semiring'), the additive operator of the monoid of
the semiring is used as the \verb'add' binary operator.

The final step is ${\bf w \langle m \rangle  = w \odot t}$, as described in
Section~\ref{accummask}, except that all the terms are column vectors instead
of matrices.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_eWiseAdd\_Matrix:} element-wise matrix addition}
%-------------------------------------------------------------------------------
\label{eWiseAdd_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_eWiseAdd               // C<Mask> = accum (C, A+B)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const <operator> add,           // defines '+' for T=A+B
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Matrix B,             // second input: matrix B
    const GrB_Descriptor desc       // descriptor for C, Mask, A, and B
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_eWiseAdd_Matrix' computes the element-wise ``addition'' of two
matrices \verb'A' and \verb'B', element-wise using any binary operator (not
just plus).  The input matrices may be transposed first, according to the
descriptor \verb'desc'.  Entries in the intersection then typecasted into the
first and second inputs of the \verb'add' operator.  Next, a matrix \verb'T' is
computed, denoted ${\bf T = A \oplus B}$.  The pattern of \verb'T' is the set
union of \verb'A' and \verb'B'.  The result \verb'T' has the type of the output
\verb'ztype' of the \verb'add' operator.

The \verb'add' operator is typically a \verb'GrB_BinaryOp', but the method is
type-generic for this parameter.  If given a monoid (\verb'GrB_Monoid'), the
additive operator of the monoid is used as the \verb'add' binary operator.  If
given a semiring (\verb'GrB_Semiring'), the additive operator of the monoid of
the semiring is used as the \verb'add' binary operator.

\vspace{0.05in}
The operation can be expressed in MATLAB notation as:
    {\footnotesize
    \begin{verbatim}
    [nrows, ncols] = size (A.matrix) ;
    T.matrix = zeros (nrows, ncols, add.ztype) ;
    p = A.pattern & B.pattern ;
    A = GB_mex_cast (A.matrix (p), add.xtype) ;
    B = GB_mex_cast (B.matrix (p), add.ytype) ;
    T.matrix (p) = add (A, B) ;
    p =  A.pattern & ~B.pattern ; T.matrix (p) = cast (A.matrix (p), add.ztype) ;
    p = ~A.pattern &  B.pattern ; T.matrix (p) = cast (B.matrix (p), add.ztype) ;
    T.pattern = A.pattern | B.pattern ;
    T.class = add.ztype ; \end{verbatim} }
Except for when typecasting is performed, this is identical to how the
\verb'accum' operator is applied in Figure~\ref{fig_accummask}.

The final step is ${\bf C \langle M \rangle  = C \odot T}$, as described in
Section~\ref{accummask}.

\newpage
%===============================================================================
\subsection{{\sf GrB\_extract:} submatrix extraction } %========================
%===============================================================================
\label{extract}

The \verb'GrB_extract' function is a generic name for three specific functions:
\verb'GrB_Vector_extract', \verb'GrB_Col_extract', and
\verb'GrB_Matrix_extract'.  The generic name appears in the function signature,
but the specific function name is used when describing what each variation
does.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_extract:} extract subvector from vector}
%-------------------------------------------------------------------------------
\label{extract_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_extract                // w<mask> = accum (w, u(I))
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_Vector u,             // first input:  vector u
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_extract' extracts a subvector from another vector, identical
to \verb't = u (I)' in MATLAB where \verb'I' is an integer vector of row
indices.  Refer to \verb'GrB_Matrix_extract' for further details; vector
extraction is the same as matrix extraction with \verb'n'-by-1 matrices.
See Section~\ref{colon} for a description of \verb'I' and \verb'ni'.
The final step is ${\bf w \langle m \rangle  = w \odot
t}$, as described in Section~\ref{accummask}, except that all the terms are
column vectors instead of matrices.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_extract:} extract submatrix from matrix}
%-------------------------------------------------------------------------------
\label{extract_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_extract                // C<Mask> = accum (C, A(I,J))
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C, Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_extract' extracts a submatrix from another matrix, identical
to \verb'T = A(I,J)' in MATLAB where \verb'I' and \verb'J' are integer vectors
of row and column indices, respectively, except that indices are zero-based in
GraphBLAS and one-based in MATLAB.  The input matrix \verb'A' may be transposed
first, via the descriptor.  The type of \verb'T' and \verb'A' are the same.
The size of \verb'C' is \verb'|I|'-by-\verb'|J|'.
Entries outside \verb'A(I,J)' are not accessed and do not take part in the
computation.  More precisely, assuming the matrix \verb'A' is not transposed,
the matrix \verb'T' is defined as follows:

    \vspace{-0.1in}
    {\footnotesize
    \begin{verbatim}
    T.matrix  = zeros (ni, nj) ;    % a matrix of size ni-by-nj
    T.pattern = false (ni, nj) ;
    for i = 1:ni
        for j = 1:nj
            if (A (I(i),J(j)).pattern)
                T (i,j).matrix  = A (I(i),J(j)).matrix ;
                T (i,j).pattern = true ;
            end
        end
    end \end{verbatim}}

\vspace{-0.1in}
If duplicate indices are present in \verb'I' or \verb'J', the above method
defines the result in \verb'T'.  Duplicates result in the same values of
\verb'A' being copied into different places in \verb'T'.
See Section~\ref{colon} for a description of the row indices 
\verb'I' and \verb'ni', and the column indices
\verb'J' and \verb'nj'.
The final step is ${\bf C \langle M \rangle  = C \odot
T}$, as described in Section~\ref{accummask}.

\paragraph{\bf Performance considerations:} % C=A(I,J)
If \verb'A' is not transposed via input descriptor: if \verb'|I|' is small,
then it is fastest if \verb'A' is \verb'GxB_BY_ROW'; if
\verb'|J|' is small, then it is fastest if \verb'A' is
\verb'GxB_BY_COL'.  The opposite is true if \verb'A' is transposed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Col\_extract:} extract column vector from matrix}
%-------------------------------------------------------------------------------
\label{extract_column}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_extract                // w<mask> = accum (w, A(I,j))
(
    GrB_Vector w,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index j,              // column index
    const GrB_Descriptor desc       // descriptor for w, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Col_extract' extracts a subvector from a matrix, identical to
\verb't = A (I,j)' in MATLAB where \verb'I' is an integer vector of row indices
and where \verb'j' is a single column index.  The input matrix \verb'A' may be
transposed first, via the descriptor, which results in the extraction of a
single row \verb'j' from the matrix \verb'A', the result of which is a column
vector \verb'w'.  The type of \verb't' and \verb'A' are the same.
The size of \verb'w' is \verb'|I|'-by-1.

See Section~\ref{colon} for a description of the row indices 
\verb'I' and \verb'ni'.
The final step is ${\bf w \langle m
\rangle  = w \odot t}$, as described in Section~\ref{accummask}, except that
all the terms are column vectors instead of matrices.

\paragraph{\bf Performance considerations:} % w = A(I,j)
If \verb'A' is not transposed: it is fastest if the format of \verb'A' is
\verb'GxB_BY_COL'.  The opposite is true if \verb'A' is transposed.

\newpage
%===============================================================================
\subsection{{\sf GxB\_subassign:} submatrix assignment} %=======================
%===============================================================================
\label{subassign}

The methods described in this section are all variations of the form
\verb'C(I,J)=A', which modifies a submatrix of the matrix \verb'C'.  All
methods can be used in their generic form with the single name
\verb'GxB_subassign'.  This is reflected in the prototypes.  However, to avoid
confusion between the different kinds of assignment, the name of the specific
function is used when describing each variation.  If the discussion applies to
all variations, the simple name \verb'GxB_subassign' is used.

See Section~\ref{colon} for a description of the row indices 
\verb'I' and \verb'ni', and the column indices
\verb'J' and \verb'nj'.

\verb'GxB_subassign' is very similar to \verb'GrB_assign', described in
Section~\ref{assign}.  The two operations are compared and contrasted in
Section~\ref{compare_assign}.

\begin{spec}
{\bf SPEC:} All variants of \verb'GxB_subassign' are extensions to the spec.
\end{spec}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_subassign:} assign to a subvector }
%-------------------------------------------------------------------------------
\label{subassign_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // w(I)<mask> = accum (w(I),u)
(
    GrB_Vector w,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for w(I), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),t)
    const GrB_Vector u,             // first input:  vector u
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w(I) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_subassign' operates on a subvector \verb'w(I)' of \verb'w',
modifying it with the vector \verb'u'.  The method is identical to
\verb'GxB_Matrix_subassign' described in Section~\ref{subassign_matrix}, where
all matrices have a single column each.  The \verb'mask' has the same size as
\verb'w(I)' and \verb'u'.  The only other difference is that the input \verb'u'
in this method is not transposed via the \verb'GrB_INP0' descriptor.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_subassign:} assign to a submatrix }
%-------------------------------------------------------------------------------
\label{subassign_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // C(I,J)<Mask> = accum (C(I,J),A)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C(I,J), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C(I,J),T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(I,J), Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_subassign' operates only on a submatrix \verb'S' of \verb'C',
modifying it with the matrix \verb'A'.   For this operation, the result is not
the entire matrix \verb'C', but a submatrix \verb'S=C(I,J)' of \verb'C'.  The
steps taken are as follows, except that ${\bf A}$ may be optionally transposed
via the \verb'GrB_INP0' descriptor option.

\vspace{0.1in}
\begin{tabular}{lll}
\hline
Step & GraphBLAS & description \\
     & notation  & \\
\hline
1 & ${\bf S} = {\bf C(I,J)}$                             & extract the ${\bf C(I,J)}$ submatrix \\
2 & ${\bf S \langle M \rangle} = {\bf S} \odot {\bf A}$  & apply the accumulator/mask to the submatrix ${\bf S}$\\
3 & ${\bf C(I,J)}= {\bf S}$                              & put the submatrix ${\bf S}$ back into ${\bf C(I,J)}$ \\ 
\hline
\end{tabular}
\vspace{0.1in}

The accumulator/mask step in Step 2 is the same as for all other GraphBLAS
operations, described in Section~\ref{accummask}, except that for
\verb'GxB_subassign', it is applied to just the submatrix ${\bf S} = {\bf
C(I,J)}$, and thus the \verb'Mask' has the same size as ${\bf A}$,
${\bf S}$, and ${\bf C(I,J)}$.

The \verb'GxB_subassign' operation is the reverse of matrix extraction:

\begin{itemize}
\item
For submatrix extraction, \verb'GrB_Matrix_extract',
the submatrix \verb'A(I,J)' appears on the right-hand side of the assignment,
\verb'C=A(I,J)', and entries outside of the submatrix are not accessed and do
not take part in the computation.

\item
For submatrix assignment, \verb'GxB_Matrix_subassign',
the submatrix \verb'C(I,J)' appears on the left-hand-side of the assignment,
\verb'C(I,J)=A', and entries outside of the submatrix are not accessed and do
not take part in the computation.

\end{itemize}

In both methods, the accumulator and mask modify the submatrix of the
assignment; they simply differ on which side of the assignment the submatrix
resides on.  In both cases, if the \verb'Mask' matrix is present it is the same
size as the submatrix:

\begin{itemize}

\item
For submatrix extraction,
${\bf C \langle M \rangle = C \odot A(I,J)}$ is computed,
where the submatrix is on the right.
The mask ${\bf M}$ has the same size as the submatrix ${\bf A(I,J)}$.

\item
For submatrix assignment,
${\bf C(I,J) \langle M \rangle = C(I,J) \odot A}$ is computed,
where the submatrix is on the left.
The mask ${\bf M}$ has the same size as the submatrix ${\bf C(I,J)}$.

\end{itemize}

In Step 1, the submatrix \verb'S' is first computed by the
\verb'GrB_Matrix_extract' operation, \verb'S=C(I,J)'.

Step 2 accumulates the results ${\bf S \langle M \rangle  = S \odot T}$,
exactly as described in Section~\ref{accummask}, but operating on the submatrix
${\bf S}$, not ${\bf C}$, using the optional \verb'Mask' and \verb'accum'
operator.  The matrix ${\bf T}$ is simply ${\bf T}={\bf A}$, or ${\bf T}={\bf
A}^{\sf T}$ if ${\bf A}$ is transposed via the \verb'desc' descriptor,
\verb'GrB_INP0'.  The \verb'GrB_REPLACE' option in the descriptor clears ${\bf
S}$ after computing ${\bf Z = T}$ or ${\bf Z = C \odot T}$, not all of ${\bf
C}$ since this operation can only modify the specified submatrix of ${\bf C}$.

Finally, Step 3 writes the result (which is the modified submatrix \verb'S' and
not all of \verb'C') back into the \verb'C' matrix that contains it, via the
assignment \verb'C(I,J)=S', using the reverse operation from the method
described for matrix extraction:

    {\footnotesize
    \begin{verbatim}
    for i = 1:ni
        for j = 1:nj
            if (S (i,j).pattern)
                C (I(i),J(j)).matrix = S (i,j).matrix ;
                C (I(i),J(j)).pattern = true ;
            end
        end
    end \end{verbatim}}

Results are not defined for any \verb'GxB_subassign' operation if duplicate
indices appear in \verb'I' or \verb'J'.

\paragraph{\bf Performance considerations:} % C(I,J) = A
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Col\_subassign:} assign to a sub-column of a matrix}
%-------------------------------------------------------------------------------
\label{subassign_column}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // C(I,j)<mask> = accum (C(I,j),u)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(I,j), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(I,j),t)
    const GrB_Vector u,             // input vector
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index j,              // column index
    const GrB_Descriptor desc       // descriptor for C(I,j) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Col_subassign' modifies a single sub-column of a matrix \verb'C'.  It
is the same as \verb'GxB_Matrix_subassign' where the index vector \verb'J[0]=j'
is a single column index (and thus \verb'nj=1'), and where all matrices in
\verb'GxB_Matrix_subassign' (except \verb'C') consist of a single column.  The
\verb'mask' vector has the same size as \verb'u' and the sub-column
\verb'C(I,j)'.  The input descriptor \verb'GrB_INP0' is ignored; the input
vector \verb'u' is not transposed.  Refer to \verb'GxB_Matrix_subassign' for
further details.

\paragraph{\bf Performance considerations:} % C(I,j) = u
\verb'GxB_Col_subassign' is much faster than \verb'GxB_Row_subassign' if the
format of \verb'C' is \verb'GxB_BY_COL'.  \verb'GxB_Row_subassign' is much
faster than \verb'GxB_Col_subassign' if the format of \verb'C' is
\verb'GxB_BY_ROW'.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Row\_subassign:} assign to a sub-row of a matrix}
%-------------------------------------------------------------------------------
\label{subassign_row}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign                 // C(i,J)<mask'> = accum (C(i,J),u')
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(i,J), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(i,J),t)
    const GrB_Vector u,             // input vector
    const GrB_Index i,              // row index
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(i,J) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Row_subassign' modifies a single sub-row of a matrix \verb'C'.  It is
the same as \verb'GxB_Matrix_subassign' where the index vector \verb'I[0]=i' is
a single row index (and thus \verb'ni=1'), and where all matrices in
\verb'GxB_Matrix_subassign' (except \verb'C') consist of a single row.  The
\verb'mask' vector has the same size as \verb'u' and the sub-column
\verb'C(I,j)'.  The input descriptor \verb'GrB_INP0' is ignored; the input
vector \verb'u' is not transposed.  Refer to \verb'GxB_Matrix_subassign' for
further details.

\paragraph{\bf Performance considerations:} % C(i,J) = u'
\verb'GxB_Col_subassign' is much faster than \verb'GxB_Row_subassign' if the
format of \verb'C' is \verb'GxB_BY_COL'.  \verb'GxB_Row_subassign' is much
faster than \verb'GxB_Col_subassign' if the format of \verb'C' is
\verb'GxB_BY_ROW'.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_subassign\_$<$type$>$:} assign a scalar to a subvector}
%-------------------------------------------------------------------------------
\label{subassign_vector_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign                 // w(I)<mask> = accum (w(I),x)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w(I), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),x)
    const <type> x,                 // scalar to assign to w(I)
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w(I) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_subassign_<type>' assigns a single scalar to an entire
subvector of the vector \verb'w'.  The operation is exactly like setting a
single entry in an \verb'n'-by-1 matrix, \verb'A(I,0) = x', where the column
index for a vector is implicitly \verb'j=0'.  For further details of this
function, see \verb'GxB_Matrix_subassign_<type>' in
Section~\ref{subassign_matrix_scalar}.

Unlike \verb'GrB_Vector_assign_<type>' (see Section~\ref{assign_vector_scalar}),
results are not defined if \verb'I' contains duplicate indices.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_subassign\_$<$type$>$:} assign a scalar to a submatrix}
%-------------------------------------------------------------------------------
\label{subassign_matrix_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign                 // C(I,J)<Mask> = accum (C(I,J),x)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C(I,J), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C(I,J),x)
    const <type> x,                 // scalar to assign to C(I,J)
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(I,J) and Mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_subassign_<type>' assigns a single scalar to an entire
submatrix of \verb'C', like the {\em scalar expansion} \verb'C(I,J)=x' in
MATLAB.  The scalar \verb'x' is implicitly expanded into a matrix \verb'A' of
size \verb'ni' by \verb'nj', and then the matrix \verb'A' is assigned to
\verb'C(I,J)' using the same method as in \verb'GxB_Matrix_subassign'.  Refer
to that function in Section~\ref{subassign_matrix} for further details.
For the accumulation step, the scalar \verb'x' is typecasted directly into the
type of \verb'C' when the \verb'accum' operator is not applied to it, or into
the \verb'ytype' of the \verb'accum' operator, if \verb'accum' is not NULL, for
entries that are already present in \verb'C'.

The \verb'<type> x' notation is otherwise the same as
\verb'GrB_Matrix_setElement' (see Section~\ref{matrix_setElement}).  Any value
can be passed to this function and its type will be detected, via the
\verb'_Generic' feature of ANSI C11.  For a user-defined type, \verb'x' is a
\verb'void *' pointer that points to a memory space holding a single entry of a
scalar that has exactly the same user-defined type as the matrix \verb'C'.
This user-defined type must exactly match the user-defined type of \verb'C'
since no typecasting is done between user-defined types.

If a \verb'void *' pointer is passed in and the type of the underlying scalar
does not exactly match the user-defined type of \verb'C', then results are
undefined.  No error status will be returned since GraphBLAS has no way of
catching this error.
Unlike \verb'GrB_Matrix_assign_<type>' (see
Section~\ref{assign_vector_scalar}), results are not defined if \verb'I' or
\verb'J' contain duplicate indices.

\paragraph{\bf Performance considerations:} % C(I,J) = scalar
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%===============================================================================
\subsection{{\sf GrB\_assign:} submatrix assignment} %==========================
%===============================================================================
\label{assign}

The methods described in this section are all variations of the form
\verb'C(I,J)=A', which modifies a submatrix of the matrix \verb'C'.  All
methods can be used in their generic form with the single name
\verb'GrB_assign'.  These methods are very similar to their
\verb'GxB_subassign' counterparts in Section~\ref{subassign}.  They differ
primarily in the size of the \verb'Mask', and how the \verb'GrB_REPLACE' option
works.  Refer to Section~\ref{compare_assign} for a complete comparison of
\verb'GxB_subassign' and \verb'GrB_assign'.

See Section~\ref{colon} for a description of
\verb'I', \verb'ni', \verb'J', and \verb'nj'.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_assign:} assign to a subvector }
%-------------------------------------------------------------------------------
\label{assign_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // w<mask>(I) = accum (w(I),u)
(
    GrB_Vector w,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),t)
    const GrB_Vector u,             // first input:  vector u
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_assign' operates on a subvector \verb'w(I)' of \verb'w',
modifying it with the vector \verb'u'.  The \verb'mask' vector has the same
size as \verb'w'.  The method is identical to \verb'GrB_Matrix_assign'
described in Section~\ref{assign_matrix}, where all matrices have a single
column each.  The only other difference is that the input \verb'u' in this
method is not transposed via the \verb'GrB_INP0' descriptor.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_assign:} assign to a submatrix }
%-------------------------------------------------------------------------------
\label{assign_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<Mask>(I,J) = accum (C(I,J),A)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C(I,J),T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C, Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_assign' operates on a submatrix \verb'S' of \verb'C',
modifying it with the matrix \verb'A'.  It may also modify all of \verb'C',
depending on the input descriptor \verb'desc' and the \verb'Mask'.

\vspace{0.1in}
\begin{tabular}{lll}
\hline
Step & GraphBLAS & description \\
     & notation  & \\
\hline
1 & ${\bf S} = {\bf C(I,J)}$                & extract ${\bf C(I,J)}$ submatrix \\
2 & ${\bf S} = {\bf S} \odot {\bf A}$       & apply the accumulator (but not the mask) to ${\bf S}$\\
3 & ${\bf Z} = {\bf C}$                     & make a copy of ${\bf C}$ \\
4 & ${\bf Z(I,J)} = {\bf S}$                & put the submatrix into ${\bf Z(I,J)}$ \\
5 & ${\bf C \langle M \rangle = Z}$         & apply the mask/replace phase to all of ${\bf C}$ \\
\hline
\end{tabular}
\vspace{0.1in}

In contrast to \verb'GxB_subassign', the \verb'Mask' has the same as \verb'C'.

Step 1 extracts the submatrix and then Step 2 applies the accumulator
(or ${\bf S}={\bf A}$ if \verb'accum' is \verb'NULL').  The \verb'Mask' is
not yet applied.

Step 3 makes a copy of the ${\bf C}$ matrix, and then Step 4 writes the
submatrix ${\bf S}$ into ${\bf Z}$.  This is the same as Step 3 of
\verb'GxB_subassign', except that it operates on a temporary matrix ${\bf Z}$.

Finally, Step 5 writes ${\bf Z}$ back into ${\bf C}$ via the \verb'Mask', using
the Mask/Replace Phase described in Section~\ref{accummask}.  If
\verb'GrB_REPLACE' is enabled, then all of ${\bf C}$ is cleared prior to
writing ${\bf Z}$ via the mask.  As a result, the \verb'GrB_REPLACE' option can
delete entries outside the ${\bf C(I,J)}$ submatrix.

\paragraph{\bf Performance considerations:} % C(I,J) = A
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Col\_assign:} assign to a sub-column of a matrix}
%-------------------------------------------------------------------------------
\label{assign_column}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<mask>(I,j) = accum (C(I,j),u)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(:,j), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(I,j),t)
    const GrB_Vector u,             // input vector
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index j,              // column index
    const GrB_Descriptor desc       // descriptor for C(:,j) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Col_assign' modifies a single sub-column of a matrix \verb'C'.  It is
the same as \verb'GrB_Matrix_assign' where the index vector \verb'J[0]=j' is a
single column index, and where all matrices in \verb'GrB_Matrix_assign' (except
\verb'C') consist of a single column.

Unlike \verb'GrB_Matrix_assign', the \verb'mask' is a vector with the same size
as a single column of \verb'C'.

The input descriptor \verb'GrB_INP0' is ignored; the input vector \verb'u' is
not transposed.  Refer to \verb'GrB_Matrix_assign' for further details.

\paragraph{\bf Performance considerations:} % C(I,j) = u
\verb'GrB_Col_assign' is much faster than \verb'GrB_Row_assign' if the format
of \verb'C' is \verb'GxB_BY_COL'.  \verb'GrB_Row_assign' is much faster than
\verb'GrB_Col_assign' if the format of \verb'C' is \verb'GxB_BY_ROW'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Row\_assign:} assign to a sub-row of a matrix}
%-------------------------------------------------------------------------------
\label{assign_row}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<mask'>(i,J) = accum (C(i,J),u')
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(i,:), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(i,J),t)
    const GrB_Vector u,             // input vector
    const GrB_Index i,              // row index
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(i,:) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Row_subassign' modifies a single sub-row of a matrix \verb'C'.  It is
the same as \verb'GxB_Matrix_subassign' where the index vector \verb'I[0]=i' is
a single row index, and where all matrices in \verb'GxB_Matrix_subassign'
(except \verb'C') consist of a single row. 

Unlike \verb'GrB_Matrix_assign', the \verb'mask' is a vector with the same size
as a single row of \verb'C'.

The input descriptor \verb'GrB_INP0' is ignored; the input vector \verb'u' is
not transposed.  Refer to \verb'GxB_Matrix_subassign' for further details.

\paragraph{\bf Performance considerations:} % C(i,J) = u'
\verb'GrB_Col_assign' is much faster than \verb'GrB_Row_assign' if the format
of \verb'C' is \verb'GxB_BY_COL'.  \verb'GrB_Row_assign' is much faster than
\verb'GrB_Col_assign' if the format of \verb'C' is \verb'GxB_BY_ROW'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_assign\_$<$type$>$:} assign a scalar to a subvector}
%-------------------------------------------------------------------------------
\label{assign_vector_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // w<mask>(I) = accum (w(I),x)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),x)
    const <type> x,                 // scalar to assign to w(I)
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_assign_<type>' assigns a single scalar to an entire subvector
of the vector \verb'w'.  The operation is exactly like setting a single entry
in an \verb'n'-by-1 matrix, \verb'A(I,0) = x', where the column index for a
vector is implicitly \verb'j=0'.  The \verb'mask' vector has the same size as
\verb'w'.  For further details of this function, see
\verb'GrB_Matrix_assign_<type>' in the next section.

In contrast to \verb'GxB_Vector_subassign_<type>', results are well-defined if
\verb'I' contains duplicate indices.  Duplicate indices are simply ignored.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_assign\_$<$type$>$:} assign a scalar to a submatrix}
%-------------------------------------------------------------------------------
\label{assign_matrix_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<Mask>(I,J) = accum (C(I,J),x)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C(I,J),x)
    const <type> x,                 // scalar to assign to C(I,J)
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C and Mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_assign_<type>' assigns a single scalar to an entire
submatrix of \verb'C', like the {\em scalar expansion} \verb'C(I,J)=x' in
MATLAB.  The scalar \verb'x' is implicitly expanded into a matrix \verb'A' of
size \verb'ni' by \verb'nj', and then the matrix \verb'A' is assigned to
\verb'C(I,J)' using the same method as in \verb'GrB_Matrix_assign'.  Refer
to that function in Section~\ref{assign_matrix} for further details.

The \verb'Mask' has the same size as \verb'C'.

For the accumulation step, the scalar \verb'x' is typecasted directly into the
type of \verb'C' when the \verb'accum' operator is not applied to it, or into
the \verb'ytype' of the \verb'accum' operator, if \verb'accum' is not NULL, for
entries that are already present in \verb'C'.

The \verb'<type> x' notation is otherwise the same as
\verb'GrB_Matrix_setElement' (see Section~\ref{matrix_setElement}).  Any value
can be passed to this function and its type will be detected, via the
\verb'_Generic' feature of ANSI C11.  For a user-defined type, \verb'x' is a
\verb'void *' pointer that points to a memory space holding a single entry of a
scalar that has exactly the same user-defined type as the matrix \verb'C'.
This user-defined type must exactly match the user-defined type of \verb'C'
since no typecasting is done between user-defined types.

If a \verb'void *' pointer is passed in and the type of the underlying scalar
does not exactly match the user-defined type of \verb'C', then results are
undefined.  No error status will be returned since GraphBLAS has no way of
catching this error.

In contrast to \verb'GxB_Matrix_subassign_<type>', results are well-defined if
\verb'I' or \verb'J' contain duplicate indices.  Duplicate indices
are simply ignored.

\paragraph{\bf Performance considerations:} % C(I,J) = scalar
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%===============================================================================
\subsection{Comparing {\sf GrB\_assign} and {\sf GxB\_subassign}} %=============
%===============================================================================
\label{compare_assign}

% \begin{spec}
% {\bf SPEC:} \verb'GxB_subassign' is an extension to the spec.
% \end{spec}

The \verb'GxB_subassign' and \verb'GrB_assign' operations are very similar, but
they differ in three ways:

\begin{enumerate}
\item {\bf The Mask has a different size:}
    The mask in \verb'GxB_subassign' has the same dimensions as \verb'w(I)' for
    vectors and \verb'C(I,J)' for matrices.  In \verb'GrB_assign', the mask is
    the same size as \verb'w' or \verb'C', respectively (except for the row/col
    variants).  The two masks are related.  If \verb'M' is the mask for
    \verb'GrB_assign', then \verb'M(I,J)' is the mask for \verb'GxB_subassign'.
    If there is no mask, or if \verb'I' and \verb'J' are both \verb'GrB_ALL',
    the two masks are the same.
    For \verb'GrB_Row_assign' and \verb'GrB_Col_assign', the \verb'mask' vector
    is the same size as a row or column of \verb'C', respectively.  For the
    corresponding \verb'GxB_Row_subassign' and \verb'GxB_Col_subassign'
    operations, the \verb'mask' is the same size as the sub-row \verb'C(i,J)' or
    subcolumn \verb'C(I,j)', respectively.

\item {\bf \verb'GrB_REPLACE' is different:}
    They differ in how \verb'C' is affected in areas outside the \verb'C(I,J)'
    submatrix.  In \verb'GxB_subassign', the \verb'C(I,J)' submatrix is the
    only part of \verb'C' that can be modified, and no part of \verb'C' outside
    the submatrix is ever modified.  In \verb'GrB_assign', it is possible to
    delete entries in \verb'C' outside the submatrix, but only in one specific
    manner.  Suppose the mask \verb'M' is present (or, suppose it is not
    present but \verb'GrB_SCMP' is true).  After (optionally) complementing the
    mask, the value of \verb'M(i,j)' can be 0 for some entry outside the
    \verb'C(I,J)' submatrix.  If the \verb'GrB_REPLACE' descriptor is
    true, \verb'GrB_assign' deletes this entry.

\item {\bf Scalar expansion when duplicates appear in \verb'I' or \verb'J':} \\
    They differ in how duplicate indices are treated in \verb'I' and \verb'J'.
    For both \verb'assign' and \verb'subassign', results are not defined for
    \verb'GrB_Matrix_*assign', \verb'GrB_Vector_*assign',
    \verb'GrB_Row_*assign', and \verb'GrB_Col_*assign' when duplicate indices
    appear in \verb'I' or \verb'J'.  The scalar expansion operations,
    \verb'GrB_*_assign_<type>', are well-defined if duplicate indices appear
    (the results are the same as if duplicates are removed first from \verb'I'
    and \verb'J').  However, the scalar expansion operations
    \verb'GxB_*_subassign_<type>' are not well-defined if duplicate indices
    appear in \verb'I' or \verb'J'.

\end{enumerate}

% \newpage
\verb'GxB_subassign' and \verb'GrB_assign' are identical if \verb'GrB_REPLACE'
is set to its default value of false, and if the masks happen to be the same.
The two masks can be the same in two cases:  either the \verb'Mask' input is
\verb'NULL' (and it is not complemented via \verb'GrB_SCMP'), or \verb'I' and
\verb'J' are both \verb'GrB_ALL'.  For scalar expansion, no duplicates can
appear in the index lists \verb'I' and \verb'J'.  If all these conditions hold,
the two algorithms are identical and have the same performance.  Otherwise,
\verb'GxB_subassign' is much faster than \verb'GrB_assign' when the latter
must examine the entire matrix \verb'C' to delete entries (when
\verb'GrB_REPLACE' is true), and if it must deal with a much larger \verb'Mask'
matrix.  However, both methods have specific uses.

Consider using \verb'C(I,J)+=F' for many submatrices \verb'F' (for example,
when assembling a finite-element matrix).  If the \verb'Mask' is meant as a
specification for which entries of \verb'C' should appear in the final result,
then use \verb'GrB_assign'.

If instead the \verb'Mask' is meant to control which entries of the submatrix
\verb'C(I,J)' are modified by the finite-element \verb'F', then use
\verb'GxB_subassign'.  This is particularly useful is the \verb'Mask' is a
template that follows along with the finite-element \verb'F', independent of
where it is applied to \verb'C'.  Using \verb'GrB_assign' would be very
difficult in this case since a new \verb'Mask', the same size as \verb'C',
would need to be constructed for each finite-element \verb'F'.

In GraphBLAS notation, the two methods can be described as follows:

\vspace{0.05in}
\begin{tabular}{ll}
\hline
matrix and vector subassign & ${\bf C(I,J) \langle M \rangle}  = {\bf C(I,J)} \odot {\bf A}$ \\
matrix and vector    assign & ${\bf C \langle M \rangle (I,J)} = {\bf C(I,J)} \odot {\bf A}$ \\
\hline
\end{tabular}
\vspace{0.05in}

This notation does not include the details of the \verb'GrB_SCMP' and
\verb'GrB_REPLACE' descriptors, but it does illustrate the difference in the
\verb'Mask'.  In the subassign, \verb'Mask' is the same size as \verb'C(I,J)'
and \verb'A'.  If \verb'I[0]=i' and \verb'J[0]=j', Then \verb'Mask(0,0)'
controls how \verb'C(i,j)' is modified by the subassign, from the value
\verb'A(0,0)'.  In the assign, \verb'Mask' is the same size as \verb'C', and
\verb'Mask(i,j)' controls how \verb'C(i,j)' is modified.

The \verb'GxB_subassign' and \verb'GrB_assign' functions have the same
signatures; they differ only in how they consider the \verb'Mask' and the
\verb'GrB_REPLACE' descriptor, and in how duplicate indices are treated for
scalar expansion.

Details of each step of the two operations are listed below:

\vspace{0.1in}
\begin{tabular}{lll}
\hline
Step & \verb'GrB_Matrix_assign'                & \verb'GxB_Matrix_subassign'                        \\
\hline
1 & ${\bf S} = {\bf C(I,J)}$                & ${\bf S} = {\bf C(I,J)}$                              \\
2 & ${\bf S} = {\bf S} \odot {\bf A}$       & ${\bf S \langle M \rangle} = {\bf S} \odot {\bf A}$   \\
3 & ${\bf Z} = {\bf C}$                     & ${\bf C(I,J)}= {\bf S}$                               \\ 
4 & ${\bf Z(I,J)} = {\bf S}$                &                                                       \\
5 & ${\bf C \langle M \rangle = Z}$         &                                                       \\
\hline
\end{tabular}
\vspace{0.1in}

Step 1 is the same.  In the Accumulator Phase (Step 2), the expression
${\bf S} \odot {\bf A}$,
described in Section~\ref{accummask}, is the same in both
operations.  The result is simply ${\bf A}$ if \verb'accum' is \verb'NULL'.  It
only applies to the submatrix ${\bf S}$, not the whole matrix.
The result ${\bf S} \odot {\bf A}$ is used differently in the Mask/Replace phase.

The Mask/Replace Phase, described in Section~\ref{accummask} is different:
\begin{itemize}
\item
    For \verb'GrB_assign' (Step 5), the mask is applied to all of ${\bf
    C}$.  The mask has the same size as ${\bf C}$.  Just prior to making the
    assignment via the mask, the \verb'GrB_REPLACE' option can be used to clear
    all of ${\bf C}$ first.  This is the only way in which entries in ${\bf C}$ that
    are outside the ${\bf C(I,J)}$ submatrix can be modified by this operation.

\item
    For \verb'GxB_subassign' (Step 2b), the mask is applied to just
    ${\bf S}$.  The mask has the same size as ${\bf C(I,J)}$, ${\bf S}$, and
    ${\bf A}$.  Just prior to making the assignment via the mask, the
    \verb'GrB_REPLACE' option can be used to clear ${\bf S}$ first.  No entries
    in ${\bf C}$ that are outside the ${\bf C(I,J)}$ can be modified by this
    operation.  Thus, \verb'GrB_REPLACE' has no effect on entries in ${\bf C}$
    outside the ${\bf C(I,J)}$ submatrix.

\end{itemize}

The differences between \verb'GrB_assign' and
\verb'GxB_subassign' can be seen in Tables~\ref{insubmatrix} and
\ref{outsubmatrix}.  The first table considers the case when the entry $c_{ij}$
is in the ${\bf C(I,J)}$ submatrix, and it describes what is computed for both
\verb'GrB_assign' and \verb'GxB_subassign'.  They perform the
exact same computation; the only difference is how the value of the mask is
specified.

The first column of the table is {\em yes} if \verb'GrB_REPLACE' is enabled,
and a dash otherwise.  The second column is {\em yes} if an accumulator
operator is given, and a dash otherwise.  The third column is $c_{ij}$ if the
entry is present in ${\bf C}$, and a dash otherwise.  The fourth column is
$a_{i'j'}$ if the corresponding entry is present in ${\bf A}$, where
$i={\bf I}(i')$ and $j={\bf J}(i')$.

The {\em mask} column is 1 if the mask allows ${\bf C}$ to be modified, and 0
otherwise.  This is $m_{ij}$ for \verb'GrB_assign', and $m_{i'j'}$ for
\verb'GxB_subassign', to reflect the difference in the mask, but this
difference is not reflected in the table.  The value 1 or 0 is the value of the
entry in the mask after it is optionally complemented via the \verb'GrB_SCMP'
option.

Finally, the last column is the action taken in this case.  It is left blank if
no action is taken, in which case $c_{ij}$ is not modified if present, or not
inserted into ${\bf C}$ if not present.

\begin{table}
{\small
\begin{tabular}{lllll|l}
\hline
repl & accum & ${\bf C}$ & ${\bf A}$ & mask & action taken by \verb'GrB_assign' and \verb'GxB_subassign'\\
\hline
    -  &-   & $c_{ij}$ & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, update \\
    -  &-   &  -       & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, insert \\
    -  &-   & $c_{ij}$ &  -          & 1    &  delete $c_{ij}$ because $a_{i'j'}$ not present \\
    -  &-   &  -       &  -          & 1    &   \\
\hline
    -  &-   & $c_{ij}$ & $a_{i'j'}$  & 0    &   \\
    -  &-   &  -       & $a_{i'j'}$  & 0    &   \\
    -  &-   & $c_{ij}$ &  -          & 0    &   \\
    -  &-   &  -       &  -          & 0    &   \\
\hline
    yes&-   & $c_{ij}$ & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, update \\
    yes&-   &  -       & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, insert \\
    yes&-   & $c_{ij}$ &  -          & 1    &  delete $c_{ij}$ because $a_{i'j'}$ not present \\
    yes&-   &  -       &  -          & 1    &   \\
\hline
    yes&-   & $c_{ij}$ & $a_{i'j'}$  & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&-   &  -       & $a_{i'j'}$  & 0    &   \\
    yes&-   & $c_{ij}$ &  -          & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&-   &  -       &  -          & 0    &   \\
\hline
    -  &yes & $c_{ij}$ & $a_{i'j'}$  & 1    &  $c_{ij} = c_{ij} \odot a_{i'j'}$, apply accumulator \\
    -  &yes &  -       & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, insert \\
    -  &yes & $c_{ij}$ &  -          & 1    &   \\
    -  &yes &  -       &  -          & 1    &   \\
\hline
    -  &yes & $c_{ij}$ & $a_{i'j'}$  & 0    &   \\
    -  &yes &  -       & $a_{i'j'}$  & 0    &   \\
    -  &yes & $c_{ij}$ &  -          & 0    &   \\
    -  &yes &  -       &  -          & 0    &   \\
\hline
    yes&yes & $c_{ij}$ & $a_{i'j'}$  & 1    &  $c_{ij} = c_{ij} \odot a_{i'j'}$, apply accumulator \\
    yes&yes &  -       & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, insert \\
    yes&yes & $c_{ij}$ &  -          & 1    &   \\
    yes&yes &  -       &  -          & 1    &   \\
\hline
    yes&yes & $c_{ij}$ & $a_{i'j'}$  & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&yes &  -       & $a_{i'j'}$  & 0    &   \\
    yes&yes & $c_{ij}$ &  -          & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&yes &  -       &  -          & 0    &   \\
\hline
\end{tabular}
}
\caption{Results of assign and subassign for entries in the ${\bf C(I,J)}$ submatrix \label{insubmatrix}}
\end{table}

\newpage
Table~\ref{outsubmatrix} illustrates how \verb'GrB_assign' and
\verb'GxB_subassign' differ for entries outside the submatrix.
\verb'GxB_subassign' never modifies any entry outside the ${\bf C(I,J)}$
submatrix, but \verb'GrB_assign' can modify them in two cases listed in
Table~\ref{outsubmatrix}.  When the \verb'GrB_REPLACE' option is selected, and
when the \verb'Mask(i,j)' for an entry $c_{ij}$ is false (or if the
\verb'Mask(i,j)' is true and \verb'GrB_SCMP' is enabled via the descriptor),
then the entry is deleted by \verb'GrB_assign'.

The fourth column of Table~\ref{outsubmatrix} differs from
Table~\ref{insubmatrix}, since entries in ${\bf A}$ never affect these entries.
Instead, for all index pairs outside the $I \times J$ submatrix, ${\bf C}$ and
${\bf Z}$ are identical (see Step 3 above).  As a result, each section of the
table includes just two cases: either $c_{ij}$ is present, or not.   This in
contrast to Table~\ref{insubmatrix}, where each section must consider four
different cases.

The \verb'GrB_Row_assign' and \verb'GrB_Col_assign' operations are slightly
different.  They only affect a single row or column of ${\bf C}$.
For \verb'GrB_Row_assign', Table~\ref{outsubmatrix} only applies to entries in
the single row \verb'C(i,J)' that are outside the list of indices, \verb'J'.
For \verb'GrB_Col_assign', Table~\ref{outsubmatrix} only applies to entries in
the single column \verb'C(I,j)' that are outside the list of indices, \verb'I'.

\begin{table}
{\small
\begin{tabular}{lllll|l}
\hline
repl & accum & ${\bf C}$ & ${\bf C=Z}$ & mask & action taken by \verb'GrB_assign' \\
\hline
   -   &-     & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   -   &-     &  -       & -        & 1 &  \\
\hline
   -   &-     & $c_{ij}$ & $c_{ij}$ & 0 &  \\
   -   &-     &  -       & -        & 0 &  \\
\hline
   yes &  -   & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   yes &  -   &    -     &     -    & 1 &  \\
\hline
   yes &  -   & $c_{ij}$ & $c_{ij}$ & 0 & delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
   yes &  -   &    -     &  -       & 0 &  \\
\hline
   -   &yes   & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   -   &yes   &    -     &  -       & 1 &  \\
\hline
   -   &yes   & $c_{ij}$ & $c_{ij}$ & 0 &  \\
   -   &yes   &    -     &  -       & 0 &  \\
\hline
   yes &  yes & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   yes &  yes &   -      &  -       & 1 &  \\
\hline
   yes &  yes & $c_{ij}$ & $c_{ij}$ & 0 & delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
   yes &  yes &   -      &  -       & 0 &  \\
\hline
\end{tabular}
}
\caption{Results of assign for entries outside the
${\bf C(I,J)}$ submatrix.  Subassign has no effect on these entries. \label{outsubmatrix}}
\end{table}

%-------------------------------------------------------------------------------
\subsubsection{Example}
%-------------------------------------------------------------------------------

The difference between \verb'GxB_subassign' and \verb'GrB_assign' is
illustrated in the following example.  Consider the 2-by-2 matrix ${\bf C}$
where all entries are present.

\[
{\bf C} = \left[
    \begin{array}{rr}
    11 & 12 \\
    21 & 22 \\
    \end{array}
    \right]
\]

Suppose \verb'GrB_REPLACE' is true, and \verb'GrB_SCMP' is false.  Let the
\verb'Mask' be:

\[
{\bf M} = \left[
    \begin{array}{rr}
    1 & 1 \\
    0 & 1 \\
    \end{array}
    \right].
\]

Let ${\bf A} = 100$, and let the index sets be ${\bf I}=0$ and ${\bf J}=1$.
Consider the computation
${\bf C \langle M \rangle} (0,1) = {\bf C}(0,1) + {\bf A}$,
using the \verb'GrB_assign' operation.  The result is:
\[
{\bf C} = \left[
    \begin{array}{rr}
    11 & 112 \\
     - &  22 \\
    \end{array}
    \right].
\]
The $(0,1)$ entry is updated and the $(1,0)$ entry is deleted because
its \verb'Mask' is zero.  The other two entries are not modified since ${\bf Z}
= {\bf C}$ outside the submatrix, and those two values are written back into
${\bf C}$ because their \verb'Mask' values are 1.  The $(1,0)$ entry is deleted
because the entry ${\bf Z}(1,0)=21$ is prevented from being written back into
${\bf C}$ since \verb'Mask(1,0)=0'.

Now consider the analogous \verb'GxB_subassign' operation.  The \verb'Mask' has
the same size as ${\bf A}$, namely:
\[
{\bf M} = \left[
    \begin{array}{r}
    1 \\
    \end{array}
    \right].
\]

After computing
${\bf C} (0,1) {\bf \langle M \rangle} = {\bf C}(0,1) + {\bf A}$,
the result is

\[
{\bf C} = \left[
    \begin{array}{rr}
    11 & 112 \\
    21 &  22 \\
    \end{array}
    \right].
\]

Only the ${\bf C(I,J)}$ submatrix, the single entry ${\bf C}(0,1)$, is modified
by \verb'GxB_subassign'.  The entry ${\bf C}(1,0)=21$ is unaffected by
\verb'GxB_subassign', but it is deleted by \verb'GrB_assign'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{Performance of {\sf GxB\_subassign}, {\sf GrB\_assign}
and {\sf GrB\_*\_setElement}}
%-------------------------------------------------------------------------------

When SuiteSparse:GraphBLAS uses non-blocking mode, the modifications to a
matrix by \verb'GxB_subassign', \verb'GrB_assign', and \verb'GrB_*_setElement'
can postponed, and computed all at once later on.  This has a huge impact on
performance.

A sequence of assignments is fast if their completion can be postponed for as
long as possible, or if they do not modify the pattern at all.  Modifying the
pattern can be costly, but it is fast if non-blocking mode can be fully
exploited.

Consider a sequence of $t$ submatrix assignments \verb'C(I,J)=C(I,J)+A' to an
$n$-by-$n$ matrix \verb'C' where each submatrix \verb'A' has size $a$-by-$a$
with $s$ entries, and where \verb'C' starts with $c$ entries.
Assume the matrices are all stored in non-hypersparse form, by row
(\verb'GxB_BY_ROW').

If blocking mode is enabled, or if the sequence requires the matrix to be
completed after each assignment, each of the $t$ assignments takes $O(a + s
\log n)$ time to process the \verb'A' matrix and then $O(n + c + s \log s)$
time to complete \verb'C'.  The latter step uses \verb'GrB_*_build' to build an
update matrix and then merge it with \verb'C'.  This step does not occur if the
sequence of assignments does not add new entries to the pattern of \verb'C',
however.  Assuming in the worst case that the pattern does change, the total
time is $O (t \left[ a + s \log n + n + c + s \log s \right] )$.

If the sequence can be computed with all updates postponed until the end of the
sequence, then the total time is no worse than $O(a + s \log n)$ to process
each \verb'A' matrix, for $t$ assignments, and then a single \verb'build' at
the end, taking $O(n + c + st \log st)$ time.
The total time is $O (t \left [a + s \log n \right] + (n + c + st \log st))$.
If no new entries appear in
\verb'C' the time drops to $O (t \left [a + s \log n \right])$, and in this
case, the time for both methods is the same; both are equally efficient.

A few simplifying assumptions are useful to compare these times.  Consider a
graph of $n$ nodes with $O(n)$ edges, and with a constant bound on the degree
of each node.  The asymptotic bounds assume a worst-case scenario where
\verb'C' has a least some dense rows (thus the $\log n$ terms).  If these
are not present, if both $t$ and $c$ are $O(n)$, and if $a$ and $s$ are
constants, then the total time with blocking mode becomes $O(n^2)$, assuming
the pattern of \verb'C' changes at each assignment.  This very high for a
sparse graph problem.  In contrast, the non-blocking time becomes $O(n \log n)$
under these same assumptions, which is asymptotically much faster.

\newpage
The difference in practice can be very dramatic, since $n$ can be many millions
for sparse graphs with $n$ nodes and $O(n)$, which can be handled on a
commodity laptop.

The following guidelines should be considered when using
\verb'GxB_subassign', \verb'GrB_assign' and \verb'GrB_*_setElement'.

\begin{enumerate}

\item A sequence of assignments that does not modify the pattern at all is
fast, taking as little as $\Omega(1)$ time per entry modified.  The worst case
time complexity is $O(\log n)$ per entry, assuming they all modify a dense
row of \verb'C' with \verb'n' entries, which can occur in practice.  It is
more common, however, that most rows of \verb'C' have a constant number of
entries, independent of \verb'n'.  No work is ever left pending when the
pattern of \verb'C' does not change.

\item A sequence of assignments that modifies the entries that already exist in
the pattern of a matrix, or adds new entries to the pattern (using the same
\verb'accum' operator), but does not delete any entries, is fast.  The matrix
is not completed until the end of the sequence.

\item Similarly, a sequence that modifies existing entries, or deletes them,
but does not add new ones, is also fast.  This sequence can also repeatedly
delete pre-existing entries and then reinstate them and still be fast.  The
matrix is not completed until the end of the sequence.

\item A sequence that mixes assignments of types (2) and (3) above can be
costly, since the matrix may need to be completed after each assignment.  The
time complexity can become quadratic in the worst case.

\item However, any single assignment takes no more than $O (a + s \log n + n +
c + s \log s )$ time, even including the time for a matrix completion, where
\verb'C' is $n$-by-$n$ with $c$ entries and \verb'A' is $a$-by-$a$ with $s$
entries.  This time is essentially linear in the size of the matrix \verb'C',
if \verb'A' is relatively small and sparse compared with \verb'C'.  In this
case, $n+c$ are the two dominant terms.

\item In general, \verb'GxB_subassign' is faster than \verb'GrB_assign'.
If \verb'GrB_REPLACE' is used with \verb'GrB_assign', the entire matrix
\verb'C' must be traversed.  This is much slower than \verb'GxB_subassign',
which only needs to examine the \verb'C(I,J)' submatrix.  Furthermore,
\verb'GrB_assign' must deal with a much larger \verb'Mask' matrix, whereas
\verb'GxB_subassign' has a smaller mask.  Since its mask is smaller,
\verb'GxB_subassign' takes less time than \verb'GrB_assign' to access the mask.

\end{enumerate}

Submatrix assignment in SuiteSparse:GraphBLAS is extremely efficient, even
without considering the advantages of non-blocking mode discussed in
Section~\ref{compare_assign}.  Consider assigning a large submatrix
\verb'C(I,J)=A' where \verb'C' is the \verb'Freescale2' matrix from the
SuiteSparse Collection \cite{DavisHu11}, of size 3 million by 3 million, with
14.3 million nonzeros.  With the vectors \verb'I=randperm(n,5500)' and
\verb'J=randperm(n,7000)' and \verb'A' a random sparse matrix with 38,500
nonzeros, \verb'C(I,J)=A' takes 87 seconds in MATLAB.\footnote{All performance
measurements in this document were done on a  MacBook Pro, 2.8 GHz Intel Core
i7, 16 GB Ram, OSX 10.11.6, clang 8.0.0, MATLAB R2017A.} The same computation
takes 0.74 seconds in SuiteSparse:GraphBLAS, a speedup of over 100.  This is
after finishing all pending computations in GraphBLAS and returning result to
MATLAB as a valid MATLAB sparse matrix.  The dominant time complexity for
GraphBLAS is $O(n+c)$, where $n$ is the dimension of \verb'C' and $c$ is its
number of nonzeros.  As a comparison, MATLAB takes just 0.42 seconds to compute
\verb"C+C'" for this matrix, which also takes time linear in the size of the
matrix data structure, $O(n+c)$.

The time for submatrix assignment can be greatly reduced if \verb'C' is
hypersparse.  Let $\bar{n}$ be the number of non-empty rows, where $\bar{n}<n$,
and sometimes $\bar{n} << n$.  The $\log n$ terms remain since they reflect the
binary search inside a row, but the term $n$ by itself is replaced by
$\bar{n}$ or $\bar{n} \log \bar{n}$.  The term $a$ is replaced by $a \log
\bar{n}$.  The total time for a sequence of $t$ updates to a hypersparse matrix
$C$ takes $O (t \left [a \log \bar{n} + s \log n \right] + (\bar{n} + c + st
\log st))$ time.  This assumes that \verb'C' could include one or more dense
rows, with $n$ entries.  If instead the number of entries in each row of
\verb'C' is bounded by a constant, the $\log n$ term becomes a constant.  If
\verb'A' is also hypersparse, the value $a$ is removed from the expression,
replaced with its number of non-empty rows, $\bar{a}$.  Suppose also $t$ is
a constant, and $s$ is $O(\bar{a})$.  Suppose the pattern of \verb'C' changes.
Suppose the number of entries in any one row of \verb'C' is bounded by
$\bar{n}$, and likewise for \verb'A'.  Then the time for the non-hypersparse
case simplifies to:
\[ O ( a                    + s \log \bar{n} + (n       + c + s \log s)). \]
For the hypersparse case it becomes
\[ O ( \bar{a} \log \bar{n} + s \log \bar{n} + (\bar{n} + c + s \log s)). \]
Both of these times include the similar terms
\[ O (                        s \log \bar{n} + (          c + s \log s)), \]
which reflects the sorting of and searching of the nonzero entries themselves,
in \verb'C' and \verb'A'.
Excluding those terms and just considering the additional time,
the non-hypersparse case takes an extra time of
\[ O ( a                    +                   n                      ), \]
whereas the hypersparse case takes only:
\[ O ( \bar{a} \log \bar{n} +                   \bar{n}                ). \]

The difference is astonishing if $\bar{n} << n$ and $\bar{a} << a$.
Hypersparse \verb'C' and \verb'A' matrices can be created with $a = n =
2^{60}$, but suppose $\bar{a} = \bar{n} = 2^{24}$, say, which is 4 million.
Then $\bar{a} \log_{2} \bar{n} + \bar{n}$ is only about 420 million.  In stark
contrast, updating the same matrices held in non-hypersparse form would take
$2^{60}$ time and memory, a number currently beyond the reach of the world's
largest supercomputer.

If the matrices \verb'C' and \verb'A' have no empty columns or rows, then
$\bar{a} = a$ and $\bar{n}=n$.  Hypersparse matrices are more costly in this
case, since they still require an extra $\log n$ term to search for a specific
row in \verb'C'.  As a result, SuiteSparse:GraphBLAS supports both
hypersparse and non-hypersparse data structures.

\newpage
%===============================================================================
\subsection{{\sf GrB\_apply:} apply a unary operator} %=========================
%===============================================================================
\label{apply}

The \verb'GrB_apply' function is the generic name for two specific functions:
\\ \verb'GrB_Vector_apply' and  \verb'GrB_Matrix_apply'.  The generic name
appears in the function prototypes, but the specific function name is used when
describing each variation.  When discussing features that apply to both
versions, the simple name \verb'GrB_apply' is used.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_apply:} apply a unary operator to a vector}
%-------------------------------------------------------------------------------
\label{apply_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_apply                  // w<mask> = accum (w, op(u))
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_UnaryOp op,           // operator to apply to the entries
    const GrB_Vector u,             // first input:  vector u
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_apply' applies a unary operator to the entries of a vector,
analogous to \verb't = op(u)'  in MATLAB except the operator \verb'op' is only
applied to entries in the pattern of \verb'u'.  Implicit values outside the
pattern of \verb'u' are not affected.  The entries in \verb'u' are typecasted
into the \verb'xtype' of the unary operator.  The vector \verb't' has the same
type as the \verb'ztype' of the unary operator.  The final step is ${\bf w
\langle m \rangle  = w \odot t}$, as described in Section~\ref{accummask},
except that all the terms are column vectors instead of matrices.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_apply:} apply a unary operator to a matrix}
%-------------------------------------------------------------------------------
\label{apply_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_apply                  // C<Mask> = accum (C, op(A)) or op(A')
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const GrB_UnaryOp op,           // operator to apply to the entries
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Descriptor desc       // descriptor for C, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_apply'
applies a unary operator to the entries of a matrix, analogous to
\verb'T = op(A)'  in MATLAB except the operator \verb'op' is only applied to
entries in the pattern of \verb'A'.  Implicit values outside the pattern of
\verb'A' are not affected.  The input matrix \verb'A' may be transposed first.
The entries in \verb'A' are typecasted into the \verb'xtype' of the unary
operator.  The matrix \verb'T' has the same type as the \verb'ztype' of the
unary operator.  The final step is ${\bf C \langle M \rangle  = C \odot T}$, as
described in Section~\ref{accummask}.

The built-in \verb'GrB_IDENTITY_'$T$ operators (one for each built-in type $T$)
are very useful when combined with this function, enabling it to compute ${\bf
C \langle M \rangle  = C \odot A}$.  This makes \verb'GrB_apply' a direct
interface to the accumulator/mask function for both matrices and vectors.

To compute ${\bf C \langle M \rangle = A}$ or ${\bf C \langle M \rangle = C
\odot A}$ for user-defined types, the user application would need to define an
identity operator for the type.  Since GraphBLAS cannot detect that it is an
identity operator, it must call the operator to make the full copy \verb'T=A'
and apply the operator to each entry of the matrix or vector.

The other GraphBLAS operation that provides a direct interface to the
accumulator/mask function is \verb'GrB_transpose', which does not require an
operator to perform this task.  As a result, \verb'GrB_transpose' can be used
as an efficient and direct interface to the accumulator/mask function for
both built-in and user-defined types.  However, it is only available for
matrices, not vectors.

\newpage
%===============================================================================
\subsection{{\sf GxB\_select:} apply a select operator} %=======================
%===============================================================================
\label{select}

The \verb'GxB_select' function is the generic name for two specific functions:
\\ \verb'GxB_Vector_select' and  \verb'GxB_Matrix_select'.  The generic name
appears in the function prototypes, but the specific function name is used when
describing each variation.  When discussing features that apply to both
versions, the simple name \verb'GxB_select' is used.

\begin{spec}
{\bf SPEC:} The \verb'GxB_select' operation and \verb'GxB_SelectOp' operator
are extensions to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_select:} apply a select operator to a vector}
%-------------------------------------------------------------------------------
\label{select_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_select                 // w<mask> = accum (w, op(u,k))
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GxB_SelectOp op,          // operator to apply to the entries
    const GrB_Vector u,             // first input:  vector u
    const void *k,                  // optional input for the select operator
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_select' applies a select operator to the entries of a vector,
analogous to \verb't = u.*op(u)'  in MATLAB except the operator \verb'op' is
only applied to entries in the pattern of \verb'u'.  Implicit values outside
the pattern of \verb'u' are not affected.  If the operator is not type-generic,
the entries in \verb'u' are typecasted into the \verb'xtype' of the select
operator.  The vector \verb't' has the same type and size as \verb'u'.  The
final step is ${\bf w \langle m \rangle  = w \odot t}$, as described in
Section~\ref{accummask}, except that all the terms are column vectors instead
of matrices.

This operation operates on vectors just as if they were \verb'm'-by-1 matrices,
except that GraphBLAS never transposes a vector via the descriptor.  The
\verb'op' is passed \verb'n=1' as the number of columns.  Refer to the next
section on \verb'GxB_Matrix_select' for more details.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_select:} apply a select operator to a matrix}
%-------------------------------------------------------------------------------
\label{select_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_select                 // C<Mask> = accum (C, op(A,k)) or op(A',k)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const GxB_SelectOp op,          // operator to apply to the entries
    const GrB_Matrix A,             // first input:  matrix A
    const void *k,                  // optional input for the select operator
    const GrB_Descriptor desc       // descriptor for C, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_select' applies a select operator to the entries of a matrix,
analogous to \verb'T = A .* op(A)'  in MATLAB except the operator \verb'op' is
only applied to entries in the pattern of \verb'A'.  Implicit values outside
the pattern of \verb'A' are not affected.  The input matrix \verb'A' may be
transposed first.  If the operator is not type-generic, the entries in \verb'A'
are typecasted into the \verb'xtype' of the select operator.  The final step is
${\bf C \langle M \rangle  = C \odot T}$, as described in
Section~\ref{accummask}.

The matrix \verb'T' has the same size and type as \verb'A' (or the transpose of
\verb'A' if the input is transposed via the descriptor).  The entries of
\verb'T' are a subset of those of \verb'A'.  Each entry \verb'A(i,j)' of
\verb'A' is passed to the \verb'op', as $z=f(i,j,m,n,a_{ij},k)$, where \verb'A'
is $m$-by-$n$.  If \verb'A' is transposed first then the operator is applied to
entries in the transposed matrix, \verb"A'".  If $z$ is returned as true, then
the entry is copied into \verb'T', unchanged.  If it returns false, the entry
does not appear in \verb'T'.

For user-defined select operators, the argument \verb'k' is passed to the
operator unchanged.  For built-in operators, \verb'k' is a pointer to an
\verb'int64_t' scalar that refers to the \verb'k'th diagonal of the matrix.
The value \verb'k=0' specifies the main diagonal of the matrix, \verb'k=1' is
the +1 diagonal (the entries just above the main diagonal), \verb'k=-1' is the
-1 diagonal, and so on.  Note that \verb'k' must be passed as a pointer to
\verb'int64_t', not merely as an integer.  The parameter \verb'k' is not used
by \verb'GxB_NONZERO' and may be passed as \verb'GrB_NULL'.

The action of \verb'GxB_select' with the built-in select operators is described
in the table below.  The MATLAB analogs are precise for \verb'tril' and
\verb'triu', but shorthand for the other operations.  The MATLAB \verb'diag'
function returns a column with the diagonal, if \verb'A' is a matrix, whereas
the matrix \verb'T' in \verb'GxB_select' always has same size as \verb'A' (or
its transpose if the \verb'GrB_INP0' is set to \verb'GrB_TRAN').  In the MATLAB
analog column, \verb'diag' is as if it operates like \verb'GxB_select', where
\verb'T' is a matrix.

\vspace{0.2in}
{\small
\begin{tabular}{llp{3in}}
\hline
GraphBLAS               & MATLAB            & \\
name                   & analog            & \\
\hline
\verb'GxB_TRIL'         & \verb'T=tril(A,k)'   &
    Entries in \verb'T' are the entries on and below the \verb'k'th diagonal of \verb'A'. \\
\verb'GxB_TRIU'         & \verb'T=triu(A,k)'   & 
    Entries in \verb'T' are the entries on and above the \verb'k'th diagonal of \verb'A'. \\
\verb'GxB_DIAG'         & \verb'T=diag(A,k)'   & 
    Entries in \verb'T' are the entries on the \verb'k'th diagonal of \verb'A'. \\
\verb'GxB_OFFDIAG'      & \verb'T=A-diag(A,k)' & 
    Entries in \verb'T' are all entries not on the \verb'k'th diagonal of \verb'A'. \\
\verb'GxB_NONZERO'      & \verb'T=A(A~=0)'     & 
    Entries in \verb'T' are all entries in \verb'A' that have nonzero value. \\
\hline
\end{tabular}
}
\vspace{0.2in}

\newpage
%===============================================================================
\subsection{{\sf GrB\_reduce:} reduce to a vector or scalar} %==================
%===============================================================================
\label{reduce}

The generic function name \verb'GrB_reduce' may be used for all specific
functions discussed in this section.  When the details of a specific function
are discussed, the specific name is used for clarity.


%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_reduce\_$<$op$>$:} reduce a matrix to a vector}
%-------------------------------------------------------------------------------
\label{reduce_to_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_reduce                 // w<mask> = accum (w,reduce(A))
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const <operator> reduce,        // reduce operator for t=reduce(A)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Descriptor desc       // descriptor for w, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_reduce_<op>' is a generic name for two specific methods.  Both
methods reduce a matrix to a column vector using an operator, roughly analogous
to \verb"t = sum (A')" in MATLAB, in the default case, where \verb't' is a
column vector.  By default, the method reduces across the rows to
obtain a column vector; use \verb'GrB_TRAN' to reduce down the columns.

\verb'GrB_Matrix_reduce_BinaryOp' relies on a binary operator for the
reduction: the fourth argument \verb'reduce', a \verb'GrB_BinaryOp'.  All three
domains of the operator must be the same.  \verb'GrB_Matrix_reduce_Monoid'
performs the same reduction using a \verb'GrB_Monoid' as its fourth argument.
In both cases the reduction operator must be commutative and associative.
Otherwise the results are undefined.

The input matrix \verb'A' may be transposed first.  Its entries are then
typecast into the type of the \verb'reduce' operator or monoid.  The reduction
is applied to all entries in \verb'A (i,:)' to produce the scalar \verb't (i)'.
This is done without the use of the identity value of the monoid.  If the
\verb'i'th row \verb'A (i,:)' has no entries, then \verb'(i)' is not an entry
in \verb't' and its value is implicit.  If \verb'A (i,:)' has a single entry,
then that is the result \verb't (i)' and \verb'reduce' is not applied at all
for the \verb'i'th row.  Otherwise, multiple entries in row \verb'A (i,:)' are
reduced via the \verb'reduce' operator or monoid to obtain a single scalar,
the result \verb't (i)'.

The final step is ${\bf w \langle m \rangle  = w \odot t}$, as described
in Section~\ref{accummask}, except that all the
terms are column vectors instead of matrices.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_reduce\_$<$type$>$:} reduce a vector to a scalar}
%-------------------------------------------------------------------------------
\label{reduce_vector_to_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_reduce                 // c = accum (c, reduce_to_scalar (u))
(
    <type> *c,                      // result scalar
    const GrB_BinaryOp accum,       // optional accum for c=accum(c,t)
    const GrB_Monoid monoid,        // monoid to do the reduction
    const GrB_Vector u,             // vector to reduce
    const GrB_Descriptor desc       // descriptor (currently unused)
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_reduce_<type>'
reduces a vector to a scalar, analogous to \verb't = sum (u)' in MATLAB,
except that in GraphBLAS any commutative and associative monoid can be used
in the reduction.

% There is no mask since the output is a mere scalar, not a GraphBLAS vector or
% matrix.  The result does not depend on whether or not the input can be
% transposed (and vectors cannot be transposed in any case).  The
% \verb'replace' option is not implemented for this function.  Thus, no
% parameters from the descriptor are used.

The reduction operator is a commutative and associative monoid with an identity
value.  Results are undefined if the monoid does not have these properties.
This function differs from \verb'GrB_Matrix_reduce_BinaryOp' (which reduces
a matrix to a vector) in that it requires a
valid monoid additive identity value.  If the vector \verb'u' has no entries,
that identity value is copied into the scalar \verb't'.  Otherwise, all of the
entries in the vector are reduced to a single scalar using the \verb'reduce'
operator.

The scalar type is any of the built-in types, or a user-defined type.  In the
function signature it is a C type: \verb'bool', \verb'int8_t', ...
\verb'float', \verb'double', or \verb'void *' for a user-defined type.
The user-defined type must be identical to the type of the vector \verb'u'.
This cannot be checked by GraphBLAS and thus results are undefined if the
types are not the same.

The descriptor is unused, but it appears in case it is needed in future
versions of the GraphBLAS API. 
This function has no mask so its accumulator/mask step differs from the other
GraphBLAS operations.  It does not use the methods described in
Section~\ref{accummask}, but uses the following method instead.

If \verb'accum' is \verb'NULL', then the scalar \verb't' is typecast into the
type of \verb'c', and \verb'c = t' is the final result.  Otherwise, the scalar
\verb't' is typecast into the \verb'ytype' of the \verb'accum' operator, and
the value of \verb'c' (on input) is typecast into the \verb'xtype' of the
\verb'accum' operator.  Next, the scalar \verb'z = accum (c,t)' is computed, of
the \verb'ztype' of the \verb'accum' operator.  Finally, \verb'z' is typecast
into the final result, \verb'c'.

\paragraph{Forced completion:}
All computations for the vector \verb'u' are
guaranteed to be finished when the method returns.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_reduce\_$<$type$>$:} reduce a matrix to a scalar}
%-------------------------------------------------------------------------------
\label{reduce_matrix_to_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_reduce                 // c = accum (c, reduce_to_scalar (A))
(
    <type> *c,                      // result scalar
    const GrB_BinaryOp accum,       // optional accum for c=accum(c,t)
    const GrB_Monoid monoid,        // monoid to do the reduction
    const GrB_Matrix A,             // matrix to reduce
    const GrB_Descriptor desc       // descriptor (currently unused)
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_reduce_<type>' reduces a matrix \verb'A' to a scalar, roughly
analogous to \verb't = sum (A (:))' in MATLAB.  This function is identical to
reducing a vector to a scalar, since the positions of the entries in a matrix
or vector have no effect on the result.  Refer to the reduction to scalar
described in the previous Section~\ref{reduce_vector_to_scalar}.

\paragraph{Forced completion:}
All computations for the matrix \verb'A' are
guaranteed to be finished when the method returns.

\newpage
%===============================================================================
\subsection{{\sf GrB\_transpose:} transpose a matrix} %=========================
%===============================================================================
\label{transpose}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_transpose              // C<Mask> = accum (C, A')
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Descriptor desc       // descriptor for C, Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_transpose'
transposes a matrix \verb'A', just like the array transpose \verb"T = A.'" in
MATLAB.  The internal result matrix \verb"T = A'" (or merely \verb"T = A" if
\verb'A' is transposed via the descriptor) has the same type as \verb'A'.  The
final step is ${\bf C \langle M \rangle  = C \odot T}$, as described in
Section~\ref{accummask}, which typecasts \verb'T' as needed and applies the
mask and accumulator.

To be consistent with the rest of the GraphBLAS API regarding the
descriptor, the input matrix \verb'A' may be transposed first.  It may seem
counter-intuitive, but this has the effect of not doing any transpose at all.
As a result, \verb'GrB_transpose' is useful for more than just transposing a
matrix.  It can be used as a direct interface to the accumulator/mask
operation, ${\bf C \langle M \rangle  = C \odot A}$.  This step also does any
typecasting needed, so \verb'GrB_transpose' can be used to typecast a matrix
\verb'A' into another matrix \verb'C'.  To do this, simply use \verb'NULL' for
the \verb'Mask' and \verb'accum', and provide a non-default descriptor
\verb'desc' that sets the transpose option:

    {\footnotesize
    \begin{verbatim}
    // C = typecasted copy of A
    GrB_Descriptor_set (desc, GrB_INP0, GrB_TRAN) ;
    GrB_transpose (C, NULL, NULL, A, desc) ; \end{verbatim}}

If the types of \verb'C' and match, then the above two lines of code are the
same as \verb'GrB_Matrix_dup (&C, A)', except that for \verb'GrB_transpose' the
matrix \verb'C' must already exist and be the right size.  If \verb'C' does not
exist, the work of \verb'GrB_Matrix_dup' can be replicated with this:

    {\footnotesize
    \begin{verbatim}
    // C = create an exact copy of A, just like GrB_Matrix_dup
    GrB_Matrix C ;
    GrB_Type type ;
    GrB_Index nrows, ncols ;
    GrB_Descriptor desc ;
    GxB_Matrix_type (&type, A) ;
    GrB_Matrix_nrows (&nrows, A) ;
    GrB_Matrix_ncols (&ncols, A) ;
    GrB_Matrix_new (&C, type, nrows, ncols) ;
    GrB_Descriptor_new (&desc) ;
    GrB_Descriptor_set (desc, GrB_INP0, GrB_TRAN) ;
    GrB_transpose (C, NULL, NULL, A, desc) ; \end{verbatim}}

Since the input matrix \verb'A' is transposed by the descriptor,
SuiteSparse:Graph\-BLAS does the right thing and does not transpose the matrix
at all.  Since \verb'T = A' is not typecasted, SuiteSparse:GraphBLAS can
construct \verb'T' internally in $O(1)$ time and using no memory at all.   This
makes \verb'Grb_transpose' a fast and direct interface to the accumulator/mask
function in GraphBLAS.

This example is of course overkill, since the work can all be done by a
single call to the \verb'GrB_Matrix_dup' function.  However, the
\verb'GrB_Matrix_dup' function can only create \verb'C' as an exact copy of
\verb'A', whereas variants of the code above can do many more things with these
two matrices.  For example, the \verb'type' in the example can be replaced with
any other type, perhaps selected from another matrix or from an operator.

Consider the following code excerpt, which uses \verb'GrB_transpose' to remove
all diagonal entries from a square matrix.  It first creates a diagonal
\verb'Mask', which is complemented so that ${\bf C \langle \neg M \rangle =A}$
does not modify the diagonal of ${\bf C}$.  The \verb'REPLACE' ensures that
\verb'C' is cleared first, and then ${\bf C \langle \neg M \rangle = A}$
modifies all entries in ${\bf C}$ where the mask ${\bf M}$ is false.  These
correspond to all the off-diagonal entries.  The descriptor ensures that ${\bf
A}$ is not transposed at all.  The \verb'Mask' can have any pattern, of course,
and wherever it is set true, the corresponding entries in \verb'A' are
deleted from the copy \verb'C'.

    {\footnotesize
    \begin{verbatim}
    // remove all diagonal entries from the matrix A
    // Mask = speye (n) ;
    GrB_Matrix_new (&Mask, GrB_BOOL, n, n) ;
    for (int64_t i = 0 ; i < n ; i++)
    {
        GrB_Matrix_setElement (Mask, (bool) true, i, i) ;
    }
    // C<~Mask> = A, clearing C first.  No transpose.
    GrB_Descriptor_new (&desc) ;
    GrB_Descriptor_set (desc, GrB_INP0, GrB_TRAN) ;
    GrB_Descriptor_set (desc, GrB_MASK, GrB_SCMP) ;
    GrB_Descriptor_set (desc, GrB_OUTP, GrB_REPLACE) ;
    GrB_transpose (A, Mask, NULL, A, desc) ; \end{verbatim}}

\newpage
%===============================================================================
\subsection{{\sf GxB\_kron:} Kronecker product} %===============================
%===============================================================================
\label{kron}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_kron                   // C<Mask> = accum (C, kron(A,B))
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const GrB_BinaryOp op,          // defines '*' for T=kron(A,B)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Matrix B,             // second input: matrix B
    const GrB_Descriptor desc       // descriptor for C, Mask, A, and B
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_kron' computes the Kronecker product,
${\bf C \langle M \rangle = C \odot \mbox{kron}(A,B)}$ where
\[
\mbox{kron}{\bf (A,B)} =
\left[
    \begin{array}{ccc}
    a_{00} \otimes {\bf B} & \ldots & a_{0,n-1} \otimes {\bf B} \\
    \vdots & \ddots & \vdots \\
    a_{m-1,0} \otimes {\bf B} & \ldots & a_{m-1,n-1} \otimes {\bf B} \\
    \end{array}
\right]
\]
The $\otimes$ operator is defined by the \verb'op' parameter.  It is applied in
an element-wise fashion (like \verb'GrB_eWiseMult'), where the pattern of the
submatrix $a_{ij} \otimes {\bf B}$ is the same as the pattern of ${\bf B}$ if
$a_{ij}$ is an entry in the matrix ${\bf A}$, or empty otherwise.  The input
matrices \verb'A' and \verb'B' can be of any dimension, and both matrices may
be transposed first via the descriptor, \verb'desc'.  Entries in \verb'A' and
\verb'B' are typecast into the input types of the \verb'op'.  The matrix
\verb'T=kron(A,B)' has the same type as the \verb'ztype' of the binary
operator, \verb'op'.  The final step is ${\bf C \langle M \rangle  = C \odot
T}$, as described in Section~\ref{accummask}.

\begin{spec}
{\bf SPEC:} \verb'GxB_kron' is an extension to the spec.
\end{spec}

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Printing GraphBLAS objects} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{fprint}

\begin{spec}
{\bf SPEC:} The GraphBLAS API has no mechanism for printing the contents of
GraphBLAS objects.  This entire section is an extension to the specification.
\end{spec}

The 9 different objects handled by SuiteSparse:GraphBLAS are all opaque,
although nearly all of their contents can be extracted via methods such as
\verb'GrB_Matrix_extractTuples', \verb'GrB_Matrix_extractElement',
\verb'GxB_Matrix_type', and so on.  The GraphBLAS C API has no mechanism for
printing all the contents of GraphBLAS objects, but this is helpful for
debugging.  Nine type-specific methods and two type-generic methods are
provided, listed in the table below:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GxB_Type_fprint'        & print and check a \verb'GrB_Type' \\
\verb'GxB_UnaryOp_fprint'     & print and check a \verb'GrB_UnaryOp' \\
\verb'GxB_BinaryOp_fprint'    & print and check a \verb'GrB_BinaryOp' \\
\verb'GxB_SelectOp_fprint'    & print and check a \verb'GxB_SelectOp' \\
\verb'GxB_Monoid_fprint'      & print and check a \verb'GrB_Monoid' \\
\verb'GxB_Semiring_fprint'    & print and check a \verb'GrB_Semiring' \\
\verb'GxB_Descriptor_fprint'  & print and check a \verb'GrB_Descriptor' \\
\verb'GxB_Matrix_fprint'      & print and check a \verb'GrB_Matrix' \\
\verb'GxB_Vector_fprint'      & print and check a \verb'GrB_Vector' \\
\hline
\verb'GxB_fprint'             & print/check any object to a file \\
\verb'GxB_print'              & print/check any object to \verb'stdout' \\
\hline
\end{tabular}
}
\vspace{0.2in}

These methods do not modify the status of any object.  If a matrix or vector
has not been completed, the pending computations are guaranteed to {\em not} be
performed. The reason is simple.  It is possible for a bug in the user
application (such as accessing memory outside the bounds of an array) to mangle
the internal content of a GraphBLAS object, and the \verb'GxB_*print' methods
can be helpful tools to track down this bug.  If \verb'GxB_*print' attempted to
complete any computations prior to printing or checking the contents of the
matrix or vector, then further errors could occur, including a segfault.

By contrast, all GraphBLAS methods and operations that return values into
user-provided arrays or variables force the completion of pending operations
(\verb'GrB_*_nvals', \verb'GrB_*_extractElement', \verb'GrB_*_extractTuples',
and \verb'GrB_reduce' (to scalar)).  The \verb'GxB_*print' methods provide
a useful alternative for debugging, and for a quick understanding of what
GraphBLAS is computing while developing a user application.

\newpage
Each of the methods has a parameter of type \verb'GxB_Print_Level' that
specifies the amount to print:

{\footnotesize
\begin{verbatim}
typedef enum
{
    GxB_SILENT = 0,     // nothing is printed, just check the object
    GxB_SUMMARY = 1,    // print a terse summary
    GxB_SHORT = 2,      // short description, about 30 entries of a matrix
    GxB_COMPLETE = 3    // print the entire contents of the object
}
GxB_Print_Level ; \end{verbatim}}

The nine type-specific functions include an additional argument, the
\verb'name' string.  The \verb'name' is printed at the beginning of the display
(assuming the print level is not \verb'GxB_SILENT') so that the object can be
more easily identified in the output.  For the type-generic methods
\verb'GxB_fprint' and \verb'GxB_print', the \verb'name' string is the variable
name of the object itself.

If the file \verb'f' is \verb'NULL', nothing is printed (\verb'pr' is
effectively \verb'GxB_SILENT') If \verb'pr' is outside the bounds 0 to 3,
negative values are treated as \verb'GxB_SILENT', and values larger than 3 are
treated as \verb'GxB_COMPLETE'.  If \verb'name' is \verb'NULL', it is treated
as the empty string.  None of these are error conditions.

The methods check their input objects carefully and extensively, even when
\verb'pr' is equal to \verb'GxB_SILENT'.  The following error codes can be
returned:

\begin{packed_itemize}
\item \verb'GrB_SUCCESS':               object is valid
\item \verb'GrB_UNINITIALIZED_OBJECT':  object is not initialized
\item \verb'GrB_INVALID_OBJECT':        object is not valid
\item \verb'GrB_NULL_POINTER':          object is a NULL pointer
\item \verb'GrB_INVALID_VALUE':         \verb'fprintf' returned an I/O error;
    see the ANSI C \verb'errno' or \verb'GrB_error( )' for details.
\end{packed_itemize}

The content of any GraphBLAS object is opaque, and subject to change.  As a
result, the exact content and format of what is printed is
implementation-dependent, and will change from version to version of
SuiteSparse:GraphBLAS.  Do not attempt to rely on the exact content or format
by trying to parse the resulting output via another program.  The intent of
these functions is to produce a report of an object for visual inspection.  If
the user application needs to extract content from a GraphBLAS matrix or
vector, use \verb'GrB_*_extractTuples' instead.

\newpage
%===============================================================================
\subsection{{\sf GxB\_fprint:} Print a GraphBLAS object to a file} %============
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_fprint                 // print and check a GraphBLAS object
(
    GrB_<objecttype> object,        // object to print and check
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

The \verb'GxB_fprint' function prints the contents of any of the 9 GraphBLAS
objects to the file \verb'f'.  If \verb'f' is \verb'NULL', the results are
printed to \verb'stdout'.  For example, to print the entire contents of a
matrix \verb'A' to the file \verb'f', use
\verb'GxB_fprint (A, GxB_COMPLETE, f)'.

%===============================================================================
\subsection{{\sf GxB\_print:} Print a GraphBLAS object to {\sf stdout}} %=======
%===============================================================================
\label{gxb_print}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_print                  // print and check a GrB_Vector
(
    GrB_<objecttype> object,        // object to print and check
    GxB_Print_Level pr              // print level
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_print' is the same as \verb'GxB_fprint', except that it prints the
contents of the object to \verb'stdout' instead of a file \verb'f'.  For
example, to print the entire contents of a matrix \verb'A',  use
\verb'GxB_print (A, GxB_COMPLETE)'.

%===============================================================================
\subsection{{\sf GxB\_Type\_fprint:} Print a {\sf GrB\_Type}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Type_fprint            // print and check a GrB_Type
(
    GrB_Type type,                  // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example, \verb'GxB_Type_fprint (GrB_BOOL, "boolean type", GxB_COMPLETE, f)'
prints the contents of the \verb'GrB_BOOL' object to the file \verb'f'.

\newpage
%===============================================================================
\subsection{{\sf GxB\_UnaryOp\_fprint:} Print a {\sf GrB\_UnaryOp}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_UnaryOp_fprint         // print and check a GrB_UnaryOp
(
    GrB_UnaryOp unaryop,            // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_UnaryOp_fprint (GrB_LNOT, "not", GxB_COMPLETE, f)'
prints the \verb'GrB_LNOT' unary operator to the file \verb'f'.


%===============================================================================
\subsection{{\sf GxB\_BinaryOp\_fprint:} Print a {\sf GrB\_BinaryOp}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_fprint        // print and check a GrB_BinaryOp
(
    GrB_BinaryOp binaryop,          // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_BinaryOp_fprint (GrB_PLUS_FP64, "plus", GxB_COMPLETE, f)' prints the
\verb'GrB_PLUS_FP64' binary operator to the file \verb'f'.


%===============================================================================
\subsection{{\sf GxB\_SelectOp\_fprint:} Print a {\sf GxB\_SelectOp}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_SelectOp_fprint        // print and check a GxB_SelectOp
(
    GxB_SelectOp selectop,          // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_SelectOp_fprint (GxB_TRIL, "tril", GxB_COMPLETE, f)' prints the
\verb'GxB_TRIL' select operator to the file \verb'f'.

\newpage
%===============================================================================
\subsection{{\sf GxB\_Monoid\_fprint:} Print a {\sf GrB\_Monoid}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Monoid_fprint          // print and check a GrB_Monoid
(
    GrB_Monoid monoid,              // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Monoid_fprint (GxB_PLUS_FP64_MONOID, "plus monoid",'
\verb'GxB_COMPLETE, f)'
prints the predefined \verb'GxB_PLUS_FP64_MONOID' (based on the binary
operator \verb'GrB_PLUS_FP64') to the file \verb'f'.

%===============================================================================
\subsection{{\sf GxB\_Semiring\_fprint:} Print a {\sf GrB\_Semiring}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Semiring_fprint        // print and check a GrB_Semiring
(
    GrB_Semiring semiring,          // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Semiring_fprint (GxB_PLUS_TIMES_FP64, "standard",'
\verb'GxB_COMPLETE, f)'
prints the predefined \verb'GxB_PLUS_TIMES_FP64' semiring to the file \verb'f'.

%===============================================================================
\subsection{{\sf GxB\_Descriptor\_fprint:} Print a {\sf GrB\_Descriptor}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Descriptor_fprint      // print and check a GrB_Descriptor
(
    GrB_Descriptor descriptor,      // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Descriptor_fprint (d, "descriptor", GxB_COMPLETE, f)'
prints the descriptor \verb'd' to the file \verb'f'.

\newpage
%===============================================================================
\subsection{{\sf GxB\_Matrix\_fprint:} Print a {\sf GrB\_Matrix}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_fprint          // print and check a GrB_Matrix
(
    GrB_Matrix A,                   // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Matrix_fprint (A, "my matrix", GxB_SHORT, f)'
prints about 30 entries from the matrix \verb'A' to the file \verb'f'.


%===============================================================================
\subsection{{\sf GxB\_Vector\_fprint:} Print a {\sf GrB\_Vector}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_fprint          // print and check a GrB_Vector
(
    GrB_Vector v,                   // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Vector_fprint (v, "my vector", GxB_SHORT, f)'
prints about 30 entries from the vector \verb'v' to the file \verb'f'.

%===============================================================================
\subsection{Performance and portability considerations}
%===============================================================================

Even when the print level is \verb'GxB_SILENT', these methods extensively check
the contents of the objects passed to them, which can take some time.  They
should be considered debugging tools only, not for final use in production.  To
control when these methods are used, the user application could define the
following macro and global variable \verb'pr' in a user include file:

{\footnotesize
\begin{verbatim}
#include <assert.h>
extern GxB_Print_Level pr ;
#define CHECK(object) assert (GxB_print (object, pr) == GrB_SUCCESS) \end{verbatim}}

Place the following statement:

{\footnotesize
\begin{verbatim}
GxB_Print_Level pr = GxB_SILENT ; \end{verbatim}}

\noindent in one of the source files (outside of any function), and then use
\verb'CHECK(A)' to check a matrix or any other object.  To enable printing, set
the global \verb'pr' value to a nonzero value, say \verb'GxB_SUMMARY' or
\verb'GxB_COMPLETE'.  Compile normally to enable debugging, or with
\verb'-DNDEBUG' to disable debugging when compiling the code for performance.

The return value of the \verb'GxB_*print' methods can be relied upon, but the
output to the file (or \verb'stdout') can change from version to version.  If
these methods are eventually added to the GraphBLAS C API Specification, a
conforming implementation might never print anything at all, regardless of the
\verb'pr' value.  This may be essential if the GraphBLAS library is installed
in a dedicated device, with no file output, for example.

Some implementations may wish to print nothing at all if the matrix is not yet
completed, or just an indication that the matrix has pending operations and
cannot be printed, when non-blocking mode is employed.  In this case, use
\verb'GrB_Matrix_nvals' or \verb'GrB_wait' to finish all pending computations
first.  If a matrix or vector has pending operations, SuiteSparse:GraphBLAS
prints a list of the {\em pending tuples}, which are the entries not yet
inserted into the primary data structure.  It can also print out entries that
remain in the data structure but are awaiting deletion; these are called {\em
zombies} in the output report.

Most of the rest of the report is self-explanatory. 

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Creating user-defined objects at compile-time} %%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{precompile}

\begin{spec}
{\bf SPEC:} The GraphBLAS API has no mechanism for constructing user-defined
objects when GraphBLAS is compiled.  This entire section, and the
\verb'GxB_*_define' macros, are extensions to the specification.
\end{spec}

User-defined types, operators, monoids, and semirings provide a powerful and
flexible mechanism for extending GraphBLAS functionality.  For example,
GraphBLAS does not support a built-in complex type, but it can be added in a
user application with a few simple functions, and a few calls to
\verb'GrB_Type_new', \verb'GrB_BinaryOp_new', \verb'GrB_Monoid_new', and
\verb'GrB_Semiring_new'.  A complete example is given in Section~\ref{user}.
See in particular the example code in \verb'Demo/Source/usercomplex.c'.

GraphBLAS does not need to be recompiled in order for the user application to
add new types, operators, monoids, or semirings.  This flexibility comes at the
cost of performance, however.  Since the multiply/add operations in a
user-defined semiring must be accessed one at a time through a function
pointer, a complex matrix multiply via \verb'GrB_mxm' is about two or three
times slower than it could be if GraphBLAS included a built-in complex type.

This performance gap could be solved in two ways.  Complex operators and types
could be added to SuiteSparse:GraphBLAS, or the GraphBLAS C API
Specification itself, but this is not flexible.  Other user-defined objects
would still need to be created.

The mechanism described in this section is another solution.  It allows the
user to create an unlimited variety of user-defined types, operators, monoids,
and semirings, and have them compiled into SuiteSparse:GraphBLAS.  This is done
by creating one or more files with the filename extension \verb'*.m4', and
placing them in the \verb'SuiteSparse/GraphBLAS/User' directory.  Then when
SuiteSparse:GraphBLAS is compiled via \verb'cmake', these new objects are
compiled as well.  This is illustrated by the example in
Figure~\ref{fig:complex}.  It is a single file,
\verb'GraphBLAS/User/Example/my_complex.m4', that defines the complex type
\verb'double complex' as a GraphBLAS \verb'GrB_Type' called \verb'My_Complex'.

If the file resides in its default location in \verb'GraphBLAS/User/Example',
it is not compiled with GraphBLAS.  Moving this file into
\verb'GraphBLAS/User', or creating other \verb'm4' files in the
\verb'GraphBLAS/User' directory, enables SuiteSparse:GraphBLAS to incorporate
these user-defined objects at compile-time.  Any number of \verb'*.m4' files
may be placed in the \verb'GraphBLAS/User' directory; they are all included in
SuiteSparse:GraphBLAS.  There is no need to tell the \verb'cmake' process what
the file names are.  All \verb'*.m4' files in \verb'GraphBLAS/User' will be
found and included.

Of course, a C++ API for GraphBLAS could also create user-defined objects at
compile-time via templates, but the API for GraphBLAS is in C, not C++.  The
solution described in this Section provides this functionality in a purely C
interface.

In Figure~\ref{fig:complex}, two inline functions are defined to perform
complex addition and multiplication, and these are used as the basis for two
GraphBLAS binary operators, \verb'My_complex_plus' and \verb'My_complex_times'.
A monoid is constructed for complex addition, and then finally the complex
plus-times semiring is defined.  All of these user-defined objects are appended
to the \verb'GraphBLAS.h' include file.

\begin{figure}
\begin{mdframed}[leftmargin=-0.4in,userdefinedwidth=5.8in]
{\footnotesize
\begin{verbatim}
#ifdef GxB_USER_INCLUDE

    // Get complex.h but remove "I" since it is used elsewhere in GraphBLAS.
    #include <complex.h>
    #undef I

    // Not all complex.h definitions include the CMPLX macro
    #ifndef CMPLX
    #define CMPLX(real,imag) \
        ( (double complex)((double)(real)) + \
          (double complex)((double)(imag) * _Complex_I) )
    #endif

    // define a token so a user application can check for existence
    #define MY_COMPLEX

    static inline void my_complex_plus
    (
        double complex *z, const double complex *x, const double complex *y
    )
    {
        (*z) = (*x) + (*y) ;
    }

    static inline void my_complex_times
    (
        double complex *z, const double complex *x, const double complex *y
    )
    {
        (*z) = (*x) * (*y) ;
    }
#endif

// define the complex type, plus & times operators, plus monoid, and semiring
GxB_Type_define(My_Complex, double complex) ;
GxB_BinaryOp_define(My_Complex_plus,
    my_complex_plus,  My_Complex, My_Complex, My_Complex) ;
GxB_BinaryOp_define(My_Complex_times, my_complex_times,
    My_Complex, My_Complex, My_Complex) ;
GxB_Monoid_define(My_Complex_plus_monoid, My_Complex_plus, CMPLX(0,0)) ;
GxB_Semiring_define(My_Complex_plus_times, My_Complex_plus_monoid,
    My_Complex_times) ; \end{verbatim}}
\end{mdframed}
\caption{User-defined complex type and operators, defined at compile-time
\label{fig:complex}}
\end{figure}

Some user definitions such as the \verb'static inline' functions
\verb'my_complex_plus' and \verb'my_complex_times' in Figure~\ref{fig:complex}
should appear in the \verb'GraphBLAS.h' include file, so that they are
available to any function in the user application.  Other user declarations
should appear only once, such as the declaration of global values used by
user-defined functions.

To handle this, an \verb'#ifdef GxB_USER_INCLUDE' mechanism is provided for
use in the \verb'User/*m4' file, in the following style:

{\footnotesize
\begin{verbatim}
    #ifdef GxB_USER_INCLUDE

        // Part 1: any code here will be active in GraphBLAS.h.  Place all
        // declarations suitable for use in an #include file here.  These
        // declarations will be available to all user application files
        // and to all internal SuiteSparse/GraphBLAS codes.

    #else

        // Part 2: declarations of user-defined variables, and executable
        // code that should be compiled just once appears here.

    #endif \end{verbatim}}

\noindent
Placing user functions inside this \verb'#ifdef' structure gives the user
control over what declarations should be available to all of GraphBLAS and to
all user application files (Part 1), and what definitions should appear just
once (Part 2).

\newpage
For example, \verb'User/Example/my_scale.m4' in
Figure~\ref{fig:scale} defines a unary operator that computes
\verb'z=my_scalar*x', where \verb'my_scalar' is a global variable.
The declaration of \verb'my_scalar' should appear in \verb'GraphBLAS.h', but
it should be defined only once.

The \verb'GxB_*_define' macros must not appear inside either Part 1 or Part 2
of the \verb'#ifdef GxB_USER_INCLUDE'.

\begin{figure}
\begin{mdframed}[leftmargin=-0.4in,userdefinedwidth=5.8in]
{\footnotesize
\begin{verbatim}
#ifdef GxB_USER_INCLUDE

    //--------------------------------------------------------------------------
    // declarations: for GraphBLAS.h
    //--------------------------------------------------------------------------

    // The following are declarations that are enabled in GraphBLAS.h and
    // appear in all user codes that #include "GraphBLAS.h", and also in all
    // internal GraphBLAS codes.  All user declarations (not definitions)
    // should appear here.

    #define MY_SCALE

    extern double my_scalar ;
    // for thread safety if the user application uses OpenMP
    #pragma omp threadprivate(my_scalar)

    static inline void my_scale
    (
        double *z,
        const double *x
    )
    {
        (*z) = my_scalar * (*x) ;
    }

#else

    //--------------------------------------------------------------------------
    // definitions: code appears just once, in Source/all_user_objects.c
    //--------------------------------------------------------------------------

    // The following defintions are enabled in only a single place:
    // SuiteSparse/GraphBLAS/Source/all_user_objects.c.  This is the place
    // where all user-defined global variables should be defined.

    double my_scalar = 0 ;

#endif

// Unary operator to compute z = my_scalar*x
GxB_UnaryOp_define(My_scale, my_scale, GrB_FP64, GrB_FP64) ; \end{verbatim}}
\end{mdframed}
\caption{User-defined unary operator, dependent upon a global variable
\label{fig:scale}}
\end{figure}

When creating user-defined objects in a \verb'User/*.m4' a useful (but
optional) strategy is to define a token that can be used to discover whether or
not a particular object is available at compile time.  For example, for the
\verb'My_complex' objects in Figure~\ref{fig:complex}, the following code
snippet could appear in a user application:

{\footnotesize
\begin{verbatim}
    #ifndef MY_COMPLEX
    // construct complex type and operators at run-time
    GrB_Type My_Complex ;
    GrB_Type_new (&My_Complex, sizeof (double complex)) ;
    ... etc
    #else
    // use the pre-defined My_Complex type and corresponding objects
    #endif \end{verbatim}}

\noindent
In either case, when the user application is finished, it can do
\verb'GrB_free(My_Complex)'.  This safely does nothing if \verb'My_Complex' is
defined at compile-time with \verb'GxB_Type_define', or frees it if the type
was created a run-time with \verb'GrB_Type_new'.

These pre-defined objects can be used in the user application just as if they
were created at run-time via the corresponding calls to \verb'GrB_Type_new',
\verb'GrB_BinaryOp_new', \verb'GrB_Monoid_new', and \verb'GrB_Semiring_new'.
For a large matrix, computing \verb'C=A*B' via \verb'GrB_mxm' with the
pre-compiled \verb'My_Complex_plus_times' semiring is about 10\% faster than
the MATLAB statement \verb'C=A*B' for sparse complex matrices.  This is the same
relative performance as when computing \verb'C=A*B' for real matrices in
MATLAB, versus using \verb'GrB_mxm' with the built-in
\verb'GxB_PLUS_TIMES_FP64' semiring.  If the complex plus-times semiring is
defined at run-time instead, \verb'GrB_mxm' is about two to three times slower.

User definitions in the \verb'User/*m4' files are visible to all internal
SuiteSparse:GraphBLAS functions and thus must be given names that do not
conflict with internal variables, functions, and macros. 

Objects defined by \verb'GxB_*_define', user-defined static inline functions,
typedefs, global variables, and macros (via \verb'#define') in the
\verb'User/*.m4' files must be given names with a unique prefix, such as
\verb'MY_', \verb'USER_', \verb'my_', \verb'user_',
or the name of the user application (say
\verb'RealCoolApp_', or \verb'PAGERANK_' as exemplified in the
\verb'my_pagerank.m4' example).  This will ensure that no name conflicts will
occur.

An example macro name conflict occurs in the \verb'User/Example/my_complex.m4'
example in Figure~\ref{fig:complex}, which includes the ANSI \verb'complex.h'
include file.  The \verb'complex.h' file defines an ANSI C11 macro \verb'I' but
that name conflicts with internal SuiteSparse:GraphBLAS variables, so
\verb'#undef I' is done immediately after the \verb'complex.h' file is
included.  Undefining \verb'I' is permitted in the ANSI C11 specification
for \verb'complex.h'.

The six \verb'GxB_*_define' macros are presented below.  They all have
essentially the same parameters in the same order as the corresponding
\verb'GrB_*_new' methods, except that where the \verb'GrB_*_new' methods use
pointers to the new objects, the corresponding \verb'GxB_*_define' macro uses
just the name of the object.  Unlike their \verb'GrB_*_new' counterparts, the
six \verb'GxB_*_define' macros do not return an error code.  Any errors will be
detected by the compiler.

Since they are \verb'm4' macros, no space can appear between the macro name
\verb'GxB_*_define' and the subsequent left parenthesis.  This restriction may
be relaxed in subsequent versions of SuiteSparse:GraphBLAS.

Since these objects are constructed at compile-time, they do not need to be
freed with \verb'GrB_free'.  Attempting to free them is safe, however.
SuiteSparse:GraphBLAS will safely (and silently) do nothing if an attempt is
made to free them.

The next sections describe the following 6 macros:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GxB_Type_define'      & define a \verb'GrB_Type' at compile-time \\
\verb'GxB_UnaryOp_define'   & define a \verb'GrB_UnaryOp' at compile-time \\
\verb'GxB_BinaryOp_define'  & define a \verb'GrB_BinaryOp' at compile-time \\
\verb'GxB_SelectOp_define'  & define a \verb'GxB_SelectOp' at compile-time \\
\verb'GxB_Monoid_define'    & define a \verb'GrB_Monoid' at compile-time \\
\verb'GxB_Monoid_terminal_define'
    & define a \verb'GrB_Monoid' at compile-time \\
    & (with a terminal value) \\
\verb'GxB_Semiring_define'  & define a \verb'GrB_Semiring' at compile-time \\
\hline
\end{tabular}
}
\vspace{0.2in}

\newpage
%-------------------------------------------------------------------------------
\subsection{{\sf GxB\_Type\_define:} define a {\sf GrB\_Type} at compile time}
%-------------------------------------------------------------------------------
\label{type_define}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GxB_Type_define(GrB_Type type, ctype) ;
\end{verbatim} } \end{mdframed}

    \verb'GxB_Type_define' is very similar to \verb'GrB_Type_new', except that
    it defines a type when SuiteSparse:GraphBLAS is compiled.  Instead of the
    \verb'sizeof(ctype)' second parameter of \verb'GrB_Type_new', the second
    parameter \verb'ctype' of \verb'GxB_Type_define' is a C type (a built-in
    one or from a \verb'typedef').  As in all \verb'GxB_*_define' macros, there
    is no \verb'&' symbol in front of the GraphBLAS \verb'type' parameter,
    since this macro defines the object instead of returning a pointer.

%-------------------------------------------------------------------------------
\subsection{{\sf GxB\_UnaryOp\_define:}
define a {\sf GrB\_UnaryOp} at compile time}
%-------------------------------------------------------------------------------
\label{unaryop_define}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GxB_UnaryOp_define(GrB_UnaryOp op, func, GrB_Type ztype, GrB_Type xtype) ;
\end{verbatim} } \end{mdframed}

    \verb'GxB_UnaryOp_define' is identical to \verb'GrB_UnaryOp_new', except
    that it defines a unary operator when SuiteSparse:GraphBLAS is compiled.
    The function \verb'func' is the name of a user-defined function, normally a
    static inline function in the user's \verb'*.m4' file.  The \verb'ztype'
    and \verb'xtype' must be built-in types (\verb'GrB_BOOL', \verb'GrB_FP64',
    etc) or types defined with \verb'GxB_Type_define'.

%-------------------------------------------------------------------------------
\subsection{{\sf GxB\_BinaryOp\_define:}
define a {\sf GrB\_BinaryOp} at compile time}
%-------------------------------------------------------------------------------
\label{binaryop_define}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GxB_BinaryOp_define(GrB_BinaryOp op, func, GrB_Type ztype, GrB_Type xtype,
    GrB_Type ytype) ;
\end{verbatim} } \end{mdframed}

    \verb'GxB_BinaryOp_define' is identical to \verb'GrB_BinaryOp_new', except
    that it defines a binary operator when SuiteSparse:GraphBLAS is compiled.
    The function \verb'func' is the name of a user-defined function, normally a
    static inline function in the user's \verb'*.m4' file.  The \verb'ztype',
    \verb'xtype', and \verb'ytype' must be built-in types (\verb'GrB_BOOL',
    \verb'GrB_FP64', etc) or types defined with \verb'GxB_Type_define'.

\newpage
%-------------------------------------------------------------------------------
\subsection{{\sf GxB\_SelectOp\_define:}
define a {\sf GxB\_SelectOp} at compile time}
%-------------------------------------------------------------------------------
\label{selectop_define}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GxB_SelectOp_define(GxB_SelectOp op, func, GrB_Type xtype) ;
\end{verbatim} } \end{mdframed}

    \verb'GxB_SelectOp_define' is identical to \verb'GxB_SelectOp_new', except
    that it defines a select operator when SuiteSparse:GraphBLAS is compiled.
    The function \verb'func' is the name of a user-defined function, normally a
    static inline function in the user's \verb'*.m4' file.  The \verb'xtype'
    may be \verb'GrB_NULL' or \verb'NULL', which denotes a type-generic
    \verb'GxB_SelectOp' operator.  If not null, \verb'xtype' must be a built-in
    type (\verb'GrB_BOOL', \verb'GrB_FP64', etc), a type defined with
    \verb'GxB_Type_define'.

%-------------------------------------------------------------------------------
\subsection{{\sf GxB\_Monoid\_define:}
define a {\sf GrB\_Monoid} at compile time}
%-------------------------------------------------------------------------------
\label{monoid_define}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GxB_Monoid_define(GrB_Monoid monoid, GrB_BinaryOp op, identity) ;
\end{verbatim} } \end{mdframed}

    \verb'GxB_Monoid_define' is identical to \verb'GrB_Monoid_new', except that
    it defines a monoid when SuiteSparse:GraphBLAS is compiled.  The \verb'op'
    is a built-in binary operator (\verb'GrB_PLUS_FP32', for example) or a
    binary operator defined by \verb'GxB_BinaryOp_define'.  The three types of
    the operator must be the same, but this cannot be checked by this method at
    compile time.  Results are undefined if this condition does not hold.

    Unlike \verb'GrB_Monoid_new', the \verb'identity' parameter must be a
    compile-time constant expression.  It must also be parsable as a valid
    argument to an \verb'm4' macro.  For example, the following is a valid
    definition that appears in \verb'User/Example/my_complex.m4',  It defines a
    plus monoid for the \verb'My_complex' type, which is \verb'double complex'
    in C.

{\footnotesize
\begin{verbatim}
GxB_Monoid_define(My_Complex_plus_monoid, My_Complex_plus, CMPLX(0,0)) ; \end{verbatim}}

For user-defined types created from a C struct, another method must be used
for the value of the \verb'identity' parameter of \verb'GxB_Monoid_define'.
Consider the following excerpt from \verb'User/Example/my_pagerank.m4'.  A
struct variable such as the \verb'pagerank_type' can be initialized with the C
expression \verb'identity = {0,0}', but the expression \verb'{0,0}' cannot be
passed to an \verb'm4' macro since it is interpreted by \verb'm4' as two
arguments.  The solution is to define a C preprocessor token,
\verb'PAGERANK_ZERO', and pass that token as the third argument of
\verb'GxB_Monoid_define'.

{\footnotesize
\begin{verbatim}
#ifdef GxB_USER_INCLUDE
typedef struct
{
    double rank ;
    double invdegree ;
}
pagerank_type ;

// This is valid.  It defines the identity value of the monoid as a
// struct with identity.rank = 0 and identity.invdegree = 0.
#define PAGERANK_ZERO {0,0}
#endif

GxB_Monoid_define(PageRank_monoid, PageRank_add, PAGERANK_ZERO) ;
\end{verbatim} }

\noindent
The following definition will fail to compile, since \verb'm4' interprets the
comma in the \verb'identity' argument as the start of a fourth argument:

{\footnotesize
\begin{verbatim}
// This will fail:
GxB_Monoid_define(PageRank_monoid, PageRank_add, {0,0}) ;
\end{verbatim} }

%-------------------------------------------------------------------------------
\subsection{{\sf GxB\_Monoid\_terminal\_define:}
define a {\sf GrB\_Monoid} at compile time, with a terminal value}
%-------------------------------------------------------------------------------
\label{monoid_terminal_define}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GxB_Monoid_terminal_define(GrB_Monoid monoid, GrB_BinaryOp op, identity, terminal) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Monoid_terminal_define' is identical to \verb'GxB_Monoid_define',
except that it allows the specification of a terminal value.  See
Section~\ref{monoid_terminal_new} for a description of the terminal value of
a monoid.

%-------------------------------------------------------------------------------
\subsection{{\sf GxB\_Semiring\_define:}
define a {\sf GrB\_Semiring} at compile time}
%-------------------------------------------------------------------------------
\label{semiring_define}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GxB_Semiring_define(GrB_Semiring semiring, GrB_Monoid add, GrB_BinaryOp mult) ;
\end{verbatim} } \end{mdframed}

    \verb'GxB_Semiring_define' is identical to \verb'GrB_Semiring_new', except
    that it defines a semiring when SuiteSparse:GraphBLAS is compiled.  The
    \verb'add' parameter is a \verb'GrB_Monoid' that is either predefined (such
    as \verb'GxB_PLUS_TIMES_FP64') or defined with \verb'GxB_Monoid_define'.
    Similarly, the \verb'mult' parameter is either a predefined binary operator
    (such as \verb'GrB_TIMES_FP32') or a binary operator defined with
    \verb'GxB_BinaryOp_define'.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{examples}

Six examples of how to use GraphBLAS are described below.  They all
appear in the \verb'Demo' folder of SuiteSparse:GraphBLAS.

\begin{enumerate}
\item performing a breadth-first search,
\item finding a maximal independent set,
\item creating a random matrix,
\item creating a finite-element matrix,
\item reading a matrix from a file, and
\item complex numbers as a user-defined type.
\end{enumerate}

Additional examples appear in the newly created LAGraph project, currently in
progress.  Finally, the \verb'Extras' folder includes triangle counting and
k-truss algorithms in GraphBLAS, and methods that do not GraphBLAS (both simple
sequential methods, and methods that use OpenMP).

%-------------------------------------------------------------------------------
\subsection{LAGraph}
%-------------------------------------------------------------------------------
\label{lagraph}

The LAGraph project is a community-wide effort to create graph algorithms based
on GraphBLAS (any implementation of the API, not just SuiteSparse: GraphBLAS).
As of Feb.~2019, the library includes the algorithms and utilities listed in
the table below.  Many additional algorithms are planned, such as betweenness
centrality, PageRank, single-source shortest path (via delta stepping), minimum
spanning trees, connected components, and many more.  Refer to
\url{https://github.com/GraphBLAS/LAGraph} for a current list of algorithms
(the one below will soon be out of date).  Most of the functions in the
\verb'Demo/' and the \verb'Extras' folder in SuiteSparse:GraphBLAS will
eventually be translated into algorithms or utilities for LAGraph.

To use LAGraph with SuiteSparse:GraphBLAS, place the two folders \verb'LAGraph'
and \verb'GraphBLAS' in the same parent directory.  This allows the
\verb'cmake' script in LAGraph to find the copy of GraphBLAS.  Alternatively,
the GraphBLAS source could be placed anywhere, as long as
\verb'sudo make install' is performed.

Build \verb'GraphBLAS' first, then the \verb'LAGraph' library, and then the
tests in \verb'LAGraph/Test'.

\vspace{0.1in}
{\small
\begin{tabular}{ll}
\hline
\hline
Algorithms & description \\
\hline
\hline
\verb'LAGraph_bfs_pushpull' & a direction-optimized BFS
                                \cite{Beamer:2012:DOB,Yang:2018:IPE}, \\
                            & typically 2x faster than \verb'bfs5m' \\
\verb'LAGraph_bfs_simple'   & a simple BFS (about the same as \verb'bfs5m') \\ 
\hline
\hline
Utilities & description \\
\hline
\hline
\verb'LAGraph_Vector_isall'     & tests 2 vectors with a binary operator \\
\verb'LAGraph_Vector_isequal'   & tests if 2 vectors are equal \\
\verb'LAGraph_Vector_to_dense'  & converts a vector to dense \\
\verb'LAGraph_alloc_global'     & types, operators, monoids, and semirings \\
\verb'LAGraph_finalize'         & ends LAGraph \\
\verb'LAGraph_free'             & wrapper for \verb'free' \\
\verb'LAGraph_free_global'      & frees objects created by \verb'_alloc_global'\\
\verb'LAGraph_init'             & starts LAGraph \\
\verb'LAGraph_isall'            & tests 2 matrices with a binary operator \\
\verb'LAGraph_isequal'          & tests if 2 matrices are equal \\
\verb'LAGraph_ispattern'        & tests if all entries in a matrix are 1 \\
\verb'LAGraph_malloc'           & wrapper for \verb'malloc' \\
\verb'LAGraph_mmread'           & read a Matrix Market file \\
\verb'LAGraph_mmwrite'          & write a Matrix Market file \\
\verb'LAGraph_pattern'          & extracts the pattern of a matrix \\
\verb'LAGraph_rand'             & simple random number generator \\
\verb'LAGraph_rand64'           & \verb'int64_t' random number generator \\
\verb'LAGraph_random'           & random matrix generator \\
\verb'LAGraph_randx'            & \verb'double' random number generator \\
\verb'LAGraph_tic'              & start a timer \\
\verb'LAGraph_toc'              & end a timer \\
\end{tabular}}

\newpage
%-------------------------------------------------------------------------------
\subsection{Breadth-first search}
%-------------------------------------------------------------------------------
\label{bfs}

The \verb'bfs' examples in the \verb'Demo' folder provide several examples of
how to compute a breadth-first search (BFS) in GraphBLAS.  The \verb'bfs5m'
function starts at a given source node \verb's' of an undirected graph with
\verb'n' nodes.  The graph is represented as an \verb'n'-by-\verb'n'
Boolean matrix, \verb'A', where \verb'A(i,j)' is the edge $(i,j)$.  The matrix
\verb'A' can actually have any type; if it is not Boolean (\verb'bool' in C, or
\verb'GrB_BOOL' in GraphBLAS), it is typecasted to Boolean by the semiring,
where zero is false and nonzero is true.

The vector \verb'v' of size \verb'n' holds the level of each node in the
BFS, where \verb'v(i)=0' if the node has not yet been seen.  This particular
value makes \verb'v' useful for another role.  It can be used as a Boolean
mask, since \verb'0' is \verb'false' and nonzero is \verb'true'.
Initially the entire \verb'v' vector is zero.

The vector \verb'q' is the set of nodes just discovered at the current level,
where \verb'q(i)=true' if node \verb'i' is in the current level.  It starts out
with just a single entry set to true, \verb'q(s)', the starting node.

Each iteration of the BFS consists of three calls to GraphBLAS.  The first one
uses \verb'q' as a mask.  It modifies all positions in \verb'v' where \verb'q'
is true, setting them all to the current \verb'level'.  No accumulator or
descriptor are used.  Since \verb'GrB_REPLACE' is not used and
\verb'I=GrB_ALL', \verb'GxB_subassign' and \verb'GrB_assign' are identical;
either can be used in this step:

        {\footnotesize
        \begin{verbatim}
        // v<q> = level, using vector assign with q as the mask
        GrB_assign (v, q, NULL, level, GrB_ALL, n, NULL) ; \end{verbatim}}

The next call to GraphBLAS is the heart of the algorithm:

        {\footnotesize
        \begin{verbatim}
        // q<!v> = q ||.&& A ; finds all the unvisited
        // successors from current q, using !v as the mask
        GrB_vxm (q, v, NULL, Boolean, q, A, desc) ; \end{verbatim}}

The vector \verb'q' is all the set of nodes at the current level.  Suppose
\verb'q(j)' is true, and it has a neighbor \verb'i'.  Then \verb'A(i,j)=1', and
the dot product of \verb'A(i,:)*q' using the \verb'OR-AND' semiring will use
the \verb'AND' multiplier on these two terms, \verb'A(i,j) AND q(j)', resulting
in a value \verb'true'.  The \verb'OR' monoid will ``sum'' up all the results
in this single row \verb'i'.  If the result is a column vector \verb't=A*q',
then this \verb't(i)' will be true.  The vector \verb't' will be true for
any node adjacent to any node in the set \verb'q'.

Some of these neighbors of the nodes in \verb'q' have already been visited by
the BFS, either in the current level or in a prior level.  These results must
be discarded; what is desired is the set of all nodes \verb'i' for which
\verb't(i)' is true, and yet \verb'v(i)' is still zero.

Enter the mask.  The vector \verb'v' is complemented for use a mask, via the
\verb'desc' descriptor.  This means that wherever the vector is true, that
position in the result is protected and will not be modified by the assignment.
Only where \verb'v' is false will the result be modified.  This is exactly the
desired result, since these represent newly seen nodes for the next level of
the BFS.  A node \verb'k' already visited will have a nonzero \verb'v(k)', and
thus \verb'q(k)' will not be modified by the assignment.

The result \verb't' is written back into the vector \verb'q', through the mask,
but to do this correctly, another descriptor parameter is used:
\verb'GrB_REPLACE'.  The vector \verb'q' was used to compute \verb't=A*q', and
after using it to compute \verb't', the entire \verb'q' vector needs to be
cleared.  Only new nodes are desired, for the next level.  This is exactly what
the \verb'REPLACE' option does.

As a result, the vector \verb'q' now contains the set of nodes at the new
level of the BFS.  It contains all those nodes (and only those nodes)
that are neighbors of the prior set and that have not already been seen in
any prior level.

Finally, a single call to GraphBLAS computes the \verb'OR' for all entries
in \verb'q', into a single scalar, \verb'successor'.  This value is true if
\verb'q' contains any value true, or false otherwise.  If it is false,
the BFS can terminate.

        {\footnotesize
        \begin{verbatim}
        GrB_reduce (&successor, NULL, Lor, q, NULL) ; \end{verbatim}}

Another method for computing the BFS is in the \verb'bfs6' function in the
\verb'Demo' folder.  It uses \verb'GrB_apply' and a unary operator to set the
levels of the newly discovered nodes, instead of
\verb'GrB_assign'.

\newpage
\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info bfs5m              // BFS of a graph (using vector assign & reduce)
(
    GrB_Vector *v_output,   // v [i] is the BFS level of node i in the graph
    const GrB_Matrix A,     // input graph, treated as if boolean in semiring
    GrB_Index s             // starting node of the BFS
)
{
    GrB_Index n ;                          // # of nodes in the graph
    GrB_Vector q = NULL ;                  // nodes visited at each level
    GrB_Vector v = NULL ;                  // result vector
    GrB_Monoid Lor = NULL ;                // Logical-or monoid
    GrB_Semiring Boolean = NULL ;          // Boolean semiring
    GrB_Descriptor desc = NULL ;           // Descriptor for vxm
    GrB_Matrix_nrows (&n, A) ;             // n = # of rows of A
    GrB_Vector_new (&v, GrB_INT32, n) ;    // Vector<int32_t> v(n) = 0
    GrB_assign (v, NULL, NULL, 0, GrB_ALL, n, NULL) ;   // make v dense
    GrB_Vector_new (&q, GrB_BOOL, n) ;     // Vector<bool> q(n) = false
    GrB_Vector_setElement (q, true, s) ;   // q[s] = true, false elsewhere
    GrB_Monoid_new (&Lor, GrB_LOR, (bool) false) ;
    GrB_Semiring_new (&Boolean, Lor, GrB_LAND) ;
    GrB_Descriptor_new (&desc) ;
    GrB_Descriptor_set (desc, GrB_MASK, GrB_SCMP) ;     // invert the mask
    GrB_Descriptor_set (desc, GrB_OUTP, GrB_REPLACE) ;  // clear q first

    bool successor = true ; // true when some successor found
    for (int32_t level = 1 ; successor && level <= n ; level++)
    {
        // v<q> = level, using vector assign with q as the mask
        GrB_assign (v, q, NULL, level, GrB_ALL, n, NULL) ;
        // q<!v> = q ||.&& A ; finds all the unvisited successors from current
        // q, using !v as the mask
        GrB_vxm (q, v, NULL, Boolean, q, A, desc) ;
        // successor = ||(q)
        GrB_reduce (&successor, NULL, Lor, q, NULL) ;
    }

    GrB_Descriptor_set (desc, GrB_MASK, GxB_DEFAULT) ;  // mask not inverted
    GrB_assign (v, v, NULL, v, GrB_ALL, n, desc) ;      // make v sparse
    *v_output = v ;         // return result
    // free workspace
    GrB_free (&q) ; GrB_free (&Lor) ; GrB_free (&Boolean) ; GrB_free (&desc) ;
    return (GrB_SUCCESS) ;
} \end{verbatim}} 
\end{mdframed}

\newpage
%-------------------------------------------------------------------------------
\subsection{Maximal independent set}
%-------------------------------------------------------------------------------
\label{mis}

The {\em maximal independent set} problem is to find a set of nodes $S$ such
that no two nodes in $S$ are adjacent to each other (an independent set), and
all nodes not in $S$ are adjacent to at least one node in $S$ (and thus $S$ is
maximal since it cannot be augmented by any node while remaining an independent
set).  The \verb'mis' function in the \verb'Demo' folder solves this problem
using Luby's method \cite{Luby86}.  The key operations in the method are
replicated on the next page.

The gist of the algorithm is this.  In each phase, all candidate nodes are
given a random score.  If a node has a score higher than all its neighbors,
then it is added to the independent set.  All new nodes added to the set cause
their neighbors to be removed from the set of candidates.  The process must be
repeated for multiple phases until no new nodes can be added.  This is because
in one phase, a node \verb'i' might not be added because one of its neighbors
\verb'j' has a higher score, yet that neighbor \verb'j' might not be added
because one of its neighbors \verb'k' is added to the independent set instead.
The node \verb'j' is no longer a candidate and can never be added to the
independent set, but node \verb'i' could be added to $S$ in a subsequent phase.

The initialization step, before the \verb'while' loop, computes the degree of
each node with a \verb'PLUS' reduction.  The set of \verb'candidates' is
Boolean vector, the \verb'i'th component is true if node \verb'i' is a
candidate.  A node with no neighbors causes the algorithm to stall, so these
nodes are not candidates.  Instead, they are immediately added to the
independent set, represented by another Boolean vector \verb'iset'.  Both steps
are done with an \verb'assign', using the \verb'degree' as a mask, except the
assignment to \verb'iset' uses the complement of the mask, via the
\verb'sr_desc' descriptor.  Finally, the \verb'GrB_Vector_nvals' statement
counts how many candidates remain.

Each phase of Luby's algorithm consists of nine calls to GraphBLAS operations.
Not all of them are described here since they are commented in the code itself.
The two matrix-vector multiplications are the important parts and also take the
most time.  They also make interesting use of semirings and masks.  The first
one computes the largest score of all the neighbors of each node in the
candidate set:

        {\footnotesize
        \begin{verbatim}
        // compute the max probability of all neighbors
        GrB_vxm (neighbor_max, candidates, NULL, maxSelect1st, prob, A, r_desc) ; \end{verbatim}}

\newpage
\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
    // compute the degree of each node
    GrB_reduce (degrees, NULL, NULL, GrB_PLUS_FP64, A, NULL) ;

    // singletons are not candidates; they are added to iset first instead
    // candidates[degree != 0] = 1
    GrB_assign (candidates, degrees, NULL, true, GrB_ALL, n, NULL); 

    // add all singletons to iset
    // iset[degree == 0] = 1
    GrB_assign (iset, degrees, NULL, true, GrB_ALL, n, sr_desc) ; 

    // Iterate while there are candidates to check.
    GrB_Index nvals ;
    GrB_Vector_nvals (&nvals, candidates) ;

    while (nvals > 0)
    {
        // compute a random probability scaled by inverse of degree
        GrB_apply (prob, candidates, NULL, set_random, degrees, r_desc) ;

        // compute the max probability of all neighbors
        GrB_vxm (neighbor_max, candidates, NULL, maxSelect1st, prob, A, r_desc) ;

        // select node if its probability is > than all its active neighbors
        GrB_eWiseAdd (new_members, NULL,NULL, GrB_GT_FP64, prob, neighbor_max,
                                                                        NULL) ;
        // add new members to independent set.
        GrB_eWiseAdd (iset, NULL, NULL, GrB_LOR, iset, new_members, NULL) ;

        // remove new members from set of candidates c = c & !new
        GrB_apply (candidates, new_members, NULL, GrB_IDENTITY_BOOL,
            candidates, sr_desc) ;

        GrB_Vector_nvals (&nvals, candidates) ;
        if (nvals == 0) { break ; }                  // early exit condition

        // Neighbors of new members can also be removed from candidates
        GrB_vxm (new_neighbors, candidates, NULL, Boolean,
            new_members, A, NULL) ;
        GrB_apply (candidates, new_neighbors, NULL, GrB_IDENTITY_BOOL,
            candidates, sr_desc) ;

        GrB_Vector_nvals (&nvals, candidates) ;
    }
\end{verbatim}}
\end{mdframed}

\verb'A' is a symmetric Boolean matrix and \verb'prob' is a sparse real vector
(of type \verb'FP32'), where \verb'prob(i)' is nonzero only if node \verb'i' is
a candidate.  The \verb'maxSelect1st' semiring uses \verb'z=FIRST(x,y)' as the
multiplier operator.  The column \verb'A(:,j)' is the adjacency of node
\verb'j', and the dot product \verb"prob'*A(:,j)" applies the \verb'FIRST'
operator on all entries that appear in the intersection of \verb'prob' and
\verb'A(:,j)', where \verb'z=FIRST(prob(i),A(i,j))' which is just
\verb'prob(i)' if \verb'A(i,j)' is present.  If \verb'A(i,j)' not an explicit
entry in the matrix, then this term is not computed and does not take part in
the reduction by the \verb'MAX' monoid.

Thus, each term \verb'z=FIRST(prob(i),A(i,j))' is the score, \verb'prob(i)',
of all neighbors \verb'i' of node \verb'j' that have a score.  Node \verb'i'
does not have a score if it is not also a candidate and so this is skipped.
These terms are then ``summed'' up by taking the maximum score, using
\verb'MAX' as the additive monoid.

Finally, the results of this matrix-vector multiply are written to the result,
\verb'neighbor_max'.  The \verb'r_desc' descriptor has the \verb'REPLACE'
option enabled.  Since \verb'neighbor_max' does not also take part in the
computation \verb"prob'*A", it is simply cleared first.  Next, is it modified
only in those positions \verb'i' where \verb'candidates(i)' is true, using
\verb'candidates' as a mask.  This sets the \verb'neighbor_max' only for
candidate nodes, and leaves the other components of \verb'neighbor_max' as zero
(implicit values not in the pattern of the vector).

All of the above work is done in a single matrix-vector multiply, with an
elegant use of the \verb'maxSelect1st' semiring coupled with a mask.  The
matrix-vector multiplication is described above as if it uses dot products of
rows of \verb'A' with the column vector \verb'prob', but SuiteSparse:GraphBLAS
does not compute it that way.  Sparse dot products are much slower the optimal
method for multiplying a sparse matrix times a sparse vector.  The result is
the same, however.

The second matrix-vector multiplication is more straight-forward.  Once the set
of new members in the independent is found, it is used to remove all neighbors
of those new members from the set of candidates.

The resulting method is very efficient.  For the \verb'Freescale2' matrix, the
algorithm finds an independent set of size 1.6 million in 1.7 seconds (on the
same MacBook Pro referred to in Section~\ref{bfs}), taking four iterations of
the \verb'while' loop.  For comparison, removing its diagonal entries (required
for the algorithm to work) takes 0.3 seconds in GraphBLAS (see
Section~\ref{transpose}), and simply transposing the matrix takes 0.24 seconds
in both MATLAB and GraphBLAS.

\newpage
%-------------------------------------------------------------------------------
\subsection{Creating a random matrix}
%-------------------------------------------------------------------------------
\label{random}

The \verb'random_matrix' function in the \verb'Demo' folder generates a random
matrix with a specified dimension and number of entries, either symmetric or
unsymmetric, and with or without self-edges (diagonal entries in the matrix).
It relies on \verb'simple_rand*' functions in the \verb'Demo' folder to provide
a portable random number generator that creates the same sequence on any
computer and operating system.

\verb'random_matrix' can use one of two methods: \verb'GrB_Matrix_setElement'
and \verb'GrB_Matrix_build'.  The former method is very simple to use:

    {\footnotesize
    \begin{verbatim}
    GrB_Matrix_new (&A, GrB_FP64, nrows, ncols) ;
    for (int64_t k = 0 ; k < ntuples ; k++)
    {
        GrB_Index i = simple_rand_i ( ) % nrows ;
        GrB_Index j = simple_rand_i ( ) % ncols ;
        if (no_self_edges && (i == j)) continue ;
        double x = simple_rand_x ( ) ;
        // A (i,j) = x
        GrB_Matrix_setElement (A, x, i, j) ;
        if (make_symmetric)
        {
            // A (j,i) = x
            GrB_Matrix_setElement (A, x, j, i) ;
        }
    } \end{verbatim}}

The above code can generate a million-by-million sparse \verb'double' matrix
with 200 million entries in 66 seconds (6 seconds of which is the time to
generate the random \verb'i', \verb'j', and \verb'x'), including the time
to finish all pending computations.  The user application does not need to
create a list of all the tuples, nor does it need to know how many entries will
appear in the matrix.  It just starts from an empty matrix and adds them one at
a time in arbitrary order.  GraphBLAS handles the rest.  This method is not
feasible in MATLAB.

The next method uses \verb'GrB_Matrix_build'.  It is more complex to use than
\verb'setElement' since it requires the user application to allocate and fill
the tuple lists, and it requires knowledge of how many entries will appear in
the matrix, or at least a good upper bound, before the matrix is constructed.
It is slightly faster, creating the same matrix in 60 seconds, 51 seconds
of which is spent in \verb'GrB_Matrix_build'.

\newpage
    {\footnotesize
    \begin{verbatim}
    GrB_Index *I, *J ;
    double *X ;
    int64_t s = ((make_symmetric) ? 2 : 1) * nedges + 1 ;
    I = malloc (s * sizeof (GrB_Index)) ;
    J = malloc (s * sizeof (GrB_Index)) ;
    X = malloc (s * sizeof (double   )) ;
    if (I == NULL || J == NULL || X == NULL)
    {
        // out of memory
        if (I != NULL) free (I) :
        if (J != NULL) free (J) :
        if (X != NULL) free (X) :
        return (GrB_OUT_OF_MEMORY) ;
    }
    int64_t ntuples = 0 ;
    for (int64_t k = 0 ; k < nedges ; k++)
    {
        GrB_Index i = simple_rand_i ( ) % nrows ;
        GrB_Index j = simple_rand_i ( ) % ncols ;
        if (no_self_edges && (i == j)) continue ;
        double x = simple_rand_x ( ) ;
        // A (i,j) = x
        I [ntuples] = i ;
        J [ntuples] = j ;
        X [ntuples] = x ;
        ntuples++ ;
        if (make_symmetric)
        {
            // A (j,i) = x
            I [ntuples] = j ;
            J [ntuples] = i ;
            X [ntuples] = x ;
            ntuples++ ;
        }
    }
    GrB_Matrix_build (A, I, J, X, ntuples, GrB_SECOND_FP64) ; \end{verbatim}}

The equivalent \verb'sprandsym' function in MATLAB takes 150 seconds, but
\verb'sprandsym' uses a much higher-quality random number generator to create
the tuples \verb'[I,J,X]'.  Considering just the time for
\verb'sparse(I,J,X,n,n)' in \verb'sprandsym' (equivalent to
\verb'GrB_Matrix_build'), the time is 70 seconds.  That is, each of these three
methods, \verb'setElement' and \verb'build' in SuiteSparse:GraphBLAS, and
\verb'sparse' in MATLAB, are equally fast.

% It is not possible to build such a matrix one entry at a time in MATLAB.
% using a comparable method.  The MATLAB equivalent to \verb'setElement',
% below, takes 105 seconds for the first 200,000 entries and 381 seconds for
% the last 1,000.  The time complexity is $O(nz^2)$.  Extrapolation from this
% data gives an estimated run time of $4 \times 10^7$ seconds (462 days),
% which is nearly a million times slower than the other three methods.

% 
%     {\footnotesize
%     \begin{verbatim}
%     A = sparse (n,n) ;
%     for k = 1:length (I)
%         A (I (k), J (k)) = X (k) ;
%     end \end{verbatim}}

% The problem is not the time spent in interpreting the \verb'for' loop.  A
% \verb'for' loop over 200 million iterations takes only 8 seconds.  The
% problem is that the sparse matrices in MATLAB do not allow computations to be
% left pending.

\newpage
%-------------------------------------------------------------------------------
\subsection{Creating a finite-element matrix}
%-------------------------------------------------------------------------------
\label{fem}

Suppose a finite-element matrix is being constructed, with \verb'k=40,000'
finite-element matrices, each of size \verb'8'-by-\verb'8'.  The following
operations (in pseudo-MATLAB notation) are very efficient in
SuiteSparse:GraphBLAS.

    {\footnotesize
    \begin{verbatim}
    A = sparse (m,n) ; % create an empty n-by-n sparse GraphBLAS matrix
    for i = 1:k
        construct a 8-by-8 sparse or dense finite-element F
        I and J define where the matrix F is to be added:
        I = a list of 8 row indices
        J = a list of 8 column indices
        % using GrB_assign, with the 'plus' accum operator:
        A (I,J) = A (I,J) + F 
    end \end{verbatim}}

If this were done in MATLAB or in GraphBLAS with blocking mode enabled, the
computations would be extremely slow.  This example is taken from Loren Shure's
blog on MATLAB Central, {\em Loren on the Art of MATLAB} \cite{Davis07},
which discusses the built-in \verb'wathen' function.  In
MATLAB, a far better approach is to construct a list of tuples \verb'[I,J,X]'
and to use \verb'sparse(I,J,X,n,n)'. This is identical to creating the same
list of tuples in GraphBLAS and using the \verb'GrB_Matrix_build', which is
equally fast.  The difference in time between using \verb'sparse' or
\verb'GrB_Matrix_build', and using submatrix assignment with blocking mode (or
in MATLAB which does not have a nonblocking mode) can be extreme.  For the
example matrix discussed in \cite{Davis07}, using \verb'sparse' instead of
submatrix assignment in MATLAB cut the run time of \verb'wathen' from 305
seconds down to 1.6 seconds.

In SuiteSparse:GraphBLAS, the performance of both methods is essentially
identical, and roughly as fast as \verb'sparse' in MATLAB.  Inside
SuiteSparse:GraphBLAS, \verb'GrB_assign' is doing the same thing. When
performing \verb'A(I,J)=A(I,J)+F', if it finds that it cannot quickly insert an
update into the \verb'A' matrix, it creates a list of pending tuples to be
assembled later on.   When the matrix is ready for use in a subsequent
GraphBLAS operation (one that normally cannot use a matrix with pending
computations), the tuples are assembled all at once via
\verb'GrB_Matrix_build'.

GraphBLAS operations on other matrices have no effect on when the pending
updates of a matrix are completed.  Thus, any GraphBLAS method or operation can
be used to construct the \verb'F' matrix in the example above, without
affecting when the pending updates to \verb'A' are completed.

The MATLAB \verb'wathen.m' script is part of Higham's \verb'gallery' of
matrices \cite{Higham}.  It creates a finite-element matrix with random
coefficients for a 2D mesh of size \verb'nx'-by-\verb'ny', a matrix formulation
by Wathen \cite{Wathen}.  The pattern of the matrix is fixed; just the values
are randomized.  The GraphBLAS equivalent can use either
\verb'GrB_Matrix_build', or \verb'GrB_assign'.  Both methods have good
performance.  The \verb'GrB_Matrix_build' version below is about 15\% to 20\%
faster than the MATLAB \verb'wathen.m' function, regardless of the problem
size.  It uses the identical algorithm as \verb'wathen.m'.

    {\footnotesize
    \begin{verbatim}
    int64_t ntriplets = nx*ny*64 ;
    I = malloc (ntriplets * sizeof (int64_t)) ;
    J = malloc (ntriplets * sizeof (int64_t)) ;
    X = malloc (ntriplets * sizeof (double )) ;
    if (I == NULL || J == NULL || X == NULL)
    {
        FREE_ALL ;
        return (GrB_OUT_OF_MEMORY) ;
    }
    ntriplets = 0 ;
    for (int j = 1 ; j <= ny ; j++)
    {
        for (int i = 1 ; i <= nx ; i++)
        {
            nn [0] = 3*j*nx + 2*i + 2*j + 1 ;
            nn [1] = nn [0] - 1 ;
            nn [2] = nn [1] - 1 ;
            nn [3] = (3*j-1)*nx + 2*j + i - 1 ;
            nn [4] = 3*(j-1)*nx + 2*i + 2*j - 3 ;
            nn [5] = nn [4] + 1 ;
            nn [6] = nn [5] + 1 ;
            nn [7] = nn [3] + 1 ;
            for (int krow = 0 ; krow < 8 ; krow++) nn [krow]-- ;
            for (int krow = 0 ; krow < 8 ; krow++)
            {
                for (int kcol = 0 ; kcol < 8 ; kcol++)
                {
                    I [ntriplets] = nn [krow] ;
                    J [ntriplets] = nn [kcol] ;
                    X [ntriplets] = em (krow,kcol) ;
                    ntriplets++ ;
                }
            }
        }
    }
    // A = sparse (I,J,X,n,n) ;
    GrB_Matrix_build (A, I, J, X, ntriplets, GrB_PLUS_FP64) ; \end{verbatim}}

The \verb'GrB_assign' version has the advantage of not requiring the
user application to construct the tuple list, and is almost as fast as using
\verb'GrB_Matrix_build'.  The code is more elegant than either the MATLAB
\verb'wathen.m' function or its GraphBLAS equivalent above.  Its performance is
comparable with the other two methods, but slightly slower, being about 5\%
slower than the MATLAB \verb'wathen', and 20\% slower than the GraphBLAS
method above.

    {\footnotesize
    \begin{verbatim}
    GrB_Matrix_new (&F, GrB_FP64, 8, 8) ;
    for (int j = 1 ; j <= ny ; j++)
    {
        for (int i = 1 ; i <= nx ; i++)
        {
            nn [0] = 3*j*nx + 2*i + 2*j + 1 ;
            nn [1] = nn [0] - 1 ;
            nn [2] = nn [1] - 1 ;
            nn [3] = (3*j-1)*nx + 2*j + i - 1 ;
            nn [4] = 3*(j-1)*nx + 2*i + 2*j - 3 ;
            nn [5] = nn [4] + 1 ;
            nn [6] = nn [5] + 1 ;
            nn [7] = nn [3] + 1 ;
            for (int krow = 0 ; krow < 8 ; krow++) nn [krow]-- ;
            for (int krow = 0 ; krow < 8 ; krow++)
            {
                for (int kcol = 0 ; kcol < 8 ; kcol++)
                {
                    // F (krow,kcol) = em (krow, kcol)
                    GrB_Matrix_setElement (F, em (krow,kcol), krow, kcol) ;
                }
            }
            // A (nn,nn) += F
            GrB_assign (A, NULL, GrB_PLUS_FP64, F, nn, 8, nn, 8, NULL) ;
        }
    } \end{verbatim}}

Since there is no \verb'Mask', and since \verb'GrB_REPLACE' is not used, the call
to \verb'GrB_assign' in the example above is identical to \verb'GxB_subassign'.
Either one can be used, and their performance would be identical.

Refer to the \verb'wathen.c' function in the \verb'Demo' folder, which
uses GraphBLAS to implement the two methods above, and two additional ones.

\newpage
%-------------------------------------------------------------------------------
\subsection{Reading a matrix from a file}
%-------------------------------------------------------------------------------
\label{read}

{\bf NOTE:} see also \verb'LAGraph_mmread' and \verb'LAGraph_mmwrite', which
can read and write any matrix in Matrix Market format.

The \verb'read_matrix' function in the \verb'Demo' reads in a triplet matrix
from a file, one line per entry, and then uses \verb'GrB_Matrix_build' to
create the matrix.  It creates a second copy with \verb'GrB_Matrix_setElement',
just to test that method and compare the run times.  A comparison of
\verb'build' versus \verb'setElement' has already been discussed in
Section~\ref{random}.

The function can return the matrix as-is, which may be rectangular or
unsymmetric.  If an input parameter is set to make the matrix symmetric,
\verb'read_matrix' computes \verb"A=(A+A')/2" if \verb'A' is square (turning
all directed edges into undirected ones.  If \verb'A' is rectangular, it
creates a bipartite graph, which is the same as the augmented matrix,
\verb"A = [0 A ; A' 0]".
If \verb'C' is an \verb'n'-by-\verb'n' matrix, then \verb"C=(C+C')/2" can be
computed as follows in GraphBLAS, (the \verb'scale2' function divides an entry
by 2):

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    GrB_Descriptor_new (&dt2) ;
    GrB_Descriptor_set (dt2, GrB_INP1, GrB_TRAN) ;
    GrB_Matrix_new (&A, GrB_FP64, n, n) ;
    GrB_eWiseAdd (A, NULL, NULL, GrB_PLUS_FP64, C, C, dt2) ;    // A=C+C'
    GrB_free (&C) ;
    GrB_Matrix_new (&C, GrB_FP64, n, n) ;
    GrB_UnaryOp_new (&scale2_op, scale2, GrB_FP64, GrB_FP64) ;
    GrB_apply (C, NULL, NULL, scale2_op, A, NULL) ;             // C=A/2
    GrB_free (&A) ;
    GrB_free (&scale2_op) ; \end{verbatim}}

This is of course not nearly as elegant as \verb"A=(A+A')/2" in MATLAB, but
with minor changes it can work on any type and use any built-in operators
instead of \verb'PLUS', or it can use any user-defined operators and types.
The above code in SuiteSparse:GraphBLAS takes 0.60 seconds for the
\verb'Freescale2' matrix, slightly slower than MATLAB (0.55 seconds).

Constructing the augmented system is more complicated using the GraphBLAS C API
Specification since it does not yet have a simple way of specifying a range of
row and column indices, as in \verb'A(10:20,30:50)' in MATLAB (\verb'GxB_RANGE'
is a SuiteSparse:GraphBLAS extension that is not in the Specification).  Using
the C API in the Specification, the application must instead build a list of
indices first, \verb'I=[10, 11' \verb'...' \verb'20]'.

Thus, to compute the MATLAB equivalent of \verb"A = [0 A ; A' 0]", index lists
\verb'I' and \verb'J' must first be constructed:

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    int64_t n = nrows + ncols ;
    I = malloc (nrows * sizeof (int64_t)) ;
    J = malloc (ncols * sizeof (int64_t)) ;
    // I = 0:nrows-1
    // J = nrows:n-1
    if (I == NULL || J == NULL)
    {
        if (I != NULL) free (I) ;
        if (J != NULL) free (J) ;
        return (GrB_OUT_OF_MEMORY) ;
    }
    for (int64_t k = 0 ; k < nrows ; k++) I [k] = k ;
    for (int64_t k = 0 ; k < ncols ; k++) J [k] = k + nrows ; \end{verbatim}}

Once the index lists are generated, however, the resulting GraphBLAS operations
are fairly straightforward, computing \verb"A=[0 C ; C' 0]".

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    GrB_Descriptor_new (&dt1) ;
    GrB_Descriptor_set (dt1, GrB_INP0, GrB_TRAN) ;
    GrB_Matrix_new (&A, GrB_FP64, n, n) ;
    // A (nrows:n-1, 0:nrows-1) = C'
    GrB_assign (A, NULL, NULL, C, J, ncols, I, nrows, dt1) ;
    // A (0:nrows-1, nrows:n-1) = C
    GrB_assign (A, NULL, NULL, C, I, nrows, J, ncols, NULL) ; \end{verbatim}}

This takes 1.38 seconds for the \verb'Freescale2' matrix, almost as fast as
\verb"A=[sparse(m,m) C ; C' sparse(n,n)]" in MATLAB (1.25 seconds).

Both calls to \verb'GrB_assign' use no accumulator, so the second one
causes the partial matrix \verb"A=[0 0 ; C' 0]" to be built first, followed by
the final build of \verb"A=[0 C ; C' 0]".  A better method, but not an obvious
one, is to use the \verb'GrB_FIRST_FP64' accumulator for both assignments.  An
accumulator enables SuiteSparse:GraphBLAS to determine that that entries
created by the first assignment cannot be deleted by the second, and thus it
need not force completion of the pending updates prior to the second
assignment.

SuiteSparse:GraphBLAS also adds a \verb'GxB_RANGE' mechanism that mimics
the MATLAB colon notation.  This speeds up the method and simplifies the
code the user needs to write to compute \verb"A=[0 C ; C' 0]":

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    int64_t n = nrows + ncols ;
    GrB_Matrix_new (&A, xtype, n, n) ;
    GrB_Index I_range [3], J_range [3] ;
    I_range [GxB_BEGIN] = 0 ;
    I_range [GxB_END  ] = nrows-1 ;
    J_range [GxB_BEGIN] = nrows ;
    J_range [GxB_END  ] = ncols+nrows-1 ;
    // A (nrows:n-1, 0:nrows-1) += C'
    GrB_assign (A, NULL, GrB_FIRST_FP64, // or NULL,
        C, J_range, GxB_RANGE, I_range, GxB_RANGE, dt1) ;
    // A (0:nrows-1, nrows:n-1) += C
    GrB_assign (A, NULL, GrB_FIRST_FP64, // or NULL,
        C, I_range, GxB_RANGE, J_range, GxB_RANGE, NULL) ; \end{verbatim}}

Any operator will suffice because it is not actually applied.  An operator is
only applied to the set intersection, and the two assignments do not overlap.
If an \verb'accum' operator is used, only the final matrix is built, and the
time in GraphBLAS drops slightly to 1.25 seconds.  This is a very small
improvement because in this particular case, SuiteSparse:GraphBLAS is able to
detect that no sorting is required for the first build, and the second one is a
simple concatenation.  In general, however, allowing GraphBLAS to postpone
pending updates can lead to significant reductions in run time.

%-------------------------------------------------------------------------------
\subsection{PageRank}
%-------------------------------------------------------------------------------
\label{pagerank}

The \verb'Demo' folder contains three methods for computing the PageRank of the
nodes of a graph.  One uses floating-point arithmetic (\verb'GrB_FP64') and two
user-defined unary operators (\verb'dpagerank.c').  The second
(\verb'ipagerank.c') is very similar, relying on integer arithmetic instead
(\verb'GrB_UINT64').  Neither method include a stopping condition.  They simply
compute a fixed number of iterations.  The third example is more extensive
(\verb'dpagerank2.c'), and serves as an example of the power and flexibility of
user-defined types, operators, monoids, and semirings.  It creates a semiring
for the entire PageRank computation.  It terminates if the 2-norm of the change
in the rank vector \verb'r' is below a threshold.

% This is computed in one of
% two ways.  If \verb'PAGERANK_UNSAFE' is defined at compile-time, the change in
% \verb'r' is computed during the accumulator step of \verb'GrB_vxm', as a
% side-effect of a user-defined operator.  This works in the current version of
% SuiteSparse:GraphBLAS, but is unsafe since it assumes the accumulator operator
% is computed sequentially.  If computed in parallel, a race condition would
% occur.  If \verb'PAGERANK_UNSAFE' is not defined, then a safe method is used
% instead.

If \verb'my_pagerank.m4' is placed in \verb'GraphBLAS/User/', then
the user objects are created at compile-time instead of at run-time, which
leads to faster execution.

\newpage
%-------------------------------------------------------------------------------
\subsection{Triangle counting}
%-------------------------------------------------------------------------------
\label{triangle}

A triangle in an undirected graph is a clique of size three:  three nodes $i$,
$j$, and $k$ that are all pairwise connected.  There are many ways of counting
the number of triangles in a graph.  Let \verb'A' be a symmetric matrix with
values 0 and 1, and no diagonal entries; this matrix is the adjacency matrix of
the graph.  Let \verb'E' be the edge incidence matrix with exactly two 1's per
column.  A column of \verb'E' with entries in rows \verb'i' and \verb'j'
represents the edge $(i,j)$ in the graph, \verb'A(i,j)=1' where \verb'i<j'.
Let \verb'L' and \verb'U' be the strictly lower and upper triangular parts of
\verb'A', respectively.

The methods are listed in the table below.  Most of them use a form of masked
matrix-matrix multiplication.  The methods are implemented in MATLAB in the
\verb'tricount.m' file, and in GraphBLAS in the \verb'tricount.c' file, both in
the \verb'GraphBLAS/Demo' folder.  Refer to the comments in those two files for
details and derivations on how these methods work.

When the matrix is stored by row, and a mask is present and not complemented,
\verb'GrB_INP1' is \verb'GrB_TRAN', and \verb'GrB_INP0' is \verb'GxB_DEFAULT',
the SuiteSparse:GraphBLAS implementation of \verb'GrB_mxm' always uses a
dot-product formulation.  Thus, the ${\bf C \langle L \rangle} = {\bf L}{\bf
U}^{\sf T}$ method uses dot products.  This provides a mechanism for the
end-user to select a masked dot product matrix multiplication method in
SuiteSparse:GraphBLAS, which is occasionally faster than the outer product
method.  The MATLAB form assumes the matrices are stored by column
(the only option in MATLAB).

Each method is followed by a reduction to a scalar, via \verb'GrB_reduce' in
GraphBLAS or by \verb'nnz' or \verb'sum(sum(...))' in MATLAB.

\vspace{0.05in}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline 
method and     & in MATLAB & in GraphBLAS \\
citation    & & \\
\hline 
minitri \cite{WolfBerryStark15} & \verb"nnz(A*E==2)/3"
    & ${\bf C}={\bf AE}$, then \verb'GrB_apply' \\
Burkhardt \cite{Burkhardt16} & \verb"sum(sum((A^2).*A))/6" 
    & ${\bf C \langle A \rangle} = {\bf A}^2$ \\
Cohen \cite{AzadBulucGilbert15,Cohen09} & \verb"sum(sum((L*U).*A))/2"
    & ${\bf C \langle A \rangle} = {\bf LU}$ \\
Sandia \cite{WolfDeveciBerryHammondRajamanickam17} & \verb"sum(sum((U*U).*U))"
    & ${\bf C \langle L \rangle} = {\bf LL}$ (outer product) \\
SandiaDot & \verb"sum(sum((U'*L).*L))"
    & ${\bf C \langle U \rangle} = {\bf L}{\bf U}^{\sf T}$ (dot product) \\
Sandia2  & \verb"sum(sum((L*L).*L))"
    & ${\bf C \langle U \rangle} = {\bf UU}$ (outer product) \\
\hline 
\end{tabular}
}
\vspace{0.05in}

In general, the Sandia methods are the fastest of the 6 methods when
implemented in GraphBLAS.  For full details on the triangle counting and
$k$-truss algorithms, and performance results, see \cite{Davis18b}, a copy of
which appears in the \verb'SuiteSparse/GraphBLAS/Doc' folder.  The code appears
in \verb'Extras'.  That paper uses an earlier version of SuiteSparse:GraphBLAS
in which all matrices are stored by column.

\newpage
%-------------------------------------------------------------------------------
\subsection{User-defined types and operators: double complex and struct-based}
%-------------------------------------------------------------------------------
\label{user}

The \verb'Demo' folder contains two working examples of user-defined types,
first discussed in Section~\ref{type_new}: \verb'double complex', and a
user-defined \verb'typedef' called \verb'wildtype' with a \verb'struct'
containing a string and a 4-by-4 \verb'float' matrix.

{\bf Double Complex:}
GraphBLAS does not have a native complex type, but this can be easily added
as a user-defined type.  The \verb'Complex_init' function in the
\verb'usercomplex.c' file in the \verb'Demo' folder creates the
\verb'Complex' type based on the ANSI C11 \verb'double complex' type.

    {\footnotesize
    \begin{verbatim}
    GrB_Type_new (&Complex, sizeof (double complex)) ; \end{verbatim}}

Next, it creates a full suite of operators that correspond to every
built-in GraphBLAS operator, both binary and unary.  In addition, it
creates the operators listed in the following table, where $D$ is
\verb'double' and $C$ is \verb'Complex'.

\vspace{0.1in}
{\footnotesize
\begin{tabular}{llll}
\hline
name                    & types             & MATLAB        & description \\
                        &                   & equivalent    & \\
\hline
\verb'Complex_complex'  & $D \times D \rightarrow C$ & \verb'z=complex(x,y)' & complex from real and imag. \\
\hline
\verb'Complex_conj'     & $C \rightarrow C$ & \verb'z=conj(x)'  & complex conjugate \\
\verb'Complex_real'     & $C \rightarrow D$ & \verb'z=real(x)'  & real part \\
\verb'Complex_imag'     & $C \rightarrow D$ & \verb'z=imag(x)'  & imaginary part \\
\verb'Complex_angle'    & $C \rightarrow D$ & \verb'z=angle(x)' & phase angle \\
\verb'Complex_complex_real'  & $D \rightarrow C$ & \verb'z=complex(x,0)' & real to complex real \\
\verb'Complex_complex_imag'  & $D \rightarrow C$ & \verb'z=complex(0,x)' & real to complex imag. \\
\hline
\end{tabular}
}

The \verb'Complex_init' function creates two monoids (\verb'Complex_add_monoid'
and \verb'Complex_times_monoid') and a semiring \verb'Complex_plus_times' that
corresponds to the conventional linear algebra for complex matrices.  The
include file \verb'usercomplex.h' in the \verb'Demo' folder is available so
that this user-defined \verb'Complex' type can easily be imported into any
other user application.  When the user application is done, the
\verb'Complex_finalize' function frees the \verb'Complex' type and its
operators, monoids, and semiring.

{\bf Struct-based:}
In addition, the \verb'wildtype.c' program  creates a user-defined
\verb'typedef' of a \verb'struct' containing a dense 4-by-4 \verb'float'
matrix, and a 64-character string.  It constructs an additive monoid that adds
two 4-by-4 dense matrices, and a multiplier operator that multiplies two 4-by-4
matrices.  Each of these 4-by-4 matrices is treated by GraphBLAS as a
``scalar'' value, and they can be manipulated in the same way any other
GraphBLAS type can be manipulated. The purpose of this type is illustrate the
endless possibilities of user-defined types and their use in GraphBLAS.

\newpage
%-------------------------------------------------------------------------------
\subsection{User applications using OpenMP or POSIX pthreads} 
%-------------------------------------------------------------------------------
\label{threads}

Two example demo programs are included that illustrate how a multi-threaded
user application can use GraphBLAS:  \verb'openmp_demo' uses OpenMP for its
user threads and \verb'pthread_demo' uses POSIX pthreads.  {\bf To be
thread-safe, SuiteSparse:GraphBLAS must be compiled with a threading library,
either OpenMP or POSIX}.  Either option used inside GraphBLAS can typically be
combined with any user threading model.  See Section~\ref{sec:install}.

The \verb'openmp_demo' can be compiled without OpenMP, in which case it
becomes single-threaded.  GraphBLAS can be compiled with OpenMP, POSIX
pthreads, or no threading support (and is not thread-safe in this latter
case).  This gives 9 different combinations:

\vspace{0.1in}
{\footnotesize
\begin{tabular}{llll}
\hline
User    & GraphBLAS & \verb'Demo/Output' file & comments \\
applic. &           & & \\
\hline
none    & none      & \verb'user_none_gb_none.out'      & OK \\
none    & OpenMP    & \verb'user_none_gb_openmp.out'    & OK \\
none    & pthread   & \verb'user_none_gb_pthread.out'   & OK \\
\hline
OpenMP  & none      & \verb'user_openmp_gb_none.out'    & fail \\
OpenMP  & OpenMP    & \verb'user_openmp_gb_openmp.out'  & OK, random \\
OpenMP  & pthread   & \verb'user_openmp_gb_pthread.out' & OK, random \\
\hline
pthread & none      & \verb'user_pthread_gb_none.out'   & fail \\
pthread & OpenMP    & \verb'user_pthread_gb_openmp.out' & OK, random \\
pthread & pthread   & \verb'user_pthread_gb_pthread.out'& OK, random \\
\hline
\end{tabular}}
\vspace{0.1in}

\noindent
When the user application is multithreaded, GraphBLAS must be compiled with a
threading library to be thread-safe.  The results listed above as {\em OK,
random} mean that the output of the program will appear out of order.  This is
by design, simply to show that the user application is running in parallel.
The output of each thread should be the same.  In particular, each thread
generates an intentional error, and later on prints it with \verb'GrB_error'.
It will print its own error, not an error from another thread.  When all the
threads finish, the master thread prints out each matrix generated by each
thread, and these results are identical for all 7 cases listed above as OK.

The GraphBLAS C API requires GraphBLAS to be thread-safe.  If
SuiteSparse:GraphBLAS is not compiled with a threading library it will not be
thread-safe (the two {\em fail} cases above).  For these cases, a thread will
not retrieve its own error, but the last error of any thread.  In addition,
since there is no critical section that SuiteSparse:GraphBLAS can use, the
output will include errors about an invalid state of the global matrix queue.
These errors are to be expected if SuiteSparse:GraphBLAS is not thread-safe.

\newpage
%-------------------------------------------------------------------------------
\section{Compiling and Installing SuiteSparse:GraphBLAS}
%-------------------------------------------------------------------------------
\label{sec:install}

%----------------------------------------
\subsection{Required compiler}
%----------------------------------------

GraphBLAS makes extensive use of features in the ANSI C11 standard, and thus a
C compiler supporting this version of the C standard is required.  On the Mac
(OS X), \verb'clang' 8.0.0 in \verb'Xcode' version 8.2.1 is sufficient,
although earlier versions of \verb'Xcode' may work as well.  For the GNU
\verb'gcc' compiler, version 4.9 or later is required.  For the Intel
\verb'icc' compiler, version 18.0 or later is required.  Version 2.8.12 or
later of \verb'cmake' is required; version 3.0.0 is preferred.

To compile SuiteSparse:GraphBLAS and the demo programs, simply type \verb'make'
in the main GraphBLAS folder, which compiles the library and runs several
demos.

If \verb'cmake' or \verb'make' fail, it might be that your default compiler
does not support ANSI C11.  Try another compiler.  For example, try one of
these options.  Go into the \verb'build' directory and type one of these:

    {\small
    \begin{verbatim}
    CC=gcc cmake ..
    CC=gcc-6 cmake ..
    CC=xlc cmake ..
    CC=icc cmake ..  \end{verbatim} }

You can also do the following in the top-level GraphBLAS folder instead:

    {\small
    \begin{verbatim}
    CC=gcc make
    CC=gcc-6 cmake
    CC=xlc cmake
    CC=icc cmake \end{verbatim} }

For faster compilation, you can specify a parallel make.  For example,
to use 32 parallel jobs and the \verb'gcc' compiler, do the following:

    {\small
    \begin{verbatim}
    JOBS=32 CC=gcc make \end{verbatim} }

%----------------------------------------
\subsection{Creating the Doxygen documentation}
\label{sec:doxygen}
%----------------------------------------

SuiteSparse:GraphBLAS is equipped with a \verb'Doxyfile' that specifies how
\verb'doxygen' can be used to create detailed documentation of each file,
including call-graphs.  The \verb'doxygen' documentation is not meant for
end-users of GraphBLAS, but for GraphBLAS developers instead.

If you edit GraphBLAS, you must first run the MATLAB script
\verb'dox_headers.m' in \verb'Doc/', in MATLAB.  This script parses all of the
source code for structured comments, to create header files suitable for
parsing by \verb'doxygen'.  Next, do the following in the top-level
\verb'GraphBLAS' folder:

    {\small
    \begin{verbatim}
    make dox\end{verbatim} }

This creates the \verb'Doc/html/' folder, which is initially empty in
the default distribution.  Open the file \verb'Doc/html/index.html' in
any web browser.  Alternatively, a copy of the \verb'doxygen' documentation can
be found at \url{http://faculty.cse.tamu.edu/davis/GraphBLAS/html}.

%----------------------------------------
\subsection{Thread-safety in multithreaded user applications}
\label{sec:threads}
%----------------------------------------

SuiteSparse:GraphBLAS is not yet parallel, but it is thread-safe if multiple
simultaneous calls are made to GraphBLAS functions.  The output variables of
those calls to GraphBLAS must be unique; you cannot safely modify one GraphBLAS
object in parallel, with two or more simultaneous GraphBLAS functions operating
on the same output object.  In addition, all pending operations of objects that
appear in parallel calls to GraphBLAS must be complete.  This can be done for
all objects via \verb'GrB_wait', or it can be done by calling a method or
operation that forces completion of a particular object (such as
\verb'GrB_*_nvals').  If multiple parallel calls to GraphBLAS functions operate
on unique inputs, then those input objects can safely have pending operations.

To use GraphBLAS from a multithreaded user application, GraphBLAS
requires access to a critical section for the \verb'GrB_wait' queue of
matrices with pending operations, and to a thread-local storage space
so that each user thread can safely retrieve its own error message with
\verb'GrB_error'.

SuiteSparse:GraphBLAS supports the following user threading models.  By
default, the \verb'cmake' script detects the presence of OpenMP and POSIX
pthreads.  If OpenMP is present, it uses OpenMP critical sections for
\verb'GrB_wait' and OpenMP \verb'threadprivate(...)' for thread-local storage
for \verb'GrB_error'.  Otherwise, if POSIX pthreads are available, it uses a
POSIX \verb'mutex', and POSIX thread-local storage via
\verb'pthread_key_create'.

These methods used inside GraphBLAS can typically inter-operate with any user
threading model.  That is, a user application that relies on POSIX threads,
OpenMP, ANSI C11 threads, or Microsoft Windows threads will find GraphBLAS
thread-safe, even though GraphBLAS uses OpenMP or POSIX internally to
synchronize the user threads.  However, for the most reliable results, the
preferred approach is to use the same threading model in GraphBLAS as is used
in the user application.

You can modify the automatic selection of a user thread synchronization model
by adding the following settings for \verb'cmake'.  This setting does not
determine how SuiteSparse:GraphBLAS creates and exploits multiple threads {\em
inside} any given GraphBLAS operation. Rather, it determines which threading
library it will use to synchronize multiple calls to GraphBLAS from more than
one user thread.

\begin{itemize}
\item OpenMP: this is the default if your compiler supports OpenMP.
    It can also be specified with \verb'cmake -DUSER_OPENMP=1' in the
    \verb'cmake' command line.  Internal parallelism in a future
    SuiteSparse:GraphBLAS version will be based on OpenMP, but this is
    typically safe to use with any user threading models.

\item POSIX: this is used if OpenMP is not available.
    If OpenMP is available but you still want GraphBLAS to use POSIX
    synchronization, compile with \verb'cmake -DUSER_POSIX=1'

\item no user threading:  compile with \verb'cmake -DUSER_NONE=1'.
    {\bf GraphBLAS will not be thread-safe}.

\end{itemize}

The following user-threading models are not yet supported, but may be in
a future version.

\begin{itemize}
\item Microsoft Windows:  \verb'cmake -DUSER_WINDOWS=1'
\item ANSI C11 threads:   \verb'cmake -DUSER_ANSI=1'
\end{itemize}

%----------------------------------------
\subsection{Default matrix format}
%----------------------------------------

By default, SuiteSparse:GraphBLAS stores its matrices by row, using the
\verb'GxB_BY_ROW' format.  You can change the default at compile time to
\verb'GxB_BY_COL' using \verb'cmake -DBYCOL=1'.  For example:

    {\small
    \begin{verbatim}
    cmake -DBYCOL=1 ..  \end{verbatim} }

The user application can also use \verb'GxB_get' and \verb'GxB_set' to set and
query the global option (see also Sections~\ref{gxbset} and \ref{gxbget}):

    {\small
    \begin{verbatim}
    GxB_Format_Value s ;
    GxB_get (GxB_FORMAT, &s) ;
    if (s == GxB_BY_COL) printf ("all new matrices are stored by column\n") :
    else printf ("all new matrices are stored by row\n") ; \end{verbatim} }

%----------------------------------------
\subsection{Setting the C flags and using CMake}
%----------------------------------------

The above options can also be combined.  For example, to use the \verb'gcc'
compiler, to change the default format \verb'GxB_FORMAT_DEFAULT' to
\verb'GxB_BY_COL', and to use a POSIX mutex inside GraphBLAS to synchronize
user threads, use the following \verb'cmake' command while in the
\verb'GraphBLAS/build' directory:

    {\small
    \begin{verbatim}
    CC=gcc cmake -DBYCOL=1 -DUSER_POSIX=1 .. \end{verbatim}}

\noindent
Then do \verb'make' in the \verb'build' directory.  If this still fails, see
the \verb'CMakeLists.txt' file.  You can edit that file to pass
compiler-specific options to your compiler.  Locate this section in the
\verb'CMakeLists.txt' file.  Use the \verb'set' command in \verb'cmake', as in
the example below, to set the compiler flags you need.

    {\small
    \begin{verbatim}
    # check which compiler is being used.  If you need to make
    # compiler-specific modifications, here is the place to do it.
    if ("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU")
        # cmake 2.8 workaround: gcc needs to be told to do ANSI C11.
        # cmake 3.0 doesn't have this problem.
        set ( CMAKE_C_FLAGS  "${CMAKE_C_FLAGS} -std=c11 -lm " )
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "Intel")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "Clang")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "MSVC")
        ...
    endif ( )
    \end{verbatim} }

To compile SuiteSparse:GraphBLAS without running the demos, use
\verb'make library' in the top-level directory, or \verb'make' in the
\verb'build' directory.

Several compile-time options can be selected by editing the \verb'Source/GB.h'
file, but these are meant only for code development of SuiteSparse:GraphBLAS
itself, not for end-users of SuiteSparse:GraphBLAS.

%----------------------------------------
\subsection{Running the Demos}
%----------------------------------------

By default, \verb'make' in the top-level directory compiles the library
and runs the demos.  You can also run the demos after compiling:

    {\small
    \begin{verbatim}
    cd Demo
    ./demo \end{verbatim} }

The \verb'./demo' command is a script that runs the demos with various input
matrices in the \verb'Demo/Matrix' folder.  The output of the demos will be
compared with expected output files in \verb'Demo/Output'.

%----------------------------------------
\subsection{Installing SuiteSparse:GraphBLAS}
%----------------------------------------

To install the library (typically in \verb'/usr/local/lib' and
\verb'/usr/local/include' for Linux systems), go to the top-level GraphBLAS
folder and type:

    {\small
    \begin{verbatim}
    sudo make install \end{verbatim} }

%----------------------------------------
\subsection{Running the tests}
%----------------------------------------

To perform the extensive tests in the \verb'Test' folder, and the statement
coverage tests in \verb'Tcov', MATLAB R2017A is required.  See the
\verb'README.txt' files in those two folders for instructions on how to run the
tests.

%----------------------------------------
\subsection{Cleaning up}
%----------------------------------------

To remove all compiled files, type \verb'make' \verb'distclean' in the top-level
GraphBLAS folder.

\newpage
%-------------------------------------------------------------------------------
\section{Acknowledgments}
%-------------------------------------------------------------------------------

I would like to thank Jeremy Kepner (MIT Lincoln Laboratory Supercomputing
Center), and the GraphBLAS API Committee: Ayd\i n Bulu\c{c} (Lawrence Berkeley
National Laboratory), Timothy G. Mattson (Intel Corporation) Scott McMillan
(Software Engineering Institute at Carnegie Mellon University), Jos\'e Moreira
(IBM Corporation), and Carl Yang (UC Davis), for creating the GraphBLAS
specification and for patiently answering my many questions while I was
implementing it.

I would like to thank Tim Mattson and Henry Gabb, Intel, Inc., for their
collaboration and for the support of Intel.

I would like to thank John Gilbert (UC Santa Barbara) for our many discussions
on GraphBLAS, and for our decades-long conversation and collaboration on sparse
matrix computations, and sparse matrices in MATLAB in particular.

I would like to thank Cleve Moler (MathWorks) for our many discussions on
MATLAB, and for creating MATLAB in the first place.  Without MATLAB,
SuiteSparse:GraphBLAS would have been impossible to implement and test.

I would like to thank S\'ebastien Villemot (Debian Developer,
\url{http://sebastien.villemot.name}) for helping me with various build issues
and other code issues with GraphBLAS (and all of SuiteSparse) for its packaging
in Debian Linux.

I would like to thank Roi Lipman, RedisLabs (\url{https://redislabs.com}), for
our many discussions on GraphBLAS and its use in RedisGraph
(\url{https://redislabs.com/redis-enterprise/technology/redisgraph/}), a graph
database module for Redis.  Based on SuiteSparse:GraphBLAS, RedisGraph is up
600x faster than the fastest graph databases ({\footnotesize
\url{https://youtu.be/9h3Qco_x0QE} \newline
\url{https://redislabs.com/blog/new-redisgraph-1-0-achieves-600x-faster-performance-graph-databases/}}).

SuiteSparse:GraphBLAS was developed with support from
MIT Lincoln Lab, Intel, and NSF grant 1514406.

\newpage
%-------------------------------------------------------------------------------
% References
%-------------------------------------------------------------------------------
{\small
\addcontentsline{toc}{section}{References}
\bibliographystyle{annotate}
\bibliography{GraphBLAS_UserGuide.bib}
}
\end{document}
