\documentclass[12pt]{article}
\usepackage{hyperref}
\usepackage{url}
\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}

\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}

\maketitle

\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.

See \cite{Davis18} for a journal article on SuiteSparse:GraphBLAS.
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{spec,BulucMattsonMcMillanMoreiraYang17}, 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
% API version and date are set by cmake (see GraphBLAS/CMakeLists.txt)
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 extensions to the spec.  They are also placed in text boxes like this one.
All functions and objects with a name of the form \verb'GxB_*'
and all macros with a name of the form \verb'GXB_'
are extensions to the spec.
Functions and objects prefixed with \verb'GB_' are
internal to SuiteSparse:GraphBLAS and should not be referenced by user
applications.
\end{spec}

\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 for a
graph of $n$ nodes takes $O(n^2)$ memory, which is impossible if $n$ is, say, a
million.  Most graphs are sparse, however, with only $O(n)$ edges, and 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.  In
SuiteSparse:GraphBLAS, creating a million-by-million sparse matrix or a
trillion-by-1 column vector can be done on quite easily on a commodity laptop,
as long as it does not have too many explicit entries.

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.  Later on
in this User Guide, this pattern of \verb'A', however it is stored, is called
\verb'A.pattern' when used in MATLAB notation.  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
each of its nine different types of objects: sparse matrices,
sparse vectors, types, operators (binary, unary and select), 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 must 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 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(nz)$
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
the same way as MATLAB except that it allows for pending computations, 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}'$, if requested via descriptor (first input option) \\
    \> ${\bf B = B}'$, 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 C language (not MATLAB) wherever the
rules of 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 Specification states that typecasting follows the rules of 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'\langle m'\rangle = w'\odot u'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'}$ \\
\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_', \verb'GRB_', \verb'GxB_', and \verb'GXB_' that may be used in user
applications.  The prefixes \verb'GrB_' and \verb'GRB_' denote items that
appear in the official GraphBLAS API C Specification.  The prefixes \verb'GxB_'
and \verb'GXB_' refer to SuiteSparse-specific extensions to the GraphBLAS API.
Both may be used in user applications but be aware that items with prefixes
\verb'GxB_' and \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 GraphBLAS 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.

\begin{itemize}
\item \verb'GXB_ABOUT': describes this particular implementation,
copyright, and URL.
\item \verb'GXB_DATE': the date of this implementation.
\item \verb'GXB_SPEC': describes the GraphBLAS specification
\item \verb'GXB_SPEC_DATE': the date of the GraphBLAS specification
\item \verb'GXB_LICENSE': the license for this particular implementation
\end{itemize}

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 Specification 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'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}

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
typedef enum
{
    GrB_NONBLOCKING,    // methods may return with pending computations
    GrB_BLOCKING        // 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}).

\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 two different algorithms for computing the matrix multiplication ${\bf
    C=A'B}$.  If ${\bf C}$ is small, or if ${\bf A}$ is a vector, then it does
    not transpose ${\bf A}$ explicitly, but uses dot-products between column
    vectors of ${\bf A}$ and ${\bf B}$ instead.  Otherwise, it transposes ${\bf
    A}$ and uses a sequence of sparse-matrix-times-sparse-vector operations.
    MATLAB uses the same algorithm in its built-in sparse matrix
    multiplication, \verb'C=A*B', also written by this author.  A user
    application in GraphBLAS has no control over the decision on which
    algorithm is used, and the heuristic used to select the algorithm may
    change in the future.  Other GraphBLAS implementations may use entirely
    different algorithms.  The \verb'GrB_wait' function has no effect on this
    order and 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}.

\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}{lp{3in}}
\hline
\verb'GrB_SUCCESS'              & the method or operation was successful \\
\verb'GrB_NO_VALUE'             & \verb'A(i,j)' requested but not there.
                                  Its value is implicit. \\
\hline
\verb'GrB_UNINITIALIZED_OBJECT' & object has not been initialized \\
\verb'GrB_INVALID_OBJECT'       & object is corrupted \\
\verb'GrB_NULL_POINTER'         & input pointer is \verb'NULL' \\
\verb'GrB_INVALID_VALUE'        & generic error code; some value is bad \\
\verb'GrB_INVALID_INDEX'        & a row or column index is out of bounds; for
                                  indices passed as scalars, not in a list. \\
\verb'GrB_DOMAIN_MISMATCH'      & object domains are not compatible \\
\verb'GrB_DIMENSION_MISMATCH'   & matrix dimensions do not match \\
\verb'GrB_OUTPUT_NOT_EMPTY'     & output matrix already has values in it \\
\hline
\verb'GrB_OUT_OF_MEMORY'        & out of memory \\
\verb'GrB_INDEX_OUT_OF_BOUNDS'  & a row or column index is out of bounds;
                                  for indices in a list of indices. \\
\hline
\verb'GrB_PANIC'                & unrecoverable error.
SuiteSparse:GraphBLAS never panics, however.
\\
\hline
\end{tabular}
\vspace{0.2in}
}

Not all GraphBLAS methods or operations can return all status codes.  According
to the GraphBLAS specification, 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
statically allocated in thread local storage and must not be freed or modified.
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)
    {
        printf ("%s\n", GrB_error ( )) ;
    } \end{verbatim}}

SuiteSparse:GraphBLAS reports many helpful details.  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'.

% #ifdef DEVELOPER:
% Also given is the filename and line number of the location in the
% SuiteSparse:GraphBLAS function where the error was detected.  An experienced
% user with access to the SuiteSparse:GraphBLAS source code may gain further
% insight into the error by examining the code that detected it.

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

\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.

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

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

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 256 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}
%-------------------------------------------------------------------------------
\label{type_size}

\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:} The \verb'GxB_Type_size' function 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 of the nine GraphBLAS objects 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.  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\_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:} The \verb'GxB_UnaryOp_ztype' function 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:} The \verb'GxB_UnaryOp_xtype' function 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.  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:} The \verb'GxB_BinaryOp_ztype' function 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:} The \verb'GxB_BinaryOp_xtype' function 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:} The \verb'GxB_BinaryOp_ytype' function 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{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},k)$ 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' are 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 *k           // user-defined auxiliary data
) ; \end{verbatim}}

There are five built-in select operators listed in the table below.  For the
first four operators, \verb'k' is a pointer to a single scalar of type
\verb'int64_t'.  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 all built-in functions in 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 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 next sections define the following methods for 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 with the signature described on the prior page.  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,k)$.  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 \verb'GxB_select' 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'.

\newpage
%-------------------------------------------------------------------------------
\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,k)$.  If the select
operator is type-generic, \verb'xtype' is returned as \verb'GrB_NULL'.

%-------------------------------------------------------------------------------
\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}{llll}
\hline
GraphBLAS             & types (domains)            & expression      & identity \\
name                  &                            & $z=f(x,y)$      & \\
\hline
% 8 numeric TxT->T
\verb'GrB_MIN_'$T$    & $T \times T \rightarrow T$ & $z = \min(x,y)$ & $+\infty$ \\
\verb'GrB_MAX_'$T$    & $T \times T \rightarrow T$ & $z = \max(x,y)$ & $-\infty$ \\
\verb'GrB_PLUS_'$T$   & $T \times T \rightarrow T$ & $z = x+y$       & 0 \\
\verb'GrB_TIMES_'$T$  & $T \times T \rightarrow T$ & $z = xy$        & 1 \\
\hline
% 4 bool x bool -> bool
\verb'GrB_LOR', \verb'GxB_LOR_BOOL'      & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \vee    y $ & false \\
\verb'GrB_LAND', \verb'GxB_LAND_BOOL'    & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \wedge  y $ & true \\
\verb'GrB_LXOR', \verb'GxB_LXOR_BOOL'    & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \veebar y $ & false \\
\verb'GrB_EQ_BOOL', \verb'GxB_ISEQ_BOOL' & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z =(x ==      y)$ & true  \\
\hline
\end{tabular}
}
\vspace{0.2in}

\noindent
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_operator'  & return the monoid operator \\
\verb'GxB_Monoid_identity'  & return the monoid identity value \\
\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 type-generic place-holder.  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'.

% \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:} The \verb'GxB_Monoid_operator' function 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:} The \verb'GxB_Monoid_identity' function 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_multipliy' & return the binary operator of a semiring \\
\verb'GrB_Semiring_free'      & free a semiring \\
\hline
\end{tabular}
}
\vspace{0.2in}

% \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'GxB_LAND_BOOL' are different operators but they are redundant since
they always return the same result).

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

    \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:

    \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:

    \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}

\begin{spec}
{\bf SPEC:} SuiteSparse:GraphBLAS pre-defines all 960 semirings that can be constructed from built-in types and operators, as 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:} The \verb'GxB_Semiring_add' function 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:} The \verb'GxB_Semiring_multiply' function 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}$.  If compiled for use in MATLAB, this maximum
size is reduced to match the MATLAB maximum size, which is $2^{48}-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
\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 explicit 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:} The \verb'GxB_Vector_type' function 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'.

\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
\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, like
\verb'nnz(A)' in MATLAB.

\paragraph{Forced completion:}
All computations for the matrix \verb'A' are guaranteed to be finished when the
method 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:} The \verb'GxB_Matrix_type' function 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 {\em GraphBLAS API Specification} 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 specification 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:}
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'.

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 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 specification states the tuples can be returned in any order.
SuiteSparse:GraphBLAS chooses to always return them in sorted order, first by
column index (all tuples in column 0 appear first, then column 1, and so on),
and then within each column the tuples are sorted by row index.
SuiteSparse:GraphBLAS guarantees this ordering but this should not be expected
of all implementations of GraphBLAS since their internal representation may
differ from that used by SuiteSparse:GraphBLAS.

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.

% \newpage
%-------------------------------------------------------------------------------
\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 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'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:} The \verb'GxB_DEFAULT' option is an extension to the spec.
\end{spec}

In the current GraphBLAS API Specification, there are four different components
in a descriptor.  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}
typedef enum
{
    GrB_OUTP,       // descriptor for output of a method
    GrB_MASK,       // descriptor for the mask input of a method
    GrB_INP0,       // descriptor for the first input of a method
    GrB_INP1        // descriptor for the second input of a method
}
GrB_Desc_Field ;
\end{verbatim} } \end{mdframed}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
typedef enum
{
    GxB_DEFAULT,    // default behavior of the method
    GrB_REPLACE,    // clear the output before assigning new values to it
    GrB_SCMP,       // use the structural complement of the input
    GrB_TRAN        // use the transpose of the input
}
GrB_Desc_Value ;
\end{verbatim} } \end{mdframed}

The internal representation is opaque to the user, but in this User Guide the
four descriptor fields of a descriptor \verb'desc' are illustrated as an array
of four 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.

\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, and neither
input matrix is transposed).

% \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', or \verb'GrB_INP1') to a particular value
(\verb'GxB_DEFAULT', \verb'GrB_SCMP', \verb'GrB_TRAN', or \verb'GrB_REPLACE').
In the current specification, the following settings can be made:

\vspace{0.2in}
\noindent
{\small
\begin{tabular}{l|p{2.4in}|p{2.2in}}
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. \\
\end{tabular}
}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Descriptor\_get:}  get a parameter from a descriptor}
%-------------------------------------------------------------------------------
\label{descriptor_get}

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

\verb'GxB_Descriptor_get' returns the value of a single field in a descriptor.

\begin{spec}
{\bf SPEC:} The \verb'GxB_Descriptor_get' function 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 GraphBLAS 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 GraphBLAS 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{GraphBLAS Operations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{operations}

The next sections define each of the GraphBLAS operations, also listed in
the table below.

\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'\langle m'\rangle = w'\odot u'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'}$ \\
\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 C API
    Specification.  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 Specification, 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 all eleven
    GraphBLAS types as dense matrices, 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}.

\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.

{\bf Performance considerations:}  Because of the way SuiteSparse:Graph\-BLAS
stores its matrices and vectors, \verb'GrB_vxm' with its default descriptor can
be slower than \verb'GrB_mxv' with its default descriptor, when the vector
\verb'u' is very sparse.  If the user application needs to use \verb'GrB_vxm'
repeatedly with very sparse vectors \verb'u', it can be faster to work on
the transpose of \verb'A' instead.

If the matrix is symmetric, then \verb"u'*A" is the same as \verb"A'*u", except
that in this case the operands to the semiring's multiplier operator are
reversed.  This has no effect if the multiplier operator is commutative, but an
adjustment would need to be made if it were not (such as replacing \verb'FIRST'
with \verb'SECOND', and \verb'GE' with \verb'LE', for example).

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 in Section~\ref{bfs} uses \verb'GrB_mxv'
instead of \verb'GrB_vxm', since the graph is symmetric and the multiplier
(\verb'AND') is commutative.

\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.

{\bf Performance considerations:}  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.  When \verb'u' is very
sparse and the default descriptor is used, \verb'GrB_mxv' is also
very efficient.

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 an application needs
to perform \verb"A'*u" repeatedly where \verb'u' is very sparse, then it
can be faster to explicitly transpose \verb'A' first, and then to use this
function with its default descriptor on the transpose.  That is, compute
\verb"C=A'" via \verb'GrB_transpose', and then use this method to
repeatedly compute \verb'C*u', without selecting \verb'GrB_TRAN'.

\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.  To
extract all rows of a vector, as in \verb't = u (:)' in MATLAB, use
\verb'I = GrB_ALL'.  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.

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:

    {\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}}

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'.

To extract all rows of a matrix, as in \verb'T = A (:,J)' in MATLAB, use
\verb'I = GrB_ALL' as the input argument.  For all columns of a matrix, use
\verb'J = GrB_ALL'.  The final step is ${\bf C \langle M \rangle  = C \odot
T}$, as described in Section~\ref{accummask}.

\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.  To extract
all rows of a matrix, as in \verb't = A (:,j)' in MATLAB, use
\verb'I = GrB_ALL' as the input argument.  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{Performance considerations:} Because of the way
SuiteSparse:Graph\-BLAS stores its matrices, row extraction is more costly than
column extraction.  That is, using the \verb'GrB_TRAN' option for the \verb'A'
matrix is slower than the default, which is to extract a column.  If this
function is to be used many times on the same matrix \verb'A' to extract rows
with the \verb'GrB_TRAN' option enabled, it can be faster to explicitly
transpose the matrix \verb'A' once, and then to extract columns instead.

\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.

\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}'$ 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'.

\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.

% \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.

Sub-row assignment in SuiteSparse:GraphBLAS is not as fast as sub-column
assignment.  If many of the rows of \verb'C' are to be modified by repeated use
of \verb'GxB_Row_subassign', it can be faster to transpose \verb'C' first and
to use \verb'GxB_Matrix_subassign' or \verb'GxB_Col_subassign' instead.

% \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.

\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'.

%-------------------------------------------------------------------------------
\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.

% \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.

% \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.

Sub-row assignment in SuiteSparse:GraphBLAS is not as fast as sub-column
assignment.  If many of the rows of \verb'C' are to be modified by repeated use
of \verb'GxB_Row_subassign', it can be faster to transpose \verb'C' first and
to use \verb'GxB_Matrix_subassign' or \verb'GxB_Col_subassign' instead.  See
\verb'GxB_Matrix_subassign' for further details.

\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.

\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
    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',
    then 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 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
    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 also
    true, then \verb'GrB_assign' deletes this entry.

\item
    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'.  In this case, the two algorithms are
identical and have the same performance.

\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}

The Accumulator Phase (${\bf S} \odot {\bf A}$ in Step 2), 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 Mask/Replace Phase, described in Section~\ref{accummask} is different:
\begin{itemize}
\item
    For \verb'GrB_Matrix_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_Matrix_subassign' (Step 2), 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_Matrix_assign' and
\verb'GxB_Matrix_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_Matrix_assign' and \verb'GxB_Matrix_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 $k$ entries.

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 + k + 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 + k + 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 + k + st \log st)$ time.  The total time is $O (t \left [a
+ s \log n \right] + (n + k + 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.  Nearly all
graphs of $n$ nodes that arise in practice have $O(n)$ edges, and most graphs
have 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 columns (thus the
$\log n$ terms).  If these are not present, if both $t$ and $k$ 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.

The difference in practice can be very dramatic, since $n$ can be many millions
for sparse graphs that can be handled on a commodity laptop.

\newpage
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
column of \verb'C' with \verb'n' entries, which can occur in practice.  It is
more common, however, that most columns 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 +
k + s \log s )$ time, even including the time for a matrix completion, where
\verb'C' is $n$-by-$n$ with $k$ 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+k$ 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+k)$, where $n$ is the dimension of \verb'C' and $k$ 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+k)$.

\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.

In SuiteSparse:GraphBLAS, this method is particularly efficient with built-in
types.  If the type of \verb'C' and \verb'A' are the same, and if \verb'A' is
not transposed via the descriptor, then \verb'T' is a pure shallow copy of
\verb'A', taking only $O(1)$ time and memory.  The output matrix \verb'C' is
never a shallow copy of \verb'T' or \verb'A'.

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 Specification.
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 Specification 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}.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{examples}

Six examples on how to use GraphBLAS are described below:
(1) performing a breadth-first search,
(2) finding a maximal independent set,
(3) creating a random matrix,
(4) creating a finite-element matrix,
(5) reading a matrix from a file,
and
(6) complex numbers as a user-defined type.
The complete set of programs appears in the
\verb'Demo' directory in SuiteSparse:GraphBLAS.

%-------------------------------------------------------------------------------
\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 a symmetric \verb'n'-by-\verb'n'
Boolean matrix, \verb'A'.  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> = A ||.&& q ; finds all the unvisited
        // successors from current q, using !v as the mask
        GrB_mxv (q, v, NULL, Boolean, A, q, 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}}

The \verb'bfs5m' function is a modified version from {\em The GraphBLAS
C API Specification} \cite{spec}.  The method here uses \verb'GrB_mxv'
instead of \verb'GrB_vxm'.

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_Info info ;
    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 mxv
    GrB_Matrix_nrows (&n, A) ;             // n = # of rows of A
    GrB_Vector_new (&v, GrB_INT32, n) ;    // Vector<int32_t> v(n) = 0
    GrB_Vector_new (&q, GrB_BOOL, n) ;     // Vector<bool> q(n) = false
    // making v dense is faster if most of the graph is expected to be searched
    // for (int32_t i = 0 ; i < n ; i++) GrB_Vector_setElement (v, 0, i) ;
    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> = A ||.&& q ; finds all the unvisited successors from current
        // q, using !v as the mask
        GrB_mxv (q, v, NULL, Boolean, A, q, desc) ;

        // successor = ||(q)
        GrB_reduce (&successor, NULL, Lor, q, NULL) ;
    }
    *v_output = v ;         // return result
    GrB_free (&q) ;         // free workspace
    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_mxv (neighbor_max, candidates, NULL, maxSelect2nd, A, prob, 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_mxv (neighbor_max, candidates, NULL, maxSelect2nd, A, prob, 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_mxv (new_neighbors, candidates, NULL, Boolean, A,
            new_members, 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 Boolean matrix and \verb'prob' is a sparse real vector (of type
\verb'FP32'), where \verb'prob(j)' is nonzero only if node \verb'j' is a
candidate.  The \verb'maxSelect2nd' semiring uses \verb'z=SECOND(x,y)' as the
multiplier operator.  The row \verb'A(i,:)' is the adjacency of node \verb'i',
and the dot product \verb'A(i,:)*prob' applies the \verb'SECOND' operator on
all entries that appear in the intersection of \verb'A(i,:)' and \verb'prob',
\verb'z=SECOND(A(i,j),prob(j))' which is just \verb'prob(j)' 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=SECOND(A(i,j),prob(j))' is the score, \verb'prob(j)',
of all neighbors \verb'j' of node \verb'i' that have a score.  Node \verb'j'
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'A*prob', 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'maxSelect2nd' 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.  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}

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]" in pseudo-MATLAB notation.

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):

    {\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 because GraphBLAS 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.  The application must instead build a list
of indices first, \verb'I=[10, 11' \verb'...' \verb'20]'.  GraphBLAS does have
a way of specifying all indices via \verb'I=GrB_ALL', which results in
\verb'A(:)', but no easy way to specify a contiguous subset of indices.  Thus,
the following index lists \verb'I' and \verb'J' must first be constructed:

    \newpage
    {\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]".

    {\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.

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.

\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 a mask is present and not complemented, \verb'GrB_INP0' is
\verb'GrB_TRAN', and \verb'GrB_INP1' 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 U}'{\bf L}$ 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.

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
{\small
\begin{tabular}{lll}
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 U \rangle} = {\bf UU}$ (outer product) \\
SandiaDot & \verb"sum(sum((U'*L).*L))"
    & ${\bf C \langle L \rangle} = {\bf U}'{\bf L}$ (dot product) \\
SandiaL  & \verb"sum(sum((L*L).*L))"
    & ${\bf C \langle L \rangle} = {\bf LL}$ (outer product) \\
\hline
\end{tabular}
}
\vspace{0.05in}

In general, the Sandia methods are the fastest of the 6 methods when
implemented in GraphBLAS.  The method in the KokkosKernels paper uses
\verb'(L*L).*L' via a masked matrix multiplication, but KokkosKernels stores
its matrices in compressed sparse row form.  GraphBLAS and MATLAB both store
their matrices in compressed sparse column form, so the Sandia method is
identical to \verb'(U*U).*U' in MATLAB and ${\bf C \langle U \rangle} = {\bf
UU}$ in GraphBLAS.  The SandiaDot and SandiaL methods do not appear in
\cite{WolfDeveciBerryHammondRajamanickam17}, but they are named this way
because they are simple extensions of the Sandia method.

The methods in MATLAB are slow because the matrix product is formed and then
its entries are pruned via the element-wise multiplication (\verb'.*').  By
contrast, \verb'GrB_mxm' only computes the entries residing in the mask, saving
time and memory.  This optimization is only exploited if the mask present and
not complemented.  Since the \verb'minitri' method does not use a mask, its
implementation in GraphBLAS has the same performance and memory requirements as
the MATLAB version \verb'nnz(A*E==2)/3'.  That is, both are very slow.

Performance results are shown in the following two tables.  The first table is
a list of matrices from the SuiteSparse Matrix Collection \cite{DavisHu11},
listing the matrix name, the number of rows and columns, the number of edges in
the graph, and the number of triangles.  The matrices were symmetrized first
with \verb"A=A+A'" and the diagonal entries were removed.  The first table
splits into two sets.  The first set of matrices also appear in the results
from the Kokkos triangles paper \cite{WolfDeveciBerryHammondRajamanickam17}.

The next table gives performance results on these matrices, with four methods.
For each method, the run time in seconds and the rate is given, where the rate
is the number of edges in the graph divided by the run time (listed in millions
of edges per second).  The first three methods in the table are for MATLAB and
the two GraphBLAS methods, on a MacBook Pro (Retina, 13inch, Late 2013), 2.8
Ghz Intel Core i7, 16 GB RAM, OSX 10.11.6, MATLAB 2017a, with the clang 8.0.0
compiler.  Only a single core was used for these results.  In addition, the
matrix \verb'L=tril(A)' and/or \verb'U=triu(A)' are used as-is without any
reordering.  The run times include the time to construct \verb'L' or \verb'U'.
MATLAB failed on one matrix because \verb'U*U' is too large.
For the first set of matrices, the outer product formulation (${\bf C \langle U
\rangle} = {\bf UU}$) is always faster than the dot product formulation, but
this is not the case for the second set.

The last column (Kokkos) is copied directly from
\cite{WolfDeveciBerryHammondRajamanickam17}.  The Kokkos results are from their
implementation of \verb"sum(sum((L*L).*L))" using a masked sparse matrix-matrix
multiply in KokkosKernels.  These results were done on an Intel Xeon Haswell
(E5-2698v3, 2.3GHz), with 512 GB RAM, 32 cores and 2 hyperthreads per core,
using the Intel \verb'icc' 17.1 compiler.  Unlike the other three methods,
\verb'L' is sorted by decreasing row degree, which improves the performance.
The Kokkos time includes the time taken to do the sort.  The run time listed is
the best time obtained from several runs with 1 to 32 threads.

Comparing GraphBLAS and Kokkos is difficult since these results were obtained
on different machines.  Also, the results in
\cite{WolfDeveciBerryHammondRajamanickam17} provide just the best-obtained
parallel results, not the results on a single core.  In addition, these results
are with a reordered \verb'L' in Kokkos, but not in GraphBLAS.  Wolf et al.
\cite{WolfDeveciBerryHammondRajamanickam17} state that reordering \verb'L'
improves the run time.  However, with these many caveats, the last column lists
the speedup of Kokkos over the GraphBLAS outer-product formulation.  Since the
Kokkos method is parallel these preliminary
comparisons indicate that the sequential performance of GraphBLAS is
competitive.  Using up to 32 threads, Kokkos is about 3 to 18 faster than
SuiteSparse:GraphBLAS, which is currently sequential (median speedup of about
9).  Further comparisons are required, however.  A parallel implementation of
the matrix-matrix multiply in \verb'GrB_mxm' is also in progress.

% in comments: the symbolic stats from SSMULTSYM on the nnz in
% L*L, the flops to compute L*L, and the memory required for L*L.

\vspace{0.5in}

{\footnotesize
\begin{tabular}{|lrrr|}
\hline
matrix & $n$  & \# edges & \# triangles \\
\hline
%------------------------------------
SNAP/cit-HepPh & 34,546 & 420,877 & 1,276,868 \\
%------------------------------------
SNAP/cit-HepTh & 27,770 & 352,285 & 1,478,735 \\
%------------------------------------
SNAP/email-EuAll & 265,214 & 364,481 & 267,313 \\
%------------------------------------
SNAP/soc-Epinions1 & 75,888 & 405,740 & 1,624,481 \\
%------------------------------------
SNAP/soc-Slashdot0811 & 77,360 & 469,180 & 551,724 \\
%------------------------------------
SNAP/soc-Slashdot0902 & 82,168 & 504,230 & 602,592 \\
%------------------------------------
SNAP/amazon0312 & 400,727 & 2,349,869 & 3,686,467 \\
%------------------------------------
SNAP/amazon0505 & 410,236 & 2,439,437 & 3,951,063 \\
%------------------------------------
SNAP/amazon0601 & 403,394 & 2,443,408 & 3,986,507 \\
%------------------------------------
SNAP/cit-Patents & 3,774,768 & 16,518,947 & 7,515,023 \\
%------------------------------------
SNAP/soc-LiveJournal1 & 4,847,571 & 42,851,237 & 285,730,264 \\
%------------------------------------
Gleich/wb-edu & 9,845,725 & 46,236,105 & 254,718,147 \\
%------------------------------------
\hline
SNAP/p2p-Gnutella09 & 8,115 & 26,013 & 2,354 \\
Mallya/lhr71 & 70,304 & 1,492,794 & 160,592 \\
Freescale/Freescale2 & 2,999,349 & 5,744,934 & 21,027,280 \\
Freescale/circuit5M & 5,558,326 & 26,983,926 & 31,019,473 \\
DIMACS10/hugebubbles-00020 & 21,198,119 & 31,790,179 & 0 \\
vanHeukelum/cage15 & 5,154,859 & 47,022,346 & 36,106,416 \\
\hline
\end{tabular}
}

\vspace{0.5in}

\hspace{-1in}
{\footnotesize
\begin{tabular}{|l|rr|rr|rr||rrr|}
\hline
matrix % & $n$  & \# entries & \# triangles
& \multicolumn{2}{|c|}{MATLAB}  % (U*U).*U
& \multicolumn{2}{|c|}{${ \bf C \langle U \rangle} = {\bf L}'{\bf U}$}
& \multicolumn{2}{|c||}{${\bf C \langle U \rangle} = {\bf UU}$}
& \multicolumn{3}{|c|}{Kokkos} \\
& time & rate & time & rate & time & rate & time & rate & speedup \\
\hline
%------------------------------------
SNAP/cit-HepPh & % 34,546 & 420,877 & 1,276,868 &
    0.363  &     1.16 &  % MATLAB
    0.180  &     2.47 &  % dot                      C<U>=L'*U
    0.049  &     9.59 &  % outer                    C<U>=U*U
    0.0044 &     79.9 &      8.3  \\ % Kokkos
%------------------------------------
SNAP/cit-HepTh & % 27,770 & 352,285 & 1,478,735 &
    0.415  &     0.85 &  % MATLAB
    0.171  &     2.05 &  % dot
    0.046  &     8.31 &  % outer
    0.0050 &     72.5 &      8.7  \\ % Kokkos
%------------------------------------
SNAP/email-EuAll & % 265,214 & 364,481 & 267,313 &
    1.264  &     0.29 &  % MATLAB
    0.133  &     2.73 &  %  dot
    0.035  &    10.33 &  %  outer
    0.0058 &     70.7 &      6.8  \\ % Kokkos
%------------------------------------
SNAP/soc-Epinions1 & % 75,888 & 405,740 & 1,624,481 &
    0.778  &     0.52 &  % MATLAB
    0.376  &     1.08 &  % dot
    0.067  &     6.01 &  % outer
    0.0039 &    108.0 &     18.0  \\ % Kokkos
%------------------------------------
SNAP/soc-Slashdot0811 & % 77,360 & 469,180 & 551,724 &
    0.990  &     0.47 &  % MATLAB
    0.318  &     1.47 &  % dot
    0.052  &     9.04 &  % outer
    0.0061 &     76.8 &      8.5 \\ % Kokkos
%------------------------------------
SNAP/soc-Slashdot0902 & % 82,168 & 504,230 & 602,592 &
    0.985  &     0.51 &  % MATLAB
    0.339  &     1.49 &  % dot
    0.059  &     8.61 &  % outer
    0.0063 &    80.1  &     9.3 \\ % Kokkos
%------------------------------------
SNAP/amazon0312 & % 400,727 & 2,349,869 & 3,686,467 &
    1.285  &     1.83 &  % MATLAB
    0.514  &     5.32 &  % dot
    0.306  &     8.61 &  % outer
    0.0754 &    30.7  &      3.6  \\ % Kokkos
%------------------------------------
SNAP/amazon0505 & % 410,236 & 2,439,437 & 3,951,063 &
    1.018  &     2.07 &  % MATLAB
    0.545  &     4.48 &  % dot
    0.297  &     8.21 &  % outer
    0.0177 &   133.0  &     16.2 \\ % Kokkos
%------------------------------------
SNAP/amazon0601 & % 403,394 & 2,443,408 & 3,986,507 &
    1.018  &     2.40 &  % MATLAB
    0.563  &     4.34 &  % dot
    0.296  &     8.27 &  % outer
    0.0184 &   132.0  &     16.0 \\ % Kokkos
%------------------------------------
SNAP/cit-Patents & % 3,774,768 & 16,518,947 & 7,515,023 &
   11.026  &     1.50 &  % MATLAB
    4.416  &     3.74 &  % dot
    2.300  &     7.18 &  % outer
    0.4970 &    31.5  &      4.4  \\ % Kokkos
%------------------------------------
SNAP/soc-LiveJournal1 & % 4,847,571 & 42,851,237 & 285,730,264 &
   11.026  &     0.40 &  % MATLAB
   39.767  &     1.08 &  % dot
   10.123  &     4.23 &  % outer
    0.7330 &    58.5  &     13.8 \\ % Kokkos
%------------------------------------
Gleich/wb-edu & % 9,845,725 & 46,236,105 & 254,718,147 &
  67.636   &     0.68 &  % MATLAB
    8.016  &     5.77 &  % dot
    3.605  &    12.82 &  % outer
    0.2320 &   199.0  &     15.5 \\ % Kokkos
%------------------------------------
\hline
%------------------------------------
SNAP/p2p-Gnutella09 &
    0.004  &     6.50 &  % MATLAB
    0.002  &    10.65 &  % dot
    0.001  &    24.24 &  % outer
           &          & \\ % Kokkos
%------------------------------------
Mallya/lhr71 & % 70,304 & 1,492,794 & 160,592 &
    0.252  &     5.93 &  % MATLAB
    0.058  &    25.90 &  % C<U>=L'*U
    0.030  &    50.37 &  % C<U>=U*U
           &          & \\ % Kokkos
%------------------------------------
Freescale/Freescale2 & % 2,999,349 & 5,744,934 & 21,027,280 \\
     0.741 &     7.75 &  % MATLAB
     0.501 &    11.46 &  % dot
     0.276 &    20.83 &  % outer
           &          & \\ % Kokkos
%------------------------------------
Freescale/circuit5M & % 5,558,326 & 26,983,926 & 31,019,473 &
       mem &          &  % MATLAB
    2.819  &     9.57 &  % dot
  194.142  &     0.14 &  % outer
           &          & \\ % Kokkos
%------------------------------------
DIMACS10/hugebubbles-00020 & % 21,198,119 & 31,790,179 & 0 &
    7.406  &     4.29 &  % MATLAB
    3.417  &     9.30 &  % dot
    6.568  &     4.84 &  % outer
           &          & \\ % Kokkos
%------------------------------------
vanHeukelum/cage15 & % 5,154,859 & 47,022,346 & 36,106,416 &
   10.187  &     4.62 &  % MATLAB
    4.407  &    10.67 &  % dot
    2.443  &    19.25 &  % outer
           &          & \\ % Kokkos
%------------------------------------
\hline
\end{tabular}
}
\vspace{0.3in}

The outer product
${\bf C \langle U \rangle} = {\bf UU}$
in GraphBLAS is very simple:

{\footnotesize
\begin{verbatim}
        int64_t ntriangles ;
        GrB_Index n, one = 1 ;
        GrB_Matrix C, U ;
        GrB_Matrix_nrows (&n, A) ;

        // U = triu (A, 1)
        GrB_Matrix_new (&U, GrB_UINT32, n, n) ;
        GxB_select (U, NULL, NULL, GxB_TRIU, A, &one, NULL) ;

        // C<U> = U*U
        GrB_Matrix_new (&C, GrB_UINT32, n, n) ;
        GrB_mxm (C, U, NULL, GxB_PLUS_TIMES_UINT32, U, U, NULL) ;

        // ntriangles = sum (C)
        GrB_reduce (&ntriangles, NULL, GxB_PLUS_INT64_MONOID, C, NULL) ;

        GrB_free (&C) ;
        GrB_free (&U) ;
\end{verbatim}
}

\newpage
The dot product method
${ \bf C \langle U \rangle} = {\bf L}'{\bf U}$
in GraphBLAS is similar:

{\footnotesize
\begin{verbatim}
        int64_t ntriangles ;
        GrB_Index n, one = 1, minusone = -1 ;
        GrB_Matrix C, L, U ;
        GrB_Matrix_nrows (&n, A) ;

        // U = triu (A, 1)
        GrB_Matrix_new (&U, GrB_UINT32, n, n) ;
        GxB_select (U, NULL, NULL, GxB_TRIU, A, &one, NULL) ;

        // L = tril (A,-1)
        GrB_Matrix_new (&L, GrB_UINT32, n, n) ;
        GxB_select (L, NULL, NULL, GxB_TRIL, A, &minusone, NULL) ;

        // C<U> = L'*U
        GrB_Matrix_new (&C, GrB_UINT32, n, n) ;
        GrB_Descriptor_new (&d) ;
        GrB_Descriptor_set (d, GrB_INP0, GrB_TRAN) ;
        GrB_mxm (C, U, NULL, GxB_PLUS_TIMES_UINT32, L, U, d) ;
        GrB_free (&d) ;

        // ntriangles = sum (C)
        GrB_reduce (&ntriangles, NULL, GxB_PLUS_INT64_MONOID, C, NULL) ;

        GrB_free (&C) ;
        GrB_free (&L) ;
        GrB_free (&U) ;
\end{verbatim}
}

\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
%-------------------------------------------------------------------------------
\section{Installing SuiteSparse:GraphBLAS}
%-------------------------------------------------------------------------------

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.

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 parallel threads, GraphBLAS must be compiled with OpenMP
so that it has access to a critical section mechanism.  OpenMP is optional if
the user application does not make multiple simultaneous calls to GraphBLAS.

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:

    {\small
    \begin{verbatim}
    CC=gcc cmake ..
    CC=gcc-6 cmake ..
    CC=xlc cmake ..
    CC=icc cmake ..  \end{verbatim} }

Then do \verb'make' in the \verb'build' directory.  If this still fails, see
the \verb'CMakeLists.txt' file.  You may need 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  "-std=c11 -lm -fopenmp")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "Intel")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "Clang")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "MSVC")
        ...
    endif ( )
    \end{verbatim} }

Once \verb'cmake' and \verb'make' finish, run the demos in the
\verb'GraphBLAS/Demo' folder:

    {\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'.

To install the library in \verb'/usr/local/lib' and \verb'/usr/local/include',
go to the top-level GraphBLAS folder and type:

    {\small
    \begin{verbatim}
    sudo make install \end{verbatim} }

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.

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.

To remove all compiled files, type \verb'make' \verb'distclean' in the top-level
GraphBLAS folder.

{\bf NOTE: SuiteSparse:GraphBLAS has not yet been ported to Windows.}
However, with \verb'cmake' the port to Windows should be straight-forward
(this is in progress).

\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 also 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.

\newpage
%-------------------------------------------------------------------------------
% References
%-------------------------------------------------------------------------------
{\small
\addcontentsline{toc}{section}{References}
\bibliographystyle{annotate}
\bibliography{GraphBLAS_UserGuide.bib}
}
\end{document}