File: GraphBLAS_UserGuide.tex

package info (click to toggle)
suitesparse-graphblas 7.4.0%2Bdfsg-2
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 67,112 kB
sloc: ansic: 1,072,243; cpp: 8,081; sh: 512; makefile: 506; asm: 369; python: 125; awk: 10
file content (16250 lines) | stat: -rw-r--r-- 748,660 bytes
parent folder | download | duplicates (2)
\documentclass[12pt]{article}
\batchmode
\usepackage{url}
\urlstyle{sf}
\usepackage[svgnames]{xcolor}
\usepackage[colorlinks,linkcolor=Blue,citecolor=Blue,urlcolor=Blue]{hyperref}
\usepackage{amssymb}
\usepackage{amsmath}
\usepackage{framed}
\usepackage{mdframed}
% \usepackage{geometry}
% \usepackage{pdflscape}
\newmdenv[backgroundcolor=yellow]{alert}
\newmdenv[backgroundcolor=red]{note}
\hyphenation{Suite-Sparse}
\hyphenation{Graph-BLAS}
\hyphenation{Suite-Sparse-Graph-BLAS}

\DeclareMathOperator{\sech}{sech}
\DeclareMathOperator{\csch}{csch}
\DeclareMathOperator{\arcsec}{arcsec}
\DeclareMathOperator{\arccot}{arcCot}
\DeclareMathOperator{\arccsc}{arcCsc}
\DeclareMathOperator{\arccosh}{arcCosh}
\DeclareMathOperator{\arcsinh}{arcsinh}
\DeclareMathOperator{\arctanh}{arctanh}
\DeclareMathOperator{\arcsech}{arcsech}
\DeclareMathOperator{\arccsch}{arcCsch}
\DeclareMathOperator{\arccoth}{arcCoth}
\DeclareMathOperator{\sgn}{sgn}
\DeclareMathOperator{\erf}{erf}
\DeclareMathOperator{\erfc}{erfc}

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

\title{User Guide for SuiteSparse:GraphBLAS}

\author{Timothy A. Davis \\
\small
davis@tamu.edu, Texas A\&M University. \\
\small
\url{http://suitesparse.com} \\
\small
\url{https://people.engr.tamu.edu/davis} \\
\small
\url{https://twitter.com/DocSparse}
}

% version and date are set by cmake
\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 high-performance graph algorithms based on the elegant
mathematics of sparse matrix operations on a semiring.

When compared with MATLAB R2021a, some methods in GraphBLAS are up to
a million times faster than MATLAB, even when using the same syntax.
Typical speedups are in the range 2x to 30x.
The statement \verb'C(M)=A' when using MATLAB sparse matrices takes
$O(e^2)$ time where $e$ is the number of entries in \verb'C'.  GraphBLAS
can perform the same computation with the exact same syntax, but
in $O(e \log e)$ time (or $O(e)$ in some cases), and in practice that
means GraphBLAS can compute \verb'C(M)=A' for a large problem in under
a second, while MATLAB takes about 4 to 5 days.

SuiteSparse:GraphBLAS is under the Apache-2.0 license.

\end{abstract}

\newpage
{\small
\tableofcontents
}

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

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

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

For more details on SuiteSparse:GraphBLAS, and its use in LAGraph, see
\cite{Davis19,Davis22,Davis18b,DavisAznavehKolodziej19,Davis20,Mattson19}.

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, Carl Yang, and Benjamin Brock}
\cite{BulucMattsonMcMillanMoreiraYang17,spec,spec2}, 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 conforms to Version
\input{GraphBLAS_API_version.tex} of {\em The GraphBLAS C API 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.

All functions, objects, and macros with a name of the form \verb'GxB_*' are
SuiteSparse-specific extensions to the specification.

\begin{alert}
{\bf SPEC:} Non-obvious deviations or additions to the GraphBLAS C API
Specification are highlighted in a box like this one, except for \verb'GxB*'
methods.  They are not highlighted since their name makes it clear that they
are extensions to the GraphBLAS C API.
\end{alert}


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

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

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

Graphs can be huge, with many nodes and edges.  A dense adjacency matrix ${\bf
A}$ for a graph of $n$ nodes takes $O(n^2)$ memory, which is impossible if $n$
is, say, a million.  Let $|{\bf A}|$ denote the number of entries in a matrix.
Most graphs arising in practice are sparse, however, with only $|{\bf A}|=O(n)$
edges, where $|{\bf A}|$ denotes the number of edges in the graph, or the
number of explicit entries present in the data structure for the matrix ${\bf
A}$.  Sparse graphs with millions of nodes and edges can easily be created by
representing them as sparse matrices, where only explicit values need to be
stored.  Some graphs are {\em hypersparse}, with ${|\bf A}| << n$.
SuiteSparse:GraphBLAS supports three kinds of sparse matrix formats: a regular
sparse format, taking $O(n+|{\bf A}|)$ space, a hypersparse format taking only
$O(|{\bf A}|)$ space, and a bitmap form, taking $O(n^2)$ space.  Full matrices
are also represented in $O(n^2)$ space.  Using its hypersparse format, creating
a sparse matrix of size $n$-by-$n$ where $n=2^{60}$ (about $10^{18}$) can be
done on quite easily on a commodity laptop, limited only by $|{\bf A}|$.
To the GraphBLAS user application, all matrices look alike, since these formats
are opaque, and SuiteSparse:GraphBLAS switches between them at will.

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} (also called the
{\em structure}) of a matrix  defines where its explicit entries appear.  It
will be referenced in one of two equivalent ways.  It can be viewed as a set of
indices $(i,j)$, where $(i,j)$ is in the pattern of a matrix ${\bf A}$ if ${\bf
A}(i,j)$ is an explicit value.  It can also be viewed as a Boolean matrix ${\bf
S}$ where ${\bf S}(i,j)$ is true if $(i,j)$ is an explicit entry and false
otherwise.  In MATLAB notation, \verb'S=spones(A)' or \verb'S=(A~=0)', if the
implicit value is zero.  The \verb'(i,j)' pairs, and their values, can also be
extracted from the matrix via the MATLAB expression \verb'[I,J,X]=find(A)',
where the \verb'k'th tuple \verb'(I(k),J(k),X(k))' represents the explicit
entry \verb'A(I(k),J(k))', with numerical value \verb'X(k)' equal to $a_{ij}$,
with row index $i$=\verb'I(k)' and column index $j$=\verb'J(k)'.

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

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

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

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

% \vspace{0.1in}
\begin{tabular}{ll}
operation                           & approximate MATLAB/Octave 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' \\
select                              & \verb'C=tril(A)' \\
\hline
\end{tabular}
\vspace{0.1in}

GraphBLAS can do far more than what MATLAB/Octave 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.

SuiteSparse:GraphBLAS has 13 built-in scalar types: Boolean, single and double
precision floating-point (real and complex), 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, vectors, or scalars.

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 many 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), four logical operators: AND, OR, exclusive-OR, and
Boolean equality (XNOR), four bitwise operators (AND, OR, XOR, and XNOR),
and the ANY operator
See Section~\ref{any_pair} for more details on the unusual ANY operator.
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 thousands of unique semirings.  With typecasting, any of these
semirings can be applied to matrices \verb'C', \verb'A', and \verb'B' of 13
predefined types, in any combination.  This results in millions of 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.

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, bitwise operators,
or any user-defined monoid on any user-defined type).

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

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

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

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

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

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

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

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

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

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

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

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

\end{itemize}

\noindent
This process can be described in mathematical notation as:
    \vspace{-0.2in}
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> ${\bf A = A}^{\sf T}$, if requested via descriptor (first input option) \\
    \> ${\bf B = B}^{\sf T}$, if requested via descriptor (second input option) \\
    \> ${\bf T}$ is computed according to the specific operation  \\
    \> ${\bf C \langle M \rangle = C \odot T}$,
        accumulating and writing the results back via the mask
    \end{tabbing} }
\noindent
The application of the mask and the accumulator operator is written as
${\bf C \langle M \rangle = C \odot T}$ where ${\bf Z = C \odot T}$ denotes the
application of the accumulator operator, and
${\bf C \langle M \rangle = Z}$
denotes the mask operator via the Boolean matrix ${\bf M}$.  The Accumulator
Phase, ${\bf Z = C \odot T}$, is performed as follows:

    % \vspace{-0.2in}
    % accum: Z = C odot T
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> {\bf Accumulator Phase}: compute ${\bf Z = C \odot T}$: \\
    \> \> if \verb'accum' is \verb'NULL' \\
    \> \>\>    ${\bf Z = T}$ \\
    \> \> else \\
    \> \>\>    ${\bf Z = C \odot T}$
    \end{tabbing}}
The accumulator operator is $\odot$ in GraphBLAS notation, or \verb'accum'
in the code.  The pattern of ${\bf C \odot T}$ is the set union of the
patterns of ${\bf C}$ and ${\bf T}$, and the operator is applied only on the
set intersection of ${\bf C}$ and ${\bf T}$.  Entries in neither the pattern
of ${\bf C}$ nor ${\bf T}$ do not appear in the pattern of ${\bf Z}$.  That is:
    % \newpage
    \vspace{-0.2in}
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> for all entries $(i,j)$ in ${\bf C \cap T}$
    (that is, entries in both ${\bf C}$ and ${\bf T}$) \\
    \> \> $z_{ij} = c_{ij} \odot t_{ij}$ \\
    \> for all entries $(i,j)$ in ${\bf C \setminus T}$
    (that is, entries in ${\bf C}$ but not ${\bf T}$) \\
    \> \> $z_{ij} = c_{ij}$ \\
    \> for all entries $(i,j)$ in ${\bf T \setminus C}$
    (that is, entries in ${\bf T}$ but not ${\bf C}$) \\
    \> \> $z_{ij} = t_{ij}$
    \end{tabbing} }
The Accumulator Phase is followed by the Mask/Replace Phase,
${\bf C \langle M \rangle = Z}$
as controlled by the \verb'GrB_REPLACE' and \verb'GrB_COMP' 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_COMP') \\
    \> \>\>\>      ${\bf C}$ is not modified \\
    \> \>\>    else \\
    \> \>\>\>      ${\bf C = Z}$ \\
    \> \> else \\
    \> \>\>    if (\verb'GrB_COMP') \\
    \> \>\>\>      ${\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}.

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

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

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.

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 a built-in method.  The Mask operator in GraphBLAS works
identically as sparse logical indexing in MATLAB, but is typically far faster
in SuiteSparse:GraphBLAS than the same operation using MATLAB sparse matrices.

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

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

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

However, unlike MATLAB, the ANSI C11 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.  Positive values
outside the range of the integer are converted to the largest positive integer,
and negative values less than the most negative integer are converted to that
most negative integer.  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'.  This is
unlike MATLAB, which does not allow a typecast of a \verb'NaN' to the MATLAB
logical type.

\begin{alert}
{\bf SPEC:} the GraphBLAS API C Specification states that typecasting follows
the rules of ANSI C.  Yet C leaves some typecasting undefined.  All typecasting
between built-in types in SuiteSparse:GraphBLAS is precisely defined, as an
extension to the specification.
\end{alert}

\begin{alert}
{\bf SPEC:} Some functions do not make use of all of their inputs; in
particular the binary operators \verb'FIRST', \verb'SECOND', and \verb'ONEB',
and many of the index unary operators.  The Specification requires that the
inputs to these operators must be compatible with (that is, can be typecasted
to) the inputs to the operators, even if those inputs are not used and no
typecasting would ever occur.  As an extension to the specification,
SuiteSparse:GraphBLAS does not perform this error check on unused inputs of
built-in operators.  For example, the \verb'GrB_FIRST_INT64' operator can be
used in \verb'GrB_eWiseAdd(C,..,A,B,...)' on a matrix \verb'B' of any type,
including user-defined types.  For this case, the matrix \verb'A' must be
compatible with \verb'GrB_INT64'.
\end{alert}

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

As a summary of what GraphBLAS can do, the following table lists all GraphBLAS
operations.  Upper case letters denote a matrix, lower case letters are
vectors, and ${\bf AB}$ denote the multiplication of two matrices over a
semiring.

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.

\vspace{0.05in}
{\footnotesize
\begin{tabular}{lll}
\hline
\verb'GrB_mxm'       & matrix-matrix multiply  & ${\bf C \langle M \rangle = C \odot AB}$ \\
\verb'GrB_vxm'       & vector-matrix multiply  & ${\bf w^{\sf T}\langle m^{\sf T}\rangle = w^{\sf T}\odot u^{\sf T}A}$ \\
\verb'GrB_mxv'       & matrix-vector multiply  & ${\bf w \langle m \rangle = w \odot Au}$ \\
\hline
\verb'GrB_eWiseMult' & element-wise,           & ${\bf C \langle M \rangle = C \odot (A \otimes B)}$ \\
                     & set intersection        & ${\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 union               & ${\bf w \langle m \rangle = w \odot (u \oplus  v)}$ \\
\hline
\verb'GxB_eWiseUnion'& element-wise,           & ${\bf C \langle M \rangle = C \odot (A \oplus  B)}$ \\
                     & set union               & ${\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)}$ \\
                     & apply binary operator   & ${\bf C \langle M \rangle = C \odot} f({\bf A},y)$ \\
                     &                         & ${\bf C \langle M \rangle = C \odot} f(x,{\bf A})$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f({\bf u},y)$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f(x,{\bf u})$ \\
                     & apply index-unary op    & ${\bf C \langle M \rangle = C \odot} f({\bf A},i,j,k)$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f({\bf u},i,0,k)$ \\
\hline
\verb'GrB_select'    & select entries          & ${\bf C \langle M \rangle = C \odot} \mbox{select}({\bf A},i,j,k)$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} \mbox{select}({\bf u},i,0,k)$ \\
\hline
\verb'GrB_reduce'    & reduce to vector        & ${\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]$ \\
                     & reduce to scalar        & $s = s \odot [{\oplus}_{ij}  {\bf A}(i,j)]$ \\
\hline
\verb'GrB_transpose' & transpose               & ${\bf C \langle M \rangle = C \odot A^{\sf T}}$ \\
\hline
\verb'GrB_kronecker' & Kronecker product       & ${\bf C \langle M \rangle = C \odot \mbox{kron}(A, B)}$ \\
\hline
\end{tabular}
}
\vspace{0.15in}

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Interfaces to MATLAB, Octave, Python, Julia, Java} %%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The MATLAB/Octave interface to SuiteSparse:GraphBLAS is included with this
distribution, described in Section~\ref{octave}.
It is fully polished, and fully tested, but does have
some limitations that will be addressed in future releases.
Two Python interfaces are now available, as is a
Julia interface.  These are not part of the SuiteSparse:GraphBLAS distribution.
See the links below (see Sections \ref{python} and \ref{julia}).

%===============================================================================
\subsection{MATLAB/Octave Interface}
%===============================================================================
\label{octave}

An easy-to-use MATLAB/Octave interface for SuiteSparse:GraphBLAS is available;
see the documentation in the \verb'GraphBLAS/GraphBLAS' folder for details.
Start with the \verb'README.md' file in that directory.  An easy-to-read output
of the MATLAB demos can be found in \verb'GraphBLAS/GraphBLAS/demo/html'.

The MATLAB/Octave interface adds the \verb'@GrB' class, which is an opaque
MATLAB/Octave object that contains a GraphBLAS matrix, either double or single
precision (real or complex), boolean, or any of the built-in integer types.
MATLAB/Octave sparse and full matrices can be arbitrarily mixed with GraphBLAS
matrices.  The following overloaded operators and methods all work as you would
expect for any matrix.  The matrix multiplication \verb'A*B' uses the
conventional \verb'PLUS_TIMES' semiring.

{\footnotesize
\begin{verbatim}
    A+B    A-B   A*B    A.*B   A./B   A.\B   A.^b    A/b    C=A(I,J)
    -A     +A    ~A     A'     A.'    A&B    A|B     b\A    C(I,J)=A
    A~=B   A>B   A==B   A<=B   A>=B   A<B    [A,B]   [A;B]  A(1:end,1:end) \end{verbatim}}

For a list of overloaded operations and static methods, type
\verb'methods GrB' in MATLAB/Octave, or \verb'help GrB' for more details.

{\bf Limitations:}
Some features for MATLAB/Octave sparse matrices are not yet available for
GraphBLAS matrices.  Some of these may be added in future releases.

\begin{packed_itemize}
    \item \verb'GrB' matrices with dimension larger than \verb'2^53' do not
        display properly in the \verb'whos' command.  The size is displayed
        correctly with \verb'disp' or \verb'display'.
    \item Non-blocking mode is not exploited.
        % ; this would require
        % a MATLAB/Octave mexFunction to modify its inputs, which is
        % technically possible but not permitted by the MATLAB/Octave API.
        % This can have significant impact on performance, if an
        % m-file makes many repeated tiny changes to a matrix.  This 
        % can be done in the C API but not MATLAB/Octave.
    \item Linear indexing: \verb'A(:)' for a 2D matrix, and \verb'I=find(A)'.
    \item Singleton expansion.
    \item Dynamically growing arrays, where \verb'C(i)=x' can increase
        the size of \verb'C'.
    \item Saturating element-wise binary and unary operators for integers.
        For \verb'C=A+B' with MATLAB \verb'uint8' matrices, results
        saturate if they exceed 255.  This is not compatible with
        a monoid for \verb'C=A*B', and thus MATLAB does not support
        matrix-matrix multiplication with \verb'uint8' matrices.
        In GraphBLAS, \verb'uint8' addition acts in a modulo fashion.
    \item Solvers, so that \verb'x=A\b' could return a GF(2) solution,
        for example.
    \item Sparse matrices with dimension higher than 2.
\end{packed_itemize}

%===============================================================================
\subsection{Python Interface}
%===============================================================================
\label{python}

See Michel Pelletier's Python interface at
\url{https://github.com/michelp/pygraphblas};
it also appears at
\url{https://anaconda.org/conda-forge/pygraphblas}.

See Jim Kitchen and Erik Welch's (both from Anaconda, Inc.) Python interface at
\url{https://github.com/python-graphblas/python-graphblas} (formerly known as grblas).
See also \\
\url{https://anaconda.org/conda-forge/graphblas}.

Both of them allow for pending work to be left pending in a \verb'GrB_Matrix'.

%===============================================================================
\subsection{Julia Interface}
%===============================================================================
\label{julia}

The Julia interface is at
\url{https://github.com/JuliaSparse/SuiteSparseGraphBLAS.jl}, developed by Will
Kimmerer, Abhinav Mehndiratta, Miha Zgubic, and Viral Shah.  
Unlike the MATLAB/Octave interface (and like the Python interfaces) the Julia 
interface can keep pending work (zombies, pending tuples, jumbled state) in
a \verb'GrB_Matrix'. This makes Python and Julia the best high-level interfaces
for SuiteSparse:GraphBLAS.  MATLAB is not as well suited, since it does not
allow inputs to a function or mexFunction to be modified, so any pending
work must be finished before a matrix can be used as input.

%===============================================================================
\subsection{Java Interface}
%===============================================================================
\label{java}

Fabian Murariu is working on a Java interface.
See \newline
\url{https://github.com/fabianmurariu/graphblas-java-native}.

%===============================================================================
\section{Performance of MATLAB versus GraphBLAS}
%===============================================================================
\label{matlab_performance}

MATLAB R2021a includes v3.3 of SuiteSparse:GraphBLAS as a built-in library, but
uses it only for \verb'C=A*B' when both \verb'A' and \verb'B' are sparse.  In
prior versions of MATLAB, \verb'C=A*B' relied on the \verb'SFMULT' and
\verb'SSMULT' packages in SuiteSparse, which are single-threaded (also written
by this author).  The GraphBLAS \verb'GrB_mxm' is up to 30x faster on a 20-core
Intel Xeon, compared with \verb'C=A*B' in MATLAB R2020b and earlier.  With
MATLAB R2021a and later, the performance of \verb'C=A*B' when using MATLAB
sparse matrices is identical to the performance for GraphBLAS matrices, since
the same code is being used by both (\verb'GrB_mxm').

Other methods in GraphBLAS are also faster, some {\em extremely} so, but are
not yet exploited as built-in operations MATLAB.  In particular, the statement
\verb'C(M)=A' (where \verb'M' is a logical matrix) takes under a second for a
large sparse problem when using GraphBLAS via its \verb'@GrB' interface.  By
stark contrast, MATLAB would take about 4 or 5 days, a speedup of about
500,000x.  For a smaller problem, GraphBLAS takes 0.4 seconds while MATLAB
takes 28 hours (a speedup of about 250,000x).  Both cases use the same
statement with the same syntax (\verb'C(M)=A') and compute exactly the same
result.  Below are the results for \verb'n'-by-\verb'n' matrices in GraphBLAS
v5.0.6 and MATLAB R2020a, on a Dell XPS13 laptop (16GB RAM, Intel(R) Core(TM)
i7-8565U CPU @ 1.80GHz with 4 hardware cores).  GraphBLAS is using 4 threads.

\vspace{0.10in}
{\scriptsize
\begin{tabular}{rrr|rrr}
\hline
\verb'n'    & \verb'nnz(C)' & \verb'nnz(M)' & GraphBLAS (sec) & MATLAB (sec) & speedup \\
\hline
2,048        & 20,432         & 2,048          & 0.005     & 0.024     & 4.7 \\
4,096        & 40,908         & 4,096          & 0.003     & 0.115     & 39 \\
8,192        & 81,876         & 8,191          & 0.009     & 0.594     & 68 \\
16,384       & 163,789        & 16,384         & 0.009     & 2.53      & 273 \\
32,768       & 327,633        & 32,767         & 0.014     & 12.4      & 864 \\
65,536       & 655,309        & 65,536         & 0.025     & 65.9      & 2,617 \\
131,072      & 1,310,677      & 131,070        & 0.055     & 276.2     & 4,986 \\
262,144      & 2,621,396      & 262,142        & 0.071     & 1,077     & 15,172 \\
524,288      & 5,242,830      & 524,288        & 0.114     & 5,855     & 51,274 \\
1,048,576    & 10,485,713     & 1,048,576      & 0.197     & 27,196    & 137,776 \\
2,097,152    & 20,971,475     & 2,097,152      & 0.406     & 100,799   & 248,200 \\
4,194,304    & 41,942,995     & 4,194,304      & 0.855  & 4 to 5 days? & 500,000?\\
\hline
\end{tabular}}
\vspace{0.10in}

The assignment \verb'C(I,J)=A' in MATLAB, when using \verb'@GrB' objects, is up
to 1000x faster than the same statement with the same syntax, when using MATLAB
sparse matrices instead.  Matrix concatenation \verb'C = [A B]' is about 17
times faster in GraphBLAS, on a 20-core Intel Xeon.  For more details, see the
\verb'GraphBLAS/GraphBLAS/demo' folder and its contents.

Below is a comparison of other methods in SuiteSparse:GraphBLAS, compared with
MATLAB 2021a.  SuiteSparse:GraphBLAS: v6.1.4 (Jan 12, 2022), was used, compiled
with gcc 11.2.0.  The system is an Intel(R) Xeon(R) CPU E5-2698 v4 @ 2.20GHz
(20 hardware cores, 40 threads), Ubuntu 20.04, 256GB RAM.  Full details appear
in the \verb'GraphBLAS/GraphBLAS/demo/benchmark' folder.  For this matrix,
SuiteSparse:GraphBLAS is anywhere from 3x to 17x faster than the built-in
methods in MATLAB.  This matrix is not special, but is typical of the relative
performance of many large matrices.  Note that two of these (\verb'C=L*S' and
\verb'C=S*R') rely on an older version of SuiteSparse:GraphBLAS (v3.3.3) built
into MATLAB R2021a.

{\footnotesize
\begin{verbatim}
    Legend:
    S: large input sparse matrix (n-by-n), the GAP-twitter matrix
    x: dense vector (1-by-n or n-by-1)
    F: dense matrix (4-by-n or n-by-4)
    L: 8-by-n sparse matrix, about 1000 entries
    R: n-by-8 sparse matrix, about 1000 entries
    B: n-by-n sparse matrix, about nnz(S)/10 entries
    p,q: random permutation vectors

    GAP/GAP-twitter: n: 61.5784 million nnz: 1468.36 million
    (run time in seconds):
    y=S*x:   MATLAB:  22.8012 GrB:   2.4018 speedup:     9.49
    y=x*S:   MATLAB:  16.1618 GrB:   1.1610 speedup:    13.92
    C=S*F:   MATLAB:  30.6121 GrB:   9.7052 speedup:     3.15
    C=F*S:   MATLAB:  26.4044 GrB:   1.5245 speedup:    17.32
    C=L*S:   MATLAB:  19.1228 GrB:   2.4301 speedup:     7.87
    C=S*R:   MATLAB:   0.0087 GrB:   0.0020 speedup:     4.40
    C=S'     MATLAB: 224.7268 GrB:  22.6855 speedup:     9.91
    C=S+S:   MATLAB:  14.3368 GrB:   1.5539 speedup:     9.23
    C=S+B:   MATLAB:  15.5600 GrB:   1.5098 speedup:    10.31
    C=S(p,q) MATLAB:  95.6219 GrB:  15.9468 speedup:     6.00    \end{verbatim}
}

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

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

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

The \verb'GraphBLAS.h' file defines functions, types, and macros prefixed with
\verb'GrB_' and \verb'GxB_' that may be used in user applications.  The prefix
\verb'GrB_' denotes items that appear in the official {\em GraphBLAS C API
Specification}.  The prefix \verb'GxB_' refers to SuiteSparse-specific
extensions to the GraphBLAS API.

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

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

{\footnotesize
\begin{verbatim}
    #if GxB_SPEC_VERSION >= 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 (5,2,0)
    ... use features from version 5.2.0 (or later)
    of a specific GraphBLAS implementation
    #endif \end{verbatim}}

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

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

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

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

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

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

The remainder of this section describes GraphBLAS functions that start or finalize GraphBLAS,
error handling, and the GraphBLAS integer.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function/type   & purpose                                 & Section \\
\hline
\verb'GrB_Index'     & the GraphBLAS integer                        & \ref{grbindex} \\
\verb'GrB_init'      & start up GraphBLAS                           & \ref{init} \\
\verb'GrB_getVersion'& C API supported by the library               & \ref{getVersion} \\
\verb'GxB_init'      & start up GraphBLAS with different \verb'malloc' & \ref{xinit} \\
\verb'GrB_Info'      & status code returned by GraphBLAS functions  & \ref{info} \\
\verb'GrB_error'     & get more details on the last error           & \ref{error} \\
\verb'GrB_finalize'  & finish GraphBLAS                             & \ref{finalize} \\
\hline
\end{tabular}
}
\vspace{0.2in}

%===============================================================================
\subsection{{\sf GrB\_Index:} the GraphBLAS integer} %==========================
%===============================================================================
\label{grbindex}

Matrix and vector dimensions and indexing rely on a specific integer,
\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/Octave.  In SuiteSparse:GraphBLAS, the largest permitted index value
is \verb'GrB_INDEX_MAX', defined as $2^{60}-1$.  The largest permitted
matrix or vector dimension is $2^{60}$ (that is, \verb'GrB_INDEX_MAX+1').
The largest \verb'GrB_Matrix' that
SuiteSparse: GraphBLAS can construct is thus $2^{60}$-by-$2^{60}$.  An
$n$-by-$n$ matrix $\bf A$ that size can easily be constructed in practice with
$O(|{\bf A}|)$ memory requirements, where $|{\bf A}|$ denotes the number of
entries that explicitly appear in the pattern of ${\bf A}$.  The time and
memory required to construct a matrix that large does not depend on $n$, since
SuiteSparse:GraphBLAS can represent ${\bf A}$ in hypersparse form (see
Section~\ref{hypersparse}).  The largest \verb'GrB_Vector' that can be
constructed is $2^{60}$-by-1.

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_init           // start up GraphBLAS
(
    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.  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.

All methods and operations that extract values from a GraphBLAS object and
return them into non-opaque user arrays always ensure that the user-visible
arrays are fully populated when they return: \verb'GrB_*_reduce' (to scalar),
\verb'GrB_*_nvals', \verb'GrB_*_extractElement', and
\verb'GrB_*_extractTuples'.  These functions do {\em not} guarantee that the
opaque objects they depend on are finalized.  To do that, use
\verb'GrB_wait' instead.

SuiteSparse:GraphBLAS is multithreaded internally, via OpenMP, and it is also
safe to use in a multithreaded user application.  See Section~\ref{sec:install}
for details.
User threads must not operate on the same matrices at the same time, with one
exception.  Multiple user threads can use the same matrices or vectors as
read-only inputs to GraphBLAS operations or methods, but only if they have no
pending operations (use \verb'GrB_wait'
first).  User threads cannot simultaneously modify a matrix or vector via any
GraphBLAS operation or method.

It is safe to use the internal parallelism in SuiteSparse:GraphBLAS on
matrices, vectors, and scalars that are not yet completed.  The library
handles this on its own.  The \verb'GrB_wait' function is only
needed when a user application makes multiple calls to GraphBLAS in parallel,
from multiple user threads.

With multiple user threads, exactly one user thread must call \verb'GrB_init'
before any user thread may call any \verb'GrB_*' or \verb'GxB_*' function.
When the user application is finished, exactly one user thread must call
\verb'GrB_finalize', after which no user thread may call any \verb'GrB_*' or
\verb'GxB_*' function.
The mode of a GraphBLAS session can be queried with \verb'GxB_get';
see Section~\ref{options} for details.

%===============================================================================
\subsection{{\sf GrB\_getVersion:} determine the C API Version} %===============
%===============================================================================
\label{getVersion}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_getVersion         // runtime access to C API version number
(
    unsigned int *version,      // returns GRB_VERSION
    unsigned int *subversion    // returns GRB_SUBVERSION
) ;
\end{verbatim}
}\end{mdframed}

GraphBLAS defines two compile-time constants that
define the version of the C API Specification
that is implemented by the library:
\verb'GRB_VERSION' and \verb'GRB_SUBVERSION'.
If the user program was compiled with one
version of the library but linked with a different one later on, the
compile-time version check with \verb'GRB_VERSION' would be stale.
\verb'GrB_getVersion' thus provides a runtime access of the version of the C
API Specification supported by the library.

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_init           // start up GraphBLAS and also define malloc
(
    GrB_Mode mode,          // blocking or non-blocking mode
    // pointers to memory management functions.
    void * (* user_malloc_function  ) (size_t),
    void * (* user_calloc_function  ) (size_t, size_t),
    void * (* user_realloc_function ) (void *, size_t),
    void   (* user_free_function    ) (void *)
) ;
\end{verbatim}
}\end{mdframed}

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

\verb'user_calloc_function' and \verb'user_realloc_function' are optional, and
may be \verb'NULL'.  If \verb'NULL', then the \verb'user_malloc_function' is
relied on instead, for all memory allocations.

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

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

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

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

Not all GraphBLAS methods or operations can return all status codes.
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,spec2}.

\vspace{0.2in}
\noindent
{\small
\begin{tabular}{lrp{2.8in}}
\hline
Error                         & value & description \\
\hline
\verb'GrB_SUCCESS'              & 0   & the method or operation was successful \\
\verb'GrB_NO_VALUE'             & 1   & the method was successful, but the entry \\
                                &     & does not appear in the matrix or vector. \\
\verb'GxB_EXHAUSTED'            & 2   & the iterator is exhausted \\
\hline
\hline
\verb'GrB_UNINITIALIZED_OBJECT' & -1   & object has not been initialized \\
\verb'GrB_NULL_POINTER'         & -2   & input pointer is \verb'NULL' \\
\verb'GrB_INVALID_VALUE'        & -3   & generic error code; some value is bad \\
\verb'GrB_INVALID_INDEX'        & -4   & a row or column index is out of bounds \\
\verb'GrB_DOMAIN_MISMATCH'      & -5   & object domains are not compatible \\
\verb'GrB_DIMENSION_MISMATCH'   & -6   & matrix dimensions do not match \\
\verb'GrB_OUTPUT_NOT_EMPTY'     & -7   & output matrix already has values in it \\
\verb'GrB_NOT_IMPLEMENTED'      & -8   & not implemented in SS:GrB \\
\verb'GrB_PANIC'                & -101 & unrecoverable error \\
\verb'GrB_OUT_OF_MEMORY'        & -102 & out of memory \\
\verb'GrB_INSUFFICIENT_SPACE'   & -103 & output array not large enough \\
\verb'GrB_INVALID_OBJECT'       & -104 & object is corrupted \\
\verb'GrB_INDEX_OUT_OF_BOUNDS'  & -105 & a row or column index is out of bounds \\
\verb'GrB_EMPTY_OBJECT'         & -106 & a input scalar has no entry \\
\hline
\end{tabular}
\vspace{0.2in}
}

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_error      // return a string describing the last error
( 
    const char **error, // error string
    <type> object       // a GrB_matrix, GrB_Vector, etc.
) ;
\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 for a
particular object in a null-terminated string.  The string returned by
\verb'GrB_error' is never a \verb'NULL' string, but it may have length zero
(with the first entry being the \verb"'\0'" string-termination value).  The
string must not be freed or modified.

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

If \verb'C' has no error status, or if the error is not recorded in
the string, an empty non-null string is returned.  In particular,
out-of-memory conditions result in an empty string from \verb'GrB_error'.

SuiteSparse:GraphBLAS reports many helpful details via \verb'GrB_error'.  For
example, if a row or column index is out of bounds, the report will state what
those bounds are.  If a matrix dimension is incorrect, the mismatching
dimensions will be provided.  \verb'GrB_BinaryOp_new', \verb'GrB_UnaryOp_new',
and \verb'GrB_IndexUnaryOp_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' and \verb'Test' folder,
which intentionally generate errors to illustrate the use of \verb'GrB_error'.

The only functions in GraphBLAS that return an error string are functions that
have a single input/output argument \verb'C', as a \verb'GrB_Matrix',
\verb'GrB_Vector', \verb'GrB_Scalar', or \verb'GrB_Descriptor'. Methods that
create these objects (such as \verb'GrB_Matrix_new') return a \verb'NULL'
object on failure, so these methods cannot also return an error string in
\verb'C'.

Any subsequent GraphBLAS method that modifies the object \verb'C' clears the
error string.

Note that \verb'GrB_NO_VALUE' is an not error, but an informational status.
\verb'GrB_*_extractElment(&x,A,i,j)', which does \verb'x=A(i,j)', returns this
value to indicate that \verb'A(i,j)' is not present in the matrix.  That
method does not have an input/output object so it cannot return an error
string.

% The \verb'GrB_error' function is a polymorphic function for the
% following variants:

% \begin{mdframed}[userdefinedwidth=6in]
% {\footnotesize
% \begin{verbatim}
% GrB_Info GrB_Type_error         (const char **err, const GrB_Type type) ;
% GrB_Info GrB_UnaryOp_error      (const char **err, const GrB_UnaryOp op) ;
% GrB_Info GrB_BinaryOp_error     (const char **err, const GrB_BinaryOp op) ;
% GrB_Info GrB_IndexUnaryOp_error (const char **err, const GrB_IndexUnaryOp op) ;
% GrB_Info GrB_Monoid_error       (const char **err, const GrB_Monoid monoid) ;
% GrB_Info GrB_Semiring_error     (const char **err, const GrB_Semiring semiring) ;
% GrB_Info GrB_Scalar_error       (const char **err, const GrB_Scalar s) ;
% GrB_Info GrB_Vector_error       (const char **err, const GrB_Vector v) ;
% GrB_Info GrB_Matrix_error       (const char **err, const GrB_Vector A) ;
% GrB_Info GrB_Descriptor_error   (const char **err, const GrB_Descriptor d) ;
% \end{verbatim}
% }\end{mdframed}

% Currently, only \verb'GrB_Matrix_error', \verb'GrB_Vector_error',
% \verb'GrB_Scalar_error', and \verb'GrB_Descriptor_error' are able to return
% non-empty error strings.  The latter can return an error string only from
% \verb'GrB_Descriptor_set' and \verb'GxB_set(d,...)'.

% The only GraphBLAS methods (Section~\ref{objects}) that return an error string
% are \verb'*setElement', \verb'*removeElement',
% \verb'GxB_Matrix_Option_set(A,...)', \newline
% \verb'GxB_Vector_Option_set(v,...)', \verb'GrB_Descriptor_set', and
% \verb'GxB_Desc_set(d,...)'.  All GraphBLAS operations discussed in
% Section~\ref{operations} can return an error string in their input/output
% object, except for \verb'GrB_reduce' when reducing to a scalar.

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

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

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

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

GraphBLAS defines ten different objects to represent matrices, vectors,
scalars, data types, operators (binary, unary, and index-unary), 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'GrB_IndexUnaryOp'  & an index-unary 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_Scalar'    & a scalar 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.

\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 13 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 (in the \verb'#include' files \verb'stdbool.h', \verb'stdint.h', and
\verb'complex.h') as listed in the following table.

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

The ANSI C11 definitions of \verb'float complex' and \verb'double complex'
are not always available.  The \verb'GraphBLAS.h' header defines them as
\verb'GxB_FC32_t' and \verb'GxB_FC64_t', respectively.

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 of fixed
size.  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}{lll}
\hline
GraphBLAS function       & purpose                          & Section \\
\hline
\verb'GrB_Type_new'      & create a user-defined type       & \ref{type_new} \\
\verb'GxB_Type_new'      & create a user-defined type,
                            with name and definition        & \ref{type_new_named} \\
\verb'GrB_Type_wait'     & wait for a user-defined type     & \ref{type_wait} \\
\verb'GxB_Type_size'     & return the size of a type        & \ref{type_size} \\
\verb'GxB_Type_name'     & return the name of a type        & \ref{type_name} \\
\verb'GxB_Type_from_name'& return the type from its name    & \ref{type_from_name} \\
\verb'GrB_Type_free'     & free a user-defined type         & \ref{type_free} \\
\hline
\end{tabular}
}

%-------------------------------------------------------------------------------
\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.  Refer to Section~\ref{user} for more details on these
example user-defined types.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Type\_new:} create a user-defined type (with name and definition)}
%-------------------------------------------------------------------------------
\label{type_new_named}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Type_new           // create a new named GraphBLAS type
(
    GrB_Type *type,             // handle of user type to create
    size_t sizeof_ctype,        // size = sizeof (ctype) of the C type
    const char *type_name,      // name of the type (max 128 characters)
    const char *type_defn       // typedef for the type (no max length)
) ;
\end{verbatim}
}\end{mdframed}

\verb'GxB_Type_new' creates a type with a name and definition that are known to
GraphBLAS, as strings.  The \verb'type_name' is any valid string (max length of 128
characters, including the required null-terminating character) that may
appear as the name of a C type created by a C \verb'typedef' statement.  It must
not contain any white-space characters.  For example, to create a type of size
16*4+1 = 65 bytes, with a 4-by-4 dense float array and a 32-bit integer:

    {\footnotesize
    \begin{verbatim}
    typedef struct { float x [4][4] ; int color ; } myquaternion ;
    GrB_Type MyQtype ;
    GxB_Type_new (&MyQtype, sizeof (myquaternion), "myquaternion",
        "typedef struct { float x [4][4] ; int color ; } myquaternion ;") ; \end{verbatim}}

The \verb'type_name' and \verb'type_defn' are both null-terminated strings.
Currently, \verb'type_defn' is unused, but it will be required for best
performance when a JIT is implemented in SuiteSparse:GraphBLAS (both on the CPU
and GPU).  User defined types created by \verb'GrB_Type_new' will not work with
a JIT.

At most \verb'GxB_MAX_NAME_LEN' characters are accessed in \verb'type_name';
characters beyond that limit are silently ignored.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Type\_wait:} wait for a type}
%-------------------------------------------------------------------------------
\label{type_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a user-defined type
(
    GrB_Type type,              // type to wait for
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined type, a GraphBLAS library may choose to exploit
non-blocking mode to delay its creation.  Currently, SuiteSparse:GraphBLAS
currently does nothing except to ensure that \verb'type' is valid.

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Type\_name:} return the name of a type}
%-------------------------------------------------------------------------------
\label{type_name}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Type_name      // return the name of a GraphBLAS type
(
    char *type_name,        // name of the type (char array of size at least
                            // GxB_MAX_NAME_LEN, owned by the user application).
    const GrB_Type type
) ;
\end{verbatim}
}\end{mdframed}

Returns the name of a type, as a string.  For built-in types, the name is
the same as the C type.  For example, \verb'GxB_Type_name(type_name,GrB_FP32)'
returns the name as \verb'"float"'.  The following table lists the
names of the 13 built-in types.

\vspace{0.2in}
{\small
\begin{tabular}{ll}
\hline
Type name & GraphBLAS type \\
\hline
    \verb'"bool"'           & \verb'GrB_BOOL' \\
    \verb'"int8_t"'         & \verb'GrB_INT8' \\
    \verb'"int16_t"'        & \verb'GrB_INT16' \\
    \verb'"int32_t"'        & \verb'GrB_INT32' \\
    \verb'"int64_t"'        & \verb'GrB_INT64' \\
    \verb'"uint8_t"'        & \verb'GrB_UINT8' \\
    \verb'"uint16_t"'       & \verb'GrB_UINT16' \\
    \verb'"uint32_t"'       & \verb'GrB_UINT32' \\
    \verb'"uint64_t"'       & \verb'GrB_UINT64' \\
    \verb'"float"'          & \verb'GrB_FP32' \\
    \verb'"double"'         & \verb'GrB_FP64' \\
    \verb'"float complex"'  & \verb'GxB_FC32' \\
    \verb'"double complex"' & \verb'GxB_FC64' \\
\hline
\end{tabular}}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Type\_from\_name:} return the type from its name}
%-------------------------------------------------------------------------------
\label{type_from_name}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Type_from_name     // return the built-in GrB_Type from a name
(
    GrB_Type *type,             // built-in type, or NULL if user-defined
    const char *type_name       // array of size at least GxB_MAX_NAME_LEN
) ;
\end{verbatim}
}\end{mdframed}

Returns the built-in type from the corresponding name of the type.  For
example, \verb'GxB_Type_from_name (&type, "bool")' returns \verb'GrB_BOOL'.  If
the name is from a user-defined type, the \verb'type' is returned as
\verb'NULL'.  This is not an error condition.  The user application must itself
do this translation since GraphBLAS does not keep a registry of all
user-defined types.

With this function, a user application can manage the translation for
both built-in types and its own user-defined types, as in the following
example.

{\footnotesize
\begin{verbatim}
    typedef struct { double x ; char stuff [16] ; } myfirsttype ;
    typedef struct { float z [4][4] ; int color ; } myquaternion ;
    GrB_Type MyType1, MyQType ;
    GxB_Type_new (&MyType1, sizeof (myfirsttype), "myfirsttype",
        "typedef struct { double x ; char stuff [16] ; } myfirsttype ;") ;
    GxB_Type_new (&MyQType, sizeof (myquaternion), "myquaternion",
        "typedef struct { float z [4][4] ; int color ; } myquaternion ;") ;

    GrB_Matrix A ;
    // ... create a matrix A of some built-in or user-defined type

    // later on, to query the type of A:
    size_t typesize ;
    GxB_Type_size (&typesize, type) ;       // works for any type
    GrB_Type atype ;
    char atype_name [GxB_MAX_NAME_LEN] ;
    GxB_Matrix_type_name (atype_name, A) ;
    GxB_Type_from_name (&atype, atype_name) ;
    if (atype == NULL)
    {
        // This is not yet an error.  It means that A has a user-defined type.
        if ((strcmp (atype_name, "myfirsttype")) == 0) atype = MyType1 ;
        else if ((strcmp (atype_name, "myquaternion")) == 0) atype = MyQType ;
        else { ... this is now an error ... the type of A is unknown.  }
    }\end{verbatim} }

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

The function signature of \verb'GrB_Type_free' uses the generic name
\verb'GrB_free', which can free any GraphBLAS object. See Section~\ref{free}
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.

In the notation in the tables
below, $T$ is any of the 13 built-in types and is a place-holder for
\verb'BOOL', \verb'INT8', \verb'UINT8', ... 
\verb'FP32', \verb'FP64', \verb'FC32', or \verb'FC64'.
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 notation $R$ refers to any real type (all but \verb'FC32' and \verb'FC64'),
$I$ refers to any integer type (\verb'INT*' and \verb'UINT*'),
$F$ refers to any real or complex floating point type
(\verb'FP32', \verb'FP64', \verb'FC32', or \verb'FC64'),
$Z$ refers to any complex floating point type
(\verb'FC32' or \verb'FC64'),
and $N$ refers to \verb'INT32' or \verb'INT64'.

The logical negation operator \verb'GrB_LNOT' only works on Boolean types.  The
\verb'GxB_LNOT_'$R$ functions operate on inputs of type $R$, implicitly
typecasting their input to Boolean and returning result of type $R$, with a
value 1 for true and 0 for false.  The operators \verb'GxB_LNOT_BOOL' and
\verb'GrB_LNOT' are identical.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Unary operators for all types} \\
\hline
GraphBLAS name          & types (domains)   & $z=f(x)$      & description \\
\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'GrB_MINV_'$T$     & $T \rightarrow T$ & $z = 1/x$     & multiplicative inverse \\
\hline
\end{tabular}

\vspace{0.2in}
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Unary operators for real and integer types} \\
\hline
GraphBLAS name          & types (domains)   & $z=f(x)$      & description \\
\hline
\verb'GrB_ABS_'$T$      & $R \rightarrow R$ & $z = |x|$     & absolute value \\
\verb'GrB_LNOT'         & \verb'bool'
                          $\rightarrow$
                          \verb'bool'       & $z = \lnot x$ & logical negation \\
\verb'GxB_LNOT_'$R$     & $R \rightarrow R$ & $z = \lnot (x \ne 0)$ & logical negation \\
\verb'GrB_BNOT_'$I$     & $I \rightarrow I$ & $z = \lnot x$ & bitwise negation \\
\hline
\end{tabular}

\vspace{0.2in}
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Positional unary operators for any type (including user-defined)} \\
\hline
GraphBLAS name            & types (domains)   & $z=f(a_{ij})$      & description \\
\hline
\verb'GxB_POSITIONI_'$N$  & $ \rightarrow N$  & $z = i$       & row index (0-based) \\
\verb'GxB_POSITIONI1_'$N$ & $ \rightarrow N$  & $z = i+1$     & row index (1-based) \\
\verb'GxB_POSITIONJ_'$N$  & $ \rightarrow N$  & $z = j$       & column index (0-based) \\
\verb'GxB_POSITIONJ1_'$N$ & $ \rightarrow N$  & $z = j+1$     & column index (1-based) \\
\hline
\end{tabular}
\vspace{0.2in}

\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Unary operators for floating-point types (real and complex)} \\
\hline
GraphBLAS name          & types (domains)   & $z=f(x)$      & description \\
\hline
\verb'GxB_SQRT_'$F$     & $F \rightarrow F$ & $z = \sqrt(x)$       & square root \\
\verb'GxB_LOG_'$F$      & $F \rightarrow F$ & $z = \log_e(x)$      & natural logarithm \\
\verb'GxB_EXP_'$F$      & $F \rightarrow F$ & $z = e^x$            & natural exponent \\
\hline
\verb'GxB_LOG10_'$F$    & $F \rightarrow F$ & $z = \log_{10}(x)$   & base-10 logarithm \\
\verb'GxB_LOG2_'$F$     & $F \rightarrow F$ & $z = \log_2(x)$      & base-2 logarithm \\
\verb'GxB_EXP2_'$F$     & $F \rightarrow F$ & $z = 2^x$            & base-2 exponent \\
\hline
\verb'GxB_EXPM1_'$F$    & $F \rightarrow F$ & $z = e^x - 1$        & natural exponent - 1 \\
\verb'GxB_LOG1P_'$F$    & $F \rightarrow F$ & $z = \log(x+1)$      & natural log of $x+1$ \\
\hline
\verb'GxB_SIN_'$F$      & $F \rightarrow F$ & $z = \sin(x)$        & sine \\
\verb'GxB_COS_'$F$      & $F \rightarrow F$ & $z = \cos(x)$        & cosine \\
\verb'GxB_TAN_'$F$      & $F \rightarrow F$ & $z = \tan(x)$        & tangent \\
\hline
\verb'GxB_ASIN_'$F$     & $F \rightarrow F$ & $z = \sin^{-1}(x)$        & inverse sine \\
\verb'GxB_ACOS_'$F$     & $F \rightarrow F$ & $z = \cos^{-1}(x)$        & inverse cosine \\
\verb'GxB_ATAN_'$F$     & $F \rightarrow F$ & $z = \tan^{-1}(x)$        & inverse tangent \\
\hline
\verb'GxB_SINH_'$F$     & $F \rightarrow F$ & $z = \sinh(x)$        & hyperbolic sine \\
\verb'GxB_COSH_'$F$     & $F \rightarrow F$ & $z = \cosh(x)$        & hyperbolic cosine \\
\verb'GxB_TANH_'$F$     & $F \rightarrow F$ & $z = \tanh(x)$        & hyperbolic tangent \\
\hline
\verb'GxB_ASINH_'$F$    & $F \rightarrow F$ & $z = \sinh^{-1}(x)$        & inverse hyperbolic sine \\
\verb'GxB_ACOSH_'$F$    & $F \rightarrow F$ & $z = \cosh^{-1}(x)$        & inverse hyperbolic cosine \\
\verb'GxB_ATANH_'$F$    & $F \rightarrow F$ & $z = \tanh^{-1}(x)$        & inverse hyperbolic tangent \\
\hline
\verb'GxB_SIGNUM_'$F$   & $F \rightarrow F$ & $z = \sgn(x)$                 & sign, or signum function \\
\verb'GxB_CEIL_'$F$     & $F \rightarrow F$ & $z = \lceil x \rceil $       & ceiling function \\
\verb'GxB_FLOOR_'$F$    & $F \rightarrow F$ & $z = \lfloor x \rfloor $     & floor function \\
\verb'GxB_ROUND_'$F$    & $F \rightarrow F$ & $z = \mbox{round}(x)$        & round to nearest \\
\verb'GxB_TRUNC_'$F$    & $F \rightarrow F$ & $z = \mbox{trunc}(x)$        & round towards zero \\
\hline
\verb'GxB_ISINF_'$F$    & $F \rightarrow $ \verb'bool' & $z = \mbox{isinf}(x)$ & true if $\pm \infty$ \\
\verb'GxB_ISNAN_'$F$    & $F \rightarrow $ \verb'bool' & $z = \mbox{isnan}(x)$ & true if \verb'NaN' \\
\verb'GxB_ISFINITE_'$F$ & $F \rightarrow $ \verb'bool' & $z = \mbox{isfinite}(x)$ & true if finite \\
\hline
\end{tabular}
\vspace{0.2in}

\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Unary operators for floating-point types (real only)} \\
\hline
GraphBLAS name          & types (domains)   & $z=f(x)$      & description \\
\hline
\verb'GxB_LGAMMA_'$R$   & $R \rightarrow R$ & $z = \log(|\Gamma (x)|)$  & log of gamma function \\
\verb'GxB_TGAMMA_'$R$   & $R \rightarrow R$ & $z = \Gamma(x)$        & gamma function \\
\verb'GxB_ERF_'$R$      & $R \rightarrow R$ & $z = \erf(x)$          & error function \\
\verb'GxB_ERFC_'$R$     & $R \rightarrow R$ & $z = \erfc(x)$         & complimentary error function \\
\verb'GxB_CBRT_'$R$     & $R \rightarrow R$ & $z = x^{1/3}$          & cube root \\
\hline
\verb'GxB_FREXPX_'$R$   & $R \rightarrow R$ & $z = \mbox{frexpx}(x)$  & normalized fraction \\
\verb'GxB_FREXPE_'$R$   & $R \rightarrow R$ & $z = \mbox{frexpe}(x)$  & normalized exponent \\
\hline
\end{tabular}
\vspace{0.2in}

\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Unary operators for complex types} \\
\hline
GraphBLAS name          & types (domains)   & $z=f(x)$      & description \\
\hline
\verb'GxB_CONJ_'$Z$    & $Z \rightarrow Z$ & $z = \overline{x}$     & complex conjugate \\
\verb'GxB_ABS_'$Z$     & $Z \rightarrow F$ & $z = |x|$              & absolute value \\
\verb'GxB_CREAL_'$Z$   & $Z \rightarrow F$ & $z = \mbox{real}(x)$   & real part \\
\verb'GxB_CIMAG_'$Z$   & $Z \rightarrow F$ & $z = \mbox{imag}(x)$   & imaginary part \\
\verb'GxB_CARG_'$Z$    & $Z \rightarrow F$ & $z = \mbox{carg}(x)$   & angle \\
\hline
\end{tabular}
}
\vspace{0.2in}

A positional unary operator return the row or column index of an entry.  For a
matrix $z=f(a_{ij})$ returns $z = i$ or $z = j$, or +1 for 1-based indices.
The latter is useful in the MATLAB/Octave interface, where row and column indices are
1-based.  When applied to a vector, $j$ is always zero, and $i$ is the index in
the vector.  Positional unary operators come in two types: \verb'INT32' and
\verb'INT64', which is the type of the output, $z$.  The functions are agnostic
to the type of their inputs; they only depend on the position of the entries,
not their values.
User-defined positional operators cannot be defined by \verb'GrB_UnaryOp_new'.

\verb'GxB_FREXPX' and \verb'GxB_FREXPE' return the mantissa and exponent,
respectively, from the ANSI C11 \verb'frexp' function.  The exponent is
returned as a floating-point value, not an integer.

The operators \verb'GxB_EXPM1_FC*' and \verb'GxB_LOG1P_FC*' for complex
types are currently not accurate.  They will be revised in a future version.

The functions \verb'casin', \verb'casinf', \verb'casinh', and \verb'casinhf'
provided by Microsoft Visual Studio for computing $\sin^{-1}(x)$ and
$\sinh^{-1}(x)$ when $x$ is complex do not compute the correct result.  Thus,
the unary operators \verb'GxB_ASIN_FC32', \verb'GxB_ASIN_FC64'
\verb'GxB_ASINH_FC32', and \verb'GxB_ASINH_FC64' do not work properly if the MS
Visual Studio compiler is used.  These functions work properly if the gcc, icc,
or clang compilers are used on Linux or MacOS.

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{alert}
{\bf SPEC:} The definition of integer division by zero is an extension to the
specification.
\end{alert}

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

\vspace{0.1in}
{\footnotesize
\noindent
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_UnaryOp_new'   & create a user-defined unary operator         & \ref{unaryop_new} \\
\verb'GxB_UnaryOp_new'   & create a named user-defined unary operator   & \ref{unaryop_new_named} \\
\verb'GrB_UnaryOp_wait'  & wait for a user-defined unary operator       & \ref{unaryop_wait} \\
\verb'GxB_UnaryOp_ztype_name' & return the name of the type of the output $z$ for $z=f(x)$   & \ref{unaryop_ztype_name} \\
\verb'GxB_UnaryOp_xtype_name' & return the name of the type of the input $x$ for $z=f(x)$    & \ref{unaryop_xtype_name} \\
\verb'GrB_UnaryOp_free'  & free a user-defined unary operator   & \ref{unaryop_free} \\
\hline
\end{tabular}
}
\vspace{0.1in}

\newpage
%-------------------------------------------------------------------------------
\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
    GrB_Type ztype,                 // type of output z
    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.

{\bf NOTE:}
The pointers passed to a user-defined operator may not be unique.  That is, the
user function may be called with multiple pointers that point to the same
space, such as when \verb'z=f(z,y)' is to be computed by a binary operator, or
\verb'z=f(z)' for a unary operator.  Any parameters passed to the user-callable
function may be aliased to each other.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_UnaryOp\_new:} create a named user-defined unary operator}
%-------------------------------------------------------------------------------
\label{unaryop_new_named}

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

Creates a named \verb'GrB_UnaryOp'.  Only the first 127 characters of
\verb'unop_name' are used.  The \verb'unop_defn' is a string containing the
entire function itself.  For example:

    {\footnotesize
    \begin{verbatim}
    void square (double *z, double *x) { (*z) = (*x) * (*x) ; } ;
    ...
    GrB_Type Square ;
    GxB_UnaryOp_new (&Square, square, GrB_FP64, GrB_FP64, "square",
        "void square (double *z, double *x) { (*z) = (*x) * (*x) ; } ;") ;
    \end{verbatim}}

Currently, only the \verb'unop_name' is used, but future versions will
rely on the \verb'unop_defn' when employing a JIT for better performance.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_UnaryOp\_wait:} wait for a unary operator}
%-------------------------------------------------------------------------------
\label{unaryop_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a user-defined unary operator
(
    GrB_UnaryOp unaryop,        // unary operator to wait for
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined unary operator, a GraphBLAS library may choose to
exploit non-blocking mode to delay its creation.  Currently,
SuiteSparse:GraphBLAS currently does nothing except to ensure that the
\verb'unaryop' is valid.

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_UnaryOp_ztype_name     // return the type_name of z
(
    char *type_name,                // user array of size GxB_MAX_NAME_LEN
    const GrB_UnaryOp unaryop       // unary operator
) ;
\end{verbatim}
}\end{mdframed}

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_UnaryOp_xtype_name     // return the type_name of x
(
    char *type_name,                // user array of size GxB_MAX_NAME_LEN
    const GrB_UnaryOp unaryop       // unary operator
) ;
\end{verbatim}
}\end{mdframed}

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

% \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.  The built-in binary operators are
listed in the tables below.  The notation $T$ refers to any of the 13
built-in types, but two of those types are SuiteSparse extensions
(\verb'GxB_FC32' and \verb'GxB_FC64').  For those types, the operator name
always starts with \verb'GxB', not \verb'GrB').
The notation $R$ refers to any real type (all but \verb'FC32' and \verb'FC64').

The six \verb'GxB_IS*' comparators and the \verb'GxB_*' logical
operators all return a result one for true and zero for false, in the same
domain $T$ or $R$ as their inputs.  These six comparators are useful
as ``multiply'' operators for creating semirings with non-Boolean monoids.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Binary operators for all 13 types} \\
\hline
GraphBLAS name        & types (domains)            & $z=f(x,y)$      & description \\
\hline
% 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'GxB_ANY_'$T$    & $T \times T \rightarrow T$ & $z = x$ or $y$  & pick $x$ or $y$ arbitrarily \\
\verb'GrB_ONEB_'$T$   & $T \times T \rightarrow T$ & $z = 1$         & one \\
\verb'GxB_PAIR_'$T$   & $T \times T \rightarrow T$ & $z = 1$         & one (historical) \\
\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'GxB_RMINUS_'$T$ & $T \times T \rightarrow T$ & $z = y-x$       & reverse 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 \\
\verb'GxB_RDIV_'$T$   & $T \times T \rightarrow T$ & $z = y/x$       & reverse division \\
\verb'GxB_POW_'$T$    & $T \times T \rightarrow T$ & $z = x^y$       & power \\
\hline
% TxT->T comparators
\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 \\
\hline
\end{tabular}
}
\vspace{0.2in}

The \verb'GxB_POW_*' operators for real types do not return a complex result,
and thus $z = f(x,y) = x^y$ is undefined if $x$ is negative and $y$ is not an
integer.  To compute a complex result, use \verb'GxB_POW_FC32' or
\verb'GxB_POW_FC64'.

Operators that require the domain to be ordered (\verb'MIN', \verb'MAX',
less-than, greater-than, and so on) are not defined for
complex types.  These are listed in the following table:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Binary operators for all non-complex types} \\
\hline
GraphBLAS name        & types (domains)            & $z=f(x,y)$      & description \\
\hline
% numeric RxR->R
\verb'GrB_MIN_'$R$    & $R \times R \rightarrow R$ & $z = \min(x,y)$ & minimum \\
\verb'GrB_MAX_'$R$    & $R \times R \rightarrow R$ & $z = \max(x,y)$ & maximum \\
\hline
% RxR->R comparators
\verb'GxB_ISGT_'$R$   & $R \times R \rightarrow R$ & $z = (x >   y)$ & greater than \\
\verb'GxB_ISLT_'$R$   & $R \times R \rightarrow R$ & $z = (x <   y)$ & less than  \\
\verb'GxB_ISGE_'$R$   & $R \times R \rightarrow R$ & $z = (x \ge y)$ & greater than or equal \\
\verb'GxB_ISLE_'$R$   & $R \times R \rightarrow R$ & $z = (x \le y)$ & less than or equal  \\
\hline
% RxR->R logical
\verb'GxB_LOR_'$R$    & $R \times R \rightarrow R$ & $z = (x \ne 0) \vee    (y \ne 0) $ & logical OR \\
\verb'GxB_LAND_'$R$   & $R \times R \rightarrow R$ & $z = (x \ne 0) \wedge  (y \ne 0) $ & logical AND \\
\verb'GxB_LXOR_'$R$   & $R \times R \rightarrow R$ & $z = (x \ne 0) \veebar (y \ne 0) $ & logical XOR \\
\hline
\end{tabular}
}
\vspace{0.2in}

Another set of six kinds of built-in comparators have the form $T
\times T \rightarrow $\verb'bool'.  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 comparators are useful as ``multiply''
operators for creating semirings with Boolean monoids.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Binary comparators for all 13 types} \\
\hline
GraphBLAS name        & types (domains)            & $z=f(x,y)$      & description \\
\hline
% 6 TxT -> bool comparators
\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 \\
\hline
\multicolumn{4}{ }{\mbox{ }} \\
\hline
\multicolumn{4}{|c|}{Binary comparators for non-complex types} \\
\hline
GraphBLAS name        & types (domains)            & $z=f(x,y)$      & description \\
\hline
\verb'GrB_GT_'$R$     & $R \times R \rightarrow $\verb'bool' & $z = (x >   y)$ & greater than \\
\verb'GrB_LT_'$R$     & $R \times R \rightarrow $\verb'bool' & $z = (x <   y)$ & less than  \\
\verb'GrB_GE_'$R$     & $R \times R \rightarrow $\verb'bool' & $z = (x \ge y)$ & greater than or equal \\
\verb'GrB_LE_'$R$     & $R \times R \rightarrow $\verb'bool' & $z = (x \le y)$ & less than or equal  \\
\hline
\end{tabular}
}
\vspace{0.2in}

GraphBLAS has four built-in binary operators that operate purely in
the Boolean domain.  The first three are identical to the \verb'GxB_L*_BOOL'
operators described above, just with a shorter name.  The \verb'GrB_LXNOR'
operator is the same as \verb'GrB_EQ_BOOL'.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Binary operators for the boolean type only} \\
\hline
GraphBLAS name        & types (domains)            & $z=f(x,y)$      & description \\
\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 \\
\verb'GrB_LXNOR'      & \verb'bool'
                        $\times$ \verb'bool'
                        $\rightarrow$ \verb'bool'  & $z = \lnot (x \veebar y) $ & logical XNOR \\
\hline
\end{tabular}
}
\vspace{0.2in}

The following operators are defined for real floating-point types only (\verb'GrB_FP32' and  \verb'GrB_FP64').
They are identical to the ANSI C11 functions of the same name.  The last one in the table constructs
the corresponding complex type.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Binary operators for the real floating-point types only} \\
\hline
GraphBLAS name        & types (domains)            & $z=f(x,y)$      & description \\
\hline
\verb'GxB_ATAN2_'$F$     & $F \times F \rightarrow F$ & $z = \tan^{-1}(y/x)$ & 4-quadrant arc tangent  \\
\verb'GxB_HYPOT_'$F$     & $F \times F \rightarrow F$ & $z = \sqrt{x^2+y^2}$ & hypotenuse \\
\verb'GxB_FMOD_'$F$      & $F \times F \rightarrow F$ &                      & ANSI C11 \verb'fmod' \\
\verb'GxB_REMAINDER_'$F$ & $F \times F \rightarrow F$ &                      & ANSI C11 \verb'remainder' \\
\verb'GxB_LDEXP_'$F$     & $F \times F \rightarrow F$ &                      & ANSI C11 \verb'ldexp' \\
\verb'GxB_COPYSIGN_'$F$  & $F \times F \rightarrow F$ &                      & ANSI C11 \verb'copysign' \\
\hline
\verb'GxB_CMPLX_'$F$     & $F \times F \rightarrow Z$ & $z = x + y \times i$ & complex from real \& imag \\
\hline
\end{tabular}
}
\vspace{0.2in}

Eight bitwise operators are predefined for signed and unsigned integers.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Binary operators for signed and unsigned integers} \\
\hline
GraphBLAS name        & types (domains)            & $z=f(x,y)$      & description \\
\hline
\verb'GrB_BOR_'$I$    & $I \times I \rightarrow I$ & \verb'z=x|y'    & bitwise logical OR \\
\verb'GrB_BAND_'$I$   & $I \times I \rightarrow I$ & \verb'z=x&y'    & bitwise logical AND \\
\verb'GrB_BXOR_'$I$   & $I \times I \rightarrow I$ & \verb'z=x^y'    & bitwise logical XOR \\
\verb'GrB_BXNOR_'$I$  & $I \times I \rightarrow I$ & \verb'z=~(x^y)' & bitwise logical XNOR \\
\hline
\verb'GxB_BGET_'$I$    & $I \times I \rightarrow I$  & & get bit y of x \\
\verb'GxB_BSET_'$I$    & $I \times I \rightarrow I$  & & set bit y of x \\
\verb'GxB_BCLR_'$I$    & $I \times I \rightarrow I$  & & clear bit y of x \\
\verb'GxB_BSHIFT_'$I$  & $I \times $\verb'int8'$  \rightarrow I$ & & bit shift \\
\hline
\end{tabular}
}
\vspace{0.2in}

There are two sets of built-in comparators 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 compute the same thing and produce a
result with same type $T$ as their input operands, returning one for true or
zero for false.  The \verb'IS*' comparators are useful when combining
comparators with other non-Boolean operators.  For example, a \verb'PLUS-ISEQ'
semiring counts how many terms 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 real 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.

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.

Eight positional operators are predefined.  They differ when used in a semiring
and when used in \verb'GrB_eWise*' and \verb'GrB_apply'.  Positional operators
cannot be used in \verb'GrB_build', nor can they be used as the \verb'accum'
operator for any operation.

The positional binary operators do not depend on the type or numerical value of
their inputs, just their position in a matrix or vector.  For a vector, $j$ is
always 0, and $i$ is the index into the vector.  There are two types $N$
available: \verb'INT32' and \verb'INT64', which is the type of the output $z$.
User-defined positional operators cannot be defined by \verb'GrB_BinaryOp_new'.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Positional binary operators for any type (including user-defined)} \\
\multicolumn{4}{|c|}{when used as a multiplicative operator in a semiring} \\
\hline
GraphBLAS name            & types (domains)   & $z=f(a_{ik},b_{kj})$      & description \\
\hline
\verb'GxB_FIRSTI_'$N$    & $ \rightarrow N$  & $z = i$       & row index of $a_{ik}$ (0-based) \\
\verb'GxB_FIRSTI1_'$N$   & $ \rightarrow N$  & $z = i+1$     & row index of $a_{ik}$ (1-based) \\
\verb'GxB_FIRSTJ_'$N$    & $ \rightarrow N$  & $z = k$       & column index of $a_{ik}$ (0-based) \\
\verb'GxB_FIRSTJ1_'$N$   & $ \rightarrow N$  & $z = k+1$     & column index of $a_{ik}$ (1-based) \\
\verb'GxB_SECONDI_'$N$   & $ \rightarrow N$  & $z = k$       & row index of $b_{kj}$ (0-based) \\
\verb'GxB_SECONDI1_'$N$  & $ \rightarrow N$  & $z = k+1$     & row index of $b_{kj}$ (1-based) \\
\verb'GxB_SECONDJ_'$N$   & $ \rightarrow N$  & $z = j$       & column index of $b_{kj}$ (0-based) \\
\verb'GxB_SECONDJ1_'$N$  & $ \rightarrow N$  & $z = j+1$     & column index of $b_{kj}$ (1-based) \\
\hline
\end{tabular}
}

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Positional binary operators for any type (including user-defined)} \\
\multicolumn{4}{|c|}{when used in all other methods} \\
\hline
GraphBLAS name            & types (domains)   & $z=f(a_{ij},b_{ij})$      & description \\
\hline
\verb'GxB_FIRSTI_'$N$    & $ \rightarrow N$  & $z = i$       & row index of $a_{ij}$ (0-based) \\
\verb'GxB_FIRSTI1_'$N$   & $ \rightarrow N$  & $z = i+1$     & row index of $a_{ij}$ (1-based) \\
\verb'GxB_FIRSTJ_'$N$    & $ \rightarrow N$  & $z = j$       & column index of $a_{ij}$ (0-based) \\
\verb'GxB_FIRSTJ1_'$N$   & $ \rightarrow N$  & $z = j+1$     & column index of $a_{ij}$ (1-based) \\
\verb'GxB_SECONDI_'$N$   & $ \rightarrow N$  & $z = i$       & row index of $b_{ij}$ (0-based) \\
\verb'GxB_SECONDI1_'$N$  & $ \rightarrow N$  & $z = i+1$     & row index of $b_{ij}$ (1-based) \\
\verb'GxB_SECONDJ_'$N$   & $ \rightarrow N$  & $z = j$       & column index of $b_{ij}$ (0-based) \\
\verb'GxB_SECONDJ1_'$N$  & $ \rightarrow N$  & $z = j+1$     & column index of $b_{ij}$ (1-based) \\
\hline
\end{tabular}
}
\vspace{0.2in}

Finally, one special binary operator can only be used as input to
\verb'GrB_Matrix_build' or \verb'GrB_Vector_build': the \verb'GxB_IGNORE_DUP'
operator.  If \verb'dup' is \verb'NULL', any duplicates in the \verb'GrB*build'
methods result in an error.  If \verb'dup' is the special binary operator
\verb'GxB_IGNORE_DUP', then any duplicates are ignored.  If duplicates appear,
the last one in the list of tuples is taken and the prior ones ignored.  This
is not an error.

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

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_BinaryOp_new'   & create a user-defined binary operator   & \ref{binaryop_new} \\
\verb'GxB_BinaryOp_new'   & create a named user-defined binary operator   & \ref{binaryop_new_named} \\
\verb'GrB_BinaryOp_wait'  & wait for a user-defined binary operator & \ref{binaryop_wait} \\
\verb'GxB_BinaryOp_ztype_name' & return the type of the output $z$ for $z=f(x,y)$    & \ref{binaryop_ztype_name} \\
\verb'GxB_BinaryOp_xtype_name' & return the type of the input $x$ for $z=f(x,y)$     & \ref{binaryop_xtype_name} \\
\verb'GxB_BinaryOp_ytype_name' & return the type of the input $y$ for $z=f(x,y)$     & \ref{binaryop_ytype_name} \\
\verb'GrB_BinaryOp_free'  & free a user-defined binary operator     & \ref{binaryop_free} \\
\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
    GrB_Type ztype,                 // type of output z
    GrB_Type xtype,                 // type of input x
    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.

{\bf NOTE:} SuiteSparse:GraphBLAS may call the function with the pointers
\verb'z' and \verb'x' equal to one another, in which case \verb'z=f(z,y)'
should be computed.  Future versions may use additional pointer aliasing.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_BinaryOp\_new:} create a named user-defined binary operator}
%-------------------------------------------------------------------------------
\label{binaryop_new_named}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_new
(
    GrB_BinaryOp *op,               // handle for the new binary operator
    GxB_binary_function function,   // pointer to the binary function
    GrB_Type ztype,                 // type of output z
    GrB_Type xtype,                 // type of input x
    GrB_Type ytype,                 // type of input y
    const char *binop_name,         // name of the user function
    const char *binop_defn          // definition of the user function
) ;
\end{verbatim} }\end{mdframed}

Creates a named \verb'GrB_BinaryOp'.  Only the first 127 characters of
\verb'binop_name' are used.  The \verb'binop_defn' is a string containing the
entire function itself.  For example:

{\footnotesize
\begin{verbatim}
void absdiff (double *z, double *x, double *y) { (*z) = fabs ((*x) - (*y)) ; } ;
...
GrB_Type AbsDiff ;
GxB_BinaryOp_new (&AbsDiff, absdiff, GrB_FP64, GrB_FP64, GrB_FP64, "absdiff",
  "void absdiff (double *z, double *x, double *y) { (*z) = fabs ((*x) - (*y)) ; }") ; \end{verbatim}}

Currently, only the \verb'binop_name' is used, but future versions will
rely on the \verb'binop_defn' when employing a JIT for better performance.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_BinaryOp\_wait:} wait for a binary operator}
%-------------------------------------------------------------------------------
\label{binaryop_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a user-defined binary operator
(
    GrB_BinaryOp binaryop,      // binary operator to wait for
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined binary operator, a GraphBLAS library may choose
to exploit non-blocking mode to delay its creation.  Currently,
SuiteSparse:GraphBLAS currently does nothing for except to ensure that the
\verb'binaryop' is valid.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_BinaryOp\_ztype\_name:} return the name of the type of $z$}
%-------------------------------------------------------------------------------
\label{binaryop_ztype_name}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_ztype_name    // return the type_name of z
(
    char *type_name,                // user array of size GxB_MAX_NAME_LEN
    const GrB_BinaryOp binaryop     // binary operator to query
) ;
\end{verbatim}
} \end{mdframed}

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_xtype_name    // return the type_name of x
(
    char *type_name,                // user array of size GxB_MAX_NAME_LEN
    const GrB_BinaryOp binaryop     // binary operator to query
) ;
\end{verbatim}
}\end{mdframed}

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_ytype_name    // return the type_name of y
(
    char *type_name,                // user array of size GxB_MAX_NAME_LEN
    const GrB_BinaryOp binaryop     // binary operator to query
) ;
\end{verbatim}
} \end{mdframed}

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

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

%-------------------------------------------------------------------------------
\subsubsection{{\sf ANY} and {\sf PAIR} ({\sf ONEB}) operators}
%-------------------------------------------------------------------------------
\label{any_pair}

The \verb'GxB_PAIR' operator (also called \verb'GrB_ONEB') is simple to describe:
just $f(x,y)=1$.  It is called
the \verb'PAIR' operator since it returns $1$ in a semiring when a pair of
entries $a_{ik}$ and $b_{kj}$ is found in the matrix multiply.  This operator
is simple yet very useful.  It allows purely structural computations to be
performed on matrices of any type, without having to typecast them to Boolean
with all values being true.  Typecasting need not be performed on the inputs to
the \verb'PAIR' operator, and the \verb'PAIR' operator does not need to access
the values of the matrix.  This cuts memory accesses, so it is a very fast
operator to use.

The \verb'GxB_PAIR_T' operator is a SuiteSparse:GraphBLAS extension.
It has since been added to the v2.0 C API Specification as \verb'GrB_ONEB_T'.
They are identical, but the latter name should be used for compatibility
with other GraphBLAS libraries.

The \verb'ANY' operator is very unusual, but very powerful.  It is the function
$f_{\mbox{any}}(x,y)=x$, or $y$, where GraphBLAS has to freedom to select
either $x$, or $y$, at its own discretion.  Do not confuse the \verb'ANY'
operator with the \verb'any' function in MATLAB/Octave, which computes a reduction
using the logical OR operator.

The \verb'ANY' function is associative and commutative, and can thus serve as
an operator for a monoid.  The selection of $x$ are $y$ is not randomized.
Instead, SuiteSparse:GraphBLAS uses this freedom to compute as fast a result as
possible.  When used as the monoid in a dot product, \[ c_{ij} = \sum_k a_{ik}
b_{kj} \] for example, the computation can terminate as soon as any matching
pair of entries is found.  When used in a parallel saxpy-style computation, the
\verb'ANY' operator allows for a relaxed form of synchronization to be used,
resulting in a fast benign race condition.

Because of this benign race condition, the result of the \verb'ANY' monoid can
be non-deterministic, unless it is coupled with the \verb'PAIR' multiplicative
operator.  In this case, the \verb'ANY_PAIR' semiring will return a
deterministic result, since $f_{\mbox{any}}(1,1)$ is always 1.

When paired with a different operator, the results are non-deterministic.  This
gives a powerful method when computing results for which any value selected by
the \verb'ANY' operator is valid.  One such example is the breadth-first-search
tree.  Suppose node $j$ is at level $v$, and there are multiple nodes $i$ at
level $v-1$ for which the edge $(i,j)$ exists in the graph.  Any of these nodes
$i$ can serve as a valid parent in the BFS tree.  Using the \verb'ANY'
operator, GraphBLAS can quickly compute a valid BFS tree; if it used again on
the same inputs, it might return a different, yet still valid, BFS tree, due to
the non-deterministic nature of intra-thread synchronization.

\newpage
%===============================================================================
\subsection{GraphBLAS IndexUnaryOp operators: {\sf GrB\_IndexUnaryOp}} %========
%===============================================================================
\label{idxunop}

An index-unary operator is a scalar function of the form
$z=f(a_{ij},i,j,y)$ that is applied to the entries $a_{ij}$ of an
$m$-by-$n$ matrix.  It can be used in \verb'GrB_apply' (Section~\ref{apply}) or
in \verb'GrB_select' (Section~\ref{select}) to select entries from a matrix or
vector.

The signature of the index-unary function \verb'f' is as follows:

{\footnotesize
\begin{verbatim}
void f
(
    void *z,            // output value z, of type ztype
    const void *x,      // input value x of type xtype; value of v(i) or A(i,j)
    GrB_Index i,        // row index of A(i,j)
    GrB_Index j,        // column index of A(i,j), or zero for v(i)
    const void *y       // input scalar y
) ; \end{verbatim}}

The following built-in operators are available.  Operators that do not depend
on the value of \verb'A(i,j)' can be used on any matrix or vector, including
those of user-defined type.  In the table, \verb'y' is a
scalar whose type matches the suffix of the operator.  The \verb'VALUEEQ' and
\verb'VALUENE' operators are defined for any built-in type. The other
\verb'VALUE' operators are defined only for real (not complex) built-in types.
Any index computations are done in \verb'int64_t' arithmetic; the result is
typecasted to \verb'int32_t' for the \verb'*INDEX_INT32' operators.

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS name          & MATLAB/Octave     & description \\
                        & analog            & \\
\hline
\verb'GrB_ROWINDEX_INT32'  & \verb'z=i+y'       & row index of \verb'A(i,j)', as int32 \\
\verb'GrB_ROWINDEX_INT64'  & \verb'z=i+y'       & row index of \verb'A(i,j)', as int64 \\
\verb'GrB_COLINDEX_INT32'  & \verb'z=j+y'       & column index of \verb'A(i,j)', as int32 \\
\verb'GrB_COLINDEX_INT64'  & \verb'z=j+y'       & column index of \verb'A(i,j)', as int64 \\
\verb'GrB_DIAGINDEX_INT32' & \verb'z=j-(i+y)'   & column diagonal index of \verb'A(i,j)', as int32 \\
\verb'GrB_DIAGINDEX_INT64' & \verb'z=j-(i+y)'   & column diagonal index of \verb'A(i,j)', as int64 \\
\hline
\verb'GrB_TRIL'    & \verb'z=(j<=(i+y))'  & true for entries on or below the \verb'y'th diagonal \\
\verb'GrB_TRIU'    & \verb'z=(j>=(i+y))'  & true for entries on or above the \verb'y'th diagonal \\
\verb'GrB_DIAG'    & \verb'z=(j==(i+y))'  & true for entries on the \verb'y'th diagonal \\
\verb'GrB_OFFDIAG' & \verb'z=(j!=(i+y))'  & true for entries not on the \verb'y'th diagonal \\
\verb'GrB_COLLE'   & \verb'z=(j<=y)'      & true for entries in columns 0 to \verb'y' \\
\verb'GrB_COLGT'   & \verb'z=(j>y)'       & true for entries in columns \verb'y+1' and above \\
\verb'GrB_ROWLE'   & \verb'z=(i<=y)'      & true for entries in rows 0 to \verb'y' \\
\verb'GrB_ROWGT'   & \verb'z=(i>y)'       & true for entries in rows \verb'y+1' and above \\
\hline
\verb'GrB_VALUENE_T'     & \verb'z=(aij!=y)'    & true if \verb'A(i,j)' is not equal to \verb'y'\\
\verb'GrB_VALUEEQ_T'     & \verb'z=(aij==y)'    & true if \verb'A(i,j)' is equal to \verb'y'\\
\verb'GrB_VALUEGT_T'     & \verb'z=(aij>y)'     & true if \verb'A(i,j)' is greater than \verb'y' \\
\verb'GrB_VALUEGE_T'     & \verb'z=(aij>=y)'    & true if \verb'A(i,j)' is greater than or equal to \verb'y' \\
\verb'GrB_VALUELT_T'     & \verb'z=(aij<y)'     & true if \verb'A(i,j)' is less than \verb'y' \\
\verb'GrB_VALUELE_T'     & \verb'z=(aij<=y)'    & true if \verb'A(i,j)' is less than or equal to \verb'y' \\
%
\hline
\end{tabular}
}
\vspace{0.2in}


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

\vspace{0.1in}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_IndexUnaryOp_new'   & create a user-defined index-unary operator   & \ref{idxunop_new} \\
\verb'GxB_IndexUnaryOp_new'   & create a named user-defined index-unary operator   & \ref{idxunop_new_named} \\
\verb'GrB_IndexUnaryOp_wait'  & wait for a user-defined index-unary operator  & \ref{idxunop_wait} \\
\verb'GrB_IndexUnaryOp_ztype_name' & return the type of the output $z$        & \ref{idxunop_ztype_name} \\
\verb'GrB_IndexUnaryOp_xtype_name' & return the type of the input $x$         & \ref{idxunop_xtype_name} \\
\verb'GrB_IndexUnaryOp_ytype_name' & return the type of the scalar $y$        & \ref{idxunop_ytype_name} \\
\verb'GrB_IndexUnaryOp_free'  & free a user-defined index-unary operator      & \ref{idxunop_free} \\
\hline
\end{tabular}
}
\vspace{0.1in}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_IndexUnaryOp\_new:} create a user-defined index-unary operator}
%-------------------------------------------------------------------------------
\label{idxunop_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_IndexUnaryOp_new       // create a new user-defined IndexUnary op
(
    GrB_IndexUnaryOp *op,           // handle for the new IndexUnary operator
    void *function,                 // pointer to IndexUnary function
    GrB_Type ztype,                 // type of output z
    GrB_Type xtype,                 // type of input x (the A(i,j) entry)
    GrB_Type ytype                  // type of scalar input y
) ;
\end{verbatim} }\end{mdframed}


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

The \verb'function' argument to \verb'GrB_IndexUnaryOp_new' is a pointer to a
user-defined function whose signature is given at the beginning of
Section~\ref{idxunop}.  Given the properties of an entry $a_{ij}$ in a
matrix, the \verb'function' should return \verb'z' as \verb'true' if the entry
should be kept in the output of \verb'GrB_select', or \verb'false' if it should
not appear in the output.  If the return value is not \verb'GrB_BOOL',
it is typecasted to \verb'GrB_BOOL' by \verb'GrB_select'.

The type \verb'xtype' is the GraphBLAS type of the input $x$ of the
user-defined function $z=f(x,i,j,y)$, which is used for the
entry \verb'A(i,j)' of a matrix or \verb'v(i)' of a vector.  The type may be
built-in or user-defined.

The type \verb'ytype' is the GraphBLAS type of the scalar input $y$ of the
user-defined function $z=f(x,i,j,y)$.  The type may be built-in
or user-defined.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_IndexUnaryOp\_new:} create a named user-defined index-unary operator}
%-------------------------------------------------------------------------------
\label{idxunop_new_named}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_IndexUnaryOp_new   // create a named user-created IndexUnaryOp
(
    GrB_IndexUnaryOp *op,           // handle for the new IndexUnary operator
    GxB_index_unary_function function,    // pointer to index_unary function
    GrB_Type ztype,                 // type of output z
    GrB_Type xtype,                 // type of input x
    GrB_Type ytype,                 // type of scalar input y
    const char *idxop_name,         // name of the user function
    const char *idxop_defn          // definition of the user function
) ;
\end{verbatim} }\end{mdframed}

Creates a named \verb'GrB_IndexUnaryOp'.  Only the first 127 characters of
\verb'idxop_name' are used.  The \verb'ixdop_defn' is a string containing the
entire function itself.  Currently, only the \verb'idxop_name' is used, but
future versions will rely on the \verb'idxop_defn' when employing a JIT for
better performance.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_IndexUnaryOp\_wait:} wait for an index-unary operator}
%-------------------------------------------------------------------------------
\label{idxunop_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a user-defined binary operator
(
    GrB_IndexUnaryOp op,        // index-unary operator to wait for   
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined select operator, a GraphBLAS library may choose
to exploit non-blocking mode to delay its creation.  Currently,
SuiteSparse:GraphBLAS currently does nothing except to ensure that the
\verb'op' is valid.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_IndexUnaryOp\_ztype\_name:} return the name of the type of $z$}
%-------------------------------------------------------------------------------
\label{idxunop_ztype_name}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_IndexUnaryOp_ztype_name    // return the type_name of x
(
    char *type_name,                    // user array of size GxB_MAX_NAME_LEN
    const GrB_IndexUnaryOp op           // index-unary operator
) ;
\end{verbatim}
}\end{mdframed}

\verb'GrB_IndexUnaryOp_ztype_name' returns the \verb'ztype' of the index-unary
operator, which is the type of $z$ in the function $z=f(x,i,j,y)$.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_IndexUnaryOp\_xtype\_name:} return the name of the type of $x$}
%-------------------------------------------------------------------------------
\label{idxunop_xtype_name}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_IndexUnaryOp_xtype_name    // return the type_name of x
(
    char *type_name,                    // user array of size GxB_MAX_NAME_LEN
    const GrB_IndexUnaryOp op           // index-unary operator
) ;
\end{verbatim}
}\end{mdframed}

\verb'GrB_IndexUnaryOp_xtype_name' returns the \verb'xtype' of the index-unary
operator, which is the type of $x$ in the function $z=f(x,i,j,y)$.
This input is used for the entry \verb'A(i,j)' of a matrix or \verb'v(i)' of a
vector.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_IndexUnaryOp\_ytype\_name:} return the name of the type of scalar $y$}
%-------------------------------------------------------------------------------
\label{idxunop_ytype_name}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_IndexUnaryOp_ytype_name    // return the type_name of the scalar y
(
    char *type_name,                    // user array of size GxB_MAX_NAME_LEN
    const GrB_IndexUnaryOp op           // index-unary operator
) ;
\end{verbatim}
}\end{mdframed}

\verb'GrB_IndexUnaryOp_ytype_name' returns the \verb'ytype' of the index-unary
operator, which is the type of the scalar y in the function $z=f(x,i,j,y)$.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_IndexUnaryOp\_free:} free a user-defined index-unary operator}
%-------------------------------------------------------------------------------
\label{idxunop_free}

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

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

    {\small
    \begin{verbatim}
    GrB_IndexUnaryOp_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 index-unary 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 operator must also have an identity element, or ``zero'' in this
domain, such that $f(x,0)=f(0,x)=x$.  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.  If used in a semiring, the operator must also be commutative.

The 77 predefined monoids are listed in the table below, which
includes nearly all monoids that can be constructed from built-in binary
operators.  A few additional monoids can be defined with \verb'GrB_Monoid_new'
using built-in operators, such as bitwise monoids for signed integers.
Recall that $T$ denotes any built-in type (including boolean, integer, floating
point real, and complex), $R$ denotes any non-complex type (including bool),
$I$ denotes any integer type, and $Z$ denotes any complex type.  Let $S$ denote
the 10 non-boolean real types.  Let $U$ denote all unsigned integer types.

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

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

The \verb'GxB_ANY_*' monoid can terminate as soon as it finds any value at all.

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lllll}
\hline
GraphBLAS             & types (domains)            & expression      & identity  & terminal \\
operator              &                            & $z=f(x,y)$      &           & \\
\hline
% numeric SxS -> S
\verb'GrB_PLUS_MONOID_'$S$   & $S \times S \rightarrow S$ & $z = x+y$       & 0         & none \\
\verb'GrB_TIMES_MONOID_'$S$  & $S \times S \rightarrow S$ & $z = xy$        & 1         & 0 or none (see note) \\
\verb'GrB_MIN_MONOID_'$S$    & $S \times S \rightarrow S$ & $z = \min(x,y)$ & $+\infty$ & $-\infty$ \\
\verb'GrB_MAX_MONOID_'$S$    & $S \times S \rightarrow S$ & $z = \max(x,y)$ & $-\infty$ & $+\infty$ \\
\hline
% complex ZxZ -> Z
\verb'GxB_PLUS_'$Z$\verb'_MONOID'   & $Z \times Z \rightarrow Z$ & $z = x+y$       & 0         & none \\
\verb'GxB_TIMES_'$Z$\verb'_MONOID'  & $Z \times Z \rightarrow Z$ & $z = xy$        & 1         & none \\
\hline
% any TxT -> T
\verb'GxB_ANY_'$T$\verb'_MONOID'   & $T \times T \rightarrow T$ & $z = x$ or $y$  & any       & any        \\
\hline
% bool x bool -> bool
\verb'GrB_LOR_MONOID'        & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \vee    y $ & false & true  \\
\verb'GrB_LAND_MONOID'       & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \wedge  y $ & true  & false \\
\verb'GrB_LXOR_MONOID'       & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \veebar y $ & false & none \\
\verb'GrB_LXNOR_MONOID'      & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z =(x ==      y)$ & true  & none \\
\hline
% bitwise: UxU -> U
\verb'GxB_BOR_'$U$\verb'_MONOID'    & $U$ $\times$ $U$ $\rightarrow$ $U$ & \verb'z=x|y'    & all bits zero & all bits one  \\
\verb'GxB_BAND_'$U$\verb'_MONOID'   & $U$ $\times$ $U$ $\rightarrow$ $U$ & \verb'z=x&y'    & all bits one  & all bits zero \\
\verb'GxB_BXOR_'$U$\verb'_MONOID'   & $U$ $\times$ $U$ $\rightarrow$ $U$ & \verb'z=x^y'    & all bits zero & none \\
\verb'GxB_BXNOR_'$U$\verb'_MONOID'  & $U$ $\times$ $U$ $\rightarrow$ $U$ & \verb'z=~(x^y)' & all bits one  & none \\
\hline
\end{tabular}
}
\vspace{0.2in}

% 40: (min,max,+,*) x (int8,16,32,64, uint8,16,32,64, fp32, fp64)
The C API Specification includes 44 predefined monoids, with the naming
convention \verb'GrB_op_MONOID_type'.  Forty monoids are available for the four
operators \verb'MIN', \verb'MAX', \verb'PLUS', and \verb'TIMES', each with the
10 non-boolean real types.  Four boolean monoids are predefined:
\verb'GrB_LOR_MONOID_BOOL', \verb'GrB_LAND_MONOID_BOOL',
\verb'GrB_LXOR_MONOID_BOOL', and \verb'GrB_LXNOR_MONOID_BOOL'.

% 13 ANY
%  4 complex (PLUS, TIMES)
% 16 bitwise
% 33 total
These all appear in SuiteSparse:GraphBLAS, which adds 33 additional predefined
\verb'GxB*' monoids, with the naming convention \verb'GxB_op_type_MONOID'.  The
\verb'ANY' operator can be used for all 13 types (including complex).  The
\verb'PLUS' and \verb'TIMES' operators are provided for both complex types, for
4 additional complex monoids.  Sixteen monoids are predefined for four bitwise
operators (\verb'BOR', \verb'BAND', \verb'BXOR', and \verb'BNXOR'), each with
four unsigned integer types (\verb'UINT8', \verb'UINT16', \verb'UINT32', and
\verb'UINT64').

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

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

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_Monoid_new'       & create a user-defined monoid                  & \ref{monoid_new} \\
\verb'GrB_Monoid_wait'      & wait for a user-defined monoid                & \ref{monoid_wait} \\
\verb'GxB_Monoid_terminal_new'  & create a monoid that has a terminal value & \ref{monoid_terminal_new} \\
\verb'GxB_Monoid_operator'  & return the monoid operator                    & \ref{monoid_operator} \\
\verb'GxB_Monoid_identity'  & return the monoid identity value              & \ref{monoid_identity} \\
\verb'GxB_Monoid_terminal'  & return the monoid terminal value (if any)     & \ref{monoid_terminal} \\
\verb'GrB_Monoid_free'      & free a monoid                                 & \ref{monoid_free} \\
\hline
\end{tabular}
}
\vspace{0.2in}

\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
    GrB_BinaryOp op,                // binary operator of the monoid
    <type> identity                 // identity value of the monoid
) ;
\end{verbatim}
} \end{mdframed}

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

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

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

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Monoid\_wait:} wait for a monoid}
%-------------------------------------------------------------------------------
\label{monoid_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a user-defined monoid
(
    GrB_Monoid monoid,          // monoid to wait for
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined monoid, a GraphBLAS library may choose to exploit
non-blocking mode to delay its creation.  Currently, SuiteSparse:GraphBLAS
currently does nothing except to ensure that the \verb'monoid' is valid.

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

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

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

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

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

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

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

There may be cases in which the user application needs to use a non-standard
terminal value for a built-in operator.  For example, suppose the matrix has
type \verb'GrB_FP32', but all values in the matrix are known to be
non-negative.  The annihilator value of \verb'MIN' is \verb'-INFINITY', but
this will never be seen.  However, the computation could terminate when
finding the value zero.  This is an example of using a terminal value that is
not actually an annihilator, but it functions like one since the monoid will
operate strictly on non-negative values.

In this case, a monoid created with \verb'GrB_MIN_FP32' will not terminate
early, because the identity and terminal inputs are ignored when using
\verb'GrB_Monoid_new' with a built-in operator as its input.
To create a monoid that can terminate early, create a user-defined operator
that computes the same thing as \verb'GrB_MIN_FP32', and then create a monoid
based on this user-defined operator with a terminal value of zero and an
identity of \verb'+INFINITY'.

%-------------------------------------------------------------------------------
\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
    GrB_Monoid monoid               // monoid to query
) ;
\end{verbatim}
} \end{mdframed}

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

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Monoid\_identity:} return the monoid identity}
%-------------------------------------------------------------------------------
\label{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
    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.

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

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

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

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

% \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 1,473 predefined
built-in semirings.  The next sections define the following methods for the
\verb'GrB_Semiring' object:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_Semiring_new'       & create a user-defined semiring           & \ref{semiring_new} \\
\verb'GrB_Semiring_wait'      & wait for a user-defined semiring         & \ref{semiring_wait} \\
\verb'GxB_Semiring_add'       & return the additive monoid of a semiring & \ref{semiring_add} \\
\verb'GxB_Semiring_multiply'  & return the binary operator of a semiring & \ref{semiring_multiply} \\
\verb'GrB_Semiring_free'      & free a semiring                          & \ref{semiring_free} \\
\hline
\end{tabular}
}

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Semiring_new           // create a semiring
(
    GrB_Semiring *semiring,         // handle of semiring to create
    GrB_Monoid add,                 // add monoid of the semiring
    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.

The v2.0 C API Specification for GraphBLAS includes 124 predefined semirings,
with names of the form \verb'GrB_add_mult_SEMIRING_type', where \verb'add' is
the operator of the additive monoid, \verb'mult' is the multiply operator, and
\verb'type' is the type of the input $x$ to the multiply operator, $f(x,y)$.
The name of the domain for the additive monoid does not appear in the name,
since it always matches the type of the output of the \verb'mult' operator.
Twelve kinds of \verb'GrB*' semirings are available for all 10 real, non-boolean types:
    \verb'PLUS_TIMES', \verb'PLUS_MIN',
    \verb'MIN_PLUS', \verb'MIN_TIMES', \verb'MIN_FIRST', \verb'MIN_SECOND', \verb'MIN_MAX',
    \verb'MAX_PLUS', \verb'MAX_TIMES', \verb'MAX_FIRST', \verb'MAX_SECOND', and \verb'MAX_MIN'.
Four semirings are for boolean types only: 
    \verb'LOR_LAND', \verb'LAND_LOR', \verb'LXOR_LAND', and \verb'LXNOR_LOR'.

SuiteSparse:GraphBLAS pre-defines 1,553 semirings from built-in types and
operators, listed below.  The naming convention is \verb'GxB_add_mult_type'.
The 124 \verb'GrB*' semirings are a subset of the list below, included with two
names: \verb'GrB*' and \verb'GxB*'.  If the \verb'GrB*' name is provided, its
use is preferred, for portability to other GraphBLAS implementations.

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

    \vspace{-0.05in}
    \begin{itemize}
    \item 5 monoids (\verb'MIN', \verb'MAX', \verb'PLUS', \verb'TIMES', \verb'ANY')
    \item 20 multiply operators
    (\verb'FIRST', \verb'SECOND', \verb'PAIR' (same as \verb'ONEB'),
    \verb'MIN', \verb'MAX',
    \verb'PLUS', \verb'MINUS', \verb'RMINUS', \verb'TIMES', \verb'DIV', \verb'RDIV',
    \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 300 semirings with a comparator $T \times T \rightarrow$
    \verb'bool', where $T$ is non-Boolean and real, from the complete cross product of:

    \vspace{-0.05in}
    \begin{itemize}
    \item 5 Boolean monoids
    (\verb'LAND', \verb'LOR', \verb'LXOR', \verb'EQ', \verb'ANY')
    \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 55 semirings with purely Boolean types, \verb'bool' $\times$ \verb'bool'
    $\rightarrow$ \verb'bool', from the complete cross product of:

    \vspace{-0.05in}
    \begin{itemize}
    \item 5 Boolean monoids
    (\verb'LAND', \verb'LOR', \verb'LXOR', \verb'EQ', \verb'ANY')
    \item 11 multiply operators
    (\verb'FIRST', \verb'SECOND', \verb'PAIR' (same as \verb'ONEB'),
    \verb'LOR', \verb'LAND', \verb'LXOR',
    \verb'EQ', \verb'GT', \verb'LT', \verb'GE', \verb'LE')
    \end{itemize}

\item 54 complex semirings, $Z \times Z \rightarrow Z$ where $Z$ is
    \verb'GxB_FC32' (single precision complex) or
    \verb'GxB_FC64' (double precision complex):

    \vspace{-0.05in}
    \begin{itemize}
    \item 3 complex monoids (\verb'PLUS', \verb'TIMES', \verb'ANY')
    \item 9 complex multiply operators
        (\verb'FIRST', \verb'SECOND', \verb'PAIR' (same as \verb'ONEB'),
        \verb'PLUS', \verb'MINUS',
            \verb'TIMES', \verb'DIV', \verb'RDIV', \verb'RMINUS')
    \item 2 complex types, $Z$
    \end{itemize}

\item 64 bitwise semirings, $U \times U \rightarrow U$ where $U$ is
    an unsigned integer.

    \vspace{-0.05in}
    \begin{itemize}
    \item 4 bitwise monoids (\verb'BOR', \verb'BAND', \verb'BXOR', \verb'BXNOR')
    \item 4 bitwise multiply operators (the same list)
    \item 4 unsigned integer types
    \end{itemize}

\item 80 positional semirings, $X \times X \rightarrow N$ where $N$ is
    \verb'INT32' or \verb'INT64':

    \vspace{-0.05in}
    \begin{itemize}
    \item 5 monoids (\verb'MIN', \verb'MAX', \verb'PLUS', \verb'TIMES', \verb'ANY')
    \item 8 positional operators
        (\verb'FIRSTI', \verb'FIRSTI1', \verb'FIRSTJ', \verb'FIRSTJ1',
        \verb'SECONDI', \verb'SECONDI1', \verb'SECONDJ', \verb'SECONDJ1')
    \item 2 integer types (\verb'INT32', \verb'INT64')
    \end{itemize}

\end{itemize}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Semiring\_wait:} wait for a semiring}
%-------------------------------------------------------------------------------
\label{semiring_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a user-defined semiring
(
    GrB_Semiring semiring,      // semiring to wait for
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined semiring, a GraphBLAS library may choose to
exploit non-blocking mode to delay its creation.  Currently,
SuiteSparse:GraphBLAS currently does nothing except to ensure that the
\verb'semiring' is valid.

%-------------------------------------------------------------------------------
\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
    GrB_Semiring semiring           // semiring to query
) ;
\end{verbatim}
} \end{mdframed}

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

%-------------------------------------------------------------------------------
\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
    GrB_Semiring semiring           // semiring to query
) ;
\end{verbatim}
} \end{mdframed}

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

%-------------------------------------------------------------------------------
\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 scalars: {\sf GrB\_Scalar}} %=============================
%===============================================================================
\label{scalar}

This section describes a set of methods that create, modify, query,
and destroy a GraphBLAS scalar, \verb'GrB_Scalar':

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_Scalar_new'            & create a scalar                      & \ref{scalar_new} \\
\verb'GrB_Scalar_wait'           & wait for a scalar                    & \ref{scalar_wait} \\
\verb'GrB_Scalar_dup'            & copy a scalar                        & \ref{scalar_dup} \\
\verb'GrB_Scalar_clear'          & clear a scalar of its entry          & \ref{scalar_clear} \\
\verb'GrB_Scalar_nvals'          & return number of entries in a scalar & \ref{scalar_nvals}  \\
\verb'GxB_Scalar_type_name'      & return name of the type of a scalar  & \ref{scalar_type_name} \\
\verb'GrB_Scalar_setElement'     & set the single entry of a scalar     & \ref{scalar_setElement} \\
\verb'GrB_Scalar_extractElement' & get the single entry from a scalar   & \ref{scalar_extractElement} \\
\verb'GxB_Scalar_memoryUsage'    & memory used by a scalar              & \ref{scalar_memusage} \\
\verb'GrB_Scalar_free'           & free a scalar                        & \ref{scalar_free} \\
\hline
\end{tabular}
}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Scalar\_new:} create a scalar}
%-------------------------------------------------------------------------------
\label{scalar_new}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Scalar_new     // create a new GrB_Scalar with no entry
(
    GrB_Scalar *s,          // handle of GrB_Scalar to create
    GrB_Type type           // type of GrB_Scalar to create
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Scalar_new' creates a new scalar with no
entry in it, of the given type.  This is analogous to MATLAB/Octave statement
\verb's = sparse(0)', except that GraphBLAS can create scalars any
type.  The pattern of the new scalar is empty.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Scalar\_wait:} wait for a scalar}
%-------------------------------------------------------------------------------
\label{scalar_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a scalar
(
    GrB_Scalar s,               // scalar to wait for
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

In non-blocking mode, the computations for a \verb'GrB_Scalar' may be delayed.
In this case, the scalar is not yet safe to use by multiple independent user
threads.  A user application may force completion of a scalar \verb's' via
\verb'GrB_Scalar_wait(&s)' (in v5.2.0), or
\verb'GrB_Scalar_wait(s,mode)' (in v6.0.0).
With a \verb'mode' of \verb'GrB_MATERIALIZE',
all pending computations are finished, and different user threads may
simultaneously call GraphBLAS operations that use the scalar \verb's' as an
input parameter.
See Section~\ref{omp_parallelism}
if GraphBLAS is compiled without OpenMP.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Scalar\_dup:} copy a scalar}
%-------------------------------------------------------------------------------
\label{scalar_dup}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Scalar_dup     // make an exact copy of a GrB_Scalar
(
    GrB_Scalar *s,          // handle of output GrB_Scalar to create
    const GrB_Scalar t      // input GrB_Scalar to copy
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Scalar_dup' makes a deep copy of a scalar.
In GraphBLAS, it is possible, and valid, to write the following:

    {\footnotesize
    \begin{verbatim}
    GrB_Scalar t, s ;
    GrB_Scalar_new (&t, GrB_FP64) ;
    s = t ;                         // s is a shallow copy of t  \end{verbatim}}

Then \verb's' and \verb't' 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 scalars are needed, then this should be used instead:

    {\footnotesize
    \begin{verbatim}
    GrB_Scalar t, s ;
    GrB_Scalar_new (&t, GrB_FP64) ;
    GrB_Scalar_dup (&s, t) ;        // like s = t, but making a deep copy \end{verbatim}}

Then \verb's' and \verb't' are two different scalars that currently have
the same value, but they do not depend on each other.  Modifying one has no
effect on the other.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Scalar\_clear:} clear a scalar of its entry}
%-------------------------------------------------------------------------------
\label{scalar_clear}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Scalar_clear   // clear a GrB_Scalar of its entry
(                           // type remains unchanged.
    GrB_Scalar s            // GrB_Scalar to clear
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Scalar_clear' clears the entry from a scalar.  The pattern of
\verb's' is empty, just as if it were created fresh with \verb'GrB_Scalar_new'.
Analogous with \verb's = sparse (0)' in MATLAB/Octave.  The type of \verb's' does not
change.  Any pending updates to the scalar are discarded.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Scalar\_nvals:} return the number of entries in a scalar}
%-------------------------------------------------------------------------------
\label{scalar_nvals}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Scalar_nvals   // get the number of entries in a GrB_Scalar
(
    GrB_Index *nvals,       // GrB_Scalar has nvals entries (0 or 1)
    const GrB_Scalar s      // GrB_Scalar to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Scalar_nvals' returns the number of entries in a scalar, which
is either 0 or 1.  Roughly analogous to \verb'nvals = nnz(s)' in MATLAB/Octave,
except that the implicit value in GraphBLAS need not be zero and \verb'nnz'
(short for ``number of nonzeros'') in MATLAB is better described as ``number of
entries'' in GraphBLAS.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Scalar\_type\_name:} return name of the type of a scalar}
%-------------------------------------------------------------------------------
\label{scalar_type_name}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Scalar_type_name      // return the name of the type of a scalar
(
    char *type_name,        // name of the type (char array of size at least
                            // GxB_MAX_NAME_LEN, owned by the user application).
    const GrB_Scalar s      // GrB_Scalar to query
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Scalar_type_name' returns the name of the type of a scalar.
Analogous to \verb'type = class (s)' in MATLAB.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Scalar\_setElement:} set the single entry of a scalar}
%-------------------------------------------------------------------------------
\label{scalar_setElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Scalar_setElement          // s = x
(
    GrB_Scalar s,                       // GrB_Scalar to modify
    <type> x                            // user scalar to assign to s
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Scalar_setElement' sets the single entry in a scalar, like
\verb's = sparse(x)' in MATLAB notation.  For further details of this function,
see \verb'GrB_Matrix_setElement' in Section~\ref{matrix_setElement}.
If an error occurs, \verb'GrB_error(&err,s)' returns details about the error.
The scalar \verb'x' can be any non-opaque C scalar corresponding to
a built-in type, or \verb'void *' for a user-defined type.  It cannot be
a \verb'GrB_Scalar'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Scalar\_extractElement:} get the single entry from a scalar}
%-------------------------------------------------------------------------------
\label{scalar_extractElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Scalar_extractElement  // x = s
(
    <type> *x,                      // user scalar extracted
    const GrB_Scalar s              // GrB_Sclar to extract an entry from
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Scalar_extractElement' extracts the single entry from a sparse
scalar, like \verb'x = full(s)' in MATLAB.  Further details of this method are
discussed in Section~\ref{matrix_extractElement}, which discusses
\verb'GrB_Matrix_extractElement'.  {\bf NOTE: }  if no entry is present in the
scalar \verb's', then \verb'x' is not modified, and the return value of
\verb'GrB_Scalar_extractElement' is \verb'GrB_NO_VALUE'.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Scalar\_memoryUsage:} memory used by a scalar}
%-------------------------------------------------------------------------------
\label{scalar_memusage}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Scalar_memoryUsage  // return # of bytes used for a scalar
(
    size_t *size,           // # of bytes used by the scalar s
    const GrB_Scalar s      // GrB_Scalar to query
) ;
\end{verbatim} } \end{mdframed}

Returns the memory space required for a scalar, in bytes.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Scalar\_free:} free a scalar}
%-------------------------------------------------------------------------------
\label{scalar_free}

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

\verb'GrB_Scalar_free' frees a scalar.  Either usage:

    {\small
    \begin{verbatim}
    GrB_Scalar_free (&s) ;
    GrB_free (&s) ; \end{verbatim}}

\noindent
frees the scalar \verb's' and sets \verb's' to \verb'NULL'.  It safely
does nothing if passed a \verb'NULL' handle, or if \verb's == NULL' on input.
Any pending updates to the scalar are abandoned.

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

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

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_Vector_new'            & create a vector                  & \ref{vector_new} \\
\verb'GrB_Vector_wait'           & wait for a vector                & \ref{vector_wait} \\
\verb'GrB_Vector_dup'            & copy a vector                    & \ref{vector_dup} \\
\verb'GrB_Vector_clear'          & clear a vector of all entries    & \ref{vector_clear} \\
\verb'GrB_Vector_size'           & size of a vector                 & \ref{vector_size} \\
\verb'GrB_Vector_nvals'          & number of entries in a vector    & \ref{vector_nvals} \\
\verb'GxB_Vector_type_name'      & name of the type of a vector     & \ref{vector_type_name} \\
\verb'GrB_Vector_build'          & build a vector from tuples       & \ref{vector_build} \\
\verb'GxB_Vector_build_Scalar'   & build a vector from tuples       & \ref{vector_build_Scalar} \\
\verb'GrB_Vector_setElement'     & add an entry to a vector         & \ref{vector_setElement} \\
\verb'GrB_Vector_extractElement' & get an entry from a vector       & \ref{vector_extractElement} \\
\verb'GxB_Vector_isStoredElement'& check if entry present in vector & \ref{vector_isStoredElement} \\
\verb'GrB_Vector_removeElement'  & remove an entry from a vector    & \ref{vector_removeElement} \\
\verb'GrB_Vector_extractTuples'  & get all entries from a vector    & \ref{vector_extractTuples} \\
\verb'GrB_Vector_resize'         & resize a vector                  & \ref{vector_resize} \\
\verb'GxB_Vector_diag'           & extract a diagonal from a matrix & \ref{vector_diag} \\
\verb'GxB_Vector_iso'            & query iso status                 & \ref{vector_iso} \\
\verb'GxB_Vector_memoryUsage'    & memory used by a vector          & \ref{vector_memusage} \\
\verb'GrB_Vector_free'           & free a vector                    & \ref{vector_free} \\
\hline
\hline
% NOTE: GrB_Vector_serialize / deserialize does not appear in the 2.0 C API.
% \verb'GrB_Vector_serializeSize'  & return size of serialized vector & \ref{vector_serialize_size} \\
% \verb'GrB_Vector_serialize'      & serialize a vector               & \ref{vector_serialize} \\
\verb'GxB_Vector_serialize'      & serialize a vector               & \ref{vector_serialize_GxB} \\
% \verb'GrB_Vector_deserialize'    & deserialize a vector             & \ref{vector_deserialize} \\
\verb'GxB_Vector_deserialize'    & deserialize a vector             & \ref{vector_deserialize_GxB} \\
\hline
\hline
\verb'GxB_Vector_pack_CSC'         & pack in CSC format      & \ref{vector_pack_csc} \\
\verb'GxB_Vector_unpack_CSC'       & unpack in CSC format    & \ref{vector_unpack_csc} \\
\hline
\verb'GxB_Vector_pack_Bitmap'      & pack in bitmap format   & \ref{vector_pack_bitmap} \\
\verb'GxB_Vector_unpack_Bitmap'    & unpack in bitmap format & \ref{vector_unpack_bitmap} \\
\hline
\verb'GxB_Vector_pack_Full'        & pack in full format     & \ref{vector_pack_full} \\
\verb'GxB_Vector_unpack_Full'      & unpack in full format   & \ref{vector_unpack_full} \\
\hline
\hline
\verb'GxB_Vector_sort'          & sort a vector & \ref{vector_sort} \\
\end{tabular}
}

\vspace{0.2in}
Refer to
Section~\ref{serialize_deserialize} for serialization/deserialization methods,
Section~\ref{pack_unpack} for pack/unpack methods,
and to
Section~\ref{sorting_methods} for sorting methods.

\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
    GrB_Type type,          // type of vector to create
    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/Octave statement
\verb'v = sparse (n,1)', except that GraphBLAS can create sparse vectors any
type.  The pattern of the new vector is empty.

\begin{alert}
{\bf SPEC:} \verb'n' may be zero, as an extension to the specification.
\end{alert}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_wait:} wait for a vector}
%-------------------------------------------------------------------------------
\label{vector_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a vector
(
    GrB_Vector w,               // vector to wait for
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

In non-blocking mode, the computations for a \verb'GrB_Vector' may be delayed.
In this case, the vector is not yet safe to use by multiple independent user
threads.  A user application may force completion of a vector \verb'w' via
\verb'GrB_Vector_wait(&w)' (in v5.2.0), or
\verb'GrB_Vector_wait(w,mode)' (in v6.0.0).
With a \verb'mode' of \verb'GrB_MATERIALIZE',
all pending computations are finished, and different user threads may
simultaneously call GraphBLAS operations that use the vector \verb'w' as an
input parameter.
See Section~\ref{omp_parallelism}
if GraphBLAS is compiled without OpenMP.

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

%-------------------------------------------------------------------------------
\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 (:) = sparse(0)' in MATLAB.  The type and dimension of \verb'v' do
not change.  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.

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_type_name      // return the name of the type of a vector
(
    char *type_name,        // name of the type (char array of size at least
                            // GxB_MAX_NAME_LEN, owned by the user application).
    const GrB_Vector v      // vector to query
) ;
\end{verbatim}
} \end{mdframed}

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

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

If \verb'dup' is \verb'NULL', any duplicates result in an error.
If \verb'dup' is the special binary operator \verb'GxB_IGNORE_DUP', then
any duplicates are ignored.  If duplicates appear, the last one in the
list of tuples is taken and the prior ones ignored.  This is not an error.

\begin{alert}
{\bf SPEC:} Results are defined even if \verb'dup' is non-associative.
\end{alert}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_build\_Scalar:} build a vector from a set of tuples}
%-------------------------------------------------------------------------------
\label{vector_build_Scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_build_Scalar    // build a vector from (i,scalar) tuples
(
    GrB_Vector w,                   // vector to build
    const GrB_Index *I,             // array of row indices of tuples
    GrB_Scalar scalar,              // value for all tuples
    GrB_Index nvals                 // number of tuples
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_build_Scalar' constructs a sparse vector \verb'w' from a set
of tuples defined by the index array \verb'I' of length \verb'nvals', and a
scalar.  The scalar is the value of all of the tuples.  Unlike
\verb'GrB_Vector_build', there is no \verb'dup' operator to handle duplicate
entries.  Instead, any duplicates are silently ignored (if the number of
duplicates is desired, simply compare the input \verb'nvals' with the value
returned by \verb'GrB_Vector_nvals' after the vector is constructed).  All
entries in the sparsity pattern of \verb'w' are identical, and equal to the
input scalar value.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_setElement:}    add an 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
    <type> x,                           // scalar to assign to w(i)
    GrB_Index i                         // 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}.
If an error occurs, \verb'GrB_error(&err,w)' returns details about the error.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_extractElement:} get an 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 (non-opaque, C scalar)
    const GrB_Vector v,         // vector to extract an entry from
    GrB_Index i                 // index
) ;

GrB_Info GrB_Vector_extractElement  // x = v(i)
(
    GrB_Scalar x,               // GrB_Scalar extracted
    const GrB_Vector v,         // vector to extract an entry from
    GrB_Index i                 // 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; see
Section~\ref{matrix_extractElement}.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_isStoredElement:} check if entry present in vector}
%-------------------------------------------------------------------------------
\label{vector_isStoredElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_isStoredElement
(
    const GrB_Vector v,         // check presence of entry v(i)
    GrB_Index i                 // index
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_isStoredElement' checks if a single entry \verb'v(i)'
is present, returning \verb'GrB_SUCCESS' if the entry is present or
\verb'GrB_NO_VALUE' otherwise.  The value of \verb'v(i)' is not returned.
See also Section~\ref{matrix_isStoredElement}.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_removeElement:} remove an entry from a vector}
%-------------------------------------------------------------------------------
\label{vector_removeElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_removeElement
(
    GrB_Vector w,                   // vector to remove an entry from
    GrB_Index i                     // index
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_removeElement' removes a single entry \verb'w(i)' from a vector.
If no entry is present at \verb'w(i)', then the vector is not modified.
If an error occurs, \verb'GrB_error(&err,w)' returns details about the error.

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

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

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

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_diag:} extract a diagonal from a matrix}
%-------------------------------------------------------------------------------
\label{vector_diag}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_diag    // extract a diagonal from a matrix
(
    GrB_Vector v,                   // output vector
    const GrB_Matrix A,             // input matrix
    int64_t k,
    const GrB_Descriptor desc       // unused, except threading control
) ;
\end{verbatim} } \end{mdframed}


\verb'GxB_Vector_diag' extracts a vector \verb'v' from an input matrix
\verb'A', which may be rectangular.  If \verb'k' = 0, the main diagonal of
\verb'A' is extracted; \verb'k' $> 0$ denotes diagonals above the main diagonal
of \verb'A', and \verb'k' $< 0$ denotes diagonals below the main diagonal of
\verb'A'.  Let \verb'A' have dimension $m$-by-$n$.  If \verb'k' is in the range
0 to $n-1$, then \verb'v' has length $\min(m,n-k)$.  If \verb'k' is negative
and in the range -1 to $-m+1$, then \verb'v' has length $\min(m+k,n)$.  If
\verb'k' is outside these ranges, \verb'v' has length 0 (this is not an error).
This function computes the same thing as the MATLAB/Octave statement
\verb'v=diag(A,k)' when \verb'A' is a matrix, except that
\verb'GxB_Vector_diag' can also do typecasting.

The vector \verb'v' must already exist on input, and
\verb'GrB_Vector_size (&len,v)' must return \verb'len' = 0 if \verb'k' $\ge n$
or \verb'k' $\le -m$, \verb'len' $=\min(m,n-k)$ if \verb'k' is in the range 0
to $n-1$, and \verb'len' $=\min(m+k,n)$ if \verb'k' is in the range -1 to
$-m+1$.  Any existing entries in \verb'v' are discarded.  The type of \verb'v'
is preserved, so that if the type of \verb'A' and \verb'v' differ, the entries
are typecasted into the type of \verb'v'.  Any settings made to \verb'v' by
\verb'GxB_Vector_Option_set' (bitmap switch and sparsity control) are
unchanged.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_iso:} query iso status of a vector}
%-------------------------------------------------------------------------------
\label{vector_iso}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_iso     // return iso status of a vector
(
    bool *iso,              // true if the vector is iso-valued
    const GrB_Vector v      // vector to query
) ;
\end{verbatim} } \end{mdframed}

Returns the true if the vector is iso-valued, false otherwise.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_memoryUsage:} memory used by a vector}
%-------------------------------------------------------------------------------
\label{vector_memusage}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_memoryUsage  // return # of bytes used for a vector
(
    size_t *size,           // # of bytes used by the vector v
    const GrB_Vector v      // vector to query
) ;
\end{verbatim} } \end{mdframed}

Returns the memory space required for a vector, in bytes.

%-------------------------------------------------------------------------------
\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.  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}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_Matrix_new'           & create a matrix                       & \ref{matrix_new} \\
\verb'GrB_Matrix_wait'          & wait for a matrix                     & \ref{matrix_wait} \\
\verb'GrB_Matrix_dup'           & copy a matrix                         & \ref{matrix_dup} \\
\verb'GrB_Matrix_clear'         & clear a matrix of all entries         & \ref{matrix_clear} \\
\verb'GrB_Matrix_nrows'         & number of rows of a matrix            & \ref{matrix_nrows} \\
\verb'GrB_Matrix_ncols'         & number of columns of a matrix         & \ref{matrix_ncols} \\
\verb'GrB_Matrix_nvals'         & number of entries in a matrix         & \ref{matrix_nvals} \\
\verb'GxB_Matrix_type_name'     & type of a matrix                      & \ref{matrix_type_name} \\
\verb'GrB_Matrix_build'         & build a matrix from tuples            & \ref{matrix_build} \\
\verb'GxB_Matrix_build_Scalar'  & build a matrix from tuples            & \ref{matrix_build_Scalar} \\
\verb'GrB_Matrix_setElement'    & add an entry to a matrix              & \ref{matrix_setElement} \\
\verb'GrB_Matrix_extractElement'& get an entry from a matrix            & \ref{matrix_extractElement} \\
\verb'GxB_Matrix_isStoredElement'& check if entry present in matrix     & \ref{matrix_isStoredElement} \\
\verb'GrB_Matrix_removeElement' & remove an entry from a matrix         & \ref{matrix_removeElement} \\
\verb'GrB_Matrix_extractTuples' & get all entries from a matrix         & \ref{matrix_extractTuples} \\
\verb'GrB_Matrix_resize'        & resize a matrix                       & \ref{matrix_resize} \\
\verb'GxB_Matrix_concat'        & concatenate matrices                  & \ref{matrix_concat} \\
\verb'GxB_Matrix_split'         & split a matrix into matrices          & \ref{matrix_split} \\
\verb'GrB_Matrix_diag'          & diagonal matrix from vector           & \ref{matrix_diag} \\
\verb'GxB_Matrix_diag'          & diagonal matrix from vector           & \ref{matrix_diag_GxB} \\
\verb'GxB_Matrix_iso'           & query iso status                      & \ref{matrix_iso} \\
\verb'GxB_Matrix_memoryUsage'   & memory used by a matrix               & \ref{matrix_memusage} \\
\verb'GrB_Matrix_free'          & free a matrix                         & \ref{matrix_free} \\
\hline
\hline
\verb'GrB_Matrix_serializeSize' & return size of serialized matrix & \ref{matrix_serialize_size} \\
\verb'GrB_Matrix_serialize'     & serialize a matrix               & \ref{matrix_serialize} \\
\verb'GxB_Matrix_serialize'     & serialize a matrix               & \ref{matrix_serialize_GxB} \\
\verb'GrB_Matrix_deserialize'   & deserialize a matrix             & \ref{matrix_deserialize} \\
\verb'GxB_Matrix_deserialize'   & deserialize a matrix             & \ref{matrix_deserialize_GxB} \\
\hline
\end{tabular}
}

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GxB_Matrix_pack_CSR'        &   pack CSR           & \ref{matrix_pack_csr} \\
\verb'GxB_Matrix_unpack_CSR'      & unpack CSR           & \ref{matrix_unpack_csr} \\
\hline
\verb'GxB_Matrix_pack_CSC'        &   pack CSC           & \ref{matrix_pack_csc} \\
\verb'GxB_Matrix_unpack_CSC'      & unpack CSC           & \ref{matrix_unpack_csc} \\
\hline
\verb'GxB_Matrix_pack_HyperCSR'   &   pack HyperCSR      & \ref{matrix_pack_hypercsr} \\
\verb'GxB_Matrix_unpack_HyperCSR' & unpack HyperCSR      & \ref{matrix_unpack_hypercsr} \\
\hline
\verb'GxB_Matrix_pack_HyperCSC'   &   pack HyperCSC      & \ref{matrix_pack_hypercsc} \\
\verb'GxB_Matrix_unpack_HyperCSC' & unpack HyperCSC      & \ref{matrix_unpack_hypercsc} \\
\hline
\verb'GxB_Matrix_pack_BitmapR'    &   pack BitmapR       & \ref{matrix_pack_bitmapr} \\
\verb'GxB_Matrix_unpack_BitmapR'  & unpack BitmapR       & \ref{matrix_unpack_bitmapr} \\
\hline
\verb'GxB_Matrix_pack_BitmapC'    &   pack BitmapC       & \ref{matrix_pack_bitmapc} \\
\verb'GxB_Matrix_unpack_BitmapC'  & unpack BitmapC       & \ref{matrix_unpack_bitmapc} \\
\hline
\verb'GxB_Matrix_pack_FullR'      &   pack FullR         & \ref{matrix_pack_fullr} \\
\verb'GxB_Matrix_unpack_FullR'    & unpack FullR         & \ref{matrix_unpack_fullr} \\
\hline
\verb'GxB_Matrix_pack_FullC'      &   pack FullC         & \ref{matrix_pack_fullc} \\
\verb'GxB_Matrix_unpack_FullC'    & unpack FullC         & \ref{matrix_unpack_fullc} \\
\hline
\hline
\verb'GrB_Matrix_import'        & import in various formats & \ref{GrB_matrix_import} \\
\verb'GrB_Matrix_export'        & export in various formats & \ref{GrB_matrix_export} \\
\verb'GrB_Matrix_exportSize'    & array sizes for export & \ref{export_size} \\
\verb'GrB_Matrix_exportHint'    & hint best export format & \ref{export_hint} \\
\hline
\hline
\verb'GxB_Matrix_sort'          & sort a matrix & \ref{matrix_sort} \\
\hline
\end{tabular}
}

\vspace{0.2in}
Refer to
Section~\ref{serialize_deserialize} for serialization/deserialization methods,
Section~\ref{pack_unpack} for \verb'GxB'pack/unpack methods,
Section~\ref{GrB_import_export} for \verb'GrB' import/export methods,
and
Section~\ref{sorting_methods} for sorting methods.

%-------------------------------------------------------------------------------
\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
    GrB_Type type,          // type of matrix to create
    GrB_Index nrows,        // matrix dimension is nrows-by-ncols
    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.

By default, matrices of size \verb'nrows-by-1' are held by column, regardless
of the global setting controlled by \verb'GxB_set (GxB_FORMAT, ...)', for any
value of \verb'nrows'.  Matrices of size \verb'1-by-ncols' with \verb'ncols'
not equal to 1 are held by row, regardless of this global setting.  The global
setting only affects matrices with both \verb'm > 1' and \verb'n > 1'.  Empty
matrices (\verb'0-by-0') are also controlled by the global setting.

Once a matrix is created, its format (by-row or by-column) can be arbitrarily
changed with \verb'GxB_set (A, GxB_FORMAT, fmt)' with \verb'fmt' equal to
\verb'GxB_BY_COL' or \verb'GxB_BY_ROW'.

\begin{alert}
{\bf SPEC:} \verb'nrows' and/or \verb'ncols' may be zero,
as an extension to the specification.
\end{alert}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_wait:} wait for a matrix}
%-------------------------------------------------------------------------------
\label{matrix_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait               // wait for a matrix
(
    GrB_Matrix C,               // matrix to wait for
    GrB_WaitMode mode           // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

In non-blocking mode, the computations for a \verb'GrB_Matrix' may be delayed.
In this case, the matrix is not yet safe to use by multiple independent user
threads.  A user application may force completion of a matrix \verb'C' via
\verb'GrB_Matrix_wait(&C)' (in v5.2.0), or
\verb'GrB_Matrix_wait(C,mode)' (in v6.0.0).
With a \verb'mode' of \verb'GrB_MATERIALIZE',
all pending computations are finished, and different user threads may
simultaneously call GraphBLAS operations that use the matrix \verb'C' as an
input parameter.
See Section~\ref{omp_parallelism}
if GraphBLAS is compiled without OpenMP.

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

%-------------------------------------------------------------------------------
\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.  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'nrows=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).

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_type_name      // return the name of the type of a matrix
(
    char *type_name,        // name of the type (char array of size at least
                            // GxB_MAX_NAME_LEN, owned by the user application).
    const GrB_Matrix A      // matrix to query
) ;
\end{verbatim} } \end{mdframed}

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

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

If \verb'dup' is \verb'NULL', any duplicates result in an error.
If \verb'dup' is the special binary operator \verb'GxB_IGNORE_DUP', then
any duplicates are ignored.  If duplicates appear, the last one in the
list of tuples is taken and the prior ones ignored.  This is not an error.

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

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

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

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

However, SuiteSparse:GraphBLAS guarantees this ordering, even when it compute
the result in parallel.  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 GxB\_Matrix\_build\_Scalar:} build a matrix from a set of tuples}
%-------------------------------------------------------------------------------
\label{matrix_build_Scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_build_Scalar    // build a matrix from (I,J,scalar) 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
    GrB_Scalar scalar,              // value for all tuples
    GrB_Index nvals                 // number of tuples
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_build_Scalar' constructs a sparse matrix \verb'C' from a set
of tuples defined the index arrays \verb'I' and \verb'J' of length
\verb'nvals', and a scalar.  The scalar is the value of all of the tuples.
Unlike \verb'GrB_Matrix_build', there is no \verb'dup' operator to handle
duplicate entries.  Instead, any duplicates are silently ignored (if the number
of duplicates is desired, simply compare the input \verb'nvals' with the value
returned by \verb'GrB_Vector_nvals' after the matrix is constructed).  All
entries in the sparsity pattern of \verb'C' are identical, and equal to the
input scalar value.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_setElement:}   add an 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
    <type> x,                           // scalar to assign to C(i,j)
    GrB_Index i,                        // row index
    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.
%
If \verb'x' is a \verb'GrB_Scalar' and contains no entry, then the
entry \verb'C(i,j)' is removed (if it exists).  The action taken is
identical to \verb'GrB_Matrix_removeElement(C,i,j)' in this case.

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_extractElement:} get an 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 (non-opaque C scalar)
    const GrB_Matrix A,         // matrix to extract a scalar from
    GrB_Index i,                // row index
    GrB_Index j                 // column index
) ;
GrB_Info GrB_Matrix_extractElement      // x = A(i,j)
(
    GrB_Scalar x,               // extracted GrB_Scalar
    const GrB_Matrix A,         // matrix to extract a scalar from
    GrB_Index i,                // row index
    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 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 no entry is present at \verb'A(i,j)', and \verb'x' is a non-opaque C scalar,
then \verb'x' is not modified, and the return value of
\verb'GrB_Matrix_extractElement' is \verb'GrB_NO_VALUE'.  If \verb'x' is a
\verb'GrB_Scalar', then \verb'x' is returned as an empty scalar with no entry,
and \verb'GrB_SUCCESS' is returned.

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

Currently, 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 GxB\_Matrix\_isStoredElement:} check if entry present in matrix}
%-------------------------------------------------------------------------------
\label{matrix_isStoredElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_isStoredElement
(
    const GrB_Matrix A,         // check for A(i,j)
    GrB_Index i,                // row index
    GrB_Index j                 // column index
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_isStoredElement' check if the single entry \verb'A(i,j)' is
present in the matrix \verb'A'.  It returns \verb'GrB_SUCCESS' if the entry is
present, or \verb'GrB_NO_VALUE' otherwise.  The value of \verb'A(i,j)' is not
returned. It is otherwise identical to \verb'GrB_Matrix_extractElement'.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_removeElement:} remove an entry from a matrix}
%-------------------------------------------------------------------------------
\label{matrix_removeElement}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_removeElement
(
    GrB_Matrix C,                   // matrix to remove an entry from
    GrB_Index i,                    // row index
    GrB_Index j                     // column index
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_removeElement' removes a single entry \verb'A(i,j)' from a
matrix.  If no entry is present at \verb'A(i,j)', then the matrix is not
modified.  If an error occurs, \verb'GrB_error(&err,A)' returns details about
the error.

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

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

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

The GraphBLAS API states the tuples can be returned in any order.  If
\verb'GrB_wait' is called first, then SuiteSparse:GraphBLAS chooses to
always return them in sorted order, depending on whether the matrix is stored
by row or by column.  Otherwise, the indices can be returned in any order.

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.

\begin{alert}
{\bf SPEC:} As an extension to the specification, the arrays \verb'I', \verb'J', and/or
\verb'X' may be passed in as \verb'NULL' pointers.
\verb'GrB_Matrix_extractTuples' does not return a component specified as
\verb'NULL'.  This is not an error condition.
\end{alert}

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_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'GrB_Matrix_resize' changes the size of a matrix.  If the dimensions
decrease, entries that fall outside the resized matrix are deleted.  Unlike
\verb'GxB_Matrix_reshape*' (see Sections \ref{matrix_reshape} and
\ref{matrix_reshapedup}), entries remain in their same position after resizing
the matrix.

%-------------------------------------------------------------------------------
\newpage
\subsubsection{{\sf GxB\_Matrix\_reshape:} reshape a matrix}
%-------------------------------------------------------------------------------
\label{matrix_reshape}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_reshape     // reshape a GrB_Matrix in place
(
    // input/output:
    GrB_Matrix C,               // input/output matrix, reshaped in place
    // input:
    bool by_col,                // true if reshape by column, false if by row
    GrB_Index nrows_new,        // new number of rows of C
    GrB_Index ncols_new,        // new number of columns of C
    const GrB_Descriptor desc   // to control # of threads used
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_reshape' changes the size of a matrix \verb'C', taking entries
from the input matrix either column-wise or row-wise.  If matrix \verb'C' on
input is \verb'nrows'-by-\verb'ncols', and the requested dimensions of
\verb'C' on output are \verb'nrows_new'-by-\verb'nrows_cols', then
the condition \verb'nrows*ncols == nrows_new*nrows_cols' must hold.
The matrix \verb'C' is modified in-place, as both an input and output for
this method.  To create a new matrix, use \verb'GxB_Matrix_reshapeDup'
instead (Section \ref{matrix_reshapedup}).

For example, if \verb'C' is 3-by-4 on input, and is reshaped column-wise to
have dimensions 2-by-6:

\begin{verbatim}
        C on input      C on output (by_col true)
        00 01 02 03     00 20 11 02 22 13
        10 11 12 13     10 01 21 12 03 23
        20 21 22 23
\end{verbatim}

If the same \verb'C' on input is reshaped row-wise to dimensions 2-by-6:

\begin{verbatim}
        C on input      C on output (by_col false)
        00 01 02 03     00 01 02 03 10 11
        10 11 12 13     12 13 20 21 22 23
        20 21 22 23
\end{verbatim}

NOTE: because an intermediate linear index must be computed for each entry,
\verb'GxB_Matrix_reshape' cannot be used on matrices for which
\verb'nrows*ncols' exceeds $2^{60}$.

%-------------------------------------------------------------------------------
\newpage
\subsubsection{{\sf GxB\_Matrix\_reshapeDup:} reshape a matrix}
%-------------------------------------------------------------------------------
\label{matrix_reshapedup}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_reshapeDup // reshape a GrB_Matrix into another GrB_Matrix
(
    // output:
    GrB_Matrix *C,              // newly created output matrix, not in place
    // input:
    GrB_Matrix A,               // input matrix, not modified
    bool by_col,                // true if reshape by column, false if by row
    GrB_Index nrows_new,        // number of rows of C
    GrB_Index ncols_new,        // number of columns of C
    const GrB_Descriptor desc   // to control # of threads used
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_reshapeDup' is identical to \verb'GxB_Matrix_reshape' (see
Section \ref{matrix_reshape}), except that creates a new output matrix
\verb'C' that is reshaped from the input matrix \verb'A'.

%-------------------------------------------------------------------------------
% \newpage
\subsubsection{{\sf GxB\_Matrix\_concat:} concatenate matrices   }
%-------------------------------------------------------------------------------
\label{matrix_concat}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_concat          // concatenate a 2D array of matrices
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix *Tiles,        // 2D row-major array of size m-by-n
    const GrB_Index m,
    const GrB_Index n,
    const GrB_Descriptor desc       // unused, except threading control
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_concat' concatenates an array of matrices (\verb'Tiles') into
a single \verb'GrB_Matrix' \verb'C'.

\verb'Tiles' is an \verb'm'-by-\verb'n' dense array of matrices held in
row-major format, where \verb'Tiles [i*n+j]' is the $(i,j)$th tile, and where
\verb'm' $> 0$ and \verb'n' $> 0$ must hold.  Let $A_{i,j}$ denote the
$(i,j)$th tile.  The matrix \verb'C' is constructed by concatenating these
tiles together, as:

\[
C = 
\left[
\begin{array}{ccccc}
          A_{0,0}   & A_{0,1}   & A_{0,2}   & \cdots & A_{0,n-1}   \\
          A_{1,0}   & A_{1,1}   & A_{1,2}   & \cdots & A_{1,n-1}   \\
          \cdots    &                                              \\
          A_{m-1,0} & A_{m-1,1} & A_{m-1,2} & \cdots & A_{m-1,n-1}
\end{array}
\right]
\]

On input, the matrix \verb'C' must already exist.  Any existing entries in
\verb'C' are discarded.  \verb'C' must have dimensions \verb'nrows' by
\verb'ncols' where \verb'nrows' is the sum of the number of rows in the
matrices $A_{i,0}$ for all $i$, and \verb'ncols' is the sum of the number of
columns in the matrices $A_{0,j}$ for all $j$.  All matrices in any given tile
row $i$ must have the same number of rows (that is, and all matrices in any
given tile column $j$ must have the same number of columns).

The type of \verb'C' is unchanged, and all matrices $A_{i,j}$ are typecasted
into the type of \verb'C'.  Any settings made to \verb'C' by
\verb'GxB_Matrix_Option_set' (format by row or by column, bitmap switch, hyper
switch, and sparsity control) are unchanged.

%-------------------------------------------------------------------------------
% \newpage
\subsubsection{{\sf GxB\_Matrix\_split:} split a matrix   }
%-------------------------------------------------------------------------------
\label{matrix_split}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_split           // split a matrix into 2D array of matrices
(
    GrB_Matrix *Tiles,              // 2D row-major array of size m-by-n
    const GrB_Index m,
    const GrB_Index n,
    const GrB_Index *Tile_nrows,    // array of size m
    const GrB_Index *Tile_ncols,    // array of size n
    const GrB_Matrix A,             // input matrix to split
    const GrB_Descriptor desc       // unused, except threading control
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_split' does the opposite of \verb'GxB_Matrix_concat'.  It
splits a single input matrix \verb'A' into a 2D array of tiles.  On input, the
\verb'Tiles' array must be a non-\verb'NULL' pointer to a previously allocated
array of size at least \verb'm*n' where both \verb'm' and \verb'n' must be
greater than zero.  The \verb'Tiles_nrows' array has size \verb'm', and
\verb'Tiles_ncols' has size \verb'n'.  The $(i,j)$th tile has dimension
\verb'Tiles_nrows[i]'-by-\verb'Tiles_ncols[j]'.  The sum of
\verb'Tiles_nrows [0:m-1]' must equal the number of rows of \verb'A', and the
sum of \verb'Tiles_ncols [0:n-1]' must equal the number of columns of \verb'A'.
The type of each tile is the same as the type of \verb'A'; no typecasting is
done.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_diag:} construct a diagonal matrix}
%-------------------------------------------------------------------------------
\label{matrix_diag}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_diag    // construct a diagonal matrix from a vector
(
    GrB_Matrix *C,                  // output matrix
    const GrB_Vector v,             // input vector
    int64_t k
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_diag' constructs a matrix from a vector.  Let $n$ be the
length of the \verb'v' vector, from \verb'GrB_Vector_size (&n, v)'.  If
\verb'k' = 0, then \verb'C' is an $n$-by-$n$ diagonal matrix with the entries
from \verb'v' along the main diagonal of \verb'C', with \verb'C(i,i)=v(i)'.  If
\verb'k' is nonzero, \verb'C' is square with dimension $n+|k|$.  If \verb'k' is
positive, it denotes diagonals above the main diagonal, with
\verb'C(i,i+k)=v(i)'.
If \verb'k' is negative, it denotes diagonals below the main diagonal of
\verb'C', with \verb'C(i-k,i)=v(i)'.  This behavior is identical to the MATLAB
statement \verb'C=diag(v,k)', where \verb'v' is a vector.

The output matrix \verb'C' is a newly-constructed square matrix with the
same type as the input vector \verb'v'.  No typecasting is performed.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_diag:} build a diagonal matrix}
%-------------------------------------------------------------------------------
\label{matrix_diag_GxB}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_diag    // build a diagonal matrix from a vector
(
    GrB_Matrix C,                   // output matrix
    const GrB_Vector v,             // input vector
    int64_t k,
    const GrB_Descriptor desc       // unused, except threading control
) ;
\end{verbatim} } \end{mdframed}

Identical to \verb'GrB_Matrix_diag', except for the extra parameter
(a \verb'descriptor' to provide control over the number of threads used),
and this method is not a constructor.

The matrix \verb'C' must already exist on input, of the correct size.  It must
be square of dimension $n+|k|$ where the vector \verb'v' has length $n$.  Any
existing entries in \verb'C' are discarded.  The type of \verb'C' is preserved,
so that if the type of \verb'C' and \verb'v' differ, the entries are typecasted
into the type of \verb'C'.  Any settings made to \verb'C' by
\verb'GxB_Matrix_Option_set' (format by row or by column, bitmap switch, hyper
switch, and sparsity control) are unchanged.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_iso:} query iso status of a matrix}
%-------------------------------------------------------------------------------
\label{matrix_iso}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_iso     // return iso status of a matrix
(
    bool *iso,              // true if the matrix is iso-valued
    const GrB_Matrix A      // matrix to query
) ;
\end{verbatim} } \end{mdframed}

Returns the true if the matrix is iso-valued, false otherwise.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_memoryUsage:} memory used by a matrix}
%-------------------------------------------------------------------------------
\label{matrix_memusage}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_memoryUsage  // return # of bytes used for a matrix
(
    size_t *size,           // # of bytes used by the matrix A
    const GrB_Matrix A      // matrix to query
) ;
\end{verbatim} } \end{mdframed}

Returns the memory space required for a matrix, in bytes.

%-------------------------------------------------------------------------------
% \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.  Any
pending updates to the matrix are abandoned.

\newpage
%===============================================================================
\subsection{Serialize/deserialize methods}
%===============================================================================
\label{serialize_deserialize}

{\em Serialization} takes an opaque GraphBLAS object (a vector or matrix) and
encodes it in a single non-opaque array of bytes, the {\em blob}.  The blob can
only be deserialized by the same library that created it (SuiteSparse:GraphBLAS
in this case).  The array of bytes can be written to a file, sent to another
process over an MPI channel, or operated on in any other way that moves the
bytes around.  The contents of the array cannot be interpreted except by
deserialization back into a vector or matrix, by the same library (and
sometimes the same version) that created the blob.  Currently, all versions of
SuiteSparse:GraphBLAS that implement serialization/deserialization use the same
format for the blob, so the library versions are compatible with each other.

There are two forms of serialization: \verb'GrB*serialize' and
\verb'GxB*serialize'.  For the \verb'GrB' form, the blob must first be
allocated by the user application, and it must be large enough to hold the
matrix or vector.

By default, ZSTD (level 1) compression is used for serialization, but other
options can be selected via the descriptor:
\verb'GxB_set (desc, GxB_COMPRESSION, method)', where \verb'method' is an
integer selected from the following options:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
method                           &  description \\
\hline
\verb'GxB_COMPRESSION_NONE'      &  no compression \\
\verb'GxB_COMPRESSION_DEFAULT'   &  ZSTD, with default level 1 \\
\verb'GxB_COMPRESSION_LZ4'       &  LZ4 \\
\verb'GxB_COMPRESSION_LZ4HC'     &  LZ4HC, with default level 9 \\
\verb'GxB_COMPRESSION_ZSTD'      &  ZSTD, with default level 1 \\
\hline
\end{tabular} }
\vspace{0.2in}

The LZ4HC method can be modified by adding a level of zero to 9, with 9 being
the default.  Higher levels lead to a more compact blob, at the cost of extra
computational time. This level is simply added to the method, so to compress a
vector with LZ4HC with level 6, use:

    {\footnotesize
    \begin{verbatim}
    GxB_set (desc, GxB_COMPRESSION, GxB_COMPRESSION_LZ4HC + 6) ; \end{verbatim}}

The ZSTD method can be specified as level 1 to 19, with 1 being the default.
To compress with ZSTD at level 6, use:

    {\footnotesize
    \begin{verbatim}
    GxB_set (desc, GxB_COMPRESSION, GxB_COMPRESSION_ZSTD + 6) ; \end{verbatim}}

Deserialization of untrusted data is a common security problem; see
\url{https://cwe.mitre.org/data/definitions/502.html}. The deserialization
methods do a few basic checks so that no out-of-bounds access occurs during
deserialization, but the output matrix or vector itself may still be corrupted.
If the data is untrusted, use \verb'GxB_*_fprint' to
check the matrix or vector after deserializing it:

{\footnotesize
\begin{verbatim}
    info = GxB_Vector_fprint (w, "w deserialized", GrB_SILENT, NULL) ;
    if (info != GrB_SUCCESS) GrB_free (&w) ;
    info = GxB_Matrix_fprint (A, "A deserialized", GrB_SILENT, NULL) ;
    if (info != GrB_SUCCESS) GrB_free (&A) ; \end{verbatim}}

The following methods are described in this Section:

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
% \verb'GrB_Vector_serializeSize'  & return size of serialized vector & \ref{vector_serialize_size} \\
% \verb'GrB_Vector_serialize'      & serialize a vector               & \ref{vector_serialize} \\
\verb'GxB_Vector_serialize'      & serialize a vector               & \ref{vector_serialize_GxB} \\
% \verb'GrB_Vector_deserialize'    & deserialize a vector             & \ref{vector_deserialize} \\
\verb'GxB_Vector_deserialize'    & deserialize a vector             & \ref{vector_deserialize_GxB} \\
\hline
\verb'GrB_Matrix_serializeSize' & return size of serialized matrix & \ref{matrix_serialize_size} \\
\verb'GrB_Matrix_serialize'     & serialize a matrix               & \ref{matrix_serialize} \\
\verb'GxB_Matrix_serialize'     & serialize a matrix               & \ref{matrix_serialize_GxB} \\
\verb'GrB_Matrix_deserialize'   & deserialize a matrix             & \ref{matrix_deserialize} \\
\verb'GxB_Matrix_deserialize'   & deserialize a matrix             & \ref{matrix_deserialize_GxB} \\
\hline
\verb'GrB_deserialize_type_name' & return the name of type of the blob & \ref{deserialize_type_name} \\
\hline
\end{tabular}
}

%-------------------------------------------------------------------------------
% \subsubsection{{\sf GrB\_Vector\_serializeSize:}  return size of serialized vector}
%-------------------------------------------------------------------------------
% \label{vector_serialize_size}

% \begin{mdframed}[userdefinedwidth=6in]
% {\footnotesize
% \begin{verbatim}
% GrB_Info GrB_Vector_serializeSize   // estimate the size of a blob
% (
%    // output:
%    GrB_Index *blob_size_handle,    // upper bound on the required size of the
%                                    // blob on output.
%    // input:
%    GrB_Vector u                    // vector to serialize
%) ;
%\end{verbatim}
%} \end{mdframed}
% 
% \verb'GrB_Vector_serializeSize' returns an upper bound on the size of the blob
% needed to serialize a \verb'GrB_Vector' using \verb'GrB_Vector_serialize'.
% After the vector is serialized, the actual size used is returned, and the blob
% may be \verb'realloc''d to that size if desired.
% This method is not required for \verb'GxB_Vector_serialize'.

% \newpage
%-------------------------------------------------------------------------------
% \subsubsection{{\sf GrB\_Vector\_serialize:}      serialize a vector}
%-------------------------------------------------------------------------------
% \label{vector_serialize}

% \begin{mdframed}[userdefinedwidth=6in]
% {\footnotesize
% \begin{verbatim}
% GrB_Info GrB_Vector_serialize       // serialize a GrB_Vector to a blob
% (
%    // output:
%    void *blob,                     // the blob, already allocated in input
%    // input/output:
%    GrB_Index *blob_size_handle,    // size of the blob on input.  On output,
%                                    // the # of bytes used in the blob.
%    // input:
%    GrB_Vector u                    // vector to serialize
% ) ;
% \end{verbatim}
% } \end{mdframed}
%
% \verb'GrB_Vector_serialize' serializes a vector into a single array of bytes
% (the blob), which must be already allocated by the user application.
% On input, \verb'&blob_size' is the size of the allocated blob in bytes.
% On output, it is reduced to the numbed of bytes actually used to serialize
% the vector.  After calling \verb'GrB_Vector_serialize', the blob may be
% \verb'realloc''d to this revised size if desired (this is optional).
% ZSTD (level 1) compression is used to construct a compact blob.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_serialize:}      serialize a vector}
%-------------------------------------------------------------------------------
\label{vector_serialize_GxB}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_serialize       // serialize a GrB_Vector to a blob
(
    // output:
    void **blob_handle,             // the blob, allocated on output
    GrB_Index *blob_size_handle,    // size of the blob on output
    // input:
    GrB_Vector u,                   // vector to serialize
    const GrB_Descriptor desc       // descriptor to select compression method
                                    // and to control # of threads used
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Vector_serialize' serializes a vector into a single array of bytes
(the blob), which is \verb'malloc''ed and filled with the serialized vector.
By default, ZSTD (level 1) compression is used, but other options can be
selected via the descriptor.  Serializing a vector is identical to serializing
a matrix; see Section \ref{matrix_serialize_GxB} for more information.

\newpage
%-------------------------------------------------------------------------------
% \subsubsection{{\sf GrB\_Vector\_deserialize:}    deserialize a vector}
%-------------------------------------------------------------------------------
% \label{vector_deserialize}

% \begin{mdframed}[userdefinedwidth=6in]
% {\footnotesize
% \begin{verbatim}
% GrB_Info GrB_Vector_deserialize     // deserialize blob into a GrB_Vector
% (
%     // output:
%     GrB_Vector *w,      // output vector created from the blob
%     // input:
%     GrB_Type type,      // type of the vector w.  Required if the blob holds a
%                         // vector of user-defined type.  May be NULL if blob
%                         // holds a built-in type; otherwise must match the
%                         // type of w.
%     const void *blob,       // the blob
%     GrB_Index blob_size     // size of the blob
% ) ;
% \end{verbatim}
% } \end{mdframed}
% 
% This method creates a vector \verb'w' by deserializing the contents of the
% blob, constructed by either \verb'GrB_Vector_serialize' or
% \verb'GxB_Vector_serialize'.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_deserialize:}    deserialize a vector}
%-------------------------------------------------------------------------------
\label{vector_deserialize_GxB}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_deserialize     // deserialize blob into a GrB_Vector
(
    // output:
    GrB_Vector *w,      // output vector created from the blob
    // input:
    GrB_Type type,      // type of the vector w.  See GxB_Matrix_deserialize.
    const void *blob,       // the blob
    GrB_Index blob_size,    // size of the blob
    const GrB_Descriptor desc       // to control # of threads used
) ;
\end{verbatim}
} \end{mdframed}

This method creates a vector \verb'w' by deserializing the contents of the
blob, constructed by
% either \verb'GrB_Vector_serialize' or
\verb'GxB_Vector_serialize'.
Deserializing a vector is identical to deserializing a matrix;
see Section \ref{matrix_deserialize_GxB} for more information.

The blob is allocated with the \verb'malloc' function passed to
\verb'GxB_init', or the ANSI C11 \verb'malloc' if \verb'GrB_init' was used
to initialize GraphBLAS.  The blob must be freed by the matching \verb'free'
method, either the \verb'free' function passed to \verb'GxB_init' or
the ANSI C11 \verb'free' if \verb'GrB_init' was used.

% Identical to \verb'GrB_Vector_deserialize', except that the descriptor
% appears as the last parameter to control the number of threads used.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_serializeSize:}  return size of serialized matrix}
%-------------------------------------------------------------------------------
\label{matrix_serialize_size}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_serializeSize   // estimate the size of a blob
(
    // output:
    GrB_Index *blob_size_handle,    // upper bound on the required size of the
                                    // blob on output.
    // input:
    GrB_Matrix A                    // matrix to serialize
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Matrix_serializeSize' returns an upper bound on the size of the blob
needed to serialize a \verb'GrB_Matrix' with \verb'GrB_Matrix_serialize'.
After the matrix is serialized, the actual size used is returned, and the blob
may be \verb'realloc''d to that size if desired.
This method is not required for \verb'GxB_Matrix_serialize'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_serialize:}      serialize a matrix}
%-------------------------------------------------------------------------------
\label{matrix_serialize}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_serialize       // serialize a GrB_Matrix to a blob
(
    // output:
    void *blob,                     // the blob, already allocated in input
    // input/output:
    GrB_Index *blob_size_handle,    // size of the blob on input.  On output,
                                    // the # of bytes used in the blob.
    // input:
    GrB_Matrix A                    // matrix to serialize
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Matrix_serialize' serializes a matrix into a single array of bytes
(the blob), which must be already allocated by the user application.
On input, \verb'&blob_size' is the size of the allocated blob in bytes.
On output, it is reduced to the numbed of bytes actually used to serialize
the matrix.  After calling \verb'GrB_Matrix_serialize', the blob may be
\verb'realloc''d to this revised size if desired (this is optional).
ZSTD (level 1) compression is used to construct a compact blob.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_serialize:}      serialize a matrix}
%-------------------------------------------------------------------------------
\label{matrix_serialize_GxB}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_serialize       // serialize a GrB_Matrix to a blob
(
    // output:
    void **blob_handle,             // the blob, allocated on output
    GrB_Index *blob_size_handle,    // size of the blob on output
    // input:
    GrB_Matrix A,                   // matrix to serialize
    const GrB_Descriptor desc       // descriptor to select compression method
                                    // and to control # of threads used
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_serialize' is identical to \verb'GrB_Matrix_serialize', except
that it does not require a pre-allocated blob.  Instead, it allocates the blob
internally, and fills it with the serialized matrix.  By default, ZSTD (level 1)
compression is used, but other options can be selected via the descriptor.

The blob is allocated with the \verb'malloc' function passed to
\verb'GxB_init', or the ANSI C11 \verb'malloc' if \verb'GrB_init' was used
to initialize GraphBLAS.  The blob must be freed by the matching \verb'free'
method, either the \verb'free' function passed to \verb'GxB_init' or
the ANSI C11 \verb'free' if \verb'GrB_init' was used.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_deserialize:}    deserialize a matrix}
%-------------------------------------------------------------------------------
\label{matrix_deserialize}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_deserialize     // deserialize blob into a GrB_Matrix
(
    // output:
    GrB_Matrix *C,      // output matrix created from the blob
    // input:
    GrB_Type type,      // type of the matrix C.  Required if the blob holds a
                        // matrix of user-defined type.  May be NULL if blob
                        // holds a built-in type; otherwise must match the
                        // type of C.
    const void *blob,       // the blob
    GrB_Index blob_size     // size of the blob
) ;
\end{verbatim}
} \end{mdframed}

This method creates a matrix \verb'A' by deserializing the contents of the
blob, constructed by either \verb'GrB_Matrix_serialize' or
\verb'GxB_Matrix_serialize'.

\begin{alert}
{\bf SPEC:} The specification requires the \verb'type' to always be non-NULL.
As an extension, SuiteSparse:GraphBLAS allows \verb'type' to be NULL if
the blob contains a serialized matrix with a built-in type.
\end{alert}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_deserialize:}    deserialize a matrix}
%-------------------------------------------------------------------------------
\label{matrix_deserialize_GxB}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_deserialize     // deserialize blob into a GrB_Matrix
(
    // output:
    GrB_Matrix *C,      // output matrix created from the blob
    // input:
    GrB_Type type,      // type of the matrix C.  Required if the blob holds a
                        // matrix of user-defined type.  May be NULL if blob
                        // holds a built-in type; otherwise must match the
                        // type of C.
    const void *blob,       // the blob
    GrB_Index blob_size,    // size of the blob
    const GrB_Descriptor desc       // to control # of threads used
) ;
\end{verbatim}
} \end{mdframed}

Identical to \verb'GrB_Matrix_deserialize', except that the descriptor
appears as the last parameter to control the number of threads used.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_deserialize\_type\_name:} name of the type of a blob}
%-------------------------------------------------------------------------------
\label{deserialize_type_name}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_deserialize_type_name  // return the type name of a blob
(
    // output:
    char *type_name,        // name of the type (char array of size at least
                            // GxB_MAX_NAME_LEN, owned by the user application).
    // input, not modified:
    const void *blob,       // the blob
    GrB_Index blob_size     // size of the blob
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_deserialize_type_name' returns the name of type of the matrix or
vector serialized into the blob.  This method works for any blob, from
% \verb'GrB_Vector_serialize',
\verb'GxB_Vector_serialize',
\verb'GrB_Matrix_serialize', or \verb'GxB_Matrix_serialize'.

\newpage
%===============================================================================
\subsection{GraphBLAS pack/unpack: using move semantics} %========
%===============================================================================
\label{pack_unpack}

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

The \verb'GrB_Matrix_import' and \verb'GrB_Matrix_export' are not
described in this section.  Refer to Section~\ref{GrB_import_export} instead.

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

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

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

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

The \verb'GxB*unpack*' of a \verb'GrB_Matrix' or \verb'GrB_Vector' is symmetric with the
pack operation.  The unpack changes the ownership of the arrays, which are
returned to the user and which contain the
matrix or vector in the requested format.  Ownership of these arrays is given
to the user application, which is then responsible for freeing them via the
ANSI C \verb'free' function (by default), or by the \verb'free_function' that
was passed in to \verb'GxB_init'.  Alternatively, these arrays can be
re-packed into a \verb'GrB_Matrix' or \verb'GrB_Vector', at which point they
again become the responsibility of GraphBLAS.

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

For the pack methods, the \verb'A' matrix/vector must already exist on input, and its contents are
populated with the new content, just like \verb'GrB_Matrix_build'.
For the unpack
methods, \verb'A' is passed in, and the matrix/vector still exists on return,
just with no entries.  Its type and dimensions are preserved.

Unpacking a matrix or vector forces completion of any pending
operations on the matrix, with one exception.  SuiteSparse:GraphBLAS supports
three kinds of pending operations: {\em zombies} (pending deletions), {\em
pending tuples} (pending insertions), and a {\em lazy sort}.  Zombies and
pending tuples are never unpacked, but the {\em jumbled} state may be
optionally unpacked.  In the latter, if the matrix or vector is unpacked in a
{\em jumbled} state, indices in any row or column may appear out of order.  If
unpacked as {\em unjumbled}, the indices always appear in ascending order.

The vector pack/unpack methods use three formats for a
\verb'GrB_Vector'.  Eight different formats are provided for the
pack/unpack of a \verb'GrB_Matrix'.  For each format, the
numerical value array (\verb'Ax' or \verb'vx') has a C type corresponding to
one of the 13 built-in types in GraphBLAS (\verb'bool', \verb'int*_t',
\verb'uint*_t', \verb'float', \verb'double' \verb'float complex', \verb'double complex'),
or that corresponds with the user-defined type.  No typecasting is
done.

If \verb'iso' is true, then all entries present in the matrix or vector
have the same value, and the \verb'Ax' array (for matrices) or \verb'vx' array
(for vectors) only need to be large enough to hold a single value.

The unpack of a \verb'GrB_Vector' in \verb'CSC' format may return the
indices in a jumbled state, in any order.
For a \verb'GrB_Matrix' in \verb'CSR' or \verb'HyperCSR' format, if the matrix
is returned as jumbled, the column indices in any given row may appear out of
order.  For \verb'CSC' or \verb'HyperCSC' formats, if the matrix is returned as
jumbled, the row indices in any given column may appear out of order.

On pack, if the user-provided arrays contain jumbled row or column vectors,
then the input flag \verb'jumbled' must be passed in as \verb'true'.  On
unpack, if \verb'*jumbled' is \verb'NULL', this indicates to the unpack method
that the user expects the unpacked matrix or vector to be returned in an
ordered, unjumbled state.  If \verb'*jumbled' is provided as non-\verb'NULL',
then it is returned as \verb'true' if the indices may appear out of order, or
\verb'false' if they are known to be in ascending order.

Matrices and vectors in bitmap or full format are never jumbled.

If data is packed using
\verb'GxB*_pack_*', the default is to trust the input data so that the
pack can be done in $O(1)$ time.  However, if the data comes from an
untrusted source, additional checks should be made during the pack.  This is
indicated with a descriptor setting, and then passing the descriptor
to the \verb'GxB' pack methods:

    {\footnotesize
    \begin{verbatim}
    GxB_set (desc, GxB_IMPORT, GxB_SECURE_IMPORT) ; \end{verbatim}}

The table below lists the methods presented in this section.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
method & purpose & Section \\
\hline
\verb'GxB_Vector_pack_CSC'       & pack a vector in CSC format & \ref{vector_pack_csc} \\
\verb'GxB_Vector_unpack_CSC'     & unpack a vector in CSC format & \ref{vector_unpack_csc} \\
\hline
\verb'GxB_Vector_pack_Bitmap'    & pack a vector in bitmap format & \ref{vector_pack_bitmap} \\
\verb'GxB_Vector_unpack_Bitmap'  & unpack a vector in bitmap format & \ref{vector_unpack_bitmap} \\
\hline
\verb'GxB_Vector_pack_Full'      & pack a vector in full format & \ref{vector_pack_full} \\
\verb'GxB_Vector_unpack_Full'    & unpack a vector in full format & \ref{vector_unpack_full} \\
\hline
\hline
\verb'GxB_Matrix_pack_CSR'        & pack a matrix in CSR form & \ref{matrix_pack_csr} \\
\verb'GxB_Matrix_unpack_CSR'      & unpack a matrix in CSR form & \ref{matrix_unpack_csr} \\
\hline
\verb'GxB_Matrix_pack_CSC'        & pack a matrix in CSC form & \ref{matrix_pack_csc} \\
\verb'GxB_Matrix_unpack_CSC'      & unpack a matrix in CSC form & \ref{matrix_unpack_csc} \\
\hline
\verb'GxB_Matrix_pack_HyperCSR'   & pack a matrix in HyperCSR form & \ref{matrix_pack_hypercsr} \\
\verb'GxB_Matrix_unpack_HyperCSR' & unpack a matrix in HyperCSR form & \ref{matrix_unpack_hypercsr} \\
\hline
\verb'GxB_Matrix_pack_HyperCSC'   & pack a matrix in HyperCSC form & \ref{matrix_pack_hypercsc} \\
\verb'GxB_Matrix_unpack_HyperCSC' & unpack a matrix in HyperCSC form & \ref{matrix_unpack_hypercsc} \\
\hline
\verb'GxB_unpack_HyperHash' & unpack a hyper-hash & \ref{unpack_hyperhash} \\
\verb'GxB_pack_HyperHash'   & pack a hyper-hash & \ref{pack_hyperhash} \\
\hline
\verb'GxB_Matrix_pack_BitmapR'    & pack a matrix in BitmapR form & \ref{matrix_pack_bitmapr} \\
\verb'GxB_Matrix_unpack_BitmapR'  & unpack a matrix in BitmapR form & \ref{matrix_unpack_bitmapr} \\
\hline
\verb'GxB_Matrix_pack_BitmapC'    & pack a matrix in BitmapC form & \ref{matrix_pack_bitmapc} \\
\verb'GxB_Matrix_unpack_BitmapC'  & unpack a matrix in BitmapC form & \ref{matrix_unpack_bitmapc} \\
\hline
\verb'GxB_Matrix_pack_FullR'      & pack a matrix in FullR form & \ref{matrix_pack_fullr} \\
\verb'GxB_Matrix_unpack_FullR'    & unpack a matrix in FullR form & \ref{matrix_unpack_fullr} \\
\hline
\verb'GxB_Matrix_pack_FullC'      & pack a matrix in FullC form & \ref{matrix_pack_fullc} \\
\verb'GxB_Matrix_unpack_FullC'    & unpack a matrix in FullC form & \ref{matrix_unpack_fullc} \\
\hline
\end{tabular}
}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_pack\_CSC} pack a vector in CSC form}
%-------------------------------------------------------------------------------
\label{vector_pack_csc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_pack_CSC  // pack a vector in CSC format
(
    GrB_Vector v,       // vector to create (type and length unchanged)
    GrB_Index **vi,     // indices, vi_size >= nvals(v) * sizeof(int64_t)
    void **vx,          // values, vx_size >= nvals(v) * (type size)
                        // or vx_size >= (type size), if iso is true
    GrB_Index vi_size,  // size of vi in bytes
    GrB_Index vx_size,  // size of vx in bytes
    bool iso,           // if true, v is iso
    GrB_Index nvals,    // # of entries in vector
    bool jumbled,       // if true, indices may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\noindent
\verb'GxB_Vector_pack_CSC' is analogous to \verb'GxB_Matrix_pack_CSC'.
Refer to the description of \verb'GxB_Matrix_pack_CSC' for details
(Section~\ref{matrix_pack_csc}).

The vector \verb'v' must
exist on input with the right type and length.  No typecasting is done.
Its entries are
the row indices given by \verb'vi', with the corresponding values in \verb'vx'.
The two pointers \verb'vi' and \verb'vx' are returned as \verb'NULL', which
denotes that they are no longer owned by the user application.  They have
instead been moved into \verb'v'.  If \verb'jumbled'
is true, the row indices in \verb'vi' must appear in sorted order.  No
duplicates can appear.  These conditions are not checked, so results are
undefined if they are not met exactly.  The user application can check the
resulting vector \verb'v' with \verb'GxB_print', if desired, which will
determine if these conditions hold.

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_unpack\_CSC:} unpack a vector in CSC form}
%-------------------------------------------------------------------------------
\label{vector_unpack_csc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_unpack_CSC  // unpack a CSC vector
(
    GrB_Vector v,       // vector to unpack (type and length unchanged)
    GrB_Index **vi,     // indices
    void **vx,          // values
    GrB_Index *vi_size, // size of vi in bytes
    GrB_Index *vx_size, // size of vx in bytes
    bool *iso,          // if true, v is iso
    GrB_Index *nvals,   // # of entries in vector
    bool *jumbled,      // if true, indices may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Vector_unpack_CSC' is analogous to \verb'GxB_Matrix_unpack_CSC'.
Refer to the description of \verb'GxB_Matrix_unpack_CSC' for details
(Section~\ref{matrix_unpack_csc}).

Exporting a vector forces completion of any pending operations on the vector,
except that indices may be unpacked out of order (\verb'jumbled' is \verb'true'
if they may be out of order, \verb'false' if sorted in ascending order).  If
\verb'jumbled' is \verb'NULL' on input, then the indices are always returned in
sorted order.

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

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_pack\_Bitmap} pack a vector in bitmap form}
%-------------------------------------------------------------------------------
\label{vector_pack_bitmap}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_pack_Bitmap // pack a bitmap vector
(
    GrB_Vector v,       // vector to create (type and length unchanged)
    int8_t **vb,        // bitmap, vb_size >= n
    void **vx,          // values, vx_size >= n * (type size)
                        // or vx_size >= (type size), if iso is true
    GrB_Index vb_size,  // size of vb in bytes
    GrB_Index vx_size,  // size of vx in bytes
    bool iso,           // if true, v is iso
    GrB_Index nvals,    // # of entries in bitmap
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\noindent
\verb'GxB_Vector_pack_Bitmap' is analogous to
\verb'GxB_Matrix_pack_BitmapC'.  Refer to the description of
\verb'GxB_Matrix_pack_BitmapC' for details
(Section~\ref{matrix_pack_bitmapc}).

The vector \verb'v' must
exist on input with the right type and length.  No typecasting is done.
Its entries are determined by \verb'vb', where \verb'vb[i]=1' denotes that
the entry $v(i)$ is present with value given by \verb'vx[i]', and
\verb'vb[i]=0' denotes that the entry $v(i)$ is not present (\verb'vx[i]' is
ignored in this case).

The two pointers \verb'vb' and \verb'vx' are returned as \verb'NULL', which
denotes that they are no longer owned by the user application.  They have
instead been moved into the new \verb'GrB_Vector' \verb'v'.

The \verb'vb' array must not hold any values other than 0 and 1.  The value
\verb'nvals' must exactly match the number of 1s in the \verb'vb' array.  These
conditions are not checked, so results are undefined if they are not met
exactly.  The user application can check the resulting vector \verb'v' with
\verb'GxB_print', if desired, which will determine if these conditions hold.

If not successful, \verb'v', \verb'vb' and
\verb'vx' are not modified.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_unpack\_Bitmap:} unpack a vector in bitmap form}
%-------------------------------------------------------------------------------
\label{vector_unpack_bitmap}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_unpack_Bitmap   // unpack a bitmap vector
(
    GrB_Vector v,       // vector to unpack (type and length unchanged)
    int8_t **vb,        // bitmap
    void **vx,          // values
    GrB_Index *vb_size, // size of vb in bytes
    GrB_Index *vx_size, // size of vx in bytes
    bool *iso,          // if true, v is iso
    GrB_Index *nvals,    // # of entries in bitmap
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Vector_unpack_Bitmap' is analogous to
\verb'GxB_Matrix_unpack_BitmapC'; see
Section~\ref{matrix_unpack_bitmapc}.
Exporting a vector forces completion of any pending operations on the vector.
If successful, \verb'v' is returned with no entries, and its contents are
returned to the user.
The entries that were in \verb'v' are returned in
\verb'vb', where \verb'vb[i]=1' means $v(i)$ is present with value
\verb'vx[i]', and \verb'vb[i]=0' means $v(i)$ is not present (\verb'vx[i]' is
undefined in this case).  The corresponding numerical values are returned in
\verb'vx'.

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_pack\_Full} pack a vector in full form}
%-------------------------------------------------------------------------------
\label{vector_pack_full}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_pack_Full // pack a full vector
(
    GrB_Vector v,       // vector to create (type and length unchanged)
    void **vx,          // values, vx_size >= nvals(v) * (type size)
                        // or vx_size >= (type size), if iso is true
    GrB_Index vx_size,  // size of vx in bytes
    bool iso,           // if true, v is iso
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\noindent
\verb'GxB_Vector_pack_Full' is analogous to \verb'GxB_Matrix_pack_FullC'.
Refer to the description of \verb'GxB_Matrix_pack_BitmapC' for details
(Section~\ref{matrix_pack_fullc}).
The vector \verb'v' must exist on input with the right type and length.
No typecasting is done.
If successful, \verb'v' has
all entries are present, and the value of $v(i)$ is given by \verb'vx[i]'.
The pointer \verb'vx' is returned as \verb'NULL', which denotes that it is no
longer owned by the user application.  It has instead been moved into the new
\verb'GrB_Vector' \verb'v'.
If not successful, \verb'v' and
\verb'vx' are not modified.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_unpack\_Full:} unpack a vector in full form}
%-------------------------------------------------------------------------------
\label{vector_unpack_full}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_unpack_Full   // unpack a full vector
(
    GrB_Vector v,       // vector to unpack (type and length unchanged)
    void **vx,          // values
    GrB_Index *vx_size, // size of vx in bytes
    bool *iso,          // if true, v is iso
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Vector_unpack_Full' is analogous to \verb'GxB_Matrix_unpack_FullC'.
Refer to the description of \verb'GxB_Matrix_unpack_FullC' for details
(Section~\ref{matrix_unpack_fullc}).
Exporting a vector forces completion of any pending operations on the vector.
All entries in \verb'v' must be present.  In other words, prior to the unpack,
\verb'GrB_Vector_nvals' for a vector of length \verb'n' must report that the
vector contains \verb'n' entries; \verb'GrB_INVALID_VALUE' is returned if this
condition does not hold.
If successful, \verb'v' is returned with no entries, and its contents are
returned to the user. The entries
that were in \verb'v' are returned in the array \verb'vx', \verb'vb', where
\verb'vb[i]=1' means $v(i)$ is present with value where the value of $v(i)$ is
\verb'vx[i]'.
If not successful, \verb'v' and \verb'vx' are not modified.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_pack\_CSR:} pack a CSR matrix}
%-------------------------------------------------------------------------------
\label{matrix_pack_csr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_pack_CSR      // pack a CSR matrix
(
    GrB_Matrix A,       // matrix to create (type, nrows, ncols unchanged)
    GrB_Index **Ap,     // row "pointers", Ap_size >= (nrows+1)* sizeof(int64_t)
    GrB_Index **Aj,     // column indices, Aj_size >= nvals(A) * sizeof(int64_t)
    void **Ax,          // values, Ax_size >= nvals(A) * (type size)
                        // or Ax_size >= (type size), if iso is true
    GrB_Index Ap_size,  // size of Ap in bytes
    GrB_Index Aj_size,  // size of Aj in bytes
    GrB_Index Ax_size,  // size of Ax in bytes
    bool iso,           // if true, A is iso
    bool jumbled,       // if true, indices in each row may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_pack_CSR' packs a matrix from 3 user arrays in CSR format.
In the resulting \verb'GrB_Matrix A', the \verb'CSR' format is a sparse matrix
with a format (\verb'GxB_FORMAT') of \verb'GxB_BY_ROW'.

The \verb'GrB_Matrix A' must exist on input with the right type and
dimensions.  No typecasting is done.

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

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

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

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

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

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

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

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

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

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

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

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

To iterate over the rows and entries of this matrix, the following code can be
used
(assuming it has type \verb'GrB_FP64'):

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

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

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_unpack\_CSR:} unpack a CSR matrix}
%-------------------------------------------------------------------------------
\label{matrix_unpack_csr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_unpack_CSR  // unpack a CSR matrix
(
    GrB_Matrix A,       // matrix to unpack (type, nrows, ncols unchanged)
    GrB_Index **Ap,     // row "pointers"
    GrB_Index **Aj,     // column indices
    void **Ax,          // values
    GrB_Index *Ap_size, // size of Ap in bytes
    GrB_Index *Aj_size, // size of Aj in bytes
    GrB_Index *Ax_size, // size of Ax in bytes
    bool *iso,          // if true, A is iso
    bool *jumbled,      // if true, indices in each row may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_unpack_CSR' unpacks a matrix in CSR form.

If successful, the \verb'GrB_Matrix A' is returned with no entries.
The CSR format is in the three arrays
\verb'Ap', \verb'Aj', and \verb'Ax'.  If the matrix has no entries, the
\verb'Aj' and \verb'Ax' arrays may be returned as \verb'NULL'; this is not an
error, and \verb'GxB_Matrix_pack_CSR' also allows these two arrays to be
\verb'NULL' on input when the matrix has no entries.  After a successful
unpack, the user application is responsible for freeing these three arrays via
\verb'free' (or the \verb'free' function passed to \verb'GxB_init').  The CSR
format is described in Section~\ref{matrix_unpack_csr}.

If \verb'jumbled' is returned as \verb'false', column indices will appear in
ascending order within each row.  If \verb'jumbled' is returned as \verb'true',
column indices may appear in any order within each row.  If \verb'jumbled' is
passed in as \verb'NULL', then column indices will be returned in ascending
order in each row.  No duplicate column indices will appear in any row.
\verb'Ap [0]' is zero, and \verb'Ap [nrows]' is equal to the number of entries
in the matrix (\verb'nvals').  The \verb'Ap' array will be of size
\verb'nrows'+1 (or larger), and the \verb'Aj' and \verb'Ax' arrays will have
size at least \verb'nvals'.

This method takes $O(1)$ time if the matrix is already in CSR format
internally.  Otherwise, the matrix is converted to CSR format and then
unpacked.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_pack\_CSC:} pack a CSC matrix}
%-------------------------------------------------------------------------------
\label{matrix_pack_csc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_pack_CSC      // pack a CSC matrix
(
    GrB_Matrix A,       // matrix to create (type, nrows, ncols unchanged)
    GrB_Index **Ap,     // col "pointers", Ap_size >= (ncols+1)*sizeof(int64_t)
    GrB_Index **Ai,     // row indices, Ai_size >= nvals(A)*sizeof(int64_t)
    void **Ax,          // values, Ax_size >= nvals(A) * (type size)
                        // or Ax_size >= (type size), if iso is true
    GrB_Index Ap_size,  // size of Ap in bytes
    GrB_Index Ai_size,  // size of Ai in bytes
    GrB_Index Ax_size,  // size of Ax in bytes
    bool iso,           // if true, A is iso
    bool jumbled,       // if true, indices in each column may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_pack_CSC' packs a matrix from 3 user arrays in CSC format.
The \verb'GrB_Matrix A' must exist on input with the right type and dimensions.
No typecasting is done.
The arguments are identical to
\verb'GxB_Matrix_pack_CSR', except for how the 3 user arrays are
interpreted.  The column ``pointer'' array has size \verb'ncols+1'.  The row
indices of the columns are in \verb'Ai', and if \verb'jumbled' is false,
they must appear in ascending order in
each column.  The corresponding numerical values are held in \verb'Ax'.  The
row indices of column \verb'j' are held in \verb'Ai [Ap [j]...Ap [j+1]-1]',
and the corresponding numerical values are in the same locations in \verb'Ax'.

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

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

is held in CSC form as follows:

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

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

To iterate over the columns and entries of this matrix, the following code can
be used
(assuming it has type \verb'GrB_FP64'):

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

The method is identical to \verb'GxB_Matrix_pack_CSR'; just the format is
transposed.

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_unpack\_CSC:} unpack a CSC matrix}
%-------------------------------------------------------------------------------
\label{matrix_unpack_csc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_unpack_CSC  // unpack a CSC matrix
(
    GrB_Matrix A,       // matrix to unpack (type, nrows, ncols unchanged)
    GrB_Index **Ap,     // column "pointers"
    GrB_Index **Ai,     // row indices
    void **Ax,          // values
    GrB_Index *Ap_size, // size of Ap in bytes
    GrB_Index *Ai_size, // size of Ai in bytes
    GrB_Index *Ax_size, // size of Ax in bytes
    bool *iso,          // if true, A is iso
    bool *jumbled,      // if true, indices in each column may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_unpack_CSC' unpacks a matrix in CSC form.

If successful, the \verb'GrB_Matrix A' is returned with no entries.
The CSC format is in the three arrays
\verb'Ap', \verb'Ai', and \verb'Ax'.  If the matrix has no entries, \verb'Ai'
and \verb'Ax' arrays are returned as \verb'NULL'; this is not an error, and
\verb'GxB_Matrix_pack_CSC' also allows these two arrays to be \verb'NULL' on
input when the matrix has no entries.  After a successful unpack, the user
application is responsible for freeing these three arrays via \verb'free' (or
the \verb'free' function passed to \verb'GxB_init').  The CSC format is
described in Section~\ref{matrix_unpack_csc}.

This method takes $O(1)$ time if the matrix is already in CSC format
internally.  Otherwise, the matrix is converted to CSC format and then
unpacked.


\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_pack\_HyperCSR:} pack a HyperCSR matrix}
%-------------------------------------------------------------------------------
\label{matrix_pack_hypercsr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_pack_HyperCSR      // pack a hypersparse CSR matrix
(
    GrB_Matrix A,       // matrix to create (type, nrows, ncols unchanged)
    GrB_Index **Ap,     // row "pointers", Ap_size >= (plen+1)*sizeof(int64_t)
    GrB_Index **Ah,     // row indices, Ah_size >= plen*sizeof(int64_t)
                        // where plen = 1 if nrows = 1, or nvec otherwise.
    GrB_Index **Aj,     // column indices, Aj_size >= nvals(A)*sizeof(int64_t)
    void **Ax,          // values, Ax_size >= nvals(A) * (type size)
                        // or Ax_size >= (type size), if iso is true
    GrB_Index Ap_size,  // size of Ap in bytes
    GrB_Index Ah_size,  // size of Ah in bytes
    GrB_Index Aj_size,  // size of Aj in bytes
    GrB_Index Ax_size,  // size of Ax in bytes
    bool iso,           // if true, A is iso
    GrB_Index nvec,     // number of rows that appear in Ah
    bool jumbled,       // if true, indices in each row may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_pack_HyperCSR' packs a matrix in hypersparse CSR format.
The hypersparse HyperCSR format is identical to the CSR format, except that the
\verb'Ap' array itself becomes sparse, if the matrix has rows that are
completely empty.  An array \verb'Ah' of size \verb'nvec' provides a list of
rows that appear in the data structure.  For example, consider
Equation~\ref{eqn:Ahyper}, which is a sparser version of the matrix in
Equation~\ref{eqn:Aexample}.  Row 2 and column 1 of this matrix are all zero.

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

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

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

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

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

Note that the \verb'Aj' and \verb'Ax' arrays are the same in the CSR and
HyperCSR formats.  If \verb'jumbled' is false, the row indices in \verb'Ah'
must appear in ascending order, and no duplicates can appear.  To iterate over
this data structure (assuming it has type \verb'GrB_FP64'):

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

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

The pack takes $O(1)$ time.  If successful, the four arrays \verb'Ah',
\verb'Ap', \verb'Aj', and \verb'Ax' are returned as \verb'NULL', and the
hypersparse \verb'GrB_Matrix A' is modified to contain the entries
they describe.

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_unpack\_HyperCSR:} unpack a HyperCSR matrix}
%-------------------------------------------------------------------------------
\label{matrix_unpack_hypercsr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_unpack_HyperCSR  // unpack a hypersparse CSR matrix
(
    GrB_Matrix A,       // matrix to unpack (type, nrows, ncols unchanged)
    GrB_Index **Ap,     // row "pointers"
    GrB_Index **Ah,     // row indices
    GrB_Index **Aj,     // column indices
    void **Ax,          // values
    GrB_Index *Ap_size, // size of Ap in bytes
    GrB_Index *Ah_size, // size of Ah in bytes
    GrB_Index *Aj_size, // size of Aj in bytes
    GrB_Index *Ax_size, // size of Ax in bytes
    bool *iso,          // if true, A is iso
    GrB_Index *nvec,    // number of rows that appear in Ah
    bool *jumbled,      // if true, indices in each row may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_unpack_HyperCSR' unpacks a matrix in HyperCSR format.

If successful, the \verb'GrB_Matrix A' is returned with no entries.
The number of non-empty rows is
\verb'nvec'.  The hypersparse CSR format is in the four arrays \verb'Ah',
\verb'Ap', \verb'Aj', and \verb'Ax'.  If the matrix has no entries, the
\verb'Aj' and \verb'Ax' arrays are returned as \verb'NULL'; this is not an
error.  After a successful unpack, the user application is responsible for
freeing these three arrays via \verb'free' (or the \verb'free' function passed
to \verb'GxB_init').  The hypersparse CSR format is described in
Section~\ref{matrix_pack_hypercsr}.

This method takes $O(1)$ time if the matrix is already in HyperCSR format
internally.  Otherwise, the matrix is converted to HyperCSR format and then
unpacked.

In v7.3.0 and later, a hypersparse matrix \verb'A' also may include a hash
table for \verb'Ah', called the {\em hyper-hash}, based on \cite{Green19}.  It
allows for fast lookups of entries in \verb'Ah'.  The hyper-hash is not
exported by this method.  Instead, it is discarded.  Use
\verb'GxB_unpack_HyperHash' (Section~\ref{unpack_hyperhash}) to preserve it,
prior to calling this method.  If the matrix is re-imported, and the hyper-hash
is not preserved, it is recomputed from \verb'Ah' when needed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_pack\_HyperCSC:} pack a HyperCSC matrix}
%-------------------------------------------------------------------------------
\label{matrix_pack_hypercsc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_pack_HyperCSC      // pack a hypersparse CSC matrix
(
    GrB_Matrix A,       // matrix to create (type, nrows, ncols unchanged)
    GrB_Index **Ap,     // col "pointers", Ap_size >= (plen+1)*sizeof(int64_t)
    GrB_Index **Ah,     // column indices, Ah_size >= plen*sizeof(int64_t)
                        // where plen = 1 if ncols = 1, or nvec otherwise.
    GrB_Index **Ai,     // row indices, Ai_size >= nvals(A)*sizeof(int64_t)
    void **Ax,          // values, Ax_size >= nvals(A)*(type size)
                        // or Ax_size >= (type size), if iso is true
    GrB_Index Ap_size,  // size of Ap in bytes
    GrB_Index Ah_size,  // size of Ah in bytes
    GrB_Index Ai_size,  // size of Ai in bytes
    GrB_Index Ax_size,  // size of Ax in bytes
    bool iso,           // if true, A is iso
    GrB_Index nvec,     // number of columns that appear in Ah
    bool jumbled,       // if true, indices in each column may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_pack_HyperCSC' packs a matrix in hypersparse CSC format.
It is identical to \verb'GxB_Matrix_pack_HyperCSR', except the data
structure defined by the four arrays \verb'Ah', \verb'Ap', \verb'Ai', and
\verb'Ax' holds the matrix as a sparse array of \verb'nvec' sparse column
vectors.  The following code iterates over the matrix,
assuming it has type \verb'GrB_FP64':

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_unpack\_HyperCSC:} unpack a HyperCSC matrix}
%-------------------------------------------------------------------------------
\label{matrix_unpack_hypercsc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_unpack_HyperCSC  // unpack a hypersparse CSC matrix
(
    GrB_Matrix A,       // matrix to unpack (type, nrows, ncols unchanged)
    GrB_Index **Ap,     // column "pointers"
    GrB_Index **Ah,     // column indices
    GrB_Index **Ai,     // row indices
    void **Ax,          // values
    GrB_Index *Ap_size, // size of Ap in bytes
    GrB_Index *Ah_size, // size of Ah in bytes
    GrB_Index *Ai_size, // size of Ai in bytes
    GrB_Index *Ax_size, // size of Ax in bytes
    bool *iso,          // if true, A is iso
    GrB_Index *nvec,    // number of columns that appear in Ah
    bool *jumbled,      // if true, indices in each column may be unsorted
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_unpack_HyperCSC' unpacks a matrix in HyperCSC form.

If successful, the \verb'GrB_Matrix A' is
returned with no entries.
The number of non-empty
rows is in \verb'nvec'.  The hypersparse CSC format is in the four arrays
\verb'Ah', \verb'Ap', \verb'Ai', and \verb'Ax'.  If the matrix has no entries,
the \verb'Ai' and \verb'Ax' arrays are returned as \verb'NULL'; this is not an
error.  After a successful unpack, the user application is responsible for
freeing these three arrays via \verb'free' (or the \verb'free' function passed
to \verb'GxB_init').  The hypersparse CSC format is described in
Section~\ref{matrix_pack_hypercsc}.

This method takes $O(1)$ time if the matrix is already in HyperCSC format
internally.  Otherwise, the matrix is converted to HyperCSC format and then
unpacked.

In v7.3.0 and later, a hypersparse matrix \verb'A' also may include a hash
table for \verb'Ah', called the {\em hyper-hash}, based on \cite{Green19}.  It
allows for fast lookups of entries in \verb'Ah'.  The hyper-hash is not
exported by this method.  Instead, it is discarded.  Use
\verb'GxB_unpack_HyperHash' (Section~\ref{unpack_hyperhash}) to preserve it,
prior to calling this method.  If the matrix is re-imported, and the hyper-hash
is not preserved, it is recomputed from \verb'Ah' when needed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_unpack\_HyperHash:} unpack the hypersparse hash}
%-------------------------------------------------------------------------------
\label{unpack_hyperhash}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_unpack_HyperHash       // move A->Y into Y
(
    GrB_Matrix A,                   // matrix to modify
    GrB_Matrix *Y,                  // hyper_hash matrix to move from A
    const GrB_Descriptor desc       // unused
) ;
\end{verbatim}
} \end{mdframed}


SuiteSparse:GraphBLAS v7.3.0 adds a new internal component to the
hypersparse matrix format: the {\em hyper-hash} \verb'GrB_Matrix' \verb'A->Y'.
The matrix provides a fast lookup into the hyperlist \verb'Ah'.

\verb'GxB_unpack_HyperHash' unpacks the hyper-hash from the hypersparse matrix
\verb'A'.  Normally, this method is called immediately before calling one of
the two methods \verb'GxB_Matrix_unpack_Hyper(CSR/CSC)'.  For example, to
unpack then pack a hypersparse CSC matrix:

    {\footnotesize
    \begin{verbatim}
    GrB_Matrix Y = NULL ;
    // to unpack all of A:
    GxB_unpack_HyperHash (A, &Y, desc) ;    // first unpack A->Y into Y
    GxB_Matrix_unpack_HyperCSC (A,          // then unpack the rest of A
        &Ap, &Ah, &Ai, &Ax, &Ap_size, &Ah_size, &Ai_size, &Ax_size,
        &iso, &nvec, &jumbled, descriptor) ;
    // use the unpacked contents of A here, but do not change Ah or nvec.
    ...
    // to pack the data back into A:
    GxB_Matrix_pack_HyperCSC (A, ...) ;     // pack most of A, except A->Y 
    GxB_pack_HyperHash (A, &Y, desc) ;      // then pack A->Y \end{verbatim}}

The same process is used with \verb'GxB_Matrix_unpack_HyperCSR'.

If \verb'A' is not hypersparse on input to \verb'GxB_unpack_HyperHash', or if
\verb'A' is hypersparse but does yet not have a hyper-hash, then \verb'Y' is
returned as \verb'NULL'.  This is not an error condition, and
\verb'GrB_SUCCESS' is returned.  The hyper-hash of a hypersparse matrix
\verb'A' is a matrix that provides quick access to the inverse of \verb'Ah'.
It is not always needed and may not be present.  It is left as pending work to
be computed when needed.  To ensure that the hyper-hash is constructed for a
hypersparse matrix \verb'A', use \verb'GrB_Matrix_wait (A, GrB_MATERIALIZE)' 

If \verb'Y' is moved from \verb'A' and returned as non-\verb'NULL' to the
caller, then it is the responsibility of the user application to free it, or to
re-pack it back into \verb'A' via \verb'GxB_pack_HyperHash', as shown in the
example above.

If this method is called to remove the hyper-hash \verb'Y' from the hypersparse
matrix \verb'A', and then \verb'GrB_Matrix_wait (A, GrB_MATERIALZE)' is called,
a new hyper-hash matrix is constructed for \verb'A'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_pack\_HyperHash:} pack the hypersparse hash}
%-------------------------------------------------------------------------------
\label{pack_hyperhash}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_pack_HyperHash         // move Y into A->Y
(
    GrB_Matrix A,                   // matrix to modify
    GrB_Matrix *Y,                  // hyper_hash matrix to pack into A
    const GrB_Descriptor desc       // unused
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_pack_HyperHash' assigns the input \verb'Y' matrix as the \verb'A->Y'
hyper-hash of the hypersparse matrix \verb'A'.  Normally, this method is called
immediately after calling one of the two methods
\verb'GxB_Matrix_pack_Hyper(CSR/CSC)'.

If \verb'A' is not hypersparse on input to \verb'GxB_pack_HyperHash', or if
\verb'A' already has a hyper-hash matrix, or if \verb'Y' is \verb'NULL' on
input, then nothing happens and \verb'Y' is unchanged.  This is not an error
condition and this method returns \verb'GrB_SUCCESS'.  In this case, if
\verb'Y' is non-\verb'NULL' after calling this method, it owned by the user
application and freeing it is the responsibility of the user application.

If \verb'Y' is moved into \verb'A' as its hyper-hash, then the caller's
\verb'Y' is set to \verb'NULL' to indicate that it has been moved into
\verb'A'.  It is no longer owned by the caller, but is instead becomes an
opaque component of the \verb'A' matrix.  It will be freed by
SuiteSparse:GraphBLAS if \verb'A' is modified or freed.

Results are undefined if the input \verb'Y' was not created by
\verb'GxB_unpack_HyperHash' (see the example in Section \ref{unpack_hyperhash})
or if the \verb'Ah' contents or \verb'nvec' of the matrix \verb'A' are modified
after they were unpacked by \verb'GxB_Matrix_unpack_Hyper(CSR/CSC)'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_pack\_BitmapR:} pack a BitmapR matrix}
%-------------------------------------------------------------------------------
\label{matrix_pack_bitmapr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_pack_BitmapR  // pack a bitmap matrix, held by row
(
    GrB_Matrix A,       // matrix to create (type, nrows, ncols unchanged)
    int8_t **Ab,        // bitmap, Ab_size >= nrows*ncols
    void **Ax,          // values, Ax_size >= nrows*ncols * (type size)
                        // or Ax_size >= (type size), if iso is true
    GrB_Index Ab_size,  // size of Ab in bytes
    GrB_Index Ax_size,  // size of Ax in bytes
    bool iso,           // if true, A is iso
    GrB_Index nvals,    // # of entries in bitmap
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_pack_BitmapR' packs a matrix from 2 user arrays in BitmapR
format.
The matrix must exist on input with the right type and dimensions.  No typecasting is done.

The \verb'GrB_Matrix' \verb'A' is populated from the arrays \verb'Ab' and
\verb'Ax', each of which are size \verb'nrows*ncols'.  Both arrays must have
been created with the ANSI C \verb'malloc', \verb'calloc', or \verb'realloc'
functions (by default), or by the corresponding \verb'malloc_function',
\verb'calloc_function', or \verb'realloc_function' provided to \verb'GxB_init'.
These arrays define the pattern and values of the new matrix \verb'A':

\begin{itemize}
\item \verb'int8_t Ab [nrows*ncols] ;'  The \verb'Ab' array defines which
entries of \verb'A' are present.  If \verb'Ab[i*ncols+j]=1', then the entry
$A(i,j)$ is present, with value \verb'Ax[i*ncols+j]'.  If
\verb'Ab[i*ncols+j]=0', then the entry $A(i,j)$ is not present.  The \verb'Ab'
array must contain only 0s and 1s.  The \verb'nvals' input must exactly match
the number of 1s in the \verb'Ab' array.

\item \verb'ctype Ax [nrows*ncols] ;'  The \verb'Ax' array defines the values
of entries in the matrix.  It is passed in as a \verb'(void *)' pointer, but it
must point to an array of size \verb'nrows*ncols' values, each of size
\verb'sizeof(ctype)', where \verb'ctype' is the exact type in C that
corresponds to the \verb'GrB_Type type' parameter.  That is, if \verb'type' is
\verb'GrB_INT32', then \verb'ctype' is \verb'int32_t'.  User types may be used,
just the same as built-in types.
If \verb'Ab[p]' is zero, the value of \verb'Ax[p]' is ignored.

\end{itemize}

To iterate over the rows and entries of this matrix, the following code can be
used (assuming it has type \verb'GrB_FP64'):

    {\footnotesize
    \begin{verbatim}
    for (int64_t i = 0 ; i < nrows ; i++)
    {
        // get A(i,:)
        for (int64_t j = 0 ; j < ncols ; j++)
        {
            // get A(i,j)
            int64_t p = i*ncols + j ;
            if (Ab [p])
            {
                double aij = Ax [iso ? 0 : p] ;   // numerical value
            }
        }
    } \end{verbatim}}

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

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_unpack\_BitmapR:} unpack a BitmapR matrix}
%-------------------------------------------------------------------------------
\label{matrix_unpack_bitmapr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_unpack_BitmapR  // unpack a bitmap matrix, by row
(
    GrB_Matrix A,       // matrix to unpack (type, nrows, ncols unchanged)
    int8_t **Ab,        // bitmap
    void **Ax,          // values
    GrB_Index *Ab_size, // size of Ab in bytes
    GrB_Index *Ax_size, // size of Ax in bytes
    bool *iso,          // if true, A is iso
    GrB_Index *nvals,   // # of entries in bitmap
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_unpack_BitmapR' unpacks a matrix in BitmapR form.
If successful, the \verb'GrB_Matrix A' is returned with no entries.
The number of entries is in \verb'nvals'.
The BitmapR format is two arrays \verb'Ab', and \verb'Ax'.  After an
unpack, the user application is responsible for freeing these
arrays via \verb'free' (or the \verb'free' function passed to \verb'GxB_init').
The BitmapR format is described in Section~\ref{matrix_pack_bitmapr}.
If \verb'Ab[p]' is zero, the value of \verb'Ax[p]' is undefined.
This method takes $O(1)$ time if the matrix is already in BitmapR format.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_pack\_BitmapC:} pack a BitmapC matrix}
%-------------------------------------------------------------------------------
\label{matrix_pack_bitmapc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_pack_BitmapC  // pack a bitmap matrix, held by column
(
    GrB_Matrix A,       // matrix to create (type, nrows, ncols unchanged)
    int8_t **Ab,        // bitmap, Ab_size >= nrows*ncols
    void **Ax,          // values, Ax_size >= nrows*ncols * (type size)
                        // or Ax_size >= (type size), if iso is true
    GrB_Index Ab_size,  // size of Ab in bytes
    GrB_Index Ax_size,  // size of Ax in bytes
    bool iso,           // if true, A is iso
    GrB_Index nvals,    // # of entries in bitmap
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_pack_BitmapC' packs a matrix from 2 user arrays in BitmapC
format.  It is identical to \verb'GxB_Matrix_pack_BitmapR', except that the
entry $A(i,j)$ is held in \verb'Ab[i+j*nrows]' and \verb'Ax[i+j*nrows]',
in column-major format.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_unpack\_BitmapC:} unpack a BitmapC matrix}
%-------------------------------------------------------------------------------
\label{matrix_unpack_bitmapc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_unpack_BitmapC  // unpack a bitmap matrix, by col
(
    GrB_Matrix A,       // matrix to unpack (type, nrows, ncols unchanged)
    int8_t **Ab,        // bitmap
    void **Ax,          // values
    GrB_Index *Ab_size, // size of Ab in bytes
    GrB_Index *Ax_size, // size of Ax in bytes
    bool *iso,          // if true, A is iso
    GrB_Index *nvals,   // # of entries in bitmap
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_unpack_BitmapC' unpacks a matrix in BitmapC form.
It is identical to \verb'GxB_Matrix_unpack_BitmapR', except that the
entry $A(i,j)$ is held in \verb'Ab[i+j*nrows]' and \verb'Ax[i+j*nrows]',
in column-major format.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_pack\_FullR:} pack a FullR matrix}
%-------------------------------------------------------------------------------
\label{matrix_pack_fullr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_pack_FullR  // pack a full matrix, held by row
(
    GrB_Matrix A,       // matrix to create (type, nrows, ncols unchanged)
    void **Ax,          // values, Ax_size >= nrows*ncols * (type size)
                        // or Ax_size >= (type size), if iso is true
    GrB_Index Ax_size,  // size of Ax in bytes
    bool iso,           // if true, A is iso
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_pack_FullR' packs a matrix from a user array in FullR format.
For the \verb'FullR' format, t value of $A(i,j)$ is \verb'Ax[i*ncols+j]'.  To
iterate over the rows and entries of this matrix, the following code can be
used (assuming it has type \verb'GrB_FP64').  If \verb'A' is both full and iso,
it takes $O(1)$ memory, regardless of \verb'nrows' and \verb'ncols'.

    \vspace{-0.1in}
    {\footnotesize
    \begin{verbatim}
    for (int64_t i = 0 ; i < nrows ; i++)
    {
        for (int64_t j = 0 ; j < ncols ; j++)
        {
            int64_t p = i*ncols + j ;
            double aij = Ax [iso ? 0 : p] ;   // numerical value of A(i,j)
        }
    } \end{verbatim}}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_unpack\_FullR:} unpack a FullR matrix}
%-------------------------------------------------------------------------------
\label{matrix_unpack_fullr}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_unpack_FullR  // unpack a full matrix, by row
(
    GrB_Matrix A,       // matrix to unpack (type, nrows, ncols unchanged)
    void **Ax,          // values
    GrB_Index *Ax_size, // size of Ax in bytes
    bool *iso,          // if true, A is iso
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_unpack_FullR' unpacks a matrix in FullR form.  It is identical
to \verb'GxB_Matrix_unpack_BitmapR', except that all entries must be present.
Prior to unpack, \verb'GrB_Matrix_nvals (&nvals, A)' must return
\verb'nvals' equal to \verb'nrows*ncols'.  Otherwise, if the \verb'A' is
unpacked with \newline \verb'GxB_Matrix_unpack_FullR', an error is returned
(\verb'GrB_INVALID_VALUE') and the matrix is not unpacked.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_pack\_FullC:} pack a FullC matrix}
%-------------------------------------------------------------------------------
\label{matrix_pack_fullc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_pack_FullC  // pack a full matrix, held by column
(
    GrB_Matrix A,       // matrix to create (type, nrows, ncols unchanged)
    void **Ax,          // values, Ax_size >= nrows*ncols * (type size)
                        // or Ax_size >= (type size), if iso is true
    GrB_Index Ax_size,  // size of Ax in bytes
    bool iso,           // if true, A is iso
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_pack_FullC' packs a matrix from a user arrays in FullC
format.  For the \verb'FullC' format,
the value of $A(i,j)$ is \verb'Ax[i+j*nrows]'.
To iterate over the rows and entries of this matrix, the following code can be
used (assuming it has type \verb'GrB_FP64').
If \verb'A' is both full and iso, it takes $O(1)$ memory,
regardless of \verb'nrows' and \verb'ncols'.

    \vspace{-0.1in}
    {\footnotesize
    \begin{verbatim}
    for (int64_t i = 0 ; i < nrows ; i++)
    {
        for (int64_t j = 0 ; j < ncols ; j++)
        {
            int64_t p = i + j*nrows ;
            double aij = Ax [iso ? 0 : p] ;   // numerical value of A(i,j)
        }
    } \end{verbatim}}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_unpack\_FullC:} unpack a FullC matrix}
%-------------------------------------------------------------------------------
\label{matrix_unpack_fullc}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_unpack_FullC  // unpack a full matrix, by column
(
    GrB_Matrix A,       // matrix to unpack (type, nrows, ncols unchanged)
    void **Ax,          // values
    GrB_Index *Ax_size, // size of Ax in bytes
    bool *iso,          // if true, A is iso
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_unpack_FullC' unpacks a matrix in FullC form.  It is identical
to \verb'GxB_Matrix_unpack_BitmapC', except that all entries must be present.
That is, prior to unpack, \verb'GrB_Matrix_nvals (&nvals, A)' must return
\verb'nvals' equal to \verb'nrows*ncols'.  Otherwise, if the \verb'A' is
unpacked with \newline \verb'GxB_Matrix_unpack_FullC', an error is returned
(\verb'GrB_INVALID_VALUE') and the matrix is not unpacked.

\newpage
%===============================================================================
\subsection{GraphBLAS import/export: using copy semantics} %====================
%===============================================================================
\label{GrB_import_export}

The v2.0 C API includes import/export methods for matrices (not vectors) using
a different strategy as compared to the \verb'GxB*pack/unpack*' methods.  The
\verb'GxB' methods are based on {\em move semantics}, in which ownership of
arrays is passed between SuiteSparse:GraphBLAS and the user application.  This
allows the \verb'GxB*pack/unpack*' methods to work in $O(1)$ time, and require
no additional memory, but it requires that GraphBLAS and the user application
agree on which memory manager to use.  This is done via \verb'GxB_init'.  This
allows GraphBLAS to \verb'malloc' an array that can be later \verb'free'd by
the user application, and visa versa.

The \verb'GrB' import/export methods take a different approach.  The data
is always copied in and out between the opaque GraphBLAS matrix and the
user arrays.  This takes $\Omega(e)$ time, if the matrix has $e$ entries,
and requires more memory.  It has the advantage that it does not require
GraphBLAS and the user application to agree on what memory manager to use,
since no ownership of allocated arrays is changed.

The format for \verb'GrB_Matrix_import' and \verb'GrB_Matrix_export' is
controlled by the following enum:

{\footnotesize
\begin{verbatim}
typedef enum
{
    GrB_CSR_FORMAT = 0,     // CSR format (equiv to GxB_SPARSE with GxB_BY_ROW)
    GrB_CSC_FORMAT = 1,     // CSC format (equiv to GxB_SPARSE with GxB_BY_COL)
    GrB_COO_FORMAT = 2      // triplet format (like input to GrB*build)
}
GrB_Format ; \end{verbatim}}

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_import:}  import a matrix}
%-------------------------------------------------------------------------------
\label{GrB_matrix_import}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_import  // import a matrix
(
    GrB_Matrix *A,          // handle of matrix to create
    GrB_Type type,          // type of matrix to create
    GrB_Index nrows,        // number of rows of the matrix
    GrB_Index ncols,        // number of columns of the matrix
    const GrB_Index *Ap,    // pointers for CSR, CSC, column indices for COO
    const GrB_Index *Ai,    // row indices for CSR, CSC
    const <type> *Ax,       // values
    GrB_Index Ap_len,       // number of entries in Ap (not # of bytes)
    GrB_Index Ai_len,       // number of entries in Ai (not # of bytes)
    GrB_Index Ax_len,       // number of entries in Ax (not # of bytes)
    GrB_Format format       // import format
) ;
\end{verbatim}
} \end{mdframed}

The \verb'GrB_Matrix_import' method copies from user-provided arrays into an
opaque \verb'GrB_Matrix' and \verb'GrB_Matrix_export' copies data out, from an
opaque \verb'GrB_Matrix' into user-provided arrays.

The suffix \verb'TYPE' in the prototype above is one of \verb'BOOL',
\verb'INT8', \verb'INT16', etc, for built-n types, or \verb'UDT' for
user-defined types.  The type of the \verb'Ax' array must match this type.  No
typecasting is performed.

Unlike the \verb'GxB'
pack/unpack methods, memory is not handed off between the user application
and GraphBLAS.   The three arrays \verb'Ap', \verb'Ai'.  and \verb'Ax' are not
modified, and are still owned by the user application when the method finishes.

The matrix can be imported in one of three different formats:

\begin{packed_itemize}
    \item \verb'GrB_CSR_FORMAT': % CSR format (equiv to GxB_SPARSE with GxB_BY_ROW)
        Compressed-row format.  \verb'Ap' is an array of size \verb'nrows+1'.
        The arrays \verb'Ai' and \verb'Ax' are of size \verb'nvals = Ap [nrows]',
        and \verb'Ap[0]' must be zero.
        The column indices of entries in the \verb'i'th row appear in
        \verb'Ai[Ap[i]...Ap[i+1]-1]', and the values of those entries appear in
        the same locations in \verb'Ax'.
        The column indices need not be in any particular order.

    \item \verb'GrB_CSC_FORMAT': % CSC format (equiv to GxB_SPARSE with GxB_BY_COL)
        Compressed-column format.  \verb'Ap' is an array of size \verb'ncols+1'.
        The arrays \verb'Ai' and \verb'Ax' are of size \verb'nvals = Ap [ncols]',
        and \verb'Ap[0]' must be zero.
        The row indices of entries in the \verb'j'th column appear in
        \verb'Ai[Ap[j]...Ap[j+1]-1]', and the values of those entries appear in
        the same locations in \verb'Ax'.
        The row indices need not be in any particular order.
        
    \item \verb'GrB_COO_FORMAT': % triplet format (like input to GrB*build)
        Coordinate format.  This is the same format as \newline
        \verb'GrB_Matrix_build'.
        The three arrays \verb'Ap', \verb'Ai', and \verb'Ax' have the same
        size.  The \verb'k'th tuple has row index \verb'Ai[k]',
        column index \verb'Ap[k]', and value \verb'Ax[k]'.  The tuples can
        appear any order, but no duplicates are permitted.

%   \item \verb'GrB_DENSE_ROW_FORMAT': % FullR format (GxB_FULL with GxB_BY_ROW)
%       Dense matrix format, held by row.  Only the \verb'Ax' array is used, of
%       size \verb'nrows*ncols'.
%       It holds the matrix in dense format, in row major order.
%
%   \item \verb'GrB_DENSE_COL_FORMAT': % FullC format (GxB_FULL with GxB_BY_ROW)
%       Dense matrix format, held by column.  Only the \verb'Ax' array is used, of
%       size \verb'nrows*ncols'.
%       It holds the matrix in dense format, in column major order.

\end{packed_itemize}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_export:}  export a matrix}
%-------------------------------------------------------------------------------
\label{GrB_matrix_export}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_export  // export a matrix
(
    GrB_Index *Ap,          // pointers for CSR, CSC, column indices for COO
    GrB_Index *Ai,          // col indices for CSR/COO, row indices for CSC
    <type> *Ax,             // values (must match the type of A_input)
    GrB_Index *Ap_len,      // number of entries in Ap (not # of bytes)
    GrB_Index *Ai_len,      // number of entries in Ai (not # of bytes)
    GrB_Index *Ax_len,      // number of entries in Ax (not # of bytes)
    GrB_Format format,      // export format
    GrB_Matrix A            // matrix to export
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_Matrix_export' copies the contents of a matrix into three
user-provided arrays, using any one of the three different formats
described in Section~\ref{GrB_matrix_import}.  The size of the arrays must be
at least as large as the lengths returned by \verb'GrB_Matrix_exportSize'.  The
matrix \verb'A' is not modified.

On input, the size of the three arrays \verb'Ap', \verb'Ai', and \verb'Ax' is
given by \verb'Ap_len', \verb'Ai_len', and \verb'Ax_len', respectively.  These
values are in terms of the number of entries in these arrays, not the number of
bytes.  On output, these three value are adjusted to report the number of
entries written to the three arrays.

The suffix \verb'TYPE' in the prototype above is one of \verb'BOOL',
\verb'INT8', \verb'INT16', etc, for built-n types, or \verb'UDT' for
user-defined types.  The type of the \verb'Ax' array must match this type.  No
typecasting is performed.

% The \verb'GrB_DENSE_ROW_FORMAT' and \verb'GrB_DENSE_COL_FORMAT' formats can
% only be used if all entries are present in the matrix.  That is,
% \verb'GrB_Matrix_nvals (&nvals,A)' must return \verb'nvals' equal to
% \verb'nrows*ncols'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_exportSize:} determine size of export}
%-------------------------------------------------------------------------------
\label{export_size}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_exportSize  // determine sizes of user arrays for export
(
    GrB_Index *Ap_len,      // # of entries required for Ap (not # of bytes)
    GrB_Index *Ai_len,      // # of entries required for Ai (not # of bytes)
    GrB_Index *Ax_len,      // # of entries required for Ax (not # of bytes)
    GrB_Format format,      // export format
    GrB_Matrix A            // matrix to export
) ;
\end{verbatim}
} \end{mdframed}

Returns the required sizes of the arrays \verb'Ap', \verb'Ai', and \verb'Ax'
for exporting a matrix using \verb'GrB_Matrix_export', using the same
\verb'format'.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_exportHint:} determine best export format}
%-------------------------------------------------------------------------------
\label{export_hint}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_exportHint  // suggest the best export format
(
    GrB_Format *format,     // export format
    GrB_Matrix A            // matrix to export
) ;
\end{verbatim}
} \end{mdframed}

This method suggests the most efficient format for the export of a given
matrix.  For SuiteSparse:GraphBLAS, the hint depends on the current
format of the \verb'GrB_Matrix':

\begin{packed_itemize}
\item \verb'GxB_SPARSE', \verb'GxB_BY_ROW': export as \verb'GrB_CSR_FORMAT'
\item \verb'GxB_SPARSE', \verb'GxB_BY_COL': export as \verb'GrB_CSC_FORMAT'
\item \verb'GxB_HYPERSPARSE': export as \verb'GrB_COO_FORMAT'
\item \verb'GxB_BITMAP', \verb'GxB_BY_ROW': export as \verb'GrB_CSR_FORMAT'
\item \verb'GxB_BITMAP', \verb'GxB_BY_COL': export as \verb'GrB_CSC_FORMAT'
%\item \verb'GxB_FULL', \verb'GxB_BY_ROW': export as \verb'GrB_DENSE_ROW_FORMAT'
%\item \verb'GxB_FULL', \verb'GxB_BY_COL': export as \verb'GrB_DENSE_COL_FORMAT'
\item \verb'GxB_FULL', \verb'GxB_BY_ROW': export as \verb'GrB_CSR_FORMAT'
\item \verb'GxB_FULL', \verb'GxB_BY_COL': export as \verb'GrB_CSC_FORMAT'
\end{packed_itemize}

\newpage
%===============================================================================
\subsection{Sorting methods}
%===============================================================================
\label{sorting_methods}

\verb'GxB_Matrix_sort' provides a mechanism to sort all the rows or
all the columns of a matrix, and \verb'GxB_Vector_sort' sorts all the
entries in a vector.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_sort:} sort a vector}
%-------------------------------------------------------------------------------
\label{vector_sort}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_sort
(
    // output:
    GrB_Vector w,           // vector of sorted values
    GrB_Vector p,           // vector containing the permutation
    // input
    GrB_BinaryOp op,        // comparator op
    GrB_Vector u,           // vector to sort
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Vector_sort' is identical to sorting the single column of an
\verb'n'-by-1 matrix.  The descriptor is ignored, except to control the number
of threads to use.  Refer to Section \ref{matrix_sort} for details.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_sort:} sort the rows/columns of a matrix}
%-------------------------------------------------------------------------------
\label{matrix_sort}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_sort
(
    // output:
    GrB_Matrix C,           // matrix of sorted values
    GrB_Matrix P,           // matrix containing the permutations
    // input
    GrB_BinaryOp op,        // comparator op
    GrB_Matrix A,           // matrix to sort
    const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}

\verb'GxB_Matrix_sort' sorts all the rows or all the columns of a matrix.
Each row (or column) is sorted separately.  The rows are sorted by default.
To sort the columns, use \verb'GrB_DESC_T0'.  A comparator operator is
provided to define the sorting order (ascending or descending).
For example, to sort a \verb'GrB_FP64' matrix in ascending order,
use \verb'GrB_LT_FP64' as the \verb'op', and to sort in descending order,
use \verb'GrB_GT_FP64'.

The \verb'op' must have a return value of \verb'GrB_BOOL', and the types of
its two inputs must be the same.  The entries in \verb'A' are typecasted to
the inputs of the \verb'op', if necessary.  Matrices with user-defined types
can be sorted with a user-defined comparator operator, whose two input types
must match the type of \verb'A', and whose output is \verb'GrB_BOOL'.

The two matrix outputs are \verb'C' and \verb'P'.  Any entries present on input
in \verb'C' or \verb'P' are discarded on output.  The type of \verb'C' must
match the type of \verb'A' exactly.  The dimensions of \verb'C', \verb'P', and
\verb'A' must also match exactly (even with the \verb'GrB_DESC_T0'
descriptor).

With the default sort (by row), suppose \verb'A(i,:)' contains \verb'k'
entries.  In this case, \verb'C(i,0:k-1)' contains the values of those entries
in sorted order, and \verb'P(i,0:k-1)' contains their corresponding column
indices in the matrix \verb'A'.  If two values are the same, ties are broken
according column index.

If the matrix is sorted by column, and \verb'A(:,j)' contains \verb'k' entries,
then \verb'C(0:k-1,j)' contains the values of those entries in sorted order,
and \verb'P(0:k-1,j)' contains their corresponding row indices in the matrix
\verb'A'.  If two values are the same, ties are broken according row index.

The outputs \verb'C' and \verb'P' are both optional; either one (but not both)
may be \verb'NULL', in which case that particular output matrix is not
computed.

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

A GraphBLAS {\em descriptor} modifies the behavior of a GraphBLAS operation.
If the descriptor is \verb'GrB_NULL', defaults are used.

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
#define GxB_NTHREADS 5  // for both GrB_Desc_field and GxB_Option_field
#define GxB_CHUNK 7
typedef enum
{
    GrB_OUTP = 0,   // descriptor for output of a method
    GrB_MASK = 1,   // descriptor for the mask input of a method
    GrB_INP0 = 2,   // descriptor for the first input of a method
    GrB_INP1 = 3,   // descriptor for the second input of a method
    GxB_DESCRIPTOR_NTHREADS = GxB_NTHREADS,   // number of threads to use
    GxB_DESCRIPTOR_CHUNK = GxB_CHUNK,   // chunk size for small problems
    GxB_AxB_METHOD = 1000, // descriptor for selecting C=A*B algorithm
    GxB_SORT = 35   // control sort in GrB_mxm
    GxB_COMPRESSION = 36,   // select compression for serialize
    GxB_IMPORT = 37,        // secure vs fast pack
}
GrB_Desc_Field ;

typedef enum
{
    // for all GrB_Descriptor fields:
    GxB_DEFAULT = 0,    // default behavior of the method
    // for GrB_OUTP only:
    GrB_REPLACE = 1,    // clear the output before assigning new values to it
    // for GrB_MASK only:
    GrB_COMP = 2,       // use the complement of the mask
    GrB_STRUCTURE = 4,  // use the structure of the mask
    // for GrB_INP0 and GrB_INP1 only:
    GrB_TRAN = 3,       // use the transpose of the input
    // for GxB_AxB_METHOD only:
    GxB_AxB_GUSTAVSON = 1001,   // gather-scatter saxpy method
    GxB_AxB_DOT       = 1003,   // dot product
    GxB_AxB_HASH      = 1004,   // hash-based saxpy method
    GxB_AxB_SAXPY     = 1005    // saxpy method (any kind)
    // for GxB_IMPORT only:
    GxB_SECURE_IMPORT = 502     // GxB*_pack* methods trust their input data
}
GrB_Desc_Value ;
\end{verbatim} } \end{mdframed}

\newpage

\begin{itemize}
\item \verb'GrB_OUTP' is a parameter that modifies the output of a
    GraphBLAS operation.  In the default case, the output is not cleared, and
    ${\bf Z = C \odot T}$ then ${\bf C \langle M \rangle = Z}$ are 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'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'GrB_MASK' parameter is set to \verb'GrB_COMP', 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.

    If the \verb'GrB_MASK' parameter is set to \verb'GrB_STRUCTURE',
    then the values of the mask are ignored, and just the pattern of the
    entries is used.  Any entry \verb'M(i,j)' in the pattern is treated as if
    it were true.

    The \verb'GrB_COMP' and \verb'GrB_STRUCTURE' settings can be combined,
    either by setting the mask option twice (once with each value), or by
    setting the mask option to \verb'GrB_COMP+GrB_STRUCTURE' (the latter is an
    extension to the specification).

    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'GrB_INP0' and \verb'GrB_INP1' modify the use of the
    first and second input matrices \verb'A' and \verb'B' of the GraphBLAS
    operation.

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

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

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

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

    \begin{itemize}

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

    \item \verb'GxB_AxB_SAXPY': select any saxpy-based method:
        \verb'GxB_AxB_GUSTAVSON', and/or
        \verb'GxB_AxB_HASH', or any mix of the two,
        in contrast to the dot-product method.

    \item \verb'GxB_AxB_GUSTAVSON':  an extended version of Gustavson's method
    \cite{Gustavson78}, which is a very good general-purpose method, but
    sometimes the workspace can be too large.  Assuming all matrices are stored
    by column, it computes \verb'C(:,j)=A*B(:,j)' with a sequence of {\em
    saxpy} operations (\verb'C(:,j)+=A(:,k)*B(k:,j)' for each nonzero
    \verb'B(k,j)').  In the {\em coarse Gustavson} method, each internal thread
    requires workspace of size $m$, to the number of rows of \verb'C', which is
    not suitable if the matrices are extremely sparse or if there are many
    threads.  For the {\em fine Gustavson} method, threads can share workspace
    and update it via atomic operations.  If all matrices are stored by row,
    then it computes \verb'C(i,:)=A(i,:)*B' in a sequence of sparse {\em saxpy}
    operations, and using workspace of size $n$ per thread, or group of
    threads, corresponding to the number of columns of \verb'C'.

    \item \verb'GxB_AxB_HASH':  a hash-based method, based on
        \cite{10.1145/3229710.3229720}.  It is very efficient for hypersparse
        matrices, matrix-vector-multiply, and when $|{\bf B}|$ is small.
        SuiteSparse:GraphBLAS includes a {\em coarse hash} method, in which
        each thread has its own hash workspace, and a {\em fine hash}
        method, in which groups of threads share a single hash workspace,
        as concurrent data structure, using atomics.

% [2] Yusuke Nagasaka, Satoshi Matsuoka, Ariful Azad, and Aydin Buluc. 2018.
% High-Performance Sparse Matrix-Matrix Products on Intel KNL and Multicore
% Architectures. In Proc. 47th Intl. Conf. on Parallel Processing (ICPP '18).
% Association for Computing Machinery, New York, NY, USA, Article 34, 1–10.
% DOI:https://doi.org/10.1145/3229710.3229720

\item \verb'GxB_AxB_DOT': computes \verb"C(i,j)=A(i,:)*B(j,:)'", for each
    entry \verb'C(i,j)'.  If the mask is present and not complemented, only
    entries for which \verb'M(i,j)=1' are computed.  This is a very specialized
    method that works well only if the mask is present, very sparse, and not
    complemented, when \verb'C' is small, or when \verb'C' is bitmap or full.
    For example, it works very well
    when \verb'A' and \verb'B' are tall and thin, and \verb"C<M>=A*B'" or
    \verb"C=A*B'" are computed.  These expressions assume all matrices are in
    CSR format.  If in CSC format, then the dot-product method used for
    \verb"A'*B".  The method is impossibly slow if \verb'C' is large and the
    mask is not present, since it takes $\Omega(mn)$ time if \verb'C' is
    $m$-by-$n$ in that case.  It does not use any workspace at all.  Since it
    uses no workspace, it can work very well for extremely sparse or
    hypersparse matrices, when the mask is present and not complemented.

    \end{itemize}

\item \verb'GxB_NTHREADS' controls how many threads a method uses.
    By default (if set to zero, or \verb'GxB_DEFAULT'), all available threads
    are used.  The maximum available threads is controlled by the global
    setting, which is \verb'omp_get_max_threads ( )' by default.  If set to
    some positive integer \verb'nthreads' less than this maximum, at most
    \verb'nthreads' threads will be used.  See Section~\ref{omp_parallelism}
    for details.

\item \verb'GxB_CHUNK' is a \verb'double' value that controls how many threads
    a method uses for small problems.  See Section~\ref{omp_parallelism} for
    details.

\item \verb'GxB_SORT' provides a hint to \verb'GrB_mxm', \verb'GrB_mxv',
    \verb'GrB_vxm', and \verb'GrB_reduce' (to vector).  These methods can leave
    the output matrix or vector in a jumbled state, where the final sort is
    left as pending work.  This is typically fastest, since some algorithms can
    tolerate jumbled matrices on input, and sometimes the sort can be skipped
    entirely.  However, if the matrix or vector will be immediately exported in
    unjumbled form, or provided as input to a method that requires it to not be
    jumbled, then sorting it during the matrix multiplication is faster.
    By default, these methods leave the result in jumbled form (a {\em lazy
    sort}), if \verb'GxB_SORT' is set to zero (\verb'GxB_DEFAULT').  A nonzero
    value will inform the matrix multiplication to sort its result, instead.

\item \verb'GxB_COMPRESSION' selects the compression method for serialization.
    The default is ZSTD (level 1).  See Section~\ref{serialize_deserialize} for
    other options.

\item \verb'GxB_IMPORT' informs the \verb'GxB' pack methods
    that they can trust their input data, or not.  The default is to trust
    the input, for faster packing.  If the data is being packed from an
    untrusted source, then additional checks should be made, and the 
    following descriptor setting should be used:

    {\footnotesize
    \begin{verbatim}
    GxB_set (desc, GxB_IMPORT, GxB_SECURE_IMPORT) ; \end{verbatim}}

\end{itemize}

The next sections describe the methods for a \verb'GrB_Descriptor':

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_Descriptor_new'        & create a descriptor                  & \ref{descriptor_new} \\
\verb'GrB_Descriptor_wait'       & wait for a descriptor                & \ref{descriptor_wait} \\
\verb'GrB_Descriptor_set'        & set a parameter in a descriptor      & \ref{descriptor_set} \\
\verb'GxB_Desc_set'              & set a parameter in a descriptor      & \ref{desc_set}  \\
\verb'GxB_Desc_get'              & get a parameter from a descriptor    & \ref{desc_get}  \\
\verb'GrB_Descriptor_free'       & free a descriptor                    & \ref{descriptor_free} \\
\hline
\end{tabular}
}

\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, the mask is not complemented, the mask
is valued not structural, neither input matrix is transposed, the method
used in \verb'C=A*B' is selected automatically, and \verb'GrB_mxm' leaves
the final sort as pending work).

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Descriptor\_wait:} wait for a descriptor}
%-------------------------------------------------------------------------------
\label{descriptor_wait}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_wait                   // wait for a descriptor
(
    GrB_Descriptor descriptor,      // descriptor to wait for
    GrB_WaitMode mode               // GrB_COMPLETE or GrB_MATERIALIZE
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined descriptor, a GraphBLAS library may choose to
exploit non-blocking mode to delay its creation.  Currently,
SuiteSparse:GraphBLAS does nothing except to ensure that \verb'd' is valid.

\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
    GrB_Desc_Field field,       // parameter to change
    GrB_Desc_Value val          // value to change it to
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Descriptor_set' sets a descriptor field (\verb'GrB_OUTP',
\verb'GrB_MASK', \verb'GrB_INP0', \verb'GrB_INP1', or \verb'GxB_AxB_METHOD') to
a particular value.  Use \verb'GxB_Dec_set' to set the value of
\verb'GxB_NTHREADS', \verb'GxB_CHUNK', and \verb'GxB_SORT'.
If an error occurs, \verb'GrB_error(&err,desc)' returns details about the error.

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

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

\hline

\verb'GrB_MASK'
    & \verb'GxB_DEFAULT':
    The Mask is not complemented.  \verb'Mask(i,j)=1' means the value $C_{ij}$
    can be modified by the operation, while \verb'Mask(i,j)=0' means the value
    $C_{ij}$ shall not be modified by the operation.
    & \verb'GrB_COMP':
    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. \\
    &
    & \verb'GrB_STRUCTURE':
    The values of the Mask are ignored.  If \verb'Mask(i,j)' is an entry
    in the \verb'Mask' matrix, it is treated as if \verb'Mask(i,j)=1'.
    The two options \verb'GrB_COMP' and \verb'GrB_STRUCTURE' can be
    combined, with two subsequent calls, or with a single call with the setting
    \verb'GrB_COMP+GrB_STRUCTURE'.  \\

\hline

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

\hline

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

\hline

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

\hline
\end{tabular}
}

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

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

\verb'GxB_Desc_set' is like \verb'GrB_Descriptor_set', except that the type of
the third parameter can vary with the field.   This function can modify all
descriptor settings, including those that do not have the type
\verb'GrB_Desc_Value'.  See also \verb'GxB_set' described in
Section~\ref{options}.  If an error occurs, \verb'GrB_error(&err,desc)' returns
details about the error.

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

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

\verb'GxB_Desc_get' returns the value of a single field in a descriptor.  The
type of the third parameter is a pointer to a variable type, whose type depends
on the field.  See also \verb'GxB_get' described in Section~\ref{options}.

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

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_DESC\_*:}  built-in descriptors}
%-------------------------------------------------------------------------------
\label{descriptor_predefined}

Built-in descriptors are listed in the table below.  A dash in the table
indicates the default.  These descriptors may not be modified or freed.
Attempts to modify them result in an error (\verb'GrB_INVALID_VALUE'); attempts
to free them are silently ignored. 

% \verb'GrB_NULL' is the default descriptor, with all settings at their defaults:
% \verb'OUTP': do not replace the output,
% \verb'MASK': mask is valued and not complemented,
% \verb'INP0': first input not transposed, and
% \verb'INP1': second input not transposed.
% For these pre-defined descriptors, the
% \verb'GxB_NTHREADS',
% \verb'GxB_CHUNK', and
% \verb'GxB_SORT' settings are at their default values.

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{|l|lllll|}
\hline
Descriptor              &  \verb'OUTP'          & \verb'MASK'           & \verb'MASK'       & \verb'INP0'       & \verb'INP1'       \\
                        &                       & structural            & complement        & & \\
\hline
\verb'GrB_NULL'         &   -                   & -                     & -                 & -                 & -                 \\
\verb'GrB_DESC_T1'      &   -                   & -                     & -                 & -                 & \verb'GrB_TRAN'   \\
\verb'GrB_DESC_T0'      &   -                   & -                     & -                 & \verb'GrB_TRAN'   & -                 \\
\verb'GrB_DESC_T0T1'    &   -                   & -                     & -                 & \verb'GrB_TRAN'   & \verb'GrB_TRAN'   \\
\hline
\verb'GrB_DESC_C'       &   -                   & -                     & \verb'GrB_COMP'   & -                 & -                 \\
\verb'GrB_DESC_CT1'     &   -                   & -                     & \verb'GrB_COMP'   & -                 & \verb'GrB_TRAN'   \\
\verb'GrB_DESC_CT0'     &   -                   & -                     & \verb'GrB_COMP'   & \verb'GrB_TRAN'   & -                 \\
\verb'GrB_DESC_CT0T1'   &   -                   & -                     & \verb'GrB_COMP'   & \verb'GrB_TRAN'   & \verb'GrB_TRAN'   \\
\hline
\verb'GrB_DESC_S'       &   -                   & \verb'GrB_STRUCTURE'  & -                 & -                 & -                 \\
\verb'GrB_DESC_ST1'     &   -                   & \verb'GrB_STRUCTURE'  & -                 & -                 & \verb'GrB_TRAN'   \\
\verb'GrB_DESC_ST0'     &   -                   & \verb'GrB_STRUCTURE'  & -                 & \verb'GrB_TRAN'   & -                 \\
\verb'GrB_DESC_ST0T1'   &   -                   & \verb'GrB_STRUCTURE'  & -                 & \verb'GrB_TRAN'   & \verb'GrB_TRAN'   \\
\hline
\verb'GrB_DESC_SC'      &   -                   & \verb'GrB_STRUCTURE'  & \verb'GrB_COMP'   & -                 & -                 \\
\verb'GrB_DESC_SCT1'    &   -                   & \verb'GrB_STRUCTURE'  & \verb'GrB_COMP'   & -                 & \verb'GrB_TRAN'   \\
\verb'GrB_DESC_SCT0'    &   -                   & \verb'GrB_STRUCTURE'  & \verb'GrB_COMP'   & \verb'GrB_TRAN'   & -                 \\
\verb'GrB_DESC_SCT0T1'  &   -                   & \verb'GrB_STRUCTURE'  & \verb'GrB_COMP'   & \verb'GrB_TRAN'   & \verb'GrB_TRAN'   \\
\hline
\verb'GrB_DESC_R'       &   \verb'GrB_REPLACE'  & -                     & -                 & -                 & -                 \\
\verb'GrB_DESC_RT1'     &   \verb'GrB_REPLACE'  & -                     & -                 & -                 & \verb'GrB_TRAN'   \\
\verb'GrB_DESC_RT0'     &   \verb'GrB_REPLACE'  & -                     & -                 & \verb'GrB_TRAN'   & -                 \\
\verb'GrB_DESC_RT0T1'   &   \verb'GrB_REPLACE'  & -                     & -                 & \verb'GrB_TRAN'   & \verb'GrB_TRAN'   \\
\hline
\verb'GrB_DESC_RC'      &   \verb'GrB_REPLACE'  & -                     & \verb'GrB_COMP'   & -                 & -                 \\
\verb'GrB_DESC_RCT1'    &   \verb'GrB_REPLACE'  & -                     & \verb'GrB_COMP'   & -                 & \verb'GrB_TRAN'   \\
\verb'GrB_DESC_RCT0'    &   \verb'GrB_REPLACE'  & -                     & \verb'GrB_COMP'   & \verb'GrB_TRAN'   & -                 \\
\verb'GrB_DESC_RCT0T1'  &   \verb'GrB_REPLACE'  & -                     & \verb'GrB_COMP'   & \verb'GrB_TRAN'   & \verb'GrB_TRAN'   \\
\hline
\verb'GrB_DESC_RS'      &   \verb'GrB_REPLACE'  & \verb'GrB_STRUCTURE'  & -                 & -                 & -                 \\
\verb'GrB_DESC_RST1'    &   \verb'GrB_REPLACE'  & \verb'GrB_STRUCTURE'  & -                 & -                 & \verb'GrB_TRAN'   \\
\verb'GrB_DESC_RST0'    &   \verb'GrB_REPLACE'  & \verb'GrB_STRUCTURE'  & -                 & \verb'GrB_TRAN'   & -                 \\
\verb'GrB_DESC_RST0T1'  &   \verb'GrB_REPLACE'  & \verb'GrB_STRUCTURE'  & -                 & \verb'GrB_TRAN'   & \verb'GrB_TRAN'   \\
\hline
\verb'GrB_DESC_RSC'     &   \verb'GrB_REPLACE'  & \verb'GrB_STRUCTURE'  & \verb'GrB_COMP'   & -                 & -                 \\
\verb'GrB_DESC_RSCT1'   &   \verb'GrB_REPLACE'  & \verb'GrB_STRUCTURE'  & \verb'GrB_COMP'   & -                 & \verb'GrB_TRAN'   \\
\verb'GrB_DESC_RSCT0'   &   \verb'GrB_REPLACE'  & \verb'GrB_STRUCTURE'  & \verb'GrB_COMP'   & \verb'GrB_TRAN'   & -                 \\
\verb'GrB_DESC_RSCT0T1' &   \verb'GrB_REPLACE'  & \verb'GrB_STRUCTURE'  & \verb'GrB_COMP'   & \verb'GrB_TRAN'   & \verb'GrB_TRAN'   \\
\hline
\end{tabular}}

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

Each of the ten 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 ten objects.  If \verb'G' is any
of the ten 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.  The \verb'GrB_free' function in SuiteSparse:GraphBLAS always
returns \verb'GrB_SUCCESS'.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The mask, accumulator, and replace option} %%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{sec:maskaccum}

After a GraphBLAS operation computes a result ${\bf T}$, (for example, ${\bf
T=AB}$ for \verb'GrB_mxm'), the results are assigned to an output matrix ${\bf
C}$ via the mask/ accumulator phase, written as ${\bf C \langle M \rangle = C
\odot T}$.  This phase is affected by the \verb'GrB_REPLACE' option in the
descriptor, the presence of an optional binary accumulator operator ($\odot$),
the presence of the optional mask matrix ${\bf M}$, and the status of the mask
descriptor.  The interplay of these options is summarized in
Table~\ref{tab:maskaccum}.

The mask ${\bf M}$ may be present, or not.  It may be structural or valued, and
it may be complemented, or not.  These options may be combined, for a total of
8 cases, although the structural/valued option as no effect if ${\bf M}$ is not
present.  If ${\bf M}$ is not present and not complemented, then $m_{ij}$ is
implicitly true.  If not present yet complemented, then all $m_{ij}$ entries are
implicitly zero; in this case, ${\bf T}$ need not be computed at all.  Either
${\bf C}$ is not modified, or all its entries are cleared if the replace option
is enabled.  If ${\bf M}$ is present, and the structural option is used, then
$m_{ij}$ is treated as true if it is an entry in the matrix (its value is
ignored).  Otherwise, the value of $m_{ij}$ is used.  In both cases, entries
not present are implicitly zero.  These values are negated if the mask is
complemented.  All of these various cases are combined to give a single
effective value of the mask at position ${ij}$.

The combination of all these options are presented in the
Table~\ref{tab:maskaccum}.  The first column is the \verb'GrB_REPLACE' option.
The second column lists whether or not the accumulator operator is present.
The third column lists whether or not $c_{ij}$ exists on input to the
mask/accumulator phase (a dash means that it does not exist).  The fourth
column lists whether or not the entry $t_{ij}$ is present in the result matrix
${\bf T}$.  The mask column is the final effective value of $m_{ij}$, after
accounting for the presence of ${\bf M}$ and the mask options.  Finally, the
last column states the result of the mask/accum step; if no action is listed in
this column, then $c_{ij}$ is not modified.

Several important observations can be made from this table.  First,
if no mask is present (and the mask-complement descriptor option is not used),
then only the first half of the table is used.  In this case, the \verb'GrB_REPLACE'
option has no effect.  The entire matrix ${\bf C}$ is modified.

Consider the cases when $c_{ij}$ is present but $t_{ij}$ is not, and there is no
mask or the effective value of the mask is true for this ${ij}$ position.  With
no accumulator operator, $c_{ij}$ is deleted.  If the accumulator operator is
present and the replace option is not used, $c_{ij}$ remains unchanged.

\begin{table}
{\small
\begin{tabular}{lllll|l}
\hline
repl & accum & ${\bf C}$ & ${\bf T}$ & mask & action taken by ${\bf C \langle M \rangle = C \odot T}$ \\
\hline
    -  &-   & $c_{ij}$ & $t_{ij}$  & 1    &  $c_{ij} = t_{ij}$, update \\
    -  &-   &  -       & $t_{ij}$  & 1    &  $c_{ij} = t_{ij}$, insert \\
    -  &-   & $c_{ij}$ &  -        & 1    &  delete $c_{ij}$ because $t_{ij}$ not present \\
    -  &-   &  -       &  -        & 1    &   \\
    -  &-   & $c_{ij}$ & $t_{ij}$  & 0    &   \\
    -  &-   &  -       & $t_{ij}$  & 0    &   \\
    -  &-   & $c_{ij}$ &  -        & 0    &   \\
    -  &-   &  -       &  -        & 0    &   \\
\hline
    yes&-   & $c_{ij}$ & $t_{ij}$  & 1    &  $c_{ij} = t_{ij}$, update \\
    yes&-   &  -       & $t_{ij}$  & 1    &  $c_{ij} = t_{ij}$, insert \\
    yes&-   & $c_{ij}$ &  -        & 1    &  delete $c_{ij}$ because $t_{ij}$ not present \\
    yes&-   &  -       &  -        & 1    &   \\
    yes&-   & $c_{ij}$ & $t_{ij}$  & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&-   &  -       & $t_{ij}$  & 0    &   \\
    yes&-   & $c_{ij}$ &  -        & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&-   &  -       &  -        & 0    &   \\
\hline
    -  &yes & $c_{ij}$ & $t_{ij}$  & 1    &  $c_{ij} = c_{ij} \odot t_{ij}$, apply accumulator \\
    -  &yes &  -       & $t_{ij}$  & 1    &  $c_{ij} = t_{ij}$, insert \\
    -  &yes & $c_{ij}$ &  -        & 1    &   \\
    -  &yes &  -       &  -        & 1    &   \\
    -  &yes & $c_{ij}$ & $t_{ij}$  & 0    &   \\
    -  &yes &  -       & $t_{ij}$  & 0    &   \\
    -  &yes & $c_{ij}$ &  -        & 0    &   \\
    -  &yes &  -       &  -        & 0    &   \\
\hline
    yes&yes & $c_{ij}$ & $t_{ij}$  & 1    &  $c_{ij} = c_{ij} \odot t_{ij}$, apply accumulator \\
    yes&yes &  -       & $t_{ij}$  & 1    &  $c_{ij} = t_{ij}$, insert \\
    yes&yes & $c_{ij}$ &  -        & 1    &   \\
    yes&yes &  -       &  -        & 1    &   \\
    yes&yes & $c_{ij}$ & $t_{ij}$  & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&yes &  -       & $t_{ij}$  & 0    &   \\
    yes&yes & $c_{ij}$ &  -        & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&yes &  -       &  -        & 0    &   \\
\hline
\end{tabular}
}
\caption{Results of the mask/accumulator phase. \label{tab:maskaccum}}
\end{table}

When there is no mask and the mask \verb'GrB_COMP' option is not selected, the
table simplifies (Table~\ref{tab:maskaccum_nomask}).  The \verb'GrB_REPLACE'
option no longer has any effect.  The \verb'GrB_SECOND_T' binary operator when
used as the accumulator unifies the first cases, shown in
Table~\ref{tab:maskaccum_nomask_2nd}.  The only difference now is the behavior
when $c_{ij}$ is present but $t_{ij}$ is not.  Finally, the effect of
\verb'GrB_FIRST_T' as the accumulator is shown in
Table~\ref{tab:maskaccum_nomask_1st}. 

\begin{table}[h]
\begin{center}
{\small
\begin{tabular}{lll|l}
\hline
       accum & ${\bf C}$ & ${\bf T}$        & action taken by ${\bf C = C \odot T}$ \\
\hline
        -   & $c_{ij}$ & $t_{ij}$         &  $c_{ij} = t_{ij}$, update \\
        -   &  -       & $t_{ij}$         &  $c_{ij} = t_{ij}$, insert \\
        -   & $c_{ij}$ &  -               &  delete $c_{ij}$ because $t_{ij}$ not present \\
        -   &  -       &  -               &   \\
\hline
        yes & $c_{ij}$ & $t_{ij}$         &  $c_{ij} = c_{ij} \odot t_{ij}$, apply accumulator \\
        yes &  -       & $t_{ij}$         &  $c_{ij} = t_{ij}$, insert \\
        yes & $c_{ij}$ &  -               &   \\
        yes &  -       &  -               &   \\
\hline
\end{tabular}
}
\caption{When no mask is present (and not complemented).
\label{tab:maskaccum_nomask}}
\end{center}
\end{table}

\begin{table}[h]
\begin{center}
{\small
\begin{tabular}{lll|l}
\hline
       accum & ${\bf C}$ & ${\bf T}$        & action taken by ${\bf C = C \odot T}$ \\
\hline
        yes & $c_{ij}$ & $t_{ij}$         &  $c_{ij} = t_{ij}$, apply \verb'GrB_SECOND' accumulator \\
        yes &  -       & $t_{ij}$         &  $c_{ij} = t_{ij}$, insert \\
        yes & $c_{ij}$ &  -               &   \\
        yes &  -       &  -               &   \\
\hline
\end{tabular}
}
\caption{No mask, with the SECOND operator as the accumulator.
\label{tab:maskaccum_nomask_2nd}}
\end{center}
\end{table}

\begin{table}[h]
\begin{center}
{\small
\begin{tabular}{lll|l}
\hline
       accum & ${\bf C}$ & ${\bf T}$        & action taken by ${\bf C = C \odot T}$ \\
\hline
        yes & $c_{ij}$ & $t_{ij}$         &  \\ 
        yes &  -       & $t_{ij}$         &  $c_{ij} = t_{ij}$, insert \\
        yes & $c_{ij}$ &  -               &   \\
        yes &  -       &  -               &   \\
\hline
\end{tabular}
}
\caption{No Mask, with the FIRST operator as the accumulator.
\label{tab:maskaccum_nomask_1st}}
\end{center}
\end{table}

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

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

\begin{itemize}

\item \verb'GxB_set (field, value)' sets global options.

{\footnotesize
\begin{tabular}{lll}
field                       & value         & description \\
\hline
\verb'GxB_HYPER_SWITCH'     & \verb'double' & hypersparsity control (0 to 1) \\
\verb'GxB_BITMAP_SWITCH'    & \verb'double [8]' & bitmap control \\
\verb'GxB_FORMAT'           & \verb'int'    & \verb'GxB_BY_ROW'
                                              or \verb'GxB_BY_COL' \\
\verb'GxB_GLOBAL_NTHREADS'  & \verb'int'    & number of threads to use \\
\verb'GxB_NTHREADS'         & \verb'int'    & number of threads to use \\
\verb'GxB_GLOBAL_CHUNK'     & \verb'double' & chunk size \\
\verb'GxB_CHUNK'            & \verb'double' & chunk size \\
\verb'GxB_BURBLE'           & \verb'int'    & diagnostic output \\
\verb'GxB_PRINTF'           & see below     & diagnostic output \\
\verb'GxB_FLUSH'            & see below     & diagnostic output \\
\verb'GxB_MEMORY_POOL'      & \verb'int64_t [64]' & memory pool control \\
\verb'GxB_PRINT_1BASED'     & \verb'int'    & for printing matrices/vectors \\
\hline
\end{tabular}
}

\item \verb'GxB_set (GrB_Matrix A, field, value)' provides hints to
    SuiteSparse: GraphBLAS on how to store a particular matrix.

{\footnotesize
\begin{tabular}{lll}
field                       & value         & description \\
\hline
\verb'GxB_HYPER_SWITCH'     & \verb'double' & hypersparsity control (0 to 1) \\
\verb'GxB_BITMAP_SWITCH'    & \verb'double' & bitmap control (0 to 1) \\
\verb'GxB_FORMAT'           & \verb'int'    & \verb'GxB_BY_ROW'
                                              or \verb'GxB_BY_COL' \\
\verb'GxB_SPARSITY_CONTROL' & \verb'int'    & 0 to 15 \\
\hline
\end{tabular}
}

\item \verb'GxB_set (GrB_Vector v, field, value)' provides hints to
    SuiteSparse: GraphBLAS on how to store a particular vector.

{\footnotesize
\begin{tabular}{lll}
field                       & value         & description \\
\hline
\verb'GxB_BITMAP_SWITCH'    & \verb'double' & bitmap control (0 to 1) \\
\verb'GxB_SPARSITY_CONTROL' & \verb'int'    & 0 to 15 \\
\hline
\end{tabular}
}

\item \verb'GxB_set (GrB_Descriptor desc, field, value)' sets
    the value of a field in a \verb'GrB_Descriptor'.

{\footnotesize
\begin{tabular}{lll}
field                       & value         & description \\
\hline
\verb'GrB_OUTP'     & \verb'GrB_Desc_Value' & replace option \\
\verb'GrB_MASK'     & \verb'GrB_Desc_Value' & mask option \\
\verb'GrB_INP0'     & \verb'GrB_Desc_Value' & transpose input 0 \\
\verb'GrB_INP1'     & \verb'GrB_Desc_Value' & transpose input 1 \\
\verb'GxB_DESCRIPTOR_NTHREADS'  & \verb'int' & number of threads to use \\
\verb'GxB_NTHREADS'             & \verb'int' & number of threads to use \\
\verb'GxB_DESCRIPTOR_CHUNK'     & \verb'double' & chunk size \\
\verb'GxB_CHUNK'                & \verb'double' & chunk size \\
\verb'GxB_AxB_METHOD'           & \verb'int' & method for matrix multiply \\
\verb'GxB_SORT'                 & \verb'int' & lazy vs aggressive sort \\
\verb'GxB_COMPRESSION'          & \verb'int' & compression for serialization \\
\verb'GxB_IMPORT'    & \verb'GrB_Desc_Value' & trust data on import/pack \\
\hline
\end{tabular}
}

\end{itemize}

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

\begin{itemize}

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

{\footnotesize
\begin{tabular}{lll}
field                       & value         & description \\
\hline
\verb'GxB_HYPER_SWITCH'     & \verb'double' & hypersparsity control (0 to 1) \\
\verb'GxB_BITMAP_SWITCH'    & \verb'double [8]' & bitmap control \\
\verb'GxB_FORMAT'           & \verb'int'    & \verb'GxB_BY_ROW' or \verb'GxB_BY_COL' \\
\verb'GxB_GLOBAL_NTHREADS'  & \verb'int'    & number of threads to use \\
\verb'GxB_NTHREADS'         & \verb'int'    & number of threads to use \\
\verb'GxB_GLOBAL_CHUNK'     & \verb'double' & chunk size \\
\verb'GxB_CHUNK'            & \verb'double' & chunk size \\
\verb'GxB_BURBLE'           & \verb'int'    & diagnostic output \\
\verb'GxB_PRINTF'           & see below     & diagnostic output \\
\verb'GxB_FLUSH'            & see below     & diagnostic output \\
\verb'GxB_MEMORY_POOL'      & \verb'int64_t [64]' & memory pool control \\
\verb'GxB_PRINT_1BASED'     & \verb'int'    & for printing matrices/vectors \\
\verb'GxB_MODE'                 & \verb'int'    & blocking/non-blocking \\
\verb'GxB_LIBRARY_NAME'         & \verb'char *' & name of library \\
\verb'GxB_LIBRARY_VERSION'      & \verb'int [3]' & library version \\
\verb'GxB_LIBRARY_DATE'         & \verb'char *' & release date \\
\verb'GxB_LIBRARY_ABOUT'        & \verb'char *' & about the library \\
\verb'GxB_LIBRARY_LICENSE'      & \verb'char *' & license \\
\verb'GxB_LIBRARY_COMPILE_DATE' & \verb'char *' & date of compilation \\
\verb'GxB_LIBRARY_COMPILE_TIME' & \verb'char *' & time of compilation \\
\verb'GxB_LIBRARY_OPENMP'       & \verb'bool'   & true if compiled with OpenMP\\
\verb'GxB_LIBRARY_URL'          & \verb'char *' & url of library \\
\verb'GxB_API_VERSION'          & \verb'int [3]' & C API version \\
\verb'GxB_API_DATE'             & \verb'char *' & C API date \\
\verb'GxB_API_ABOUT'            & \verb'char *' & about the C API \\
\verb'GxB_API_URL'              & \verb'char *' & \verb'http://graphblas.org' \\
\verb'GxB_COMPILER_NAME'        & \verb'char *' & C compiler name \\
\verb'GxB_COMPILER_VERSION'     & \verb'int [3]' & C compiler version \\
\hline
\end{tabular}
}

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

{\footnotesize
\begin{tabular}{lll}
field                       & value         & description \\
\hline
\verb'GxB_HYPER_SWITCH'     & \verb'double' & hypersparsity control (0 to 1) \\
\verb'GxB_BITMAP_SWITCH'    & \verb'double' & bitmap control (0 to 1) \\
\verb'GxB_FORMAT'           & \verb'int'    & \verb'GxB_BY_ROW'
                                              or \verb'GxB_BY_COL' \\
\verb'GxB_SPARSITY_CONTROL' & \verb'int'    & 0 to 15 \\
\verb'GxB_SPARSITY_STATUS'  & \verb'int'    & 1, 2, 4, or 8 \\
\hline
\end{tabular}
}

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

{\footnotesize
\begin{tabular}{lll}
field                       & value         & description \\
\hline
\verb'GxB_BITMAP_SWITCH'    & \verb'double' & bitmap control (0 to 1) \\
\verb'GxB_FORMAT'           & \verb'int'    & \verb'GxB_BY_ROW'
                                              or \verb'GxB_BY_COL' \\
\verb'GxB_SPARSITY_CONTROL' & \verb'int'    & 0 to 15 \\
\verb'GxB_SPARSITY_STATUS'  & \verb'int'    & 1, 2, 4, or 8 \\
\hline
\end{tabular}
}

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

{\footnotesize
\begin{tabular}{lll}
field                       & value         & description \\
\hline
\verb'GrB_OUTP'     & \verb'GrB_Desc_Value' & replace option \\
\verb'GrB_MASK'     & \verb'GrB_Desc_Value' & mask option \\
\verb'GrB_INP0'     & \verb'GrB_Desc_Value' & transpose input 0 \\
\verb'GrB_INP1'     & \verb'GrB_Desc_Value' & transpose input 1 \\
\verb'GxB_DESCRIPTOR_NTHREADS'  & \verb'int' & number of threads to use \\
\verb'GxB_NTHREADS'             & \verb'int' & number of threads to use \\
\verb'GxB_DESCRIPTOR_CHUNK'     & \verb'double' & chunk size \\
\verb'GxB_CHUNK'                & \verb'double' & chunk size \\
\verb'GxB_AxB_METHOD'           & \verb'int' & method for matrix multiply \\
\verb'GxB_SORT'                 & \verb'int' & lazy vs aggressive sort \\
\verb'GxB_COMPRESSION'          & \verb'int' & compression for serialization \\
\verb'GxB_IMPORT'    & \verb'GrB_Desc_Value' & trust data on import/pack \\
\hline
\end{tabular}
}

\end{itemize}

%-------------------------------------------------------------------------------
\subsection{OpenMP parallelism}
%-------------------------------------------------------------------------------
\label{omp_parallelism}

SuiteSparse:GraphBLAS is a parallel library, based on OpenMP.  By
default, all GraphBLAS operations will use up to the maximum number of threads
specified by the \verb'omp_get_max_threads' OpenMP function.  For small
problems, GraphBLAS may choose to use fewer threads, using two parameters: the
maximum number of threads to use (which may differ from the
\verb'omp_get_max_threads' value), and a parameter called the \verb'chunk'.
Suppose \verb'work' is a measure of the work an operation needs to perform (say
the number of entries in the two input matrices for \verb'GrB_eWiseAdd').  No
more than \verb'floor(work/chunk)' threads will be used (or one thread if the
ratio is less than 1).

The default \verb'chunk' value is 65,536, but this may change in future versions,
or it may be modified when GraphBLAS is installed on a particular machine.

Both parameters can be set in two ways:

\begin{itemize}

\item Globally:  If the following methods are used, then all subsequent
GraphBLAS operations will use these settings.  Note the typecast,
\verb'(double)' \verb'chunk'.  This is necessary if a literal constant such as
\verb'20000' is passed as this argument.  The type of the constant must be
\verb'double'.

    {\footnotesize
    \begin{verbatim}
    int nthreads_max = 40 ;
    GxB_set (GxB_NTHREADS, nthreads_max) ;
    GxB_set (GxB_CHUNK, (double) 20000) ; \end{verbatim} }

\item Per operation:  Most GraphBLAS operations take a \verb'GrB_Descriptor'
input, and this can be modified to set the number of threads and chunk
size for the operation that uses this descriptor.  Note that \verb'chunk'
is a \verb'double'.

    {\footnotesize
    \begin{verbatim}
    GrB_Descriptor desc ;
    GrB_Descriptor_new (&desc)
    int nthreads_max = 40 ;
    GxB_set (desc, GxB_NTHREADS, nthreads_max) ;
    double chunk = 20000 ;
    GxB_set (desc, GxB_CHUNK, chunk) ; \end{verbatim} }

\end{itemize}

The smaller of \verb'nthreads_max' and \verb'floor(work/chunk)' is used for any
given GraphBLAS operation, except that a single thread is used if this value is
zero or less.

If either parameter is set to \verb'GxB_DEFAULT', then default values are used.
The default for \verb'nthreads_max' is the return value from
\verb'omp_get_max_threads', and the default chunk size is currently 65,536.

If a descriptor value for either parameter is left at its default, or set to
\verb'GxB_DEFAULT', then the global setting is used.  This global setting may
have been modified from its default, and this modified value will be used.

For example, suppose \verb'omp_get_max_threads' reports 8 threads.  If \newline
\verb'GxB_set (GxB_NTHREADS, 4)' is used, then the global setting is four
threads, not eight.  If a descriptor is used but its \verb'GxB_NTHREADS' is not
set, or set to \verb'GxB_DEFAULT', then any operation that uses this descriptor
will use 4 threads.

GraphBLAS may be compiled without OpenMP, by setting \verb'-DNOPENMP=1'.
The library will be thread-safe, with one exception.  \verb'GrB_wait' is
intended to provide thread-safety by flushing the cache of one user thread
so the object can be safely read by another thread.  This is accomplished
with \verb'pragma omp flush', but if OpenMP is not available, this does
nothing.  If OpenMP is not available or \verb'-DNOPEMP=1' is used, then
user applications need to ensure their own thread safety when one user thread
computes a result that is then read by another thread.

You can query GraphBLAS at run time to ask if it was compiled with OpenMP:

\begin{verbatim}
    bool have_openmp ;
    GxB_get (GxB_LIBRARY_OPENMP, &have_openmp) ;
    if (!have_openmp) printf ("GraphBLAS not compiled with OpenMP\n") :
\end{verbatim}

Compiling GraphBLAS without OpenMP is not recommended for installation in a
package manager (Linux, conda-forge, spack, brew, vcpkg, etc).

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

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

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

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

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

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

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

If this is done, and no other \verb'GxB_set' calls are made with
\verb'GxB_FORMAT', all matrices will be stored by column.
The default format is \verb'GxB_BY_ROW'.

All vectors (\verb'GrB_Vector') are held by column, and this cannot be changed.

By default, matrices of size \verb'm-by-1' are held by column, regardless of
the global setting described above.  Matrices of size \verb'1-by-n' with
\verb'n' not equal to 1 are held by row, regardless of the global setting.
The global setting only affects matrices with both \verb'm > 1' and \verb'n > 1'.
Empty matrices (\verb'0-by-0') are also controlled by the global setting.

After creating a matrix with \verb'GrB_Matrix_new (&A, ...)',
its format can be changed arbitrarily with \verb'GxB_set (A, GxB_FORMAT, ...)'.
So even an \verb'm-by-1' matrix can then be changed to be held by row, for
example.  Likewise, once a \verb'1-by-n' matrix is created, it can be converted
to column-oriented format.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

%-------------------------------------------------------------------------------
\subsection{Bitmap matrices}
\label{bitmap_switch}
%-------------------------------------------------------------------------------

By default, SuiteSparse:GraphBLAS switches between all four formats
(hypersparse, sparse, bitmap, and full) automatically.  Let $d = |{\bf A}|/mn$
for an $m$-by-$n$ matrix $\bf A$ with $|{\bf A}|$ entries.  If the matrix is
currently in sparse or hypersparse format, and is modified so that $d$ exceeds
a given threshold, it is converted into bitmap format.  The default threshold
is controlled by the \verb'GxB_BITMAP_SWITCH' setting, which can be set
globally, or for a particular matrix or vector.

The default value of the switch to bitmap format depends on $\min(m,n)$, for a
matrix of size $m$-by-$n$.  For the global setting, the bitmap switch is a
\verb'double' array of size \verb'GxB_NBITMAP_SWITCH'.  The defaults are given
below:

\vspace{0.2in}
{\small
\begin{tabular}{lll}
parameter & default & matrix sizes \\
\hline
\verb'bitmap_switch [0]' & 0.04 & $\min(m,n) = 1$ (and all vectors) \\
\verb'bitmap_switch [1]' & 0.05 & $\min(m,n) = 2$ \\
\verb'bitmap_switch [2]' & 0.06 & $\min(m,n) = 3$ to 4 \\
\verb'bitmap_switch [3]' & 0.08 & $\min(m,n) = 5$ to 8 \\
\verb'bitmap_switch [4]' & 0.10 & $\min(m,n) = 9$ to 16\\
\verb'bitmap_switch [5]' & 0.20 & $\min(m,n) = 17$ to 32\\
\verb'bitmap_switch [6]' & 0.30 & $\min(m,n) = 33$ to 64 \\
\verb'bitmap_switch [7]' & 0.40 & $\min(m,n) > 64$ \\
\end{tabular}
}
\vspace{0.2in}

That is, by default a \verb'GrB_Vector' is held in bitmap format if its density
exceeds 4\%.  To change the global settings, do the following:

{\footnotesize
\begin{verbatim}
    double bswitch [GxB_NBITMAP_SWITCH] = { 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8 } ;
    GxB_set (GxB_BITMAP_SWITCH, bswitch) ;
\end{verbatim}
}

If the matrix is currently in bitmap format, it is converted to full if all
entries are present, or to sparse/hypersparse if $d$ drops below $b/2$, if its
bitmap switch is $b$.  A matrix or vector with $d$ between $b/2$ and $b$
remains in its current format.

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

{\footnotesize
\begin{verbatim}
typedef enum
{
    // for matrix/vector get/set and global get/set:
    GxB_HYPER_SWITCH = 0,    // defines switch to hypersparse (double value)
    GxB_BITMAP_SWITCH = 34,  // defines switch to hypersparse (double value)
    GxB_FORMAT = 1,     // defines CSR/CSC format: GxB_BY_ROW or GxB_BY_COL
    GxB_SPARSITY_CONTROL = 32,  // control the sparsity of a matrix or vector

    // for global get/set only:
    GxB_GLOBAL_NTHREADS = GxB_NTHREADS, // max number of threads to use
    GxB_GLOBAL_CHUNK = GxB_CHUNK,       // chunk size for small problems
    GxB_BURBLE = 99,                    // diagnositic output
    GxB_PRINTF = 101,               // printf function for diagnostic output
    GxB_FLUSH = 102,                // flush function for diagnostic output
    GxB_MEMORY_POOL = 103,  // memory pool control
    GxB_PRINT_1BASED = 104, // print matrices as 0-based or 1-based

    // for matrix/vector get only:
    GxB_SPARSITY_STATUS = 33,   // query the sparsity of a matrix or vector

    // for global get only:
    GxB_MODE = 2,       // mode passed to GrB_init (blocking or non-blocking)
    GxB_LIBRARY_NAME = 8,           // name of the library (char *)
    GxB_LIBRARY_VERSION = 9,        // library version (3 int's)
    GxB_LIBRARY_DATE = 10,          // date of the library (char *)
    GxB_LIBRARY_ABOUT = 11,         // about the library (char *)
    GxB_LIBRARY_URL = 12,           // URL for the library (char *)
    GxB_LIBRARY_LICENSE = 13,       // license of the library (char *)
    GxB_LIBRARY_COMPILE_DATE = 14,  // date library was compiled (char *)
    GxB_LIBRARY_COMPILE_TIME = 15,  // time library was compiled (char *)
    GxB_LIBRARY_OPENMP = 25,        // library compiled with OpenMP
    GxB_API_VERSION = 16,           // API version (3 int's)
    GxB_API_DATE = 17,              // date of the API (char *)
    GxB_API_ABOUT = 18,             // about the API (char *)
    GxB_API_URL = 19,               // URL for the API (char *)
}
GxB_Option_Field ;
\end{verbatim} }

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

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

The default format is given by the predefined value \verb'GxB_FORMAT_DEFAULT',
which is equal to \verb'GxB_BY_ROW'.
The default hypersparsity
ratio is 0.0625 (1/16), but this value may change in the future.

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

{\footnotesize
\begin{verbatim}
    GxB_set (GxB_HYPER_SWITCH, GxB_HYPER_DEFAULT) ;
    GxB_set (GxB_FORMAT, GxB_BY_ROW) ;
\end{verbatim} }

That is, by default, all new matrices are held by row in CSR format (except
for \verb'n-by-1' matrices; see \verb'GrB_Matrix_new').
If a matrix has fewer than $n/16$
columns, it can be converted to hypersparse format.  If it has more than $n/8$
columns, it can be converted to non-hypersparse format.  These options can be
changed for all future matrices with \verb'GxB_set'.  For example, to change
all future matrices to be in non-hypersparse CSC when created, use:

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

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

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

This changes the matrix \verb'A' so that it is stored by row, and it is
converted from non-hypersparse to hypersparse format if it has fewer than 10\%
non-empty columns.  If it is hypersparse, it is a candidate for conversion to
non-hypersparse if has 20\% or more non-empty columns.  If it has between 10\%
and 20\% non-empty columns, it remains in its current format.
MATLAB only supports a non-hypersparse CSC format.  The format in
SuiteSparse:GraphBLAS that is equivalent to the MATLAB format is:

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

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

The sparsity status of a matrix can be queried with the following, which
returns a value of \verb'GxB_HYPERSPARSE' \verb'GxB_SPARSE' \verb'GxB_BITMAP'
or \verb'GxB_FULL'.

{\footnotesize
\begin{verbatim}
    int sparsity ;
    GxB_get (A, GxB_SPARSITY_STATUS, &sparsity) ; \end{verbatim}}

The sparsity format of a matrix can be controlled with \verb'GxB_set', which
can be any mix (a sum or bitwise or) of \verb'GxB_HYPERSPARSE'
\verb'GxB_SPARSE' \verb'GxB_BITMAP', and \verb'GxB_FULL'.  By default, a matrix
or vector can be held in any format, with the default setting
\verb'GxB_AUTO_SPARSITY', which is equal to \verb'GxB_HYPERSPARSE' +
\verb'GxB_SPARSE' + \verb'GxB_BITMAP' + \verb'GxB_FULL'.  To enable a matrix to
take on just \verb'GxB_SPARSE' or \verb'GxB_FULL' formats, but not
\verb'GxB_HYPERSPARSE' or \verb'GxB_BITMAP', for example, use the following:

{\footnotesize
\begin{verbatim}
    GxB_set (A, GxB_SPARSITY_CONTROL, GxB_SPARSE + GxB_FULL) ; \end{verbatim}}

In this case, SuiteSparse:GraphBLAS will hold the matrix in sparse format
(\verb'CSC' or \verb'CSC', depending on its \verb'GxB_FORMAT'), unless all
entries are present, in which case it will be converted to full format.

Only the least 4 bits of the sparsity control are considered, so the
formats can be bitwise negated.  For example, to allow for any format
except full:

{\footnotesize
\begin{verbatim}
    GxB_set (A, GxB_SPARSITY_CONTROL, ~GxB_FULL) ; \end{verbatim}}

%-------------------------------------------------------------------------------
\subsection{{\sf GxB\_BURBLE}, {\sf GxB\_PRINTF}, {\sf GxB\_FLUSH}: diagnostics}
%-------------------------------------------------------------------------------

\verb'GxB_set (GxB_BURBLE, ...)' controls the burble setting.  It can also be
controlled via \verb'GrB.burble(b)' in the MATLAB/Octave interface.

{\footnotesize
\begin{verbatim}
     GxB_set (GxB_BURBLE, true) ;   // enable burble
     GxB_set (GxB_BURBLE, false) ;  // disable burble \end{verbatim}}

If enabled, SuiteSparse:GraphBLAS reports which internal kernels it uses, and
how much time is spent.  If you see the word \verb'generic', it means that
SuiteSparse:GraphBLAS was unable to use is faster kernels in
\verb'Source/Generated2', but used a generic kernel that relies on function
pointers.  This is done for user-defined types and operators, and when
typecasting is performed, and it is typically slower than the kernels in
\verb'Source/Generated2'.

If you see a lot of \verb'wait' statements, it may mean that a lot of time is
spent finishing a matrix or vector.  This may be the result of an inefficient
use of the \verb'setElement' and \verb'assign' methods.  If this occurs you
might try changing the sparsity format of a vector or matrix to
\verb'GxB_BITMAP', assuming there's enough space for it.

\verb'GxB_set (GxB_PRINTF, printf)' allows the user application to change the
function used to print diagnostic output.  This also controls the output of the
\verb'GxB_*print' functions.  By default this parameter is \verb'NULL', in
which case the ANSI C11 \verb'printf' function is used.  The parameter is a
function pointer with the same signature as the ANSI C11 \verb'printf'
function.  The MATLAB/Octave interface to GraphBLAS uses the following so that
GraphBLAS can print to the MATLAB/Octave Command Window:

{\footnotesize
\begin{verbatim}
    GxB_set (GxB_PRINTF, mexPrintf) \end{verbatim}}

After each call to the \verb'printf' function, an optional
\verb'flush' function is called, which is \verb'NULL' by default.  If
\verb'NULL', the function is not used.  This can be changed with
\verb'GxB_set (GxB_FLUSH, flush)'.  The \verb'flush' function takes no
arguments, and returns an \verb'int' which is 0 if successful, or any nonzero
value on failure (the same output as the ANSI C11 \verb'fflush' function,
except that \verb'flush' has no inputs).

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

\verb'GxB_MODE' can only be
queried by \verb'GxB_get'; it cannot be modified by \verb'GxB_set'.  The mode
is the value passed to \verb'GrB_init' (blocking or non-blocking).

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

The \verb'GxB_LIBRARY_*' options can be used with \verb'GxB_get' to query the
current implementation.  For all of these, \verb'GxB_get' returns a string
(\verb'char *'), except for \verb'GxB_LIBRARY_VERSION', which takes as input an
\verb'int' array of size three.  The \verb'GxB_API_*' options can be used with
\verb'GxB_get' to query the current GraphBLAS C API Specification.  For all of
these, \verb'GxB_get' returns a string (\verb'char *'), except for
\verb'GxB_API_VERSION', which takes as input an \verb'int' array of size three.  

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

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

This usage of \verb'GxB_set' sets the value of a global option.
The \verb'field' parameter can be
\verb'GxB_HYPER_SWITCH',
\verb'GxB_BITMAP_SWITCH',
\verb'GxB_FORMAT',
\verb'GxB_NTHREADS',
\verb'GxB_CHUNK',
\verb'GxB_BURBLE',
\verb'GxB_PRINTF',
\verb'GxB_FLUSH',
\verb'GxB_MEMORY_POOL',
or
\verb'GxB_PRINT_1BASED'.

For example, the following usage sets the global hypersparsity ratio to 0.2,
the format of future matrices to \verb'GxB_BY_COL', the maximum number
of threads to 4, the chunk size to 10000, and enables the burble.
No existing matrices are changed.

{\footnotesize
\begin{verbatim}
    GxB_set (GxB_HYPER_SWITCH, 0.2) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
    GxB_set (GxB_NTHREADS, 4) ;
    GxB_set (GxB_CHUNK, (double) 10000) ;
    GxB_set (GxB_BURBLE, true) ;
    GxB_set (GxB_PRINTF, mexPrintf) ;
\end{verbatim} }

The memory pool parameter sets an upper bound on the number of freed blocks of
memory that SuiteSparse:GraphBLAS keeps in its internal memory pool for future
allocations.   \verb'free_pool_limit'  is an \verb'int64_t' array of size 64,
and \verb'free_pool_limit [k]' is the upper bound on the number of blocks
of size $2^k$ that are kept in the pool.  Passing in a \verb'NULL' pointer
sets the defaults.  Passing in an array of size 64 whose entries are all zero
disables the memory pool entirely.

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

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

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

For example, the following usage sets the hypersparsity ratio to 0.2, and the
format of \verb'GxB_BY_COL', for a particular matrix \verb'A', and sets the
sparsity control to \verb'GxB_SPARSE+GxB_FULL' (allowing the matrix to be held
in CSC or FullC formats, but not BitmapC or HyperCSC).  SuiteSparse:GraphBLAS
currently applies these changes immediately, but since they are simply hints,
future versions of SuiteSparse:GraphBLAS may delay the change in format if it
can obtain better performance.

If the setting is just \verb'GxB_FULL' and some entries are missing, then
the matrix is held in bitmap format.

{\footnotesize
\begin{verbatim}
    GxB_set (A, GxB_HYPER_SWITCH, 0.2) ;
    GxB_set (A, GxB_FORMAT, GxB_BY_COL) ;
    GxB_set (A, GxB_SPARSITY_CONTROL, GxB_SPARSE + GxB_FULL) ;
\end{verbatim} }

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

If an error occurs, \verb'GrB_error(&err,A)' returns details about the error.

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

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

This usage is similar to \verb'GrB_Descriptor_set', just with a name that is
consistent with the other usages of this generic function.  Unlike
\verb'GrB_Descriptor_set', the \verb'field' may also be \verb'GxB_NTHREADS',
\verb'GxB_CHUNK', \verb'GxB_SORT', \verb'GxB_COMPRESSION', or
\verb'GxB_IMPORT'.  Refer to Sections~\ref{descriptor_set}~and~\ref{desc_set}
for details.  If an error occurs, \verb'GrB_error(&err,desc)' returns details
about the error.

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

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

This usage of \verb'GxB_get' retrieves the value of a global option.  The
\verb'field' parameter can be one of the following:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
        \hline
        \verb'GxB_HYPER_SWITCH'         & sparse/hyper setting \\
        \verb'GxB_BITMAP_SWITCH'        & bitmap/sparse setting \\
        \verb'GxB_FORMAT'               & by row/col setting \\
        \verb'GxB_MODE'                 & blocking / non-blocking \\
        \verb'GxB_NTHREADS'             & default number of threads \\
        \verb'GxB_CHUNK'                & default chunk size \\
        \verb'GxB_BURBLE'       & burble setting \\
        \verb'GxB_PRINTF'       & printf function \\
        \verb'GxB_FLUSH'        & flush function \\
        \verb'GxB_MEMORY_POOL'  & memory pool control \\
        \verb'GxB_PRINT_1BASED' & for printing matrices/vectors \\
        \hline
        \verb'GxB_LIBRARY_NAME'         & the string
                                        \verb'"SuiteSparse:GraphBLAS"' \\
        \verb'GxB_LIBRARY_VERSION'      & \verb'int' array of size 3 \\
        \verb'GxB_LIBRARY_DATE'         & date of release \\
        \verb'GxB_LIBRARY_ABOUT'        & author, copyright \\
        \verb'GxB_LIBRARY_LICENSE'      & license for the library \\
        \verb'GxB_LIBRARY_COMPILE_DATE' & date of compilation \\
        \verb'GxB_LIBRARY_COMPILE_TIME' & time of compilation \\
        \verb'GxB_LIBRARY_OPENMP'       & library compiled with OpenMP\\
        \verb'GxB_LIBRARY_URL'          & URL of the library \\
        \hline
        \verb'GxB_API_VERSION'  & GraphBLAS C API Specification Version \\
        \verb'GxB_API_DATE'     & date of the C API Spec.  \\
        \verb'GxB_API_ABOUT'    & about of the C API Spec. \\
        \verb'GxB_API_URL'      & URL of the specification \\
        \hline
\end{tabular}
}
\vspace{0.2in}

For example:

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

    double b [GxB_BITMAP_SWITCH] ;
    GxB_get (GxB_BITMAP_SWITCH, b) ;
    for (int k = 0 ; k < GxB_NBITMAP_SWITCH ; k++)
    {
        printf ("bitmap_switch [%d] = %g ", k, b [k]) ;
        if (k == 0)
        {
            printf ("for vectors and matrices with 1 row or column\n") ;
        }
        else if (k == GxB_NBITMAP_SWITCH - 1) 
        {
            printf ("for matrices with min dimension > %d\n", 1 << (k-1)) ;
        }
        else
        {
            printf ("for matrices with min dimension %d to %d\n",
                (1 << (k-1)) + 1, 1 << k) ;
        }
    }

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

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

    int nthreads_max ;
    GxB_get (GxB_NTHREADS, &nthreads_max) ;
    printf ("max # of threads to use: %d\n", nthreads_max) ;

    double chunk ;
    GxB_get (GxB_CHUNK, &chunk) ;
    printf ("chunk size: %g\n", chunk) ;

    int64_t free_pool_limit [64] ;
    GxB_get (GxB_MEMORY_POOL, free_pool_limit) ;
    for (int k = 0 ; k < 64 ; k++)
        printf ("pool %d: limit %ld\n", free_pool_limit [k]) ;

    char *name ;
    int ver [3] ;
    GxB_get (GxB_LIBRARY_NAME, &name) ;
    GxB_get (GxB_LIBRARY_VERSION, ver) ;
    printf ("Library %s, version %d.%d.%d\n", name, ver [0], ver [1], ver [2]) ; \end{verbatim} }

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

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

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

\vspace{-0.1in}
{\footnotesize
\begin{verbatim}
    double h, b  ;
    int sparsity, scontrol ;
    GxB_get (A, GxB_SPARSITY_STATUS, &sparsity) ;
    GxB_get (A, GxB_HYPER_SWITCH, &h) ;
    printf ("matrix A has hyper_switch = %g\n", h) ;
    GxB_get (A, GxB_BITMAP_SWITCH, &b) ;
    printf ("matrix A has bitmap_switch = %g\n", b) ;
    switch (sparsity)
    {
        case GxB_HYPERSPARSE: printf ("matrix A is hypersparse\n") ; break ;
        case GxB_SPARSE:      printf ("matrix A is sparse\n"     ) ; break ;
        case GxB_BITMAP:      printf ("matrix A is bitmap\n"     ) ; break ;
        case GxB_FULL:        printf ("matrix A is full\n"       ) ; break ;
    }
    GxB_Format_Value s ;
    GxB_get (A, GxB_FORMAT, &s) ;
    printf ("matrix A is stored by %s\n", (s == GxB_BY_COL) ? "col" : "row") ;
    GxB_get (A, GxB_SPARSITY_CONTROL, &scontrol) ;
    if (scontrol & GxB_HYPERSPARSE) printf ("A may become hypersparse\n") ;
    if (scontrol & GxB_SPARSE     ) printf ("A may become sparse\n") ;
    if (scontrol & GxB_BITMAP     ) printf ("A may become bitmap\n") ;
    if (scontrol & GxB_FULL       ) printf ("A may become full\n") ; \end{verbatim} }

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

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

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

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

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

\noindent
To set/get the global options:

    {\footnotesize
    \begin{verbatim}
    GxB_set (GxB_HYPER_SWITCH, double h) ;
    GxB_set (GxB_HYPER_SWITCH, GxB_ALWAYS_HYPER) ;
    GxB_set (GxB_HYPER_SWITCH, GxB_NEVER_HYPER) ;
    GxB_get (GxB_HYPER_SWITCH, double *h) ;
    double b [GxB_NBITMAP_SWITCH] ;
    GxB_set (GxB_BITMAP_SWITCH, b) ;
    GxB_set (GxB_BITMAP_SWITCH, NULL) ;     // set defaults
    GxB_get (GxB_BITMAP_SWITCH, b) ;
    GxB_set (GxB_FORMAT, GxB_BY_ROW) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
    GxB_get (GxB_FORMAT, GxB_Format_Value *s) ;
    GxB_set (GxB_NTHREADS, int nthreads_max) ;
    GxB_get (GxB_NTHREADS, int *nthreads_max) ;
    GxB_set (GxB_CHUNK, double chunk) ;
    GxB_get (GxB_CHUNK, double *chunk) ;
    GxB_set (GxB_BURBLE, bool burble) ;
    GxB_get (GxB_BURBLE, bool *burble) ;
    GxB_set (GxB_PRINTF, void *printf_function) ;
    GxB_get (GxB_PRINTF, void **printf_function) ;
    GxB_set (GxB_FLUSH, void *flush_function) ;
    GxB_get (GxB_FLUSH, void **flush_function) ;
    int64_t free_pool_limit [64] ;
    GxB_set (GxB_MEMORY_POOL, free_pool_limit) ;
    GxB_set (GxB_MEMORY_POOL, NULL) ;     // set defaults
    GxB_get (GxB_MEMORY_POOL, free_pool_limit) ;
    GxB_set (GxB_PRINT_1BASED, bool onebased) ;
    GxB_get (GxB_PRINT_1BASED, bool *onebased) ; \end{verbatim} }

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

    {\footnotesize
    \begin{verbatim}
    GxB_get (GxB_MODE,                 GrB_Mode *mode) ;
    GxB_get (GxB_LIBRARY_NAME,         char **) ;
    GxB_get (GxB_LIBRARY_VERSION,      int *) ;
    GxB_get (GxB_LIBRARY_DATE,         char **) ;
    GxB_get (GxB_LIBRARY_ABOUT,        char **) ;
    GxB_get (GxB_LIBRARY_LICENSE,      char **) ;
    GxB_get (GxB_LIBRARY_COMPILE_DATE, char **) ;
    GxB_get (GxB_LIBRARY_COMPILE_TIME, char **) ;
    GxB_get (GxB_LIBRARY_OPENMP,       bool *) ;
    GxB_get (GxB_LIBRARY_URL,          char **) ;
    GxB_get (GxB_API_VERSION,          int *) ;
    GxB_get (GxB_API_DATE,             char **) ;
    GxB_get (GxB_API_ABOUT,            char **) ;
    GxB_get (GxB_API_URL,              char **) ; \end{verbatim} }

\noindent
To set/get a matrix option or status

    {\footnotesize
    \begin{verbatim}
    GxB_set (GrB_Matrix A, GxB_HYPER_SWITCH, double h) ;
    GxB_set (GrB_Matrix A, GxB_HYPER_SWITCH, GxB_ALWAYS_HYPER) ;
    GxB_set (GrB_Matrix A, GxB_HYPER_SWITCH, GxB_NEVER_HYPER) ;
    GxB_get (GrB_Matrix A, GxB_HYPER_SWITCH, double *h) ;
    GxB_set (GrB_Matrix A, GxB_BITMAP_SWITCH, double b) ;
    GxB_get (GrB_Matrix A, GxB_BITMAP_SWITCH, double *b) ;
    GxB_set (GrB_Matrix A, GxB_FORMAT, GxB_BY_ROW) ;
    GxB_set (GrB_Matrix A, GxB_FORMAT, GxB_BY_COL) ;
    GxB_get (GrB_Matrix A, GxB_FORMAT, GxB_Format_Value *s) ;
    GxB_set (GrB_Matrix A, GxB_SPARSITY_CONTROL, GxB_AUTO_SPARSITY) ;
    GxB_set (GrB_Matrix A, GxB_SPARSITY_CONTROL, scontrol) ;
    GxB_get (GrB_Matrix A, GxB_SPARSITY_CONTROL, int *scontrol) ;
    GxB_get (GrB_Matrix A, GxB_SPARSITY_STATUS, int *sparsity) ; \end{verbatim} }

\noindent
To set/get a vector option or status:

    {\footnotesize
    \begin{verbatim}
    GxB_set (GrB_Vector v, GxB_BITMAP_SWITCH, double b) ;
    GxB_get (GrB_Vector v, GxB_BITMAP_SWITCH, double *b) ;
    GxB_set (GrB_Vector v, GxB_FORMAT, GxB_BY_ROW) ;
    GxB_set (GrB_Vector v, GxB_FORMAT, GxB_BY_COL) ;
    GxB_get (GrB_Vector v, GxB_FORMAT, GxB_Format_Value *s) ;
    GxB_set (GrB_Vector v, GxB_SPARSITY_CONTROL, GxB_AUTO_SPARSITY) ;
    GxB_set (GrB_Vector v, GxB_SPARSITY_CONTROL, scontrol) ;
    GxB_get (GrB_Vector v, GxB_SPARSITY_CONTROL, int *scontrol) ;
    GxB_get (GrB_Vector v, GxB_SPARSITY_STATUS, int *sparsity) ; \end{verbatim} }

\noindent
To set/get a descriptor field:

    {\footnotesize
    \begin{verbatim}
    GxB_set (GrB_Descriptor d, GrB_OUTP, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GrB_OUTP, GrB_REPLACE) ;
    GxB_get (GrB_Descriptor d, GrB_OUTP, GrB_Desc_Value *v) ;
    GxB_set (GrB_Descriptor d, GrB_MASK, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GrB_MASK, GrB_COMP) ;
    GxB_set (GrB_Descriptor d, GrB_MASK, GrB_STRUCTURE) ;
    GxB_set (GrB_Descriptor d, GrB_MASK, GrB_COMP+GrB_STRUCTURE) ;
    GxB_get (GrB_Descriptor d, GrB_MASK, GrB_Desc_Value *v) ;
    GxB_set (GrB_Descriptor d, GrB_INP0, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GrB_INP0, GrB_TRAN) ;
    GxB_get (GrB_Descriptor d, GrB_INP0, GrB_Desc_Value *v) ;
    GxB_set (GrB_Descriptor d, GrB_INP1, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GrB_INP1, GrB_TRAN) ;
    GxB_get (GrB_Descriptor d, GrB_INP1, GrB_Desc_Value *v) ;
    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_DEFAULT) ;
    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_GUSTAVSON) ;
    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_HASH) ;
    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_SAXPY) ;
    GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_DOT) ;
    GxB_get (GrB_Descriptor d, GrB_AxB_METHOD, GrB_Desc_Value *v) ;
    GxB_set (GrB_Descriptor d, GxB_NTHREADS, int nthreads) ;
    GxB_get (GrB_Descriptor d, GxB_NTHREADS, int *nthreads) ;
    GxB_set (GrB_Descriptor d, GxB_CHUNK, double chunk) ;
    GxB_get (GrB_Descriptor d, GxB_CHUNK, double *chunk) ;
    GxB_set (GrB_Descriptor d, GxB_SORT, sort) ;
    GxB_get (GrB_Descriptor d, GxB_SORT, int *sort) ;
    GxB_set (GrB_Descriptor d, GxB_COMPRESSION, GxB_FAST_IMPORT) ;
    GxB_set (GrB_Descriptor d, GxB_COMPRESSION, GxB_SECURE_IMPORT) ;
    GxB_get (GrB_Descriptor d, GxB_COMPRESSION, GrB_Desc_Value *method) ;
    GxB_set (GrB_Descriptor d, GxB_IMPORT, int method) ;
    GxB_get (GrB_Descriptor d, GxB_IMPORT, int *method) ; \end{verbatim} }

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

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

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

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

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

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

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

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

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

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

\begin{enumerate}
\item
    An explicit list of indices, such as \verb'I = [2 1 4 7 2]' in MATLAB
    notation, is handled by passing in \verb'I' as a pointer to an array of
    size 5, and passing \verb'ni=5' as the size of the list.
    The length of the explicit list is \verb'ni=|I|'.
    Duplicates may appear, except that for some uses of \verb'GrB_assign'
    and \verb'GxB_subassign', duplicates lead to undefined behavior
    according to the GraphBLAS C API Specification.
    SuiteSparse:GraphBLAS specifies how duplicates are handled in all cases,
    as an addition to the specification.
    See Section~\ref{duplicates} for details.

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

    \begin{alert}
    {\bf SPEC:} If \verb'I' or \verb'J' are \verb'GrB_ALL', the specification
    requires that \verb'ni' be passed in as \verb'm' (the number of rows)
    and \verb'nj' be passed in as \verb'n'.  Any other value is an error.
    SuiteSparse:GraphBLAS ignores these scalar inputs and treats them as if
    they are equal to their only possible correct value.
    \end{alert}

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

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

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

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

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

    \vspace{-0.05in}
    The \verb'GxB_STRIDE' sequence is the same as the \verb'List' generated by
    the following for loop:

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

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

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

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

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

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

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

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

\end{enumerate}

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

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

\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^{\sf T}\langle m^{\sf T}\rangle = w^{\sf T}\odot u^{\sf T}A}$ \\
\verb'GrB_mxv'       & matrix-vector multiply  & ${\bf w \langle m \rangle = w \odot Au}$ \\
\hline
\verb'GrB_eWiseMult' & element-wise,           & ${\bf C \langle M \rangle = C \odot (A \otimes B)}$ \\
                     & set intersection        & ${\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 union               & ${\bf w \langle m \rangle = w \odot (u \oplus  v)}$ \\
\hline
\verb'GxB_eWiseUnion'& element-wise,           & ${\bf C \langle M \rangle = C \odot (A \oplus  B)}$ \\
                     & set union               & ${\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)}$ \\
                     & apply binary operator   & ${\bf C \langle M \rangle = C \odot} f(x,{\bf A})$ \\
                     &                         & ${\bf C \langle M \rangle = C \odot} f({\bf A},y)$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f(x,{\bf x})$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f({\bf u},y)$ \\
                     & apply index-unary op    & ${\bf C \langle M \rangle = C \odot} f({\bf A},i,j,k)$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} f({\bf u},i,0,k)$ \\
\hline
\verb'GrB_select'    & select entries          & ${\bf C \langle M \rangle = C \odot} \mbox{select}({\bf A},i,j,k)$ \\
                     &                         & ${\bf w \langle m \rangle = w \odot} \mbox{select}({\bf u},i,0,k)$ \\
\hline
\verb'GrB_reduce'    & reduce to vector        & ${\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]$ \\
                     & reduce to scalar        & $s = s \odot [{\oplus}_{ij}  {\bf A}(I,J)]$ \\
\hline
\verb'GrB_transpose' & transpose               & ${\bf C \langle M \rangle = C \odot A^{\sf T}}$ \\
\hline
\verb'GrB_kronecker' & Kronecker product       & ${\bf C \langle M \rangle = C \odot \mbox{kron}(A, B)}$ \\
\hline
\end{tabular}
}
\vspace{0.2in}

If an error occurs, \verb'GrB_error(&err,C)' or \verb'GrB_error(&err,w)'
returns details about the error, for operations that return a modified matrix
\verb'C' or vector \verb'w'.  The only operation that cannot return an error
string is reduction to a scalar with \verb'GrB_reduce'.

\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 in \verb'GraphBLAS/Test'.  The actual algorithm
exploits sparsity and does not take $O(n^3)$ time, but it computes the
following:

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

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

\paragraph{\bf Performance considerations:}
Suppose all matrices are in \verb'GxB_BY_COL' format, and \verb'B' is extremely
sparse but \verb'A' is not as sparse.  Then computing \verb'C=A*B' is very
fast, and much faster than when \verb'A' is extremely sparse.  For example, if
\verb'A' is square and \verb'B' is a column vector that is all nonzero except
for one entry \verb'B(j,0)=1', then \verb'C=A*B' is the same as extracting
column \verb'A(:,j)'.  This is very fast if \verb'A' is stored by column but
slow if \verb'A' is stored by row.  If \verb'A' is a sparse row with a single
entry \verb'A(0,i)=1', then \verb'C=A*B' is the same as extracting row
\verb'B(i,:)'.  This is fast if \verb'B' is stored by row but slow if \verb'B'
is stored by column.

If the user application needs to repeatedly extract rows and columns from a
matrix, whether by matrix multiplication or by \verb'GrB_extract', then keep
two copies: one stored by row, and other by column, and use the copy that
results in the fastest computation.

By default, \verb'GrB_mxm', \verb'GrB_mxv', \verb'GrB_vxm', and
\verb'GrB_reduce' (to vector) can return their result in a jumbled state, with
the sort left pending.  It can sometimes be faster for these methods to do the
sort as they compute their result.  Use the \verb'GxB_SORT' descriptor setting
to select this option.  Refer to Section~\ref{descriptor} for details.

\newpage
%===============================================================================
\subsection{{\sf GrB\_vxm:} vector-matrix multiply} %===========================
%===============================================================================
\label{vxm}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_vxm                    // w'<mask> = accum (w, u'*A)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_Semiring semiring,    // defines '+' and '*' for u'*A
    const GrB_Vector u,             // first input:  vector u
    const GrB_Matrix A,             // second input: matrix A
    const GrB_Descriptor desc       // descriptor for w, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_vxm' multiplies a row vector \verb"u'" times a matrix \verb'A'.  The
matrix \verb'A' may be first transposed according to \verb'desc' (as the second
input, \verb'GrB_INP1'); the column vector \verb'u' is never transposed via the
descriptor.  The inputs \verb'u' and \verb'A' are typecasted to match the
\verb'xtype' and \verb'ytype' inputs, respectively, of the multiply operator of
the \verb'semiring'.  Next, an intermediate column vector \verb"t=A'*u" is
computed on the \verb'semiring' using the same method as \verb'GrB_mxm'.
Finally, the column vector \verb't' is typecasted from the \verb'ztype' of the
multiply operator of the \verb'semiring' into the type of \verb'w', and the
results are written back into \verb'w' using the optional accumulator
\verb'accum' and \verb'mask'.

The last step is ${\bf w \langle m \rangle  = w \odot t}$, as described
in Section~\ref{accummask}, except that all the
terms are column vectors instead of matrices.

\paragraph{\bf Performance considerations:} % u'=u'*A
If the \verb'GxB_FORMAT' of \verb'A' is \verb'GxB_BY_ROW', and the default
descriptor is used (\verb'A' is not transposed), then \verb'GrB_vxm' is faster
than than \verb'GrB_mxv' with its default descriptor, when the vector \verb'u'
is very sparse.
However, if the \verb'GxB_FORMAT' of \verb'A' is \verb'GxB_BY_COL', then
\verb'GrB_mxv' with its default descriptor is faster than \verb'GrB_vxm' with
its default descriptor, when the vector \verb'u' is very sparse.
Using the non-default \verb'GrB_TRAN' descriptor for \verb'A' makes the
\verb'GrB_vxm' operation equivalent to \verb'GrB_mxv' with its default
descriptor (with the operands reversed in the multiplier, as well).  The
reverse is true as well; \verb'GrB_mxv' with \verb'GrB_TRAN' is the same as
\verb'GrB_vxm' with a default descriptor.

\newpage
%===============================================================================
\subsection{{\sf GrB\_mxv:} matrix-vector multiply} %===========================
%===============================================================================
\label{mxv}

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

\verb'GrB_mxv' multiplies a matrix \verb'A' times a column vector \verb'u'.
The matrix \verb'A' may be first transposed according to \verb'desc' (as the
first input); the column vector \verb'u' is never transposed via the
descriptor.  The inputs \verb'A' and \verb'u' are typecasted to match the
\verb'xtype' and \verb'ytype' inputs, respectively, of the multiply operator of
the \verb'semiring'. Next, an intermediate column vector \verb't=A*u' is
computed on the \verb'semiring' using the same method as \verb'GrB_mxm'.
Finally, the column vector \verb't' is typecasted from the \verb'ztype' of the
multiply operator of the \verb'semiring' into the type of \verb'w', and the
results are written back into \verb'w' using the optional accumulator
\verb'accum' and \verb'mask'.

The last step is ${\bf w \langle m \rangle  = w \odot t}$, as described
in Section~\ref{accummask}, except that all the terms are column vectors instead
of matrices.

\paragraph{\bf Performance considerations:} % u=A*u
Refer to the discussion of \verb'GrB_vxm'.  In SuiteSparse:GraphBLAS,
\verb'GrB_mxv' is very efficient when \verb'u' is sparse or dense, when the
default descriptor is used, and when the matrix is \verb'GxB_BY_COL'.  When
\verb'u' is very sparse and \verb'GrB_INP0' is set to its non-default
\verb'GrB_TRAN', then this method is not efficient if the matrix is in
\verb'GxB_BY_COL' format.  If an application needs to perform \verb"A'*u"
repeatedly where \verb'u' is very sparse, then use the \verb'GxB_BY_ROW' format
for \verb'A' instead.

\newpage
%===============================================================================
\subsection{{\sf GrB\_eWiseMult:} element-wise operations, set intersection} %==
%===============================================================================
\label{eWiseMult}

Element-wise ``multiplication'' is shorthand for applying a binary operator
element-wise on two matrices or vectors \verb'A' and \verb'B', for all entries
that appear in the set intersection of the patterns of \verb'A' and \verb'B'.
This is like \verb'A.*B' for two sparse matrices in MATLAB, except that in
GraphBLAS any binary operator can be used, not just multiplication.

The pattern of the result of the element-wise ``multiplication'' is exactly
this set intersection.  Entries in \verb'A' but not \verb'B', or visa versa, do
not appear in the result.

Let $\otimes$ denote the binary operator to be used.  The computation ${\bf T =
A \otimes B}$ is given below.  Entries not in the intersection of ${\bf A}$ and
${\bf B}$ do not appear in the pattern of ${\bf T}$.  That is:
    \vspace{-0.2in}
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> for all entries $(i,j)$ in ${\bf A \cap B}$ \\
    \> \> $t_{ij} = a_{ij} \otimes b_{ij}$ \\
    \end{tabbing} }
    \vspace{-0.2in}

Depending on what kind of operator is used and what the implicit value is
assumed to be, this can give the Hadamard product.  This is the case for
\verb'A.*B' in MATLAB since the implicit value is zero.  However, computing a
Hadamard product is not necessarily the goal of the \verb'eWiseMult' operation.
It simply applies any binary operator, built-in or user-defined, to the set
intersection of \verb'A' and \verb'B', and discards any entry outside this
intersection.  Its usefulness in a user's application does not depend upon it
computing a Hadamard product in all cases.  The operator need not be
associative, commutative, nor have any particular property except for type
compatibility with \verb'A' and \verb'B', and the output matrix \verb'C'.

The generic name for this operation is \verb'GrB_eWiseMult', which can be used
for both matrices and vectors.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_eWiseMult:} 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_Vector_eWiseMult' 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\_Matrix\_eWiseMult:} 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_Matrix_eWiseMult' 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\_Vector\_eWiseAdd:} 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_Vector_eWiseAdd' 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\_Matrix\_eWiseAdd:} 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_Matrix_eWiseAdd' 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 GxB\_eWiseUnion:} element-wise operations, set union} %========
%===============================================================================
\label{eWiseUnion}

\verb'GxB_eWiseUnion' computes a result with the same pattern
\verb'GrB_eWiseAdd', namely, a set union of its two inputs.  It differs in how
the binary operator is applied.

Let $\oplus$ denote the binary operator to be used.  The operator is applied to
every entry in $\bf A$ and $\bf B$.  A pair of scalars, $\alpha$ and $\beta$
(\verb'alpha' and \verb'beta' in the API, respectively) define the
inputs to the operator when entries are present in one matrix but not the
other.

    \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} \oplus \beta $ \\
    \> for all entries $(i,j)$ in ${\bf B \setminus A}$ \\
    \> \> $t_{ij} = \alpha \oplus b_{ij}$
    \end{tabbing}
    }

\verb'GxB_eWiseUnion' is useful in contexts where \verb'GrB_eWiseAdd' cannot be
used because of the typecasting rules of GraphBLAS.  In particular, suppose
\verb'A' and \verb'B' are matrices with a user-defined type, and suppose
\verb'<' is a user-defined operator that compares two entries of this type and
returns a Boolean value.  Then \verb'C=A<B' can be computed with
\verb'GxB_eWiseUnion' but not with \verb'GrB_eWiseAdd'.  In the latter, if
\verb'A(i,j)' is present but \verb'B(i,j)' is not, then \verb'A(i,j)' must
typecasted to the type of \verb'C' (\verb'GrB_BOOL' in this case), and the
assigment \verb'C(i,j) = (bool) A(i,j)' would be performed.  This is not
possible because user-defined types cannot be typecasted to any other type.

Another advantage of \verb'GxB_eWiseUnion' is its performance.  For example,
the MATLAB/Octave expression \verb'C=A-B' computes \verb'C(i,j)=-B(i,j)' when
\verb'A(i,j)' is not present.  This cannot be done with a single call
\verb'GrB_eWiseAdd', but it can be done with a single call to
\verb'GxB_eWiseUnion', with the \verb'GrB_MINUS_FP64' operator, and with both
\verb'alpha' and \verb'beta' scalars equal to zero.  It is possible to
compute this result with a temporary matrix, \verb'E=-B', computed with
\verb'GrB_apply' and \verb'GrB_AINV_FP64', followed by a call to
\verb'GrB_eWiseAdd' to compute \verb'C=A+E', but this is slower than a single
call to \verb'GxB_eWiseUnion', and uses more memory.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_eWiseUnion:} element-wise vector addition}
%-------------------------------------------------------------------------------
\label{eWiseUnion_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_eWiseUnion             // 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 GrB_BinaryOp add,         // defines '+' for t=u+v
    const GrB_Vector u,             // first input:  vector u
    const GrB_Scalar alpha,
    const GrB_Vector v,             // second input: vector v
    const GrB_Scalar beta,
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

Identical to \verb'GrB_Vector_eWiseAdd' except that two scalars are used
to define how to compute the result when entries are present in one of
the two input vectors (\verb'u' and \verb'v'), but not the other.
Each of the two input scalars, \verb'alpha' and \verb'beta'
must contain an entry.
When computing the result \verb't=u+v',
if \verb'u(i)' is present but \verb'v(i)' is not, then \verb't(i)=u(i)+beta'.
Likewise,
if \verb'v(i)' is present but \verb'u(i)' is not, then \verb't(i)=alpha+v(i)',
where \verb'+' denotes the binary operator, \verb'add'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_eWiseUnion:} element-wise matrix addition}
%-------------------------------------------------------------------------------
\label{eWiseUnion_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_eWiseUnion             // C<M> = 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_BinaryOp add,         // defines '+' for T=A+B
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Scalar alpha,
    const GrB_Matrix B,             // second input: matrix B
    const GrB_Scalar beta,
    const GrB_Descriptor desc       // descriptor for C, M, A, and B
) ;
\end{verbatim} } \end{mdframed}

Identical to \verb'GrB_Matrix_eWiseAdd' except that two scalars are used
to define how to compute the result when entries are present in one of
the two input matrices (\verb'A' and \verb'B'), but not the other.
Each of the two input scalars, \verb'alpha' and \verb'beta'
must contain an entry.
When computing the result \verb'T=A+B',
if \verb'A(i,j)' is present but \verb'B(i,j))' is not, then \verb'T(i,j)=A(i,j)+beta'.
Likewise,
if \verb'B(i,j)' is present but \verb'A(i,j)' is not, then \verb'T(i,j)=alpha+B(i,j)',
where \verb'+' denotes the binary operator, \verb'add'.

\newpage
%===============================================================================
\subsection{{\sf GrB\_extract:} submatrix extraction } %========================
%===============================================================================
\label{extract}

The \verb'GrB_extract' function is a generic name for three specific functions:
\verb'GrB_Vector_extract', \verb'GrB_Col_extract', and
\verb'GrB_Matrix_extract'.  The generic name appears in the function signature,
but the specific function name is used when describing what each variation
does.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_extract:} extract subvector from vector}
%-------------------------------------------------------------------------------
\label{extract_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_extract                // w<mask> = accum (w, u(I))
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_Vector u,             // first input:  vector u
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_extract' extracts a subvector from another vector, identical
to \verb't = u (I)' in MATLAB where \verb'I' is an integer vector of row
indices.  Refer to \verb'GrB_Matrix_extract' for further details; vector
extraction is the same as matrix extraction with \verb'n'-by-1 matrices.
See Section~\ref{colon} for a description of \verb'I' and \verb'ni'.
The final step is ${\bf w \langle m \rangle  = w \odot
t}$, as described in Section~\ref{accummask}, except that all the terms are
column vectors instead of matrices.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_extract:} extract submatrix from matrix}
%-------------------------------------------------------------------------------
\label{extract_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_extract                // C<Mask> = accum (C, A(I,J))
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C, Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_extract' extracts a submatrix from another matrix, identical
to \verb'T = A(I,J)' in MATLAB where \verb'I' and \verb'J' are integer vectors
of row and column indices, respectively, except that indices are zero-based in
GraphBLAS and one-based in MATLAB.  The input matrix \verb'A' may be transposed
first, via the descriptor.  The type of \verb'T' and \verb'A' are the same.
The size of \verb'C' is \verb'|I|'-by-\verb'|J|'.
Entries outside \verb'A(I,J)' are not accessed and do not take part in the
computation.  More precisely, assuming the matrix \verb'A' is not transposed,
the matrix \verb'T' is defined as follows:

    \vspace{-0.1in}
    {\footnotesize
    \begin{verbatim}
    T.matrix  = zeros (ni, nj) ;    % a matrix of size ni-by-nj
    T.pattern = false (ni, nj) ;
    for i = 1:ni
        for j = 1:nj
            if (A (I(i),J(j)).pattern)
                T (i,j).matrix  = A (I(i),J(j)).matrix ;
                T (i,j).pattern = true ;
            end
        end
    end \end{verbatim}}

\vspace{-0.1in}
If duplicate indices are present in \verb'I' or \verb'J', the above method
defines the result in \verb'T'.  Duplicates result in the same values of
\verb'A' being copied into different places in \verb'T'.
See Section~\ref{colon} for a description of the row indices
\verb'I' and \verb'ni', and the column indices
\verb'J' and \verb'nj'.
The final step is ${\bf C \langle M \rangle  = C \odot
T}$, as described in Section~\ref{accummask}.

\paragraph{\bf Performance considerations:} % C=A(I,J)
If \verb'A' is not transposed via input descriptor: if \verb'|I|' is small,
then it is fastest if \verb'A' is \verb'GxB_BY_ROW'; if
\verb'|J|' is small, then it is fastest if \verb'A' is
\verb'GxB_BY_COL'.  The opposite is true if \verb'A' is transposed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Col\_extract:} extract column vector from matrix}
%-------------------------------------------------------------------------------
\label{extract_column}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_extract                // w<mask> = accum (w, A(I,j))
(
    GrB_Vector w,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index j,              // column index
    const GrB_Descriptor desc       // descriptor for w, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Col_extract' extracts a subvector from a matrix, identical to
\verb't = A (I,j)' in MATLAB where \verb'I' is an integer vector of row indices
and where \verb'j' is a single column index.  The input matrix \verb'A' may be
transposed first, via the descriptor, which results in the extraction of a
single row \verb'j' from the matrix \verb'A', the result of which is a column
vector \verb'w'.  The type of \verb't' and \verb'A' are the same.
The size of \verb'w' is \verb'|I|'-by-1.

See Section~\ref{colon} for a description of the row indices
\verb'I' and \verb'ni'.
The final step is ${\bf w \langle m
\rangle  = w \odot t}$, as described in Section~\ref{accummask}, except that
all the terms are column vectors instead of matrices.

\paragraph{\bf Performance considerations:} % w = A(I,j)
If \verb'A' is not transposed: it is fastest if the format of \verb'A' is
\verb'GxB_BY_COL'.  The opposite is true if \verb'A' is transposed.

\newpage
%===============================================================================
\subsection{{\sf GxB\_subassign:} submatrix assignment} %=======================
%===============================================================================
\label{subassign}

The methods described in this section are all variations of the form
\verb'C(I,J)=A', which modifies a submatrix of the matrix \verb'C'.  All
methods can be used in their generic form with the single name
\verb'GxB_subassign'.  This is reflected in the prototypes.  However, to avoid
confusion between the different kinds of assignment, the name of the specific
function is used when describing each variation.  If the discussion applies to
all variations, the simple name \verb'GxB_subassign' is used.

See Section~\ref{colon} for a description of the row indices
\verb'I' and \verb'ni', and the column indices
\verb'J' and \verb'nj'.

\verb'GxB_subassign' is very similar to \verb'GrB_assign', described in
Section~\ref{assign}.  The two operations are compared and contrasted in
Section~\ref{compare_assign}.  For a discussion of how duplicate indices
are handled in \verb'I' and \verb'J', see Section~\ref{duplicates}.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_subassign:} assign to a subvector }
%-------------------------------------------------------------------------------
\label{subassign_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // w(I)<mask> = accum (w(I),u)
(
    GrB_Vector w,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for w(I), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),t)
    const GrB_Vector u,             // first input:  vector u
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w(I) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_subassign' operates on a subvector \verb'w(I)' of \verb'w',
modifying it with the vector \verb'u'.  The method is identical to
\verb'GxB_Matrix_subassign' described in Section~\ref{subassign_matrix}, where
all matrices have a single column each.  The \verb'mask' has the same size as
\verb'w(I)' and \verb'u'.  The only other difference is that the input \verb'u'
in this method is not transposed via the \verb'GrB_INP0' descriptor.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_subassign:} assign to a submatrix }
%-------------------------------------------------------------------------------
\label{subassign_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // C(I,J)<Mask> = accum (C(I,J),A)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C(I,J), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C(I,J),T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(I,J), Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_subassign' operates only on a submatrix \verb'S' of \verb'C',
modifying it with the matrix \verb'A'.   For this operation, the result is not
the entire matrix \verb'C', but a submatrix \verb'S=C(I,J)' of \verb'C'.  The
steps taken are as follows, except that ${\bf A}$ may be optionally transposed
via the \verb'GrB_INP0' descriptor option.

\vspace{0.1in}
\begin{tabular}{lll}
\hline
Step & GraphBLAS & description \\
     & notation  & \\
\hline
1 & ${\bf S} = {\bf C(I,J)}$                             & extract the ${\bf C(I,J)}$ submatrix \\
2 & ${\bf S \langle M \rangle} = {\bf S} \odot {\bf A}$  & apply the accumulator/mask to the submatrix ${\bf S}$\\
3 & ${\bf C(I,J)}= {\bf S}$                              & put the submatrix ${\bf S}$ back into ${\bf C(I,J)}$ \\
\hline
\end{tabular}
\vspace{0.1in}

The accumulator/mask step in Step 2 is the same as for all other GraphBLAS
operations, described in Section~\ref{accummask}, except that for
\verb'GxB_subassign', it is applied to just the submatrix ${\bf S} = {\bf
C(I,J)}$, and thus the \verb'Mask' has the same size as ${\bf A}$,
${\bf S}$, and ${\bf C(I,J)}$.

The \verb'GxB_subassign' operation is the reverse of matrix extraction:

\begin{itemize}
\item
For submatrix extraction, \verb'GrB_Matrix_extract',
the submatrix \verb'A(I,J)' appears on the right-hand side of the assignment,
\verb'C=A(I,J)', and entries outside of the submatrix are not accessed and do
not take part in the computation.

\item
For submatrix assignment, \verb'GxB_Matrix_subassign',
the submatrix \verb'C(I,J)' appears on the left-hand-side of the assignment,
\verb'C(I,J)=A', and entries outside of the submatrix are not accessed and do
not take part in the computation.

\end{itemize}

In both methods, the accumulator and mask modify the submatrix of the
assignment; they simply differ on which side of the assignment the submatrix
resides on.  In both cases, if the \verb'Mask' matrix is present it is the same
size as the submatrix:

\begin{itemize}

\item
For submatrix extraction,
${\bf C \langle M \rangle = C \odot A(I,J)}$ is computed,
where the submatrix is on the right.
The mask ${\bf M}$ has the same size as the submatrix ${\bf A(I,J)}$.

\item
For submatrix assignment,
${\bf C(I,J) \langle M \rangle = C(I,J) \odot A}$ is computed,
where the submatrix is on the left.
The mask ${\bf M}$ has the same size as the submatrix ${\bf C(I,J)}$.

\end{itemize}

In Step 1, the submatrix \verb'S' is first computed by the
\verb'GrB_Matrix_extract' operation, \verb'S=C(I,J)'.

Step 2 accumulates the results ${\bf S \langle M \rangle  = S \odot T}$,
exactly as described in Section~\ref{accummask}, but operating on the submatrix
${\bf S}$, not ${\bf C}$, using the optional \verb'Mask' and \verb'accum'
operator.  The matrix ${\bf T}$ is simply ${\bf T}={\bf A}$, or ${\bf T}={\bf
A}^{\sf T}$ if ${\bf A}$ is transposed via the \verb'desc' descriptor,
\verb'GrB_INP0'.  The \verb'GrB_REPLACE' option in the descriptor clears ${\bf
S}$ after computing ${\bf Z = T}$ or ${\bf Z = C \odot T}$, not all of ${\bf
C}$ since this operation can only modify the specified submatrix of ${\bf C}$.

Finally, Step 3 writes the result (which is the modified submatrix \verb'S' and
not all of \verb'C') back into the \verb'C' matrix that contains it, via the
assignment \verb'C(I,J)=S', using the reverse operation from the method
described for matrix extraction:

    {\footnotesize
    \begin{verbatim}
    for i = 1:ni
        for j = 1:nj
            if (S (i,j).pattern)
                C (I(i),J(j)).matrix = S (i,j).matrix ;
                C (I(i),J(j)).pattern = true ;
            end
        end
    end \end{verbatim}}

\paragraph{\bf Performance considerations:} % C(I,J) = A
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Col\_subassign:} assign to a sub-column of a matrix}
%-------------------------------------------------------------------------------
\label{subassign_column}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // C(I,j)<mask> = accum (C(I,j),u)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(I,j), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(I,j),t)
    const GrB_Vector u,             // input vector
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index j,              // column index
    const GrB_Descriptor desc       // descriptor for C(I,j) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Col_subassign' modifies a single sub-column of a matrix \verb'C'.  It
is the same as \verb'GxB_Matrix_subassign' where the index vector \verb'J[0]=j'
is a single column index (and thus \verb'nj=1'), and where all matrices in
\verb'GxB_Matrix_subassign' (except \verb'C') consist of a single column.  The
\verb'mask' vector has the same size as \verb'u' and the sub-column
\verb'C(I,j)'.  The input descriptor \verb'GrB_INP0' is ignored; the input
vector \verb'u' is not transposed.  Refer to \verb'GxB_Matrix_subassign' for
further details.

\paragraph{\bf Performance considerations:} % C(I,j) = u
\verb'GxB_Col_subassign' is much faster than \verb'GxB_Row_subassign' if the
format of \verb'C' is \verb'GxB_BY_COL'.  \verb'GxB_Row_subassign' is much
faster than \verb'GxB_Col_subassign' if the format of \verb'C' is
\verb'GxB_BY_ROW'.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Row\_subassign:} assign to a sub-row of a matrix}
%-------------------------------------------------------------------------------
\label{subassign_row}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // C(i,J)<mask'> = accum (C(i,J),u')
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(i,J), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(i,J),t)
    const GrB_Vector u,             // input vector
    const GrB_Index i,              // row index
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(i,J) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Row_subassign' modifies a single sub-row of a matrix \verb'C'.  It is
the same as \verb'GxB_Matrix_subassign' where the index vector \verb'I[0]=i' is
a single row index (and thus \verb'ni=1'), and where all matrices in
\verb'GxB_Matrix_subassign' (except \verb'C') consist of a single row.  The
\verb'mask' vector has the same size as \verb'u' and the sub-column
\verb'C(I,j)'.  The input descriptor \verb'GrB_INP0' is ignored; the input
vector \verb'u' is not transposed.  Refer to \verb'GxB_Matrix_subassign' for
further details.

\paragraph{\bf Performance considerations:} % C(i,J) = u'
\verb'GxB_Col_subassign' is much faster than \verb'GxB_Row_subassign' if the
format of \verb'C' is \verb'GxB_BY_COL'.  \verb'GxB_Row_subassign' is much
faster than \verb'GxB_Col_subassign' if the format of \verb'C' is
\verb'GxB_BY_ROW'.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_subassign\_$<$type$>$:} assign a scalar to a subvector}
%-------------------------------------------------------------------------------
\label{subassign_vector_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // w(I)<mask> = accum (w(I),x)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w(I), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),x)
    const <type> x,                 // scalar to assign to w(I)
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w(I) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_subassign_<type>' assigns a single scalar to an entire
subvector of the vector \verb'w'.  The operation is exactly like setting a
single entry in an \verb'n'-by-1 matrix, \verb'A(I,0) = x', where the column
index for a vector is implicitly \verb'j=0'.  For further details of this
function, see \verb'GxB_Matrix_subassign_<type>' in
Section~\ref{subassign_matrix_scalar}.

\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', with all entries present and equal to \verb'x',
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.
If \verb'x' is a \verb'GrB_Scalar' with no entry, then it is implicitly
expanded into a matrix \verb'A' of size \verb'ni' by \verb'nj', with no entries
present.

\paragraph{\bf Performance considerations:} % C(I,J) = scalar
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%===============================================================================
\subsection{{\sf GrB\_assign:} submatrix assignment} %==========================
%===============================================================================
\label{assign}

The methods described in this section are all variations of the form
\verb'C(I,J)=A', which modifies a submatrix of the matrix \verb'C'.  All
methods can be used in their generic form with the single name
\verb'GrB_assign'.  These methods are very similar to their
\verb'GxB_subassign' counterparts in Section~\ref{subassign}.  They differ
primarily in the size of the \verb'Mask', and how the \verb'GrB_REPLACE' option
works.  Section~\ref{compare_assign} compares
\verb'GxB_subassign' and \verb'GrB_assign'.

See Section~\ref{colon} for a description of
\verb'I', \verb'ni', \verb'J', and \verb'nj'.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_assign:} assign to a subvector }
%-------------------------------------------------------------------------------
\label{assign_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // w<mask>(I) = accum (w(I),u)
(
    GrB_Vector w,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),t)
    const GrB_Vector u,             // first input:  vector u
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_assign' operates on a subvector \verb'w(I)' of \verb'w',
modifying it with the vector \verb'u'.  The \verb'mask' vector has the same
size as \verb'w'.  The method is identical to \verb'GrB_Matrix_assign'
described in Section~\ref{assign_matrix}, where all matrices have a single
column each.  The only other difference is that the input \verb'u' in this
method is not transposed via the \verb'GrB_INP0' descriptor.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_assign:} assign to a submatrix }
%-------------------------------------------------------------------------------
\label{assign_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<Mask>(I,J) = accum (C(I,J),A)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C(I,J),T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C, Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_assign' operates on a submatrix \verb'S' of \verb'C',
modifying it with the matrix \verb'A'.  It may also modify all of \verb'C',
depending on the input descriptor \verb'desc' and the \verb'Mask'.

\vspace{0.1in}
\begin{tabular}{lll}
\hline
Step & GraphBLAS & description \\
     & notation  & \\
\hline
1 & ${\bf S} = {\bf C(I,J)}$                & extract ${\bf C(I,J)}$ submatrix \\
2 & ${\bf S} = {\bf S} \odot {\bf A}$       & apply the accumulator (but not the mask) to ${\bf S}$\\
3 & ${\bf Z} = {\bf C}$                     & make a copy of ${\bf C}$ \\
4 & ${\bf Z(I,J)} = {\bf S}$                & put the submatrix into ${\bf Z(I,J)}$ \\
5 & ${\bf C \langle M \rangle = Z}$         & apply the mask/replace phase to all of ${\bf C}$ \\
\hline
\end{tabular}
\vspace{0.1in}

In contrast to \verb'GxB_subassign', the \verb'Mask' has the same as \verb'C'.

Step 1 extracts the submatrix and then Step 2 applies the accumulator
(or ${\bf S}={\bf A}$ if \verb'accum' is \verb'NULL').  The \verb'Mask' is
not yet applied.

Step 3 makes a copy of the ${\bf C}$ matrix, and then Step 4 writes the
submatrix ${\bf S}$ into ${\bf Z}$.  This is the same as Step 3 of
\verb'GxB_subassign', except that it operates on a temporary matrix ${\bf Z}$.

Finally, Step 5 writes ${\bf Z}$ back into ${\bf C}$ via the \verb'Mask', using
the Mask/Replace Phase described in Section~\ref{accummask}.  If
\verb'GrB_REPLACE' is enabled, then all of ${\bf C}$ is cleared prior to
writing ${\bf Z}$ via the mask.  As a result, the \verb'GrB_REPLACE' option can
delete entries outside the ${\bf C(I,J)}$ submatrix.

\paragraph{\bf Performance considerations:} % C(I,J) = A
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Col\_assign:} assign to a sub-column of a matrix}
%-------------------------------------------------------------------------------
\label{assign_column}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<mask>(I,j) = accum (C(I,j),u)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(:,j), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(I,j),t)
    const GrB_Vector u,             // input vector
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index j,              // column index
    const GrB_Descriptor desc       // descriptor for C(:,j) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Col_assign' modifies a single sub-column of a matrix \verb'C'.  It is
the same as \verb'GrB_Matrix_assign' where the index vector \verb'J[0]=j' is a
single column index, and where all matrices in \verb'GrB_Matrix_assign' (except
\verb'C') consist of a single column.

Unlike \verb'GrB_Matrix_assign', the \verb'mask' is a vector with the same size
as a single column of \verb'C'.

The input descriptor \verb'GrB_INP0' is ignored; the input vector \verb'u' is
not transposed.  Refer to \verb'GrB_Matrix_assign' for further details.

\paragraph{\bf Performance considerations:} % C(I,j) = u
\verb'GrB_Col_assign' is much faster than \verb'GrB_Row_assign' if the format
of \verb'C' is \verb'GxB_BY_COL'.  \verb'GrB_Row_assign' is much faster than
\verb'GrB_Col_assign' if the format of \verb'C' is \verb'GxB_BY_ROW'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Row\_assign:} assign to a sub-row of a matrix}
%-------------------------------------------------------------------------------
\label{assign_row}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<mask'>(i,J) = accum (C(i,J),u')
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(i,:), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(i,J),t)
    const GrB_Vector u,             // input vector
    const GrB_Index i,              // row index
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(i,:) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Row_assign' modifies a single sub-row of a matrix \verb'C'.  It is
the same as \verb'GrB_Matrix_assign' where the index vector \verb'I[0]=i' is
a single row index, and where all matrices in \verb'GrB_Matrix_assign'
(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'GrB_Matrix_assign' for further details.

\paragraph{\bf Performance considerations:} % C(i,J) = u'
\verb'GrB_Col_assign' is much faster than \verb'GrB_Row_assign' if the format
of \verb'C' is \verb'GxB_BY_COL'.  \verb'GrB_Row_assign' is much faster than
\verb'GrB_Col_assign' if the format of \verb'C' is \verb'GxB_BY_ROW'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_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
(\ref{assign_matrix_scalar}).

Following the C API Specification, results are well-defined if \verb'I'
contains duplicate indices.  Duplicate indices are simply ignored.  See
Section~\ref{duplicates} for more details.

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

If \verb'x' is a \verb'GrB_Scalar' with no entry, then it is implicitly
expanded into a matrix \verb'A' of size \verb'ni' by \verb'nj', with no entries
present.

Following the C API Specification, results are well-defined if \verb'I' or
\verb'J' contain duplicate indices.  Duplicate indices are simply ignored.  See
Section~\ref{duplicates} for more details.

\paragraph{\bf Performance considerations:} % C(I,J) = scalar
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%===============================================================================
\subsection{Duplicate indices in {\sf GrB\_assign} and {\sf GxB\_subassign}}
%===============================================================================
\label{duplicates}

According to the GraphBLAS C API Specification if the index vectors \verb'I' or
\verb'J' contain duplicate indices, the results are undefined for
\verb'GrB_Matrix_assign', \verb'GrB_Matrix_assign', \verb'GrB_Col_assign', and
\verb'GrB_Row_assign'.  Only the scalar assignment operations
(\verb'GrB_Matrix_assign_TYPE' and \verb'GrB_Matrix_assign_TYPE') are
well-defined when duplicates appear in \verb'I' and \verb'J'.  In those two
functions, duplicate indices are ignored.

As an extension to the specification, SuiteSparse:GraphBLAS provides a
definition of how duplicate indices are handled in all cases.  If \verb'I' has
duplicate indices, they are ignored and the last unique entry in the list is
used.  When no mask and no accumulator is present, the results are identical to
how MATLAB handles duplicate indices in the built-in expression
\verb'C(I,J)=A'.  Details of how this is done is shown below.

{\small
\begin{verbatim}
    function C = subassign (C, I, J, A)
    % submatrix assignment with pre-sort of I and J; and remove duplicates

    % delete duplicates from I, keeping the last one seen
    [I2 I2k] = sort (I) ;
    Idupl = [(I2 (1:end-1) == I2 (2:end)), false] ;
    I2  = I2  (~Idupl) ;
    I2k = I2k (~Idupl) ;
    assert (isequal (I2, unique (I)))

    % delete duplicates from J, keeping the last one seen
    [J2 J2k] = sort (J) ;
    Jdupl = [(J2 (1:end-1) == J2 (2:end)), false] ;
    J2  = J2  (~Jdupl) ;
    J2k = J2k (~Jdupl) ;
    assert (isequal (J2, unique (J)))

    % do the submatrix assignment, with no duplicates in I2 or J2
    C (I2,J2) = A (I2k,J2k) ;
\end{verbatim}}

If a mask is present, then it is replaced with \verb'M = M (I2k, J2k)' for
\verb'GxB_subassign', or with \verb'M = M (I2, J2)' for \verb'GrB_assign'.
If an accumulator operator is present, it is applied after the duplicates
are removed, as (for example):

{\small
\begin{verbatim}
    C (I2,J2) = C (I2,J2) + A (I2k,J2k) ;
\end{verbatim}}

These definitions allow the MATLAB/Octave interface to GraphBLAS to return the same
results for \verb'C(I,J)=A' for a \verb'GrB' object as they do for built-in
MATLAB/Octave matrices.  They also allow the assignment to be done in parallel.

Results are always well-defined in SuiteSparse:GraphBLAS, but they might not be
what you expect.  For example, suppose the \verb'MIN' operator is being used
the following assigment to the vector \verb'x', and suppose \verb'I' contains
the entries \verb'[0 0]'.  Suppose \verb'x' is initially empty, of length 1,
and suppose \verb'y' is a vector of length 2 with the values \verb'[5 7]'.

{\small
\begin{verbatim}
    #include "GraphBLAS.h"
    #include <stdio.h>
    int main (void)
    {
        GrB_init (GrB_NONBLOCKING) ;
        GrB_Vector x, y ;
        GrB_Vector_new (&x, GrB_INT32, 1) ;
        GrB_Vector_new (&y, GrB_INT32, 2) ;
        GrB_Index I [2] = {0, 0} ;
        GrB_Vector_setElement (y, 5, 0) ;
        GrB_Vector_setElement (y, 7, 1) ;
        GrB_Vector_wait (&y) ;
        GxB_print (x, 3) ;
        GxB_print (y, 3) ;
        GrB_assign (x, NULL, GrB_MIN_INT32, y, I, 2, NULL) ;
        GrB_Vector_wait (&y) ;
        GxB_print (x, 3) ;
        GrB_finalize ( ) ;
    }
\end{verbatim}}

You might (wrongly) expect the result to be the vector \verb'x(0)=5', since
two entries seem to be assigned, and the min operator might be expected to
take the minimum of the two.  This is not how SuiteSparse:GraphBLAS handles
duplicates.

Instead, the first duplicate index of \verb'I' is discarded
(\verb'I [0] = 0', and \verb'y(0)=5').
and only the second entry is used
(\verb'I [1] = 0', and \verb'y(1)=7').
The output of the above program is:

{\small
\begin{verbatim}

  1x1 GraphBLAS int32_t vector, sparse by col:
  x, no entries


  2x1 GraphBLAS int32_t vector, sparse by col:
  y, 2 entries

    (0,0)   5
    (1,0)   7


  1x1 GraphBLAS int32_t vector, sparse by col:
  x, 1 entry

    (0,0)   7

\end{verbatim}}

You see that the result is \verb'x(0)=7', since the \verb'y(0)=5' entry
has been ignored because of the duplicate indices in \verb'I'.

\begin{alert}
{\bf SPEC:} Providing a well-defined behavior for duplicate
indices with matrix and vector assignment is an extension to the specification.
The specification only defines the behavior when assigning a scalar into a matrix
or vector, and states that duplicate indices otherwise lead to undefined
results.
\end{alert}


\newpage
%===============================================================================
\subsection{Comparing {\sf GrB\_assign} and {\sf GxB\_subassign}} %=============
%===============================================================================
\label{compare_assign}

The \verb'GxB_subassign' and \verb'GrB_assign' operations are very similar, but
they differ in two ways:

\begin{enumerate}
\item {\bf The Mask has a different size:}
    The mask in \verb'GxB_subassign' has the same dimensions as \verb'w(I)' for
    vectors and \verb'C(I,J)' for matrices.  In \verb'GrB_assign', the mask is
    the same size as \verb'w' or \verb'C', respectively (except for the row/col
    variants).  The two masks are related.  If \verb'M' is the mask for
    \verb'GrB_assign', then \verb'M(I,J)' is the mask for \verb'GxB_subassign'.
    If there is no mask, or if \verb'I' and \verb'J' are both \verb'GrB_ALL',
    the two masks are the same.
    For \verb'GrB_Row_assign' and \verb'GrB_Col_assign', the \verb'mask' vector
    is the same size as a row or column of \verb'C', respectively.  For the
    corresponding \verb'GxB_Row_subassign' and \verb'GxB_Col_subassign'
    operations, the \verb'mask' is the same size as the sub-row \verb'C(i,J)' or
    subcolumn \verb'C(I,j)', respectively.

\item {\bf \verb'GrB_REPLACE' is different:}
    They differ in how \verb'C' is affected in areas outside the \verb'C(I,J)'
    submatrix.  In \verb'GxB_subassign', the \verb'C(I,J)' submatrix is the
    only part of \verb'C' that can be modified, and no part of \verb'C' outside
    the submatrix is ever modified.  In \verb'GrB_assign', it is possible to
    delete entries in \verb'C' outside the submatrix, but only in one specific
    manner.  Suppose the mask \verb'M' is present (or, suppose it is not
    present but \verb'GrB_COMP' is true).  After (optionally) complementing the
    mask, the value of \verb'M(i,j)' can be 0 for some entry outside the
    \verb'C(I,J)' submatrix.  If the \verb'GrB_REPLACE' descriptor is
    true, \verb'GrB_assign' deletes this entry.

\end{enumerate}

\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_COMP'), or \verb'I' and
\verb'J' are both \verb'GrB_ALL'.
If all these conditions hold,
the two algorithms are identical and have the same performance.  Otherwise,
\verb'GxB_subassign' is much faster than \verb'GrB_assign' when the latter
must examine the entire matrix \verb'C' to delete entries (when
\verb'GrB_REPLACE' is true), and if it must deal with a much larger \verb'Mask'
matrix.  However, both methods have specific uses.

Consider using \verb'C(I,J)+=F' for many submatrices \verb'F' (for example,
when assembling a finite-element matrix).  If the \verb'Mask' is meant as a
specification for which entries of \verb'C' should appear in the final result,
then use \verb'GrB_assign'.

If instead the \verb'Mask' is meant to control which entries of the submatrix
\verb'C(I,J)' are modified by the finite-element \verb'F', then use
\verb'GxB_subassign'.  This is particularly useful is the \verb'Mask' is a
template that follows along with the finite-element \verb'F', independent of
where it is applied to \verb'C'.  Using \verb'GrB_assign' would be very
difficult in this case since a new \verb'Mask', the same size as \verb'C',
would need to be constructed for each finite-element \verb'F'.

In GraphBLAS notation, the two methods can be described as follows:

\vspace{0.05in}
\begin{tabular}{ll}
\hline
matrix and vector subassign & ${\bf C(I,J) \langle M \rangle}  = {\bf C(I,J)} \odot {\bf A}$ \\
matrix and vector    assign & ${\bf C \langle M \rangle (I,J)} = {\bf C(I,J)} \odot {\bf A}$ \\
\hline
\end{tabular}
\vspace{0.05in}

This notation does not include the details of the \verb'GrB_COMP' 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

Details of each step of the two operations are listed below:

\vspace{0.1in}
\begin{tabular}{lll}
\hline
Step & \verb'GrB_Matrix_assign'                & \verb'GxB_Matrix_subassign'                        \\
\hline
1 & ${\bf S} = {\bf C(I,J)}$                & ${\bf S} = {\bf C(I,J)}$                              \\
2 & ${\bf S} = {\bf S} \odot {\bf A}$       & ${\bf S \langle M \rangle} = {\bf S} \odot {\bf A}$   \\
3 & ${\bf Z} = {\bf C}$                     & ${\bf C(I,J)}= {\bf S}$                               \\
4 & ${\bf Z(I,J)} = {\bf S}$                &                                                       \\
5 & ${\bf C \langle M \rangle = Z}$         &                                                       \\
\hline
\end{tabular}
\vspace{0.1in}

Step 1 is the same.  In the Accumulator Phase (Step 2), the expression
${\bf S} \odot {\bf A}$,
described in Section~\ref{accummask}, is the same in both
operations.  The result is simply ${\bf A}$ if \verb'accum' is \verb'NULL'.  It
only applies to the submatrix ${\bf S}$, not the whole matrix.
The result ${\bf S} \odot {\bf A}$ is used differently in the Mask/Replace
phase.

The Mask/Replace Phase, described in Section~\ref{accummask} is different:
\begin{itemize}
\item
    For \verb'GrB_assign' (Step 5), the mask is applied to all of ${\bf
    C}$.  The mask has the same size as ${\bf C}$.  Just prior to making the
    assignment via the mask, the \verb'GrB_REPLACE' option can be used to clear
    all of ${\bf C}$ first.  This is the only way in which entries in ${\bf C}$ that
    are outside the ${\bf C(I,J)}$ submatrix can be modified by this operation.

\item
    For \verb'GxB_subassign' (Step 2b), the mask is applied to just
    ${\bf S}$.  The mask has the same size as ${\bf C(I,J)}$, ${\bf S}$, and
    ${\bf A}$.  Just prior to making the assignment via the mask, the
    \verb'GrB_REPLACE' option can be used to clear ${\bf S}$ first.  No entries
    in ${\bf C}$ that are outside the ${\bf C(I,J)}$ can be modified by this
    operation.  Thus, \verb'GrB_REPLACE' has no effect on entries in ${\bf C}$
    outside the ${\bf C(I,J)}$ submatrix.

\end{itemize}

The differences between \verb'GrB_assign' and
\verb'GxB_subassign' can be seen in Tables~\ref{insubmatrix} and
\ref{outsubmatrix}.  The first table considers the case when the entry $c_{ij}$
is in the ${\bf C(I,J)}$ submatrix, and it describes what is computed for both
\verb'GrB_assign' and \verb'GxB_subassign'.  They perform the
exact same computation; the only difference is how the value of the mask is
specified.  Compare Table~\ref{insubmatrix} with Table~\ref{tab:maskaccum}
in Section~\ref{sec:maskaccum}.

The first column of Table~\ref{insubmatrix} 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 effective value of the mask 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_COMP' 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    &   \\
    -  &-   & $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    &   \\
    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    &   \\
    -  &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    &   \\
    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_COMP' 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 &  \\
   -   &-     & $c_{ij}$ & $c_{ij}$ & 0 &  \\
   -   &-     &  -       & -        & 0 &  \\
\hline
   yes &  -   & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   yes &  -   &    -     &     -    & 1 &  \\
   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 &  \\
   -   &yes   & $c_{ij}$ & $c_{ij}$ & 0 &  \\
   -   &yes   &    -     &  -       & 0 &  \\
\hline
   yes &  yes & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   yes &  yes &   -      &  -       & 1 &  \\
   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_COMP' is false.  Let the
\verb'Mask' be:

\[
{\bf M} = \left[
    \begin{array}{rr}
    1 & 1 \\
    0 & 1 \\
    \end{array}
    \right].
\]

Let ${\bf A} = 100$, and let the index sets be ${\bf I}=0$ and ${\bf J}=1$.
Consider the computation
${\bf C \langle M \rangle} (0,1) = {\bf C}(0,1) + {\bf A}$,
using the \verb'GrB_assign' operation.  The result is:
\[
{\bf C} = \left[
    \begin{array}{rr}
    11 & 112 \\
     - &  22 \\
    \end{array}
    \right].
\]
The $(0,1)$ entry is updated and the $(1,0)$ entry is deleted because
its \verb'Mask' is zero.  The other two entries are not modified since ${\bf Z}
= {\bf C}$ outside the submatrix, and those two values are written back into
${\bf C}$ because their \verb'Mask' values are 1.  The $(1,0)$ entry is deleted
because the entry ${\bf Z}(1,0)=21$ is prevented from being written back into
${\bf C}$ since \verb'Mask(1,0)=0'.

Now consider the analogous \verb'GxB_subassign' operation.  The \verb'Mask' has
the same size as ${\bf A}$, namely:
\[
{\bf M} = \left[
    \begin{array}{r}
    1 \\
    \end{array}
    \right].
\]

After computing
${\bf C} (0,1) {\bf \langle M \rangle} = {\bf C}(0,1) + {\bf A}$,
the result is

\[
{\bf C} = \left[
    \begin{array}{rr}
    11 & 112 \\
    21 &  22 \\
    \end{array}
    \right].
\]

Only the ${\bf C(I,J)}$ submatrix, the single entry ${\bf C}(0,1)$, is modified
by \verb'GxB_subassign'.  The entry ${\bf C}(1,0)=21$ is unaffected by
\verb'GxB_subassign', but it is deleted by \verb'GrB_assign'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{Performance of {\sf GxB\_subassign}, {\sf GrB\_assign}
and {\sf GrB\_*\_setElement}}
%-------------------------------------------------------------------------------

When SuiteSparse:GraphBLAS uses non-blocking mode, the modifications to a
matrix by \verb'GxB_subassign', \verb'GrB_assign', and \verb'GrB_*_setElement'
can postponed, and computed all at once later on.  This has a huge impact on
performance.

A sequence of assignments is fast if their completion can be postponed for as
long as possible, or if they do not modify the pattern at all.  Modifying the
pattern can be costly, but it is fast if non-blocking mode can be fully
exploited.

Consider a sequence of $t$ submatrix assignments \verb'C(I,J)=C(I,J)+A' to an
$n$-by-$n$ matrix \verb'C' where each submatrix \verb'A' has size $a$-by-$a$
with $s$ entries, and where \verb'C' starts with $c$ entries.
Assume the matrices are all stored in non-hypersparse form, by row
(\verb'GxB_BY_ROW').

If blocking mode is enabled, or if the sequence requires the matrix to be
completed after each assignment, each of the $t$ assignments takes $O(a + s
\log n)$ time to process the \verb'A' matrix and then $O(n + c + s \log s)$
time to complete \verb'C'.  The latter step uses \verb'GrB_*_build' to build an
update matrix and then merge it with \verb'C'.  This step does not occur if the
sequence of assignments does not add new entries to the pattern of \verb'C',
however.  Assuming in the worst case that the pattern does change, the total
time is $O (t \left[ a + s \log n + n + c + s \log s \right] )$.

If the sequence can be computed with all updates postponed until the end of the
sequence, then the total time is no worse than $O(a + s \log n)$ to process
each \verb'A' matrix, for $t$ assignments, and then a single \verb'build' at
the end, taking $O(n + c + st \log st)$ time.
The total time is $O (t \left [a + s \log n \right] + (n + c + st \log st))$.
If no new entries appear in
\verb'C' the time drops to $O (t \left [a + s \log n \right])$, and in this
case, the time for both methods is the same; both are equally efficient.

A few simplifying assumptions are useful to compare these times.  Consider a
graph of $n$ nodes with $O(n)$ edges, and with a constant bound on the degree
of each node.  The asymptotic bounds assume a worst-case scenario where
\verb'C' has a least some dense rows (thus the $\log n$ terms).  If these
are not present, if both $t$ and $c$ are $O(n)$, and if $a$ and $s$ are
constants, then the total time with blocking mode becomes $O(n^2)$, assuming
the pattern of \verb'C' changes at each assignment.  This very high for a
sparse graph problem.  In contrast, the non-blocking time becomes $O(n \log n)$
under these same assumptions, which is asymptotically much faster.

\newpage
The difference in practice can be very dramatic, since $n$ can be many millions
for sparse graphs with $n$ nodes and $O(n)$, which can be handled on a
commodity laptop.

The following guidelines should be considered when using
\verb'GxB_subassign', \verb'GrB_assign' and \verb'GrB_*_setElement'.

\begin{enumerate}

\item A sequence of assignments that does not modify the pattern at all is
fast, taking as little as $\Omega(1)$ time per entry modified.  The worst case
time complexity is $O(\log n)$ per entry, assuming they all modify a dense
row of \verb'C' with \verb'n' entries, which can occur in practice.  It is
more common, however, that most rows of \verb'C' have a constant number of
entries, independent of \verb'n'.  No work is ever left pending when the
pattern of \verb'C' does not change.

\item A sequence of assignments that modifies the entries that already exist in
the pattern of a matrix, or adds new entries to the pattern (using the same
\verb'accum' operator), but does not delete any entries, is fast.  The matrix
is not completed until the end of the sequence.

\item Similarly, a sequence that modifies existing entries, or deletes them,
but does not add new ones, is also fast.  This sequence can also repeatedly
delete pre-existing entries and then reinstate them and still be fast.  The
matrix is not completed until the end of the sequence.

\item A sequence that mixes assignments of types (2) and (3) above can be
costly, since the matrix may need to be completed after each assignment.  The
time complexity can become quadratic in the worst case.

\item However, any single assignment takes no more than $O (a + s \log n + n +
c + s \log s )$ time, even including the time for a matrix completion, where
\verb'C' is $n$-by-$n$ with $c$ entries and \verb'A' is $a$-by-$a$ with $s$
entries.  This time is essentially linear in the size of the matrix \verb'C',
if \verb'A' is relatively small and sparse compared with \verb'C'.  In this
case, $n+c$ are the two dominant terms.

\item In general, \verb'GxB_subassign' is faster than \verb'GrB_assign'.
If \verb'GrB_REPLACE' is used with \verb'GrB_assign', the entire matrix
\verb'C' must be traversed.  This is much slower than \verb'GxB_subassign',
which only needs to examine the \verb'C(I,J)' submatrix.  Furthermore,
\verb'GrB_assign' must deal with a much larger \verb'Mask' matrix, whereas
\verb'GxB_subassign' has a smaller mask.  Since its mask is smaller,
\verb'GxB_subassign' takes less time than \verb'GrB_assign' to access the mask.

\end{enumerate}

% see GraphBLAS/Test/test46.m

Submatrix assignment in SuiteSparse:GraphBLAS is extremely efficient, even
without considering the advantages of non-blocking mode discussed in
Section~\ref{compare_assign}.  It can be up to 1000x faster than MATLAB R2019b,
or even higher depending on the kind of matrix assignment.  MATLAB logical
indexing (the mask of GraphBLAS) is extremely faster with GraphBLAS as compared
in MATLAB R2019b; differences of up to 250,000x have been observed (0.4 seconds
in GraphBLAS versus 28 hours in MATLAB).

All of the 28 variants (each with their own source code) are either
asymptotically optimal, or to within a log factor of being asymptotically
optimal.  The methods are also fully parallel.  For hypersparse matrices, the
term $n$ in the expressions in the above discussion is dropped, and is replaced
with $h \log h$, at the worst case, where $h << n$ is the number of non-empty
columns of a hypersparse matrix stored by column, or the number of non-empty
rows of a hypersparse matrix stored by row.  In many methods, $n$ is replaced
with $h$, not $h \log h$.

\newpage
%===============================================================================
\subsection{{\sf GrB\_apply:} apply a unary, binary, or index-unary operator}
%===============================================================================
\label{apply}

\verb'GrB_apply' is the generic name for 92 specific functions:

\begin{packed_itemize}
\item
\verb'GrB_Vector_apply' and \verb'GrB_Matrix_apply' apply a unary operator to
the entries of a matrix (two variants).

\item \verb'GrB_*_apply_BinaryOp1st_*' applies a binary
operator where a single scalar is provided as the $x$ input to the binary
operator.
There are 30 variants, depending on the type of the scalar: (matrix or vector)
x (13 built-in types, one for user-defined types, and a version for
\verb'GrB_Scalar').

\item \verb'GrB_*_apply_BinaryOp2nd_*' applies a binary operator where a
single scalar is provided as the $y$ input to the binary operator.
There are 30 variants, depending on the type of the scalar: (matrix or vector)
x (13 built-in types, one for user-defined types, and a version for
\verb'GrB_Scalar').

\item \verb'GrB_*_apply_IndexOp_*' applies a \verb'GrB_IndexUnaryOp',
single scalar is provided as the scalar $y$ input to the index-unary operator.
There are 30 variants, depending on the type of the scalar: (matrix or vector)
x (13 built-in types, one for user-defined types, and a version for
\verb'GrB_Scalar').

\end{packed_itemize}

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 all
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.
The \verb'GrB_IDENTITY_'$T$ operators also provide the fastest stand-alone
typecasting methods in SuiteSparse:GraphBLAS, with all $13 \times 13=169$
methods appearing as individual functions, to typecast between any of the 13
built-in types.

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
%===============================================================================
\subsubsection{{\sf GrB\_Vector\_apply\_BinaryOp1st:} apply a binary operator to a vector; 1st scalar binding}
%===============================================================================
\label{vector_apply1st}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_apply                  // w<mask> = accum (w, op(x,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_BinaryOp op,          // operator to apply to the entries
    <type> x,                       // first input:  scalar x
    const GrB_Vector u,             // second input: vector u
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_apply_BinaryOp1st_<type>'  applies a binary operator
$z=f(x,y)$ to a vector, where a scalar $x$ is bound to the first input of the
operator.
The scalar \verb'x' can be a non-opaque C scalar corresponding to a built-in
type, a \verb'void *' for user-defined types, or a \verb'GrB_Scalar'.
It is otherwise identical to \verb'GrB_Vector_apply'.

%===============================================================================
\subsubsection{{\sf GrB\_Vector\_apply\_BinaryOp2nd:} apply a binary operator to a vector; 2nd scalar binding}
%===============================================================================
\label{vector_apply2nd}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_apply                  // w<mask> = accum (w, op(u,y))
(
    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_BinaryOp op,          // operator to apply to the entries
    const GrB_Vector u,             // first input:  vector u
    <type> y,                       // second input: scalar y
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_apply_BinaryOp2nd_<type>'  applies a binary operator
$z=f(x,y)$ to a vector, where a scalar $y$ is bound to the second input of the
operator.
The scalar \verb'x' can be a non-opaque C scalar corresponding to a built-in
type, a \verb'void *' for user-defined types, or a \verb'GrB_Scalar'.
It is otherwise identical to \verb'GrB_Vector_apply'.

\newpage
%===============================================================================
\subsubsection{{\sf GrB\_Vector\_apply\_IndexOp:} apply an index-unary operator to a vector}
%===============================================================================
\label{vector_apply_idxunop}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_apply                  // w<mask> = accum (w, op(u,y))
(
    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_IndexUnaryOp op,      // operator to apply to the entries
    const GrB_Vector u,             // first input:  vector u
    const <type> y,                 // second input: scalar y
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_apply_IndexOp_<type>'  applies an index-unary operator
$z=f(x,i,0,y)$ to a vector.
The scalar \verb'y' can be a non-opaque C scalar corresponding to a built-in
type, a \verb'void *' for user-defined types, or a \verb'GrB_Scalar'.
It is otherwise identical to \verb'GrB_Vector_apply'.

%===============================================================================
\subsubsection{{\sf GrB\_Matrix\_apply\_BinaryOp1st:} apply a binary operator to a matrix; 1st scalar binding}
%===============================================================================
\label{matrix_apply1st}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_apply                  // C<M>=accum(C,op(x,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_BinaryOp op,          // operator to apply to the entries
    <type> x,                       // first input:  scalar x
    const GrB_Matrix A,             // second input: matrix A
    const GrB_Descriptor desc       // descriptor for C, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_apply_BinaryOp1st_<type>'  applies a binary operator
$z=f(x,y)$ to a matrix, where a scalar $x$ is bound to the first input of the
operator. 
The scalar \verb'x' can be a non-opaque C scalar corresponding to a built-in
type, a \verb'void *' for user-defined types, or a \verb'GrB_Scalar'.
It is otherwise identical to \verb'GrB_Matrix_apply'.

\newpage
%===============================================================================
\subsubsection{{\sf GrB\_Matrix\_apply\_BinaryOp2nd:} apply a binary operator to a matrix; 2nd scalar binding}
%===============================================================================
\label{matrix_apply2nd}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_apply                  // C<M>=accum(C,op(A,y))
(
    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,          // operator to apply to the entries
    const GrB_Matrix A,             // first input:  matrix A
    <type> y,                       // second input: scalar y
    const GrB_Descriptor desc       // descriptor for C, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_apply_BinaryOp2nd_<type>'  applies a binary operator
$z=f(x,y)$ to a matrix, where a scalar $x$ is bound to the second input of the
operator.
The scalar \verb'y' can be a non-opaque C scalar corresponding to a built-in
type, a \verb'void *' for user-defined types, or a \verb'GrB_Scalar'.
It is otherwise identical to \verb'GrB_Matrix_apply'.

%===============================================================================
\subsubsection{{\sf GrB\_Matrix\_apply\_IndexOp:} apply an index-unary operator to a matrix}
%===============================================================================
\label{matrix_apply_idxunop}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_apply                  // C<M>=accum(C,op(A,y))
(
    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_IndexUnaryOp op,      // operator to apply to the entries
    const GrB_Matrix A,             // first input:  matrix A
    const <type> y,                 // second input: scalar y
    const GrB_Descriptor desc       // descriptor for C, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_apply_IndexOp_<type>'  applies an index-unary operator
$z=f(x,i,j,y)$ to a matrix.
The scalar \verb'y' can be a non-opaque C scalar corresponding to a built-in
type, a \verb'void *' for user-defined types, or a \verb'GrB_Scalar'.
It is otherwise identical to \verb'GrB_Matrix_apply'.

\newpage
%===============================================================================
\subsection{{\sf GrB\_select:} select entries based on an index-unary operator}
%===============================================================================
\label{select}

The \verb'GrB_select' function is the generic name for 30 specific functions,
depending on whether it operates on a matrix or vector, and depending on the
type of the scalar \verb'y': (matrix or vector) x (13 built-in types,
\verb'void *' for user-defined types, and a \verb'GrB_Scalar').  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_select' is used.

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_select:} select entries from a vector}
%-------------------------------------------------------------------------------
\label{select_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_select                 // 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_IndexUnaryOp op,      // operator to apply to the entries
    const GrB_Vector u,             // first input:  vector u
    const <type> y,                 // second input: scalar y
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_select_*' applies a \verb'GrB_IndexUnaryOp' operator to the
entries of a vector.  If the operator evaluates as \verb'true' for the entry
\verb'u(i)', it is copied to the vector \verb't', or not copied if the operator
evaluates to \verb'false'.   The vector \verb't' is then written to the result
\verb'w' via the mask/accumulator step.  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.  Refer to the next section
(\ref{select_matrix}) on \verb'GrB_Matrix_select' for more details.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_select:} apply a select operator to a matrix}
%-------------------------------------------------------------------------------
\label{select_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_select                 // C<M>=accum(C,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_IndexUnaryOp op,      // operator to apply to the entries
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Scalar y,             // second input: scalar y
    const GrB_Descriptor desc       // descriptor for C, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_select_*' applies a \verb'GrB_IndexUnaryOp' operator to the
entries of a matrix.  If the operator evaluates as \verb'true' for the entry
\verb'A(i,j)', it is copied to the matrix \verb'T', or not copied if the
operator evaluates to \verb'false'.  The input matrix \verb'A' may be
transposed first.  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(a_{ij},i,j,y)$.  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'.

The action of \verb'GrB_select' with the built-in index-unary 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'GrB_select' always has the 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'GrB_select', where \verb'T' is a matrix.

The following operators may be used on matrices with a user-defined type:
\verb'GrB_ROWINDEX_*',
\verb'GrB_COLINDEX_*',
\verb'GrB_DIAGINDEX_*',
\verb'GrB_TRIL', \newline
\verb'GrB_TRIU',
\verb'GrB_DIAG',
\verb'GrB_OFFIAG',
\verb'GrB_COLLE',
\verb'GrB_COLGT',
\verb'GrB_ROWLE',
and
\verb'GrB_ROWGT'.

For floating-point values, comparisons with \verb'NaN' always return false.
The \verb'GrB_VALUE*' operators should not be used with a scalar \verb'y' that is
equal to \verb'NaN'.  For this case, create a user-defined select operator that
performs the test with the ANSI C \verb'isnan' function instead.

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS name          & MATLAB/Octave     & description \\
                        & analog            & \\
\hline
\verb'GrB_ROWINDEX_*'    & \verb'z=i+y'         & select \verb'A(i,j)' if \verb'i != -y' \\
\verb'GrB_COLINDEX_*'    & \verb'z=j+y'         & select \verb'A(i,j)' if \verb'j != -y' \\
\verb'GrB_DIAGINDEX_*'   & \verb'z=j-(i+y)'     & select \verb'A(i,j)' if \verb'j != i+y' \\
\hline
\verb'GrB_TRIL'    & \verb'z=(j<=(i+y))'  & select entries on or below the \verb'y'th diagonal \\
\verb'GrB_TRIU'    & \verb'z=(j>=(i+y))'  & select entries on or above the \verb'y'th diagonal \\
\verb'GrB_DIAG'    & \verb'z=(j==(i+y))'  & select entries on the \verb'y'th diagonal \\
\verb'GrB_OFFDIAG' & \verb'z=(j!=(i+y))'  & select entries not on the \verb'y'th diagonal \\
\verb'GrB_COLLE'   & \verb'z=(j<=y)'      & select entries in columns 0 to \verb'y' \\
\verb'GrB_COLGT'   & \verb'z=(j>y)'       & select entries in columns \verb'y+1' and above \\
\verb'GrB_ROWLE'   & \verb'z=(i<=y)'      & select entries in rows 0 to \verb'y' \\
\verb'GrB_ROWGT'   & \verb'z=(i>y)'       & select entries in rows \verb'y+1' and above \\
\hline
\verb'GrB_VALUENE_T'     & \verb'z=(aij!=y)'    & select \verb'A(i,j)' if it is not equal to \verb'y'\\
\verb'GrB_VALUEEQ_T'     & \verb'z=(aij==y)'    & select \verb'A(i,j)' is it equal to \verb'y'\\
\verb'GrB_VALUEGT_T'     & \verb'z=(aij>y)'     & select \verb'A(i,j)' is it greater than \verb'y' \\
\verb'GrB_VALUEGE_T'     & \verb'z=(aij>=y)'    & select \verb'A(i,j)' is it greater than or equal to \verb'y' \\
\verb'GrB_VALUELT_T'     & \verb'z=(aij<y)'     & select \verb'A(i,j)' is it less than \verb'y' \\
\verb'GrB_VALUELE_T'     & \verb'z=(aij<=y)'    & select \verb'A(i,j)' is it less than or equal to \verb'y' \\
%
\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.

\begin{alert}
{\bf SPEC:} 
All methods below use a monoid for the reduction.  The Specification also
allows reductions using an associative and commutative binary operator.
SuiteSparse:GraphBLAS permits the use of a \verb'GrB_BinaryOp' instead of a
\verb'GrB_Monoid', but only if the binary operator is built-in and corresponds
to a known built-in monoid.  For example, the binary operator
\verb'GrB_PLUS_FP64' can be used, since this is the binary operator of the
built-in \verb'GrB_PLUS_MONOID_FP64'.  For other binary ops (including any
user-defined ones), \verb'GrB_NOT_IMPLEMENTED' is returned.

\end{alert}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_reduce\_Monoid} 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 GrB_Monoid monoid,        // reduce monoid 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_Monoid'
reduces a matrix to a column vector using a monoid, 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.

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

GrB_Info GrB_reduce                 // c = accum (c, reduce_to_scalar (u))
(
    GrB_Scalar 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.

The scalar \verb'c' can be a pointer C type: \verb'bool', \verb'int8_t', ...
\verb'float', \verb'double', or \verb'void *' for a user-defined type,
or a \verb'GrB_Scalar'.
If \verb'c' is a \verb'void *' pointer to a user-defined type,
the 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.

If the vector \verb'u' has no entries, that identity value of the \verb'monoid'
is copied into the scalar \verb't' (unless \verb'c' is a \verb'GrB_Scalar',
in which case \verb't' is an empty \verb'GrB_Scalar', with no entry).
Otherwise, all of the entries in the
vector are reduced to a single scalar using the \verb'monoid'.

The descriptor is unused, but it appears in case it is needed in future
versions of the GraphBLAS API.
This function has no mask so its accumulator/mask step differs from the other
GraphBLAS operations.  It does not use the methods described in
Section~\ref{accummask}, but uses the following method instead.

If \verb'accum' is \verb'NULL', then the scalar \verb't' is typecast into the
type of \verb'c', and \verb'c = t' is the final result.  Otherwise, the scalar
\verb't' is typecast into the \verb'ytype' of the \verb'accum' operator, and
the value of \verb'c' (on input) is typecast into the \verb'xtype' of the
\verb'accum' operator.  Next, the scalar \verb'z = accum (c,t)' is computed, of
the \verb'ztype' of the \verb'accum' operator.  Finally, \verb'z' is typecast
into the final result, \verb'c'.

If \verb'c' is a non-opaque scalar, no error message can be returned by
\verb'GrB_error'.  If \verb'c' is a \verb'GrB_Scalar', then
\verb'GrB_error(&err,c)' can be used to return an error string, if an error
occurs.

\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)
) ;

GrB_Info GrB_reduce                 // c = accum (c, reduce_to_scalar (A))
(
    GrB_Scalar 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}.

\newpage
%===============================================================================
\subsection{{\sf GrB\_transpose:} transpose a matrix} %=========================
%===============================================================================
\label{transpose}

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

\verb'GrB_transpose'
transposes a matrix \verb'A', just like the array transpose \verb"T = A.'" in
MATLAB.  The internal result matrix \verb"T = A'" (or merely \verb"T = A" if
\verb'A' is transposed via the descriptor) has the same type as \verb'A'.  The
final step is ${\bf C \langle M \rangle  = C \odot T}$, as described in
Section~\ref{accummask}, which typecasts \verb'T' as needed and applies the
mask and accumulator.

To be consistent with the rest of the GraphBLAS API regarding the
descriptor, the input matrix \verb'A' may be transposed first by
setting the \verb'GrB_INP0' setting to \verb'GrB_TRAN'.  This results in
a double transpose, and thus \verb'A' is not transposed is computed.

\newpage
%===============================================================================
\subsection{{\sf GrB\_kronecker:} Kronecker product} %==========================
%===============================================================================
\label{kron}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_kronecker              // 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 <operator> 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'GrB_kronecker' 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}.

The operator \verb'op' may be a \verb'GrB_BinaryOp', a \verb'GrB_Monoid', or a
\verb'GrB_Semiring'.  In the latter case, the multiplicative operator of
the semiring is used.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Printing GraphBLAS objects} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{fprint}

The ten different objects handled by SuiteSparse:GraphBLAS are all opaque,
although nearly all of their contents can be extracted via methods such as
\verb'GrB_Matrix_extractTuples', \verb'GrB_Matrix_extractElement',
\verb'GxB_Matrix_type', and so on.  The GraphBLAS C API has no mechanism for
printing all the contents of GraphBLAS objects, but this is helpful for
debugging.  Ten type-specific methods and two type-generic methods are
provided:

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GxB_Type_fprint'         & print and check a \verb'GrB_Type' \\
\verb'GxB_UnaryOp_fprint'      & print and check a \verb'GrB_UnaryOp' \\
\verb'GxB_BinaryOp_fprint'     & print and check a \verb'GrB_BinaryOp' \\
\verb'GxB_IndexUnaryOP_fprint' & print and check a \verb'GrB_IndexUnaryOp' \\
\verb'GxB_Monoid_fprint'       & print and check a \verb'GrB_Monoid' \\
\verb'GxB_Semiring_fprint'     & print and check a \verb'GrB_Semiring' \\
\verb'GxB_Descriptor_fprint'   & print and check a \verb'GrB_Descriptor' \\
\verb'GxB_Matrix_fprint'       & print and check a \verb'GrB_Matrix' \\
\verb'GxB_Vector_fprint'       & print and check a \verb'GrB_Vector' \\
\verb'GxB_Scalar_fprint'       & print and check a \verb'GrB_Scalar' \\
\hline
\verb'GxB_fprint'             & print/check any object to a file \\
\verb'GxB_print'              & print/check any object to \verb'stdout' \\
\hline
\end{tabular}
}
\vspace{0.2in}

These methods do not modify the status of any object, and thus they
cannot return an error string for use by \verb'GrB_error'.

If a matrix or vector
has not been completed, the pending computations are guaranteed to {\em not} be
performed. The reason is simple.  It is possible for a bug in the user
application (such as accessing memory outside the bounds of an array) to mangle
the internal content of a GraphBLAS object, and the \verb'GxB_*print' methods
can be helpful tools to track down this bug.  If \verb'GxB_*print' attempted to
complete any computations prior to printing or checking the contents of the
matrix or vector, then further errors could occur, including a segfault.

By contrast, GraphBLAS methods and operations that return values into
user-provided arrays or variables might finish pending operations before the
return these values, and this would change their state.  Since they do not
change the state of any object, the \verb'GxB_*print' methods provide a useful
alternative for debugging, and for a quick understanding of what GraphBLAS is
computing while developing a user application.

Each of the methods has a parameter of type \verb'GxB_Print_Level' that
specifies the amount to print:

{\footnotesize
\begin{verbatim}
typedef enum
{
    GxB_SILENT = 0,     // nothing is printed, just check the object
    GxB_SUMMARY = 1,    // print a terse summary
    GxB_SHORT = 2,      // short description, about 30 entries of a matrix
    GxB_COMPLETE = 3,   // print the entire contents of the object
    GxB_SHORT_VERBOSE = 4,    // GxB_SHORT but with "%.15g" for doubles
    GxB_COMPLETE_VERBOSE = 5  // GxB_COMPLETE but with "%.15g" for doubles
}
GxB_Print_Level ; \end{verbatim}}

The ten type-specific functions include an additional argument, the
\verb'name' string.  The \verb'name' is printed at the beginning of the display
(assuming the print level is not \verb'GxB_SILENT') so that the object can be
more easily identified in the output.  For the type-generic methods
\verb'GxB_fprint' and \verb'GxB_print', the \verb'name' string is the variable
name of the object itself.

If the file \verb'f' is \verb'NULL', \verb'stdout' is used.
If \verb'name' is \verb'NULL', it is treated
as the empty string.  These are not error conditions.

The methods check their input objects carefully and extensively, even when
\verb'pr' is equal to \verb'GxB_SILENT'.  The following error codes can be
returned:

\begin{packed_itemize}
\item \verb'GrB_SUCCESS':               object is valid
\item \verb'GrB_UNINITIALIZED_OBJECT':  object is not initialized
\item \verb'GrB_INVALID_OBJECT':        object is not valid
\item \verb'GrB_NULL_POINTER':          object is a NULL pointer
\item \verb'GrB_INVALID_VALUE':         \verb'fprintf' returned an I/O error.
\end{packed_itemize}

The content of any GraphBLAS object is opaque, and subject to change.  As a
result, the exact content and format of what is printed is
implementation-dependent, and will change from version to version of
SuiteSparse:GraphBLAS.  Do not attempt to rely on the exact content or format
by trying to parse the resulting output via another program.  The intent of
these functions is to produce a report of an object for visual inspection.  If
the user application needs to extract content from a GraphBLAS matrix or
vector, use \verb'GrB_*_extractTuples' or the import/export methods instead.

GraphBLAS matrices and vectors are zero-based, where indices of an $n$-by-$n$
matrix are in the range 0 to $n-1$.  However, MATLAB, Octave, and Julia prefer
to print their matrices and vectors as one-based.  To enable 1-based printing,
use \verb'GxB_set (GxB_PRINT_1BASED, true)'.  Printing is done as zero-based by
default.

\newpage
%===============================================================================
\subsection{{\sf GxB\_fprint:} Print a GraphBLAS object to a file} %============
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_fprint                 // print and check a GraphBLAS object
(
    GrB_<objecttype> object,        // object to print and check
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

The \verb'GxB_fprint' function prints the contents of any of the ten GraphBLAS
objects to the file \verb'f'.  If \verb'f' is \verb'NULL', the results are
printed to \verb'stdout'.  For example, to print the entire contents of a
matrix \verb'A' to the file \verb'f', use
\verb'GxB_fprint (A, GxB_COMPLETE, f)'.

%===============================================================================
\subsection{{\sf GxB\_print:} Print a GraphBLAS object to {\sf stdout}} %=======
%===============================================================================
\label{gxb_print}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_print                  // print and check a GrB_Vector
(
    GrB_<objecttype> object,        // object to print and check
    GxB_Print_Level pr              // print level
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_print' is the same as \verb'GxB_fprint', except that it prints the
contents of the object to \verb'stdout' instead of a file \verb'f'.  For
example, to print the entire contents of a matrix \verb'A',  use
\verb'GxB_print (A, GxB_COMPLETE)'.

%===============================================================================
\subsection{{\sf GxB\_Type\_fprint:} Print a {\sf GrB\_Type}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Type_fprint            // print and check a GrB_Type
(
    GrB_Type type,                  // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example, \verb'GxB_Type_fprint (GrB_BOOL, "boolean type", GxB_COMPLETE, f)'
prints the contents of the \verb'GrB_BOOL' object to the file \verb'f'.

\newpage
%===============================================================================
\subsection{{\sf GxB\_UnaryOp\_fprint:} Print a {\sf GrB\_UnaryOp}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_UnaryOp_fprint         // print and check a GrB_UnaryOp
(
    GrB_UnaryOp unaryop,            // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_UnaryOp_fprint (GrB_LNOT, "not", GxB_COMPLETE, f)'
prints the \verb'GrB_LNOT' unary operator to the file \verb'f'.


%===============================================================================
\subsection{{\sf GxB\_BinaryOp\_fprint:} Print a {\sf GrB\_BinaryOp}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_BinaryOp_fprint        // print and check a GrB_BinaryOp
(
    GrB_BinaryOp binaryop,          // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_BinaryOp_fprint (GrB_PLUS_FP64, "plus", GxB_COMPLETE, f)' prints the
\verb'GrB_PLUS_FP64' binary operator to the file \verb'f'.


%===============================================================================
\subsection{{\sf GxB\_IndexUnaryOp\_fprint:} Print a {\sf GrB\_IndexUnaryOp}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_IndexUnaryOp_fprint    // print and check a GrB_IndexUnaryOp
(
    GrB_IndexUnaryOp op,            // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GrB_IndexUnaryOp_fprint (GrB_TRIL, "tril", GxB_COMPLETE, f)' prints
the \verb'GrB_TRIL' index-unary operator to the file \verb'f'.

\newpage
%===============================================================================
\subsection{{\sf GxB\_Monoid\_fprint:} Print a {\sf GrB\_Monoid}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Monoid_fprint          // print and check a GrB_Monoid
(
    GrB_Monoid monoid,              // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Monoid_fprint (GxB_PLUS_FP64_MONOID, "plus monoid",'
\verb'GxB_COMPLETE, f)'
prints the predefined \verb'GxB_PLUS_FP64_MONOID' (based on the binary
operator \verb'GrB_PLUS_FP64') to the file \verb'f'.

%===============================================================================
\subsection{{\sf GxB\_Semiring\_fprint:} Print a {\sf GrB\_Semiring}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Semiring_fprint        // print and check a GrB_Semiring
(
    GrB_Semiring semiring,          // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Semiring_fprint (GxB_PLUS_TIMES_FP64, "standard",'
\verb'GxB_COMPLETE, f)'
prints the predefined \verb'GxB_PLUS_TIMES_FP64' semiring to the file \verb'f'.

%===============================================================================
\subsection{{\sf GxB\_Descriptor\_fprint:} Print a {\sf GrB\_Descriptor}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Descriptor_fprint      // print and check a GrB_Descriptor
(
    GrB_Descriptor descriptor,      // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Descriptor_fprint (d, "descriptor", GxB_COMPLETE, f)'
prints the descriptor \verb'd' to the file \verb'f'.

\newpage
%===============================================================================
\subsection{{\sf GxB\_Matrix\_fprint:} Print a {\sf GrB\_Matrix}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_fprint          // print and check a GrB_Matrix
(
    GrB_Matrix A,                   // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example, \verb'GxB_Matrix_fprint (A, "my matrix", GxB_SHORT, f)'
prints about 30 entries from the matrix \verb'A' to the file \verb'f'.


%===============================================================================
\subsection{{\sf GxB\_Vector\_fprint:} Print a {\sf GrB\_Vector}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_fprint          // print and check a GrB_Vector
(
    GrB_Vector v,                   // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example, \verb'GxB_Vector_fprint (v, "my vector", GxB_SHORT, f)'
prints about 30 entries from the vector \verb'v' to the file \verb'f'.

%===============================================================================
\subsection{{\sf GxB\_Scalar\_fprint:} Print a {\sf GrB\_Scalar}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Scalar_fprint          // print and check a GrB_Scalar
(
    GrB_Scalar s,                   // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example, \verb'GxB_Scalar_fprint (s, "my scalar", GxB_SHORT, f)'
prints a short description of the scalar \verb's' to the file \verb'f'.

\newpage
%===============================================================================
\subsection{Performance and portability considerations}
%===============================================================================

Even when the print level is \verb'GxB_SILENT', these methods extensively check
the contents of the objects passed to them, which can take some time.  They
should be considered debugging tools only, not for final use in production.

The return value of the \verb'GxB_*print' methods can be relied upon, but the
output to the file (or \verb'stdout') can change from version to version.  If
these methods are eventually added to the GraphBLAS C API Specification, a
conforming implementation might never print anything at all, regardless of the
\verb'pr' value.  This may be essential if the GraphBLAS library is installed
in a dedicated device, with no file output, for example.

Some implementations may wish to print nothing at all if the matrix is not yet
completed, or just an indication that the matrix has pending operations and
cannot be printed, when non-blocking mode is employed.  In this case, use
\verb'GrB_Matrix_wait', \verb'GrB_Vector_wait', or \verb'GxB_Scalar_wait' to
finish all pending computations first.  If a matrix or vector has pending
operations, SuiteSparse:GraphBLAS prints a list of the {\em pending tuples},
which are the entries not yet inserted into the primary data structure.  It can
also print out entries that remain in the data structure but are awaiting
deletion; these are called {\em zombies} in the output report.

Most of the rest of the report is self-explanatory.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Matrix and Vector iterators} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{iter}

The \verb'GxB_Iterator' is an object that allows user applications to iterate
over the entries of a matrix or vector, one entry at a time.  Iteration can
be done in a linear manner (analogous to reading a file one entry at a time,
from start to finish), or in a random-access pattern (analogous to
the \verb'fseek' method for repositioning the access to file to a different 
position).

Multiple iterators can be used on a single matrix or vector, even in parallel
by multiple user threads.  While a matrix or vector is being used with an
iterator, the matrix or vector must not be modified.  Doing so will lead to
undefined results.

Since accessing a matrix or vector via an iterator requires many calls to
the iterator methods, they must be very fast.  Error checking is skipped,
except for the methods that create, attach, or free an iterator.  Methods
that advance an iterator or that access values or indices from a matrix or
vector do not return error conditions.  Instead, they have well-defined
preconditions that must be met (and which should be checked by the user
application).  If those preconditions are not met, results are undefined.

The iterator methods are implemented in SuiteSparse:GraphBLAS as both macros
(via \verb'#define') and as functions of the same name that appear in the
compiled \verb'libgraphblas.so' library.  This requires that the opaque
contents of the iterator object be defined in \verb'GraphBLAS.h' itself.  The
user application must not access these contents directly, but can only do so
safely via the iterator methods provided by SuiteSparse:GraphBLAS.

The iterator object can be used in one of four sets of methods,
for four different access patterns:

    \begin{enumerate}
    \item {\em row iterator}:  iterates across the rows of a matrix, and then
        within each row to access the entries in a given row.  Accessing all
        the entries of a matrix using a row iterator requires an outer loop
        (for the rows) and an inner loop (for the entries in each row).
        A matrix can be accessed via a row iterator only if its format
        (determined by \verb'GxB_get (A, GxB_FORMAT, &fmt)') is by-row
        (that is, \verb'GxB_BY_ROW').
        See Section~\ref{options}.
    \item {\em column iterator}:  iterates across the columns of a matrix, and
        then within each column to access the entries in a given column.
        Accessing all the entries of a matrix using a column iterator requires
        an outer loop (for the columns) and an inner loop (for the entries in
        each column).  A matrix can be accessed via a column iterator only if
        its format (determined by \verb'GxB_get (A, GxB_FORMAT, &fmt)') is
        by-column (that is, \verb'GxB_BY_COL').
        See Section~\ref{options}.
    \item {\em entry iterator}:  iterates across the entries of a matrix.
        Accessing all the entries of a matrix using an entry iterator requires
        just a single loop.  Any matrix can be accessed with an entry iterator.
    \item {\em vector iterator}:  iterates across the entries of a vector.
        Accessing all the entries of a vector using a vector iterator requires
        just a single loop.  Any vector can be accessed with a vector iterator.
    \end{enumerate}

\newpage
%===============================================================================
\subsection{Creating and destroying an iterator}
%===============================================================================

The process for using an iterator starts with the creation of an iterator, with
\verb'GxB_Iterator_new'.  This method creates an \verb'iterator' object but
does not {\em attach} it to any specific matrix or vector:

    {\footnotesize
    \begin{verbatim}
    GxB_Iterator iterator ;
    GxB_Iterator_new (&iterator) ; \end{verbatim}}

When finished, the \verb'iterator' is freed with either of these methods:

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

%===============================================================================
\subsection{Attaching an iterator to a matrix or vector}
%===============================================================================

This new \verb'iterator' object can be {\em attached} to any matrix or vector,
and used as a row, column, or entry iterator for any matrix, or as an iterator
for any vector.  The \verb'iterator' can be used in any of these methods before
it is freed, but with just one access method at a time.

Once it is created, the \verb'iterator' must be attached to a matrix or
vector.  This process also selects the method by which the \verb'iterator'
will be used for a matrix.  Each of the four \verb'GxB_*Iterator_attach'
methods returns a \verb'GrB_Info' result.  The descriptor \verb'desc' in the
examples below is used only to control the number of threads used for the
internal call to \verb'GrB_wait', if the matrix \verb'A' or vector \verb'v' has
pending operations.

    \begin{enumerate}
    \item {\em row iterator}: 
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_rowIterator_attach (iterator, A, desc) ; \end{verbatim}}
    \item {\em column iterator}: 
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_colIterator_attach (iterator, A, desc) ; \end{verbatim}}
    \item {\em entry iterator}:
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_Matrix_Iterator_attach (iterator, A, desc) ; \end{verbatim}}
    \item {\em vector iterator}:
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_Vector_Iterator_attach (iterator, v, desc) ; \end{verbatim}}
    \end{enumerate}

On input to \verb'GxB_*Iterator_attach', the \verb'iterator' must already
exist, having been created by \verb'GxB_Iterator_new'.  If the \verb'iterator'
is already attached to a matrix or vector, it is detached and then attached to
the given matrix \verb'A' or vector \verb'v'.

The return values for row/column methods are:

    \begin{itemize}
    \item
    \verb'GrB_SUCCESS':         if the \verb'iterator' is successfully
        attached to the matrix \verb'A'.
    \item
    \verb'GrB_NULL_POINTER':    if the \verb'iterator' or \verb'A' are NULL.
    \item
    \verb'GrB_INVALID_OBJECT':  if the matrix \verb'A' is invalid.
    \item
    \verb'GrB_NOT_IMPLEMENTED': if the matrix \verb'A' cannot be iterated
        in the requested access method (row iterators require the matrix to
        be held by-row, and column iterators require the matrix to be held
        by-column).
    \item
    \verb'GrB_OUT_OF_MEMORY':   if the method runs out of memory.
    \end{itemize}

The other two methods (entry iterator for matrices, or the vector iterator)
return the same error codes, except that they
do not return \verb'GrB_NOT_IMPLEMENTED'.

%===============================================================================
\subsection{Seeking to an arbitrary position}
%===============================================================================

Attaching the \verb'iterator' to a matrix or vector does not define a specific
position for the \verb'iterator'.  To use the \verb'iterator', a single call to
the corresponding {\em seek} method is required.  These
\verb'GxB*_Iterator_*seek*' methods may also be used later on to change the
position of the iterator arbitrarily.

    \begin{enumerate}
    \item {\em row iterator}: 
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_rowIterator_seekRow (iterator, row) ;
    GrB_Index kount = GxB_rowIterator_kount (iterator) ;
    GrB_Info info = GxB_rowIterator_kseek (iterator, k) ; \end{verbatim}}

        These methods move a row iterator to a specific row, defined in one of
        two ways: (1) the row index itself (in range 0 to \verb'nrows'-1), or
        (2) by specifying \verb'k', which moves the iterator to the \verb'k'th
        {\em explicit} row (in the range 0 to \verb'kount'-1). For sparse,
        bitmap, or full matrices, these two methods are identical.  For
        hypersparse matrices, not all rows are present in the data structure;
        these {\em implicit} rows are skipped and not included in the
        \verb'kount'.  Implicit rows contain no entries.  The
        \verb'GxB_rowIterator_kount' method returns the \verb'kount' of the
        matrix, where \verb'kount' is equal to \verb'nrows' for sparse, bitmap,
        and matrices, and \verb'kount' $\le$ \verb'nrows' for hypersparse
        matrices.  All three methods listed above can be used for any row
        iterator.

        The \verb'GxB_rowIterator_*seek*' methods return \verb'GrB_SUCCESS' if
        the iterator has been moved to a row that contains at least one entry,
        \verb'GrB_NO_VALUE' if the row has no entries, or \verb'GxB_EXHAUSTED'
        if the row is out of bounds (\verb'row' $\ge$ \verb'nrows' or
        if \verb'k' $\ge$ \verb'kount').
        None of these return conditions are
        errors; they are all informational.

        For sparse, bitmap, and full matrices, \verb'GxB_rowIterator_seekRow'
        always moves to the given row.  For hypersparse matrices, if the
        requested row is implicit, the iterator is moved to the first
        explicit row following it.  If no such row exists, the iterator
        is exhausted and \verb'GxB_EXHAUSTED' is returned.
        The \verb'GxB_rowIterator_kseek' method always moves to the \verb'k'th
        explicit row, for any matrix.
        Use \verb'GxB_rowIterator_getRowIndex', described below, to determine
        the row index of the current position.

        Precondition: on input, the \verb'iterator' must have been successfully
        attached to a matrix via a prior call to \verb'GxB_rowIterator_attach'.
        Results are undefined if this precondition is not met.

    \item {\em column iterator}: 
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_colIterator_seekCol (iterator, col) ;
    GrB_Index kount = GxB_colIterator_kount (iterator) ;
    GrB_Info info = GxB_colIterator_kseek (iterator, k) ; \end{verbatim}}

        These methods move a column iterator to a specific column, defined in
        one of two ways: (1) the column index itself (in range 0 to
        \verb'ncols'-1), or (2) by specifying \verb'k', which moves the
        iterator to the \verb'k'th {\em explicit} column (in the range 0 to
        \verb'kount'-1). For sparse, bitmap, or full matrices, these two
        methods are identical.  For hypersparse matrices, not all columns are
        present in the data structure; these {\em implicit} columns are skipped
        and not included in the \verb'kount'.  Implicit columns contain no
        entries.  The \verb'GxB_colIterator_kount' method returns the
        \verb'kount' of the matrix, where \verb'kount' is equal to \verb'ncols'
        for sparse, bitmap, and matrices, and \verb'kount' $\le$ \verb'ncols'
        for hypersparse matrices.  All three methods listed above can be used
        for any column iterator.

        The \verb'GxB_colIterator_*seek*' methods return \verb'GrB_SUCCESS' if
        the iterator has been moved to a column that contains at least one
        entry, \verb'GrB_NO_VALUE' if the column has no entries, or
        \verb'GxB_EXHAUSTED' if the column is out of bounds (\verb'col' $\ge$
        \verb'ncols' or \verb'k' $\ge$ \verb'kount').
        None of these return conditions are
        errors; they are all informational.

        For sparse, bitmap, and full matrices, \verb'GxB_colIterator_seekCol'
        always moves to the given column.  For hypersparse matrices, if the
        requested column is implicit, the iterator is moved to the first
        explicit column following it.  If no such column exists, the iterator
        is exhausted and \verb'GxB_EXHAUSTED' is returned.
        The \verb'GxB_colIterator_kseek' method always moves to the \verb'k'th
        explicit column, for any matrix.
        Use \verb'GxB_colIterator_getColIndex', described below, to determine
        the column index of the current position.

        Precondition: on input, the \verb'iterator' must have been successfully
        attached to a matrix via a prior call to \verb'GxB_colIterator_attach'.
        Results are undefined if this precondition is not met.

    \item {\em entry iterator}:
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_Matrix_Iterator_seek (iterator, p) ;
    GrB_Index pmax = GxB_Matrix_Iterator_getpmax (iterator) ;
    GrB_Index p = GxB_Matrix_Iterator_getp (iterator); \end{verbatim}}

        The \verb'GxB_Matrix_Iterator_seek' method moves the \verb'iterator' to
        the given position \verb'p', which is in the range 0 to \verb'pmax'-1,
        where the value of \verb'pmax' is obtained from
        \verb'GxB_Matrix_Iterator_getpmax'.
        For sparse, hypersparse, and full matrices, \verb'pmax' is the same as
        \verb'nvals' returned by \verb'GrB_Matrix_nvals'.  For bitmap matrices,
        \verb'pmax' is equal to \verb'nrows*ncols'.  If \verb'p' $\ge$
        \verb'pmax', the iterator is exhausted and \verb'GxB_EXHAUSTED' is
        returned.  Otherwise, \verb'GrB_SUCCESS' is returned.

        All entries in the matrix are given an ordinal position, \verb'p'.
        Seeking to position \verb'p' will either move the \verb'iterator' to
        that particular position, or to the next higher position containing an
        entry if there is entry at position \verb'p'.  The latter case only
        occurs for bitmap matrices.
        Use \verb'GxB_Matrix_Iterator_getp' to determine the current
        position of the iterator.

        Precondition: on input, the \verb'iterator' must have been successfully
        attached to a matrix via a prior call to
        \verb'GxB_Matrix_Iterator_attach'.  Results are undefined if this
        precondition is not met.

    \item {\em vector iterator}:
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_Vector_Iterator_seek (iterator, p) ;
    GrB_Index pmax = GxB_Vector_Iterator_getpmax (iterator) ;
    GrB_Index p = GxB_Vector_Iterator_getp (iterator); \end{verbatim}}

        The \verb'GxB_Vector_Iterator_seek' method is identical to the
        entry iterator of a matrix, but applied to a \verb'GrB_Vector' instead.

        Precondition: on input, the \verb'iterator' must have been successfully
        attached to a vector via a prior call to
        \verb'GxB_Vector_Iterator_attach'.  Results are undefined if this
        precondition is not met.

    \end{enumerate}

%===============================================================================
\subsection{Advancing to the next position}
%===============================================================================

For best performance, the {\em seek} methods described above should be used
with care, since some of them require $O(\log n)$ time.  The fastest method
for changing the position of the iterator is the corresponding {\em next}
method, described below for each iterator:

    \begin{enumerate}
    \item {\em row iterator}:  To move to the next row.

    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_rowIterator_nextRow (iterator) ; \end{verbatim}}

    The row iterator is a 2-dimensional iterator, requiring an outer loop and
    an inner loop.  The outer loop iterates over the rows of the matrix, using
    \verb'GxB_rowIterator_nextRow' to move to the next row.  If the matrix is
    hypersparse, the next row is always an explicit row; implicit rows are
    skipped.  The return conditions are identical to
    \verb'GxB_rowIterator_seekRow'.

    Preconditions: on input, the row iterator must already be attached to a
    matrix via a prior call to \verb'GxB_rowIterator_attach', and the
    \verb'iterator' must be at a specific row, via a prior call to
    \verb'GxB_rowIterator_*seek*' or \verb'GxB_rowIterator_nextRow'. 
    Results are undefined if these conditions are not met.

    \item {\em row iterator}:  To move to the next entry within a row.

    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_rowIterator_nextCol (iterator) ; \end{verbatim}}

    The row iterator is moved to the next entry in the current row.
    The method returns \verb'GrB_NO_VALUE' if the end of the row is reached.
    The iterator does not move to the next row in this case.
    The method returns \verb'GrB_SUCCESS' if the iterator has been moved
    to a specific entry in the current row.

    Preconditions: the same as \verb'GxB_rowIterator_nextRow'.

    \item {\em column iterator}:  To move to the next column

    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_colIterator_nextCol (iterator) ; \end{verbatim}}

    The column iterator is a 2-dimensional iterator, requiring an outer loop
    and an inner loop.  The outer loop iterates over the columns of the matrix,
    using \verb'GxB_colIterator_nextCol' to move to the next column.  If the
    matrix is hypersparse, the next column is always an explicit column;
    implicit columns are skipped.  The return conditions are identical to
    \verb'GxB_colIterator_seekCol'.

    Preconditions: on input, the column iterator must already be attached to a
    matrix via a prior call to \verb'GxB_colIterator_attach', and the
    \verb'iterator' must be at a specific column, via a prior call to
    \verb'GxB_colIterator_*seek*' or \verb'GxB_colIterator_nextCol'.
    Results are undefined if these conditions are not met.

    {\footnotesize
    \item {\em column iterator}:  To move to the next entry within a column.

    \begin{verbatim}
    GrB_Info info = GxB_colIterator_nextRow (iterator) ; \end{verbatim}}

    The column iterator is moved to the next entry in the current column.
    The method returns \verb'GrB_NO_VALUE' if the end of the column is reached.
    The iterator does not move to the next column in this case.
    The method returns \verb'GrB_SUCCESS' if the iterator has been moved
    to a specific entry in the current column.

    Preconditions: the same as \verb'GxB_colIterator_nextCol'.

    \item {\em entry iterator}: To move to the next entry.
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_Matrix_Iterator_next (iterator) ; \end{verbatim}}

    This method moves an iterator to the next entry of a matrix.
    It returns \verb'GrB_SUCCESS' if the iterator is at an entry that
    exists in the matrix, or \verb'GrB_EXHAUSTED' otherwise.

    Preconditions: on input, the entry iterator must be already attached to a
    matrix via \verb'GxB_Matrix_Iterator_attach', and the position of the
    iterator must also have been defined by a prior call to
    \verb'GxB_Matrix_Iterator_seek' or \verb'GxB_Matrix_Iterator_next'.
    Results are undefined if these conditions are not met.

    \item {\em vector iterator}: To move to the next entry.
    {\footnotesize
    \begin{verbatim}
    GrB_Info info = GxB_Vector_Iterator_next (iterator) ; \end{verbatim}}

    This method moves an iterator to the next entry of a vector.
    It returns \verb'GrB_SUCCESS' if the iterator is at an entry that
    exists in the vector, or \verb'GrB_EXHAUSTED' otherwise.

    Preconditions: on input, the iterator must be already attached to a
    vector via \verb'GxB_Vector_Iterator_attach', and the position of the
    iterator must also have been defined by a prior call to
    \verb'GxB_Vector_Iterator_seek' or \verb'GxB_Vector_Iterator_next'.
    Results are undefined if these conditions are not met.

    \end{enumerate}

%===============================================================================
\subsection{Accessing the indices of the current entry}
%===============================================================================

Once the iterator is attached to a matrix or vector, and is placed in position
at an entry in the matrix or vector, the indices and value of this entry can be
obtained.  The methods for accessing the value of the entry are described in
Section~\ref{getvalu}.  Accessing the indices is performed with four different
sets of methods, depending on which access pattern is in use, described below:

    \begin{enumerate}
    \item {\em row iterator}:  To get the current row index.
    {\footnotesize
    \begin{verbatim}
    GrB_Index i = GxB_rowIterator_getRowIndex (iterator) ; \end{verbatim}}

    The method returns \verb'nrows(A)' if the iterator is exhausted, or the
    current row index \verb'i' otherwise.  There need not be any entry in the
    current row.  Zero is returned if the iterator is attached to the matrix
    but \verb'GxB_rowIterator_*seek*' has not been called, but this does not
    mean the iterator is positioned at row zero.

    Preconditions: on input, the iterator must be already successfully attached
    to matrix as a row iterator via \verb'GxB_rowIterator_attach'.
    Results are undefined if this condition is not met.

    \item {\em row iterator}:  To get the current column index.
    {\footnotesize
    \begin{verbatim}
    GrB_Index j = GxB_rowIterator_getColIndex (iterator) ; \end{verbatim}}

    Preconditions: on input, the iterator must be already successfully attached
    to matrix as a row iterator via \verb'GxB_rowIterator_attach', and in
    addition, the row iterator must be positioned at a valid entry present in
    the matrix.  That is, the last call to \verb'GxB_rowIterator_*seek*' or
    \verb'GxB_rowIterator_*next*', must have returned \verb'GrB_SUCCESS'.
    Results are undefined if these conditions are not met.

    \item {\em column iterator}:  To get the current column index.
    {\footnotesize
    \begin{verbatim}
    GrB_Index j = GxB_colIterator_getColIndex (iterator) ; \end{verbatim}}

    The method returns \verb'ncols(A)' if the iterator is exhausted, or the
    current column index \verb'j' otherwise.  There need not be any entry in the
    current column.  Zero is returned if the iterator is attached to the matrix
    but \verb'GxB_colIterator_*seek*' has not been called, but this does not
    mean the iterator is positioned at column zero.

    Precondition: on input, the iterator must be already successfully attached
    to matrix as a column iterator via \verb'GxB_colIterator_attach'.
    Results are undefined if this condition is not met.

    \item {\em column iterator}:  To get the current row index.
    {\footnotesize
    \begin{verbatim}
    GrB_Index i = GxB_colIterator_getRowIndex (iterator) ; \end{verbatim}}

    Preconditions: on input, the iterator must be already successfully attached
    to matrix as a column iterator via \verb'GxB_colIterator_attach', and in
    addition, the column iterator must be positioned at a valid entry present in
    the matrix.  That is, the last call to \verb'GxB_colIterator_*seek*' or
    \verb'GxB_colIterator_*next*', must have returned \verb'GrB_SUCCESS'.
    Results are undefined if these conditions are not met.

    \item {\em entry iterator}: To get the current row and column index.
    {\footnotesize
    \begin{verbatim}
    GrB_Index i, j ;
    GxB_Matrix_Iterator_getIndex (iterator, &i, &j) ; \end{verbatim}}

    Returns the row and column index of the current entry.

    Preconditions: on input, the entry iterator must be already attached to a
    matrix via \verb'GxB_Matrix_Iterator_attach', and the position of the
    iterator must also have been defined by a prior call to
    \verb'GxB_Matrix_Iterator_seek' or \verb'GxB_Matrix_Iterator_next', with a
    return value of \verb'GrB_SUCCESS'.
    Results are undefined if these conditions are not met.

    \item {\em vector iterator}: To get the current index.
    {\footnotesize
    \begin{verbatim}
    GrB_Index i = GxB_Vector_Iterator_getIndex (iterator) ; \end{verbatim}}

    Returns the index of the current entry.

    Preconditions: on input, the entry iterator must be already attached to a
    matrix via \verb'GxB_Vector_Iterator_attach', and the position of the
    iterator must also have been defined by a prior call to
    \verb'GxB_Vector_Iterator_seek' or \verb'GxB_Vector_Iterator_next', with a
    return value of \verb'GrB_SUCCESS'.
    Results are undefined if these conditions are not met.

    \end{enumerate}

%===============================================================================
\subsection{Accessing the value of the current entry}
\label{getvalu}
%===============================================================================

So far, all methods that create or use an iterator have been split into four
sets of methods, for the row, column, or entry iterators attached to a matrix,
or for a vector iterator.  Accessing the value is different.  All four
iterators use the same set of methods to access the value of their current
entry.  These methods return the value of the current entry at the position
determined by the iterator.  The return value can of course be typecasted
using standard C syntax once the value is returned to the caller.

Preconditions: on input, the prior call to \verb'GxB_*Iterator_*seek*', or
\verb'GxB_*Iterator_*next*' must have returned \verb'GrB_SUCCESS', indicating
that the iterator is at a valid current entry for either a matrix or vector.
No typecasting is permitted, in the sense that the method name must match the
type of the matrix or vector.
Results are undefined if these conditions are not met.

    {\footnotesize
    \begin{verbatim}
    // for built-in types:
    bool       value = GxB_Iterator_get_BOOL (iterator) ;
    int8_t     value = GxB_Iterator_get_INT8 (iterator) ;
    int16_t    value = GxB_Iterator_get_INT16 (iterator) ;
    int32_t    value = GxB_Iterator_get_INT32 (iterator) ;
    int64_t    value = GxB_Iterator_get_INT64 (iterator) ;
    uint8_t    value = GxB_Iterator_get_UINT8 (iterator) ;
    uint16_t   value = GxB_Iterator_get_UINT16 (iterator) ;
    uint32_t   value = GxB_Iterator_get_UINT32 (iterator) ;
    uint64_t   value = GxB_Iterator_get_UINT64 (iterator) ;
    float      value = GxB_Iterator_get_FP32 (iterator) ;
    double     value = GxB_Iterator_get_FP64 (iterator) ;
    GxB_FC32_t value = GxB_Iterator_get_FC32 (iterator) ;
    GxB_FC64_t value = GxB_Iterator_get_FC64 (iterator) ;

    // for user-defined types:
    <type> value ;
    GxB_Iterator_get_UDT (iterator, (void *) &value) ; \end{verbatim}}

%===============================================================================
\newpage
\subsection{Example: row iterator for a matrix}
%===============================================================================

The following example uses a row iterator to access all of the entries
in a matrix \verb'A' of type \verb'GrB_FP64'.  Note the inner and outer loops.
The outer loop iterates over all rows of the matrix.  The inner loop iterates
over all entries in the row \verb'i'.  This access pattern requires the matrix
to be held by-row, but otherwise it works for any matrix.  If the matrix is
held by-column, then use the column iterator methods instead.

    {\footnotesize
    \begin{verbatim}
    // create an iterator
    GxB_Iterator iterator ;
    GxB_Iterator_new (&iterator) ;
    // attach it to the matrix A, known to be type GrB_FP64
    GrB_Info info = GxB_rowIterator_attach (iterator, A, NULL) ;
    if (info < 0) { handle the failure ... }
    // seek to A(0,:)
    info = GxB_rowIterator_seekRow (iterator, 0) ;
    while (info != GxB_EXHAUSTED)
    {
        // iterate over entries in A(i,:)
        GrB_Index i = GxB_rowIterator_getRowIndex (iterator) ;
        while (info == GrB_SUCCESS)
        {
            // get the entry A(i,j)
            GrB_Index j = GxB_rowIterator_getColIndex (iterator) ;
            double  aij = GxB_Iterator_get_FP64 (iterator) ;
            // move to the next entry in A(i,:)
            info = GxB_rowIterator_nextCol (iterator) ;
        }
        // move to the next row, A(i+1,:), or a subsequent one if i+1 is implicit
        info = GxB_rowIterator_nextRow (iterator) ;
    }
    GrB_free (&iterator) ; \end{verbatim}}

%===============================================================================
\newpage
\subsection{Example: column iterator for a matrix}
%===============================================================================

The column iterator is analgous to the row iterator.

The following example uses a column iterator to access all of the entries in a
matrix \verb'A' of type \verb'GrB_FP64'.  The outer loop iterates over all
columns of the matrix.  The inner loop iterates over all entries in the column
\verb'j'.  This access pattern requires the matrix to be held by-column, but
otherwise it works for any matrix.  If the matrix is held by-row, then use
the row iterator methods instead.

    {\footnotesize
    \begin{verbatim}
    // create an iterator
    GxB_Iterator iterator ;
    GxB_Iterator_new (&iterator) ;
    // attach it to the matrix A, known to be type GrB_FP64
    GrB_Info info = GxB_colIterator_attach (iterator, A, NULL) ;
    // seek to A(:,0)
    info = GxB_colIterator_seekCol (iterator, 0) ;
    while (info != GxB_EXHAUSTED)
    {
        // iterate over entries in A(:,j)
        GrB_Index j = GxB_colIterator_getColIndex (iterator) ;
        while (info == GrB_SUCCESS)
        {
            // get the entry A(i,j)
            GrB_Index i = GxB_colIterator_getRowIndex (iterator) ;
            double  aij = GxB_Iterator_get_FP64 (iterator) ;
            // move to the next entry in A(:,j)
            info = GxB_colIterator_nextRow (iterator) ;
            OK (info) ;
        }
        // move to the next column, A(:,j+1), or a subsequent one if j+1 is implicit
        info = GxB_colIterator_nextCol (iterator) ;
    }
    GrB_free (&iterator) ; \end{verbatim}}

%===============================================================================
\newpage
\subsection{Example: entry iterator for a matrix}
%===============================================================================

The entry iterator allows for a simpler access pattern, with a single loop, but
using a row or column iterator is faster.  The method works for any matrix.

    {\footnotesize
    \begin{verbatim}
    // create an iterator
    GxB_Iterator iterator ;
    GxB_Iterator_new (&iterator) ;
    // attach it to the matrix A, known to be type GrB_FP64
    GrB_Info info = GxB_Matrix_Iterator_attach (iterator, A, NULL) ;
    if (info < 0) { handle the failure ... }
    // seek to the first entry
    info = GxB_Matrix_Iterator_seek (iterator, 0) ;
    while (info != GxB_EXHAUSTED)
    {
        // get the entry A(i,j)
        GrB_Index i, j ;
        GxB_Matrix_Iterator_getIndex (iterator, &i, &j) ;
        double aij = GxB_Iterator_get_FP64 (iterator) ;
        // move to the next entry in A
        info = GxB_Matrix_Iterator_next (iterator) ;
    }
    GrB_free (&iterator) ; \end{verbatim}}

%===============================================================================
\subsection{Example: vector iterator}
%===============================================================================

A vector iterator is used much like an entry iterator for a matrix.

    {\footnotesize
    \begin{verbatim}
    // create an iterator
    GxB_Iterator iterator ;
    GxB_Iterator_new (&iterator) ;
    // attach it to the vector v, known to be type GrB_FP64
    GrB_Info info = GxB_Vector_Iterator_attach (iterator, v, NULL) ;
    if (info < 0) { handle the failure ... }
    // seek to the first entry
    info = GxB_Vector_Iterator_seek (iterator, 0) ;
    while (info != GxB_EXHAUSTED)
    {
        // get the entry v(i)
        GrB_Index i = GxB_Vector_Iterator_getIndex (iterator) ;
        double vi = GxB_Iterator_get_FP64 (iterator) ;
        // move to the next entry in v
        info = GxB_Vector_Iterator_next (iterator) ;
    }
    GrB_free (&iterator) ; \end{verbatim}}

%===============================================================================
\newpage
\subsection{Performance}
%===============================================================================

I have benchmarked the performance of the row and column iterators to compute
\verb'y=0' and then \verb'y+=A*x' where \verb'y' is a dense vector and \verb'A'
is a sparse matrix, using a single thread.  The row and column iterators are
very fast, sometimes only 1\% slower than calling \verb'GrB_mxv' to compute the
same thing (also assuming a single thread), for large problems.  For sparse
matrices that average just 1 or 2 entries per row, the row iterator can be
about 30\% slower than \verb'GrB_mxv', likely because of the slightly higher
complexity of moving from one row to the next using these methods.

It is possible to split up the problem for multiple user threads, each with its
own iterator.  Given the low overhead of the row and column iterator for a
single thread, this should be very fast.  Care must be taken to ensure a good
load balance.  Simply spliting up the rows of a matrix and giving the same
number of rows to each user thread can result in imbalanced work.  This is
handled internally in \verb'GrB_*' methods, but enabling parallelism when using
iterators is the responsibility of the user application.

The entry iterators are easier to use but harder to implement.  The methods
must internally fuse both inner and outer loops so that the user application can
use a single loop.  As a result, the computation \verb'y+=A*x' can be up to
4x slower (about 2x typical) than when using \verb'GrB_mxv' with a single
thread.

To obtain the best performace possible, many of the iterator methods are
implemented as macros in \verb'GraphBLAS.h'.  Using macros is the default,
giving typical C and C++ applications access to the fastest methods possible.

To ensure access to these methods when not using the macros, these methods are
also defined as regular functions that appear in the compiled
\verb'libgraphblas.so' library with the same name as the macros.  Applications
that cannot use the macro versions can \verb'#undef' the macros after the
\verb'#include <GraphBLAS.h>' statement, and then they would access the regular
compiled functions in \verb'libgraphblas.so'.  This non-macro approach is not
the default, and the iterator methods may be slightly slower.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Iso-Valued Matrices and Vectors } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{iso}

The GraphBLAS C API states that the entries in all \verb'GrB_Matrix' and
\verb'GrB_Vector' objects have a numerical value, with either a built-in or
user-defined type.  Representing an unweighted graph requires a value to be
placed on each edge, typically $a_{ij}=1$.  Adding a structure-only data type
would not mix well with the rest of GraphBLAS, where all operators, monoids,
and semirings need to operate on a value, of some data type.  And yet
unweighted graphs are very important in graph algorithms.

The solution is simple, and exploiting it in SuiteSparse:GraphBLAS requires
nearly no extensions to the GraphBLAS C API.   SuiteSparse:GraphBLAS can often
detect when the user application is creating a matrix or vector where all
entries in the sparsity pattern take on the same numerical value.

For example, ${\bf C \langle C \rangle} = 1$, when the mask is structural, sets
all entries in $\bf C$ to the value 1.  SuiteSparse:GraphBLAS detects this, and
performs this assignment in $O(1)$ time.  It stores a single copy of this
``iso-value'' and sets an internal flag in the opaque data structure for $\bf
C$, which states that all entries in the pattern of $\bf C$ are equal to 1.
This saves both time and memory and allows for the efficient representation of
sparse adjacency matrices of unweighted graphs, yet does not change the C API.
To the user application, it still appears that $\bf C$ has \verb'nvals(C)'
entries, all equal to 1.

Creating and operating on iso-valued matrices (or just {\em iso matrices} for 
short) is significantly faster than creating matrices with different data
values.  A matrix that is iso requires only $O(1)$ space for its numerical
values.  The sparse and hypersparse formats require an additional $O(n+e)$ or
$O(e)$ integer space to hold the pattern of an $n$-by-$n$ matrix \verb'C',
respectively, and a matrix \verb'C' in bitmap format requires $O(n^2)$ space
for the bitmap.  A full matrix requires no integer storage, so a matrix that is
both iso and full requires only $O(1)$ space, regardless of its dimension.

The sections below a describe the methods that can be used to create iso
matrices and vectors.  Let $a$, $b$, and $c$ denote the iso values of \verb'A',
\verb'B', and \verb'C', respectively.

%-------------------------------------------------------------------------------
\subsection{Using iso matrices and vectors in a graph algorithm}
%-------------------------------------------------------------------------------
\label{iso_usage}

There are two primary useful ways to use iso-valued matrices and vectors: (1)
as iso sparse/hypersparse adjacency matrices for unweighted graphs, and (2) as
iso full matrices or vectors used with operations that do not need to access
all of the content of the iso full matrix or vector.

In the first use case, simply create a \verb'GrB_Matrix' with values that are
all the same (those in the sparsity pattern).  The
\verb'GxB_Matrix_build_Scalar' method can be used for this, since it
guarantees that the time and work spent on the numerical part of the array
is only $O(1)$.  The method still must spend $O(e)$ or $O(e \log e)$ time
on the integer arrays that represent the sparsity pattern, but the reduction
in time and work on the numerical part of the matrix will improve performance.

The use of \verb'GxB_Matrix_build_Scalar' is optional.  Matrices can also be
constructed with \verb'GrB*' methods.  In particular, \verb'GrB_Matrix_build_*'
can be used.  It first builds a non-iso matrix and then checks if all of the
values are the same, after assembling any duplicate entries.  This does not
save time or memory for the construction of the matrix itself, but it will
lead to savings in time and memory later on, when the matrix is used.

To ensure a matrix \verb'C' is iso-valued, simply use \verb'GrB_assign' to
compute \verb'C<C,struct>=1', or assign whatever value of scalar you wish.
It is essential to use a structural mask.  Otherwise, it is not clear that
all entries in \verb'C' will be assigned the same value.  The following
code takes $O(1)$ time, and it resets the size of the numerical part of the
\verb'C' matrix to be $O(1)$ in size:

{\footnotesize
\begin{verbatim}
    bool scalar = true ;
    GrB_Matrix_assign (C, C, NULL, scalar, GrB_ALL, nrows, GrB_ALL, ncols,
        GrB_DESC_S) ; \end{verbatim}}

The MATLAB/Octave analog of the code above is \verb'C=spones(C)'.

The second case for where iso matrices and vectors are useful is to use them
with operations that do not necessarily access all of their content.
Suppose you have a matrix \verb'A' of arbitrarily large dimension (say
\verb'n'-by-\verb'n' where \verb'n=2^60', of type \verb'GrB_FP64').  A matrix
this large can be represented by SuiteSparse:GraphBLAS, but only in a
hypersparse form.

Now, suppose you wish to compute the maximum value in each row, reducing the
matrix to a vector.  This can be done with \verb'GrB_reduce':

{\footnotesize
\begin{verbatim}
    GrB_Vector_new (&v, GrB_FP64, n) ;
    GrB_reduce (v, NULL, GrB_MAX_MONOID_FP64, A, NULL) ; \end{verbatim}}

It can also be done with \verb'GrB_mxv', by creating an iso full vector
\verb'x'.  The creation of \verb'x' takes $O(1)$ time and memory,
and the \verb'GrB_mxv' computation takes $O(e)$ time (with modest assumptions;
if \verb'A' needs to be transposed the time would be $O(e \log e)$).

{\footnotesize
\begin{verbatim}
    GrB_Vector_new (&v, GrB_FP64, n) ;
    GrB_Vector_new (&x, GrB_FP64, n) ;
    GrB_assign (x, NULL, NULL, 1, GrB_ALL, n, NULL) ;
    GrB_mxv (v, NULL, NULL, GrB_MAX_FIRST_SEMIRING_FP64, A, x, NULL) ; \end{verbatim}}

The above computations are identical in SuiteSparse:GraphBLAS.  Internally,
\verb'GrB_reduce' creates \verb'x' and calls \verb'GrB_mxv'.  Using
\verb'GrB_mxm' directly gives the user application additional flexibility in
creating new computations that exploit the multiplicative operator in the
semiring.  \verb'GrB_reduce' always uses the \verb'FIRST' operator in its
semiring, but any other binary operator can be used instead when using
\verb'GrB_mxv'.

Below is a method for computing the argmax of each row of a square matrix
\verb'A' of dimension \verb'n' and type \verb'GrB_FP64'.  The vector \verb'x'
contains the maximum value in each row, and the vector \verb'p' contains the
zero-based column index of the maximum value in each row.  If there are
duplicate maximum values in each row, any one of them is selected arbitrarily
using the \verb'ANY' monoid.  To select the minimum column index of the
duplicate maximum values, use the \verb'GxB_MIN_SECONDI_INT64' semiring instead
(this will be slightly slower than the \verb'ANY' monoid if there are many
duplicates).

To compute the argmax of each column, use the \verb'GrB_DESC_T0' descriptor
in \verb'GrB_mxv', and compute \verb'G=A*D' instead of \verb'G=D*A' with
\verb'GrB_mxm'.  See the \verb'GrB.argmin' and \verb'GrB.argmax' functions
in the MATLAB/Octave interface for details.

% corresponds to GrB.argmax with dim = 2

{\footnotesize
\begin{verbatim}
    GrB_Vector_new (&x, GrB_FP64, n) ;
    GrB_Vector_new (&y, GrB_FP64, n) ;
    GrB_Vector_new (&p, GrB_INT64, n) ;
    // y (:) = 1, an iso full vector
    GrB_assign (y, NULL, NULL, 1, GrB_ALL, n, NULL) ;
    // x = max (A) where x(i) = max (A (i,:))
    GrB_mxv (x, NULL, NULL, GrB_MAX_FIRST_SEMIRING_FP64, A, y, NULL) ;
    // D = diag (x)
    GrB_Matrix_diag (&D, x, 0) ;
    // G = D*A using the ANY_EQ semiring
    GrB_Matrix_new (&G, GrB_BOOL, n, n) ;
    GrB_mxm (G, NULL, NULL, GxB_ANY_EQ_FP64, D, A, NULL) ;
    // drop explicit zeros from G
    GrB_select (G, NULL, NULL, GrB_VALUENE_BOOL, G, 0, NULL) ;
    // find the position of any max entry in each row: p = G*y,
    // so that p(i) = j if x(i) = A(i,j) = max (A (i,:))
    GrB_mxv (p, NULL, NULL, GxB_ANY_SECONDI_INT64, G, y, NULL) ; \end{verbatim}}

No part of the above code takes $\Omega(n)$ time or memory.  The data type of
the iso full vector \verb'y' can be anything, and its iso value can be
anything.  It is operated on by the \verb'FIRST' operator in the first
\verb'GrB_mxv', and the \verb'SECONDI' positional operator in the second
\verb'GrB_mxv', and both operators are oblivious to the content and even the
type of \verb'y'.  The semirings simply note that \verb'y' is a full vector and
compute their result according, by accessing the matrices only (\verb'A' and
\verb'G', respectively).

For floating-point values, \verb'NaN' values are ignored, and treated as if
they were not present in the input matrix, unless all entries in a given row
are equal to \verb'NaN'.  In that case, if all entries in \verb'A(i,:)' are
equal to \verb'NaN', then \verb'x(i)' is \verb'NaN' and the entry \verb'p(i)'
is not present.

%-------------------------------------------------------------------------------
\subsection{Iso matrices from matrix multiplication}
%-------------------------------------------------------------------------------
\label{iso_mxm}

Consider \verb'GrB_mxm', \verb'GrB_mxv', and \verb'GrB_vxm', and
    let \verb'C=A*B', where no mask is present, or \verb'C<M>=A*B' where
    \verb'C' is initially empty.  If \verb'C' is not initially empty,
    then these rules apply to a temporary matrix \verb'T<M>=A*B', which is
    initially empty and is then assigned to \verb'C' via \verb'C<M>=T'.

    The iso property of \verb'C' is determined with the following rules,
    where the first rule that fits defines the property and value of \verb'C'.

    \begin{itemize}
    \item If the semiring includes a positional multiplicative operator
    (\verb'GxB_FIRSTI', \verb'GrB_SECONDI', and related operators), then
    \verb'C' is never iso.

    \item Define an {\em iso-monoid} as a built-in monoid with the property
    that reducing a set of $n>1$ identical values $x$ returns the same value
    $x$.  These are the \verb'MIN' \verb'MAX' \verb'LOR' \verb'LAND' \verb'BOR'
    \verb'BAND' and \verb'ANY' monoids.  All other monoids are not iso monoids:
    \verb'PLUS', \verb'TIMES', \verb'LXNOR', \verb'EQ', \verb'BXOR',
    \verb'BXNOR', and all user-defined monoids.   Currently, there is no
    mechanism for telling SuiteSparse:GraphBLAS that a user-defined monoid
    is an iso-monoid.

    \item If the multiplicative op is \verb'PAIR' (same as \verb'ONEB'),
    and the monoid is an
    iso-monoid, or the \verb'EQ' or \verb'TIMES' monoids, then \verb'C' is
    iso with a value of 1.

    \item If both \verb'B' and the monoid are iso, and the multiplicative op is
    \verb'SECOND' or \verb'ANY', then \verb'C' is iso with a value of $b$.

    \item If both \verb'A' and the monoid are iso, and the multiplicative op is
    \verb'FIRST' or \verb'ANY', then \verb'C' is iso with a value of $a$.

    \item If \verb'A', \verb'B', and the monoid are all iso, then \verb'C'
    is iso, with a value $c=f(a,b)$, where $f$ is any multiplicative op
    (including user-defined, which assumes that a user-defined $f$ has no 
    side effects).

    \item If \verb'A' and \verb'B' are both iso and full (all entries present,
    regardless of the format of the matrices), then \verb'C' is iso and full.
    Its iso value is computed in $O(\log(n))$ time, via a reduction of $n$
    copies of the value $t=f(a,b)$ to a scalar.  The storage required to
    represent \verb'C' is just $O(1)$, regardless of its dimension.
    Technically, the \verb'PLUS' monoid could be computed as $c=nt$ in $O(1)$
    time, but the log-time reduction works for any monoid, including
    user-defined ones.

    \item Otherwise, \verb'C' is not iso.
    \end{itemize}

%-------------------------------------------------------------------------------
\subsection{Iso matrices from eWiseMult and kronecker}
%-------------------------------------------------------------------------------
\label{iso_emult}

Consider \verb'GrB_eWiseMult'.  Let
\verb'C=A.*B', or \verb'C<M>=A.*B' with any mask and where \verb'C' is
initially empty, where \verb'.*' denotes a binary operator $f(x,y)$
applied with \verb'eWiseMult'.  These rules also apply to \verb'GrB_kronecker'.

    \begin{itemize}
    \item If the operator is positional (\verb'GxB_FIRSTI' and related) then
    \verb'C' is not iso.

    \item If the op is \verb'PAIR' (same as \verb'ONEB'),
        then \verb'C' is iso with $c=1$.

    \item If \verb'B' is iso and the op is \verb'SECOND' or \verb'ANY',
        then \verb'C' is iso with $c=b$.

    \item If \verb'A' is iso and the op is \verb'FIRST' or \verb'ANY',
        then \verb'C' is iso with $c=a$.

    \item If both \verb'A' and \verb'B' are iso,
        then \verb'C' is iso with $c=f(a,b)$.

    \item Otherwise, \verb'C' is not iso.
    \end{itemize}

%-------------------------------------------------------------------------------
\subsection{Iso matrices from eWiseAdd}
%-------------------------------------------------------------------------------
\label{iso_add}

Consider \verb'GrB_eWiseAdd', and also the accumulator phase of \verb'C<M>+=T'
when an accumulator operator is present.  Let \verb'C=A+B', or \verb'C<M>=A+B'
with any mask and where \verb'C' is initially empty.

    \begin{itemize}
    \item If both \verb'A' and \verb'B' are full (all entries present), then
    the rules for \verb'eWiseMult' in Section~\ref{iso_emult} are used
    instead.

    \item If the operator is positional (\verb'GxB_FIRSTI' and related) then
    \verb'C' is not iso.

    \item If $a$ and $b$ differ (when typecasted to the type of \verb'C'),
    then \verb'C' is not iso.

    \item If $c=f(a,b) = a = b$ holds, then \verb'C' is iso,
    where $f(a,b)$ is the operator.

    \item Otherwise, \verb'C' is not iso.
    \end{itemize}

%-------------------------------------------------------------------------------
\subsection{Iso matrices from eWiseUnion}
%-------------------------------------------------------------------------------
\label{iso_union}

\verb'GxB_eWiseUnion' is very similar to \verb'GrB_eWiseAdd', but the rules
for when the result is iso-valued are very different.

    \begin{itemize}
    \item If both \verb'A' and \verb'B' are full (all entries present), then
    the rules for \verb'eWiseMult' in Section~\ref{iso_emult} are used
    instead.

    \item If the operator is positional (\verb'GxB_FIRSTI' and related) then
    \verb'C' is not iso.

    \item If the op is \verb'PAIR' (same as \verb'ONEB'),
        then \verb'C' is iso with $c=1$.

    \item If \verb'B' is iso and the op is \verb'SECOND' or \verb'ANY',
        and the input scalar \verb'beta' matches $b$
        (the iso-value of \verb'B'),
        then \verb'C' is iso with $c=b$.

    \item If \verb'A' is iso and the op is \verb'FIRST' or \verb'ANY',
        and the input scalar \verb'alpha' matches $a$
        (the iso-value of \verb'A'),
        then \verb'C' is iso with $c=a$.

    \item If both \verb'A' and \verb'B' are iso,
        and $f(a,b) = f(\alpha,b) = f(a,\beta)$,
        then \verb'C' is iso with $c=f(a,b)$.

    \item Otherwise, \verb'C' is not iso.
    \end{itemize}

%-------------------------------------------------------------------------------
\subsection{Reducing iso matrices to a scalar or vector}
%-------------------------------------------------------------------------------
\label{iso_reduce}

If \verb'A' is iso with $e$ entries, reducing it to a scalar takes $O(\log(e))$
time, regardless of the monoid used to reduce the matrix to a scalar.  Reducing
\verb'A' to a vector \verb'c' is the same as the matrix-vector multiply
\verb"c=A*x" or \verb"c=A'*x", depending on the descriptor, where \verb'x'
is an iso full vector (refer to Section~\ref{iso_mxm}).

%-------------------------------------------------------------------------------
\subsection{Iso matrices from apply}
%-------------------------------------------------------------------------------
\label{iso_apply}

Let \verb'C=f(A)' denote the application of a unary operator \verb'f',
and let \verb'C=f(A,s)' and \verb'C=f(s,A)' denote the application of a binary
operator with \verb's' a scalar.

    \begin{itemize}
    \item If the operator is positional (\verb'GxB_POSITION*',
    \verb'GxB_FIRSTI', and related) then \verb'C' is not iso.

    \item If the operator is \verb'ONE' or \verb'PAIR' (same as \verb'ONEB'),
        then \verb'C' iso with $c=1$.

    \item If the operator is \verb'FIRST' or \verb'ANY' with \verb'C=f(s,A)',
        then \verb'C' iso with $c=s$.

    \item If the operator is \verb'SECOND' or \verb'ANY' with \verb'C=f(A,s)',
        then \verb'C' iso with $c=s$.

    \item If \verb'A' is iso then \verb'C' is iso, with the following value
        of $c$:

        \begin{itemize}
        \item If the op is \verb'IDENTITY', then $c=a$.
        \item If the op is unary with \verb'C=f(A)', then $c=f(a)$.
        \item If the op is binary with \verb'C=f(s,A)', then $c=f(s,a)$.
        \item If the op is binary with \verb'C=f(A,s)', then $c=f(a,s)$.
        \end{itemize}


    \item Otherwise, \verb'C' is not iso.
    \end{itemize}

%-------------------------------------------------------------------------------
\subsection{Iso matrices from select}
%-------------------------------------------------------------------------------
\label{iso_select}

Let \verb'C=select(A)' denote the application of a \verb'GrB_IndexUnaryOp' operator
in \verb'GrB_select'.

    \begin{itemize}
    \item If \verb'A' is iso, then \verb'C' is iso with $c=a$.
    \item If the operator is any \verb'GrB_VALUE*_BOOL' operator,
        with no typecasting, and the test is true only for a single boolean
        value, then \verb'C' is iso.
    \item If the operator is \verb'GrB_VALUEEQ_*', with no typecasting,
        then \verb'C' is iso, with $c=t$ where $t$ is the value of the scalar
        \verb'y'.
    \item If the operator is \verb'GrB_VALUELE_UINT*', with no typecasting,
        and the scalar \verb'y' is zero, then \verb'C' is iso with $c=0$.
    \item Otherwise, \verb'C' is not iso.
    \end{itemize}

%-------------------------------------------------------------------------------
\subsection{Iso matrices from assign and subassign}
%-------------------------------------------------------------------------------
\label{iso_assign}

These rules are somewhat complex.  Consider the assignment \verb'C<M>(I,J)=...'
with \verb'GrB_assign'.  Internally, this assignment is converted into
\verb'C(I,J)<M(I,J)>=...' and then \verb'GxB_subassign' is used.  Thus,
all of the rules below assume the form \verb'C(I,J)<M>=...' where \verb'M'
has the same size as the submatrix \verb'C(I,J)'.

\subsubsection{Assignment with no accumulator operator}

If no accumulator operator is present, the following rules are used.

\begin{itemize}
\item 
For matrix assignment, \verb'A' must be iso.  For scalar assignment, the single
scalar is implicitly expanded into an iso matrix \verb'A' of the right size.
If these rules do not hold, \verb'C' is not iso.

\item
If \verb'A' is not iso, or if \verb'C' is not iso on input, then \verb'C' is
not iso on output.

\item
If \verb'C' is iso or empty on input, and \verb'A' is iso (or scalar assignment
is begin performed) and the iso values $c$ and $a$ (or the scalar $s$) match,
then the following forms of assignment result in an iso matrix \verb'C'  on
output:

                \begin{itemize}
                \item \verb'C(I,J) = scalar'
                \item \verb'C(I,J)<M> = scalar'
                \item \verb'C(I,J)<!M> = scalar'
                \item \verb'C(I,J)<M,replace> = scalar'
                \item \verb'C(I,J)<!M,replace> = scalar'
                \item \verb'C(I,J) = A'
                \item \verb'C(I,J)<M> = A'
                \item \verb'C(I,J)<!M> = A'
                \item \verb'C(I,J)<M,replace> = A'
                \item \verb'C(I,J)<!M,replace> = A'
                \end{itemize}

\item
For these forms of assignment, \verb'C' is always iso on output, regardless
of its iso property on input:

                \begin{itemize}
                \item \verb'C = scalar'
                \item \verb'C<M,struct>=scalar'; C empty on input.
                \item \verb'C<C,struct>=scalar'
                \end{itemize}

\item
For these forms of assignment, \verb'C' is always iso on output if \verb'A'
is iso:

                \begin{itemize}
                \item \verb'C = A'
                \item \verb'C<M,str> = A'; C empty on input.
                \end{itemize}
\end{itemize}


\subsubsection{Assignment with an accumulator operator}

If an accumulator operator is present, the following rules are used.
Positional operators (\verb'GxB_FIRSTI' and related) cannot be used as
accumulator operators, so these rules do not consider that case.

\begin{itemize}
\item 
For matrix assignment, \verb'A' must be iso.  For scalar assignment, the single
scalar is implicitly expanded into an iso matrix \verb'A' of the right size.
If these rules do not hold, \verb'C' is not iso.

\item For these forms of assignment \verb'C' is iso if \verb'C' is 
empty on input, or if $c=c+a$ for the where $a$ is the iso value of \verb'A' or
the value of the scalar for scalar assignment.

                \begin{itemize}
                \item \verb'C(I,J) += scalar'
                \item \verb'C(I,J)<M> += scalar'
                \item \verb'C(I,J)<!M> += scalar'
                \item \verb'C(I,J)<M,replace> += scalar'
                \item \verb'C(I,J)<!M,replace> += scalar'
                \item \verb'C(I,J)<M,replace> += A'
                \item \verb'C(I,J)<!M,replace> += A'
                \item \verb'C(I,J) += A'
                \item \verb'C(I,J)<M> += A'
                \item \verb'C(I,J)<!M> += A '
                \item \verb'C += A'
                \end{itemize}
\end{itemize}

%-------------------------------------------------------------------------------
\subsection{Iso matrices from build methods}
%-------------------------------------------------------------------------------
\label{iso_build}

\verb'GxB_Matrix_build_Scalar' and \verb'GxB_Vector_build_Scalar'
always construct an iso matrix/vector.

\verb'GrB_Matrix_build' and \verb'GrB_Vector_build' can also construct iso
matrices and vectors.  A non-iso matrix/vector is constructed first, and then
the entries are checked to see if they are all equal.  The resulting iso-valued
matrix/vector will be efficient to use and will use less memory than a non-iso
matrix/vector.  However, constructing an iso matrix/vector with
\verb'GrB_Matrix_build' and \verb'GrB_Vector_build' will take more time
and memory than constructing the matrix/vector with
\verb'GxB_Matrix_build_Scalar' or \verb'GxB_Vector_build_Scalar'.

%-------------------------------------------------------------------------------
\subsection{Iso matrices from other methods}
%-------------------------------------------------------------------------------
\label{iso_other}

\begin{itemize}
\item
For \verb'GrB_Matrix_dup' and \verb'GrB_Vector_dup', the output matrix/vector
has the same iso property as the input matrix/vector.

\item
\verb'GrB_*_setElement_*' preserves the iso property of the matrix/vector it
modifies, if the input scalar is equal to the iso value of the matrix/vector.
If the matrix or vector has no entries, the first call to \verb'setElement'
makes it iso.  This allows a sequence of \verb'setElement' calls with the same
scalar value to create an entire iso matrix or vector, if starting from
an empty matrix or vector.

\item
\verb'GxB_Matrix_concat' constructs an iso matrix as its result if all input
tiles are either empty or iso.

\item
\verb'GxB_Matrix_split' constructs its output tiles as iso if its input
matrix is iso.

\item
\verb'GxB_Matrix_diag' and \verb'GrB_Matrix_diag' construct an iso matrix if
its input vector is iso.

\item
\verb'GxB_Vector_diag' constructs an iso vector if its input matrix is iso.

\item
\verb'GrB_*extract' constructs an iso matrix/vector if its input matrix/vector
is iso.

\item
\verb'GrB_transpose' constructs an iso matrix if its input is iso.

\item
The \verb'GxB_import/export/pack/unpack' methods preserve the iso property
of their matrices/vectors.
\end{itemize}

%-------------------------------------------------------------------------------
\subsection{Iso matrices not exploited}
%-------------------------------------------------------------------------------

There are many cases where an matrix may have the iso property but it is not
detected by SuiteSparse:GraphBLAS.  For example, if \verb'A' is non-iso,
\verb'C=A(I,J)' from \verb'GrB_extract' may be iso, if all entries in the
extracted submatrix have the same value.  Future versions of
SuiteSparse:GraphBLAS may extend the rules described in this section to detect
these cases.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Performance} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{perf}

Getting the best performance out of an algorithm that relies on GraphBLAS can
depend on many factors.  This section describes some of the possible
performance pitfalls you can hit when using SuiteSparse:GraphBLAS, and how to
avoid them (or at least know when you've encountered them).

%-------------------------------------------------------------------------------
\subsection{The burble is your friend}
%-------------------------------------------------------------------------------

Turn on the burble with \verb'GxB_set (GxB_BURBLE, true)'.  You will get a
single line of output from each (significant) call to GraphBLAS.
The burble output can help you detect when you are likely using sub-optimal
methods, as described in the next sections.

%-------------------------------------------------------------------------------
\subsection{Data types and typecasting}
%-------------------------------------------------------------------------------

Avoid mixing data types and relying on typecasting as much as possible.
SuiteSparse:GraphBLAS has a set of highly-tuned kernels for each data type,
and many operators and semirings, but there are too many combinations to
generate ahead of time.  If typecasting is required, or if
SuiteSparse:GraphBLAS does not have a kernel for the specific operator or
semiring, the word \verb'generic' will appear in the burble.  The generic
methods rely on function pointers for each operation on every scalar, so they
are slow.  A future JIT will avoid this problem.

The only time that typecasting is fast is when computing \verb'C=A' via
\verb'GrB_assign' or \verb'GrB_apply', where the data types of \verb'C' and
\verb'A' can differ.  In this case, one of $13^2 = 169$ kernels are called,
each of which performs the specific typecasting requested, without relying on
function pointers.

%-------------------------------------------------------------------------------
\subsection{Matrix data structures: sparse, hypersparse, bitmap, or full}
%-------------------------------------------------------------------------------

SuiteSparse:GraphBLAS tries to automatically determine the best data structure
for your matrices and vectors, selecting between sparse, hypersparse, bitmap,
and full formats.  By default, all 4 formats can be used.  A matrix typically
starts out hypersparse when it is created by \verb'GrB_Matrix_new', and then
changes during its lifetime, possibly taking on all four different formats
at different times.  This can be modified via \verb'GxB_set'.  For example,
this line of code:

    {\scriptsize
    \begin{verbatim}
    GxB_set (A, GxB_SPARSITY_CONTROL, GxB_SPARSE + GxB_BITMAP) ; \end{verbatim}}

\noindent
tells SuiteSparse that the matrix \verb'A' can be held in either sparse or
bitmap format (at its discretion), but not hypersparse or full.  The bitmap
format will be used if the matrix has enough entries, or sparse otherwise.
Sometimes this selection is best controlled by the user algorithm, so a single
format can be requested:

    {\scriptsize
    \begin{verbatim}
    GxB_set (A, GxB_SPARSITY_CONTROL, GxB_SPARSE) ; \end{verbatim}}

This ensures that SuiteSparse will primarily use the sparse format.  This is
still just a hint, however.  The data structure is opaque and SuiteSparse is
free to choose otherwise.  In particular, if you insist on using only the
\verb'GxB_FULL' format, then that format is used when all entries are present.
However, if the matrix is not actually full with all entries present, then the
bitmap format is used instead.  The full format does not preserve the sparsity
structure in this case.  Any GraphBLAS library must preserve the proper
structure, per the C Specification.  This is critical in a graph algorithm,
since an edge $(i,j)$ of weight zero, say, is not the same as no edge $(i,j)$
at all.

%-------------------------------------------------------------------------------
\subsection{Matrix formats: by row or by column, or using the transpose of
a matrix}
%-------------------------------------------------------------------------------

By default, SuiteSparse uses a simple rule:
all matrices are held by row, unless the consist of a single
column, in which case they are held by column.  All vectors are treated as if
they are $n$-by-1 matrices with a single column.  Changing formats from
row-oriented to column-oriented can have significant performance implications,
so SuiteSparse never tries to outguess the application.  It just uses this
simple rule.

However, there are cases where changing the format can greatly improve
performance.  There are two ways to handle this, which in the end are
equivalent in the SuiteSparse internals.  You can change the format (row to
column oriented, or visa versa), or work with the explicit transpose of a
matrix in the same storage orientation.

There are cases where SuiteSparse must explicitly transpose an input matrix, or
the output matrix, in order to perform a computation.  For example, if all
matrices are held in row-oriented fashion, SuiteSparse does not have a method
for computing \verb"C=A'*B", where \verb'A' is transposed.  Thus, SuiteSparse
either computes a temporary transpose of its input matrix \verb'AT=A' and then
\verb'C=AT*B', or it swaps the computations, performing \verb"C=(B'*A)'", which
requires an explicit transpose of \verb'BT=B', and a transpose of the final
result to obtain \verb'C'.

These temporary transposes are costly to compute, taking time and memory.  They
are not kept, but are discarded when the method returns to the user
application.  If you see the term \verb'transpose' in the burble output, and if
you need to perform this computation many times, try constructing your own
explicit transpose, say \verb"AT=A'", via \verb'GrB_transpose', or create a
copy of \verb'A' but held in another orientation via \verb'GxB_set'.  For
example, assuming the default matrix format is by-row, and that \verb'A' is
\verb'm'-by-\verb'n' of type \verb'GrB_FP32':

    {\scriptsize
    \begin{verbatim}
    // method 1: AT = A'
    GrB_Matrix_new (AT, GrB_FP32, n, m) ;
    GrB_transpose (AT, NULL, NULL, A, NULL) ;

    // method 2: A2 = A but held by column instead of by row
    // note: doing the set before the assign is faster than the reverse
    GrB_Matrix_new (A2, GrB_FP32, m, n) ;
    GxB_set (A2, GxB_FORMAT, GxB_BY_COL) ;
    GrB_assign (A2, NULL, NULL, A, GrB_ALL, m, GrB_ALL, n, NULL) ; \end{verbatim}}

Internally, the data structure for \verb'AT' and \verb'A2' are nearly identical
(that is, the tranpose of \verb'A' held in row format is the same as \verb'A'
held in column format).  Using either of them in subsequent calls to GraphBLAS
will allow SuiteSparse to avoid computing an explicit transpose.  The two
matrices \verb'AT' and \verb'A2' do differ in one very significant way:  their
dimensions are different, and they behave differement mathematically.
Computing \verb"C=A'*B" using these matrices would differ:

    {\scriptsize
    \begin{verbatim}
    // method 1: C=A'*B using AT
    GrB_mxm (C, NULL, NULL, semiring, AT, B, NULL) ;

    // method 2: C=A'*B using A2
    GrB_mxm (C, NULL, NULL, semiring, A2, B, GrB_DESC_T0) ; \end{verbatim}}

The first method computes \verb'C=AT*B'.  The second method computes
\verb"C=A2'*B", but the result of both computations is the same, and internally
the same kernels will be used.

%-------------------------------------------------------------------------------
\subsection{Push/pull optimization}
%-------------------------------------------------------------------------------

Closely related to the discussion above on when to use a matrix or its
transpose is the exploitation of ``push/pull'' direction optimization.  In
linear algebraic terms, this is simply deciding whether to multiply by the
matrix or its transpose.  Examples can be see in the BFS and
Betweeness-Centrality methods of LAGraph.  Here is the BFS kernel:

    {\scriptsize
    \begin{verbatim}
    int sparsity = do_push ? GxB_SPARSE : GxB_BITMAP ;
    GxB_set (q, GxB_SPARSITY_CONTROL, sparsity) ;
    if (do_push)
    {
        // q'{!pi} = q'*A
        GrB_vxm (q, pi, NULL, semiring, q, A, GrB_DESC_RSC) ;
    }
    else
    {
        // q{!pi} = AT*q
        GrB_mxv (q, pi, NULL, semiring, AT, q, GrB_DESC_RSC) ;
    }\end{verbatim}}

The call to \verb'GxB_set' is optional, since SuiteSparse will likely already
determine that a bitmap format will work best when the frontier \verb'q' has
many entries, which is also when the pull step is fastest.  The push step
relies on a sparse vector times sparse matrix method originally due to
Gustavson.  The output is computed as a set union of all rows \verb'A(i,:)'
where \verb'q(i)' is present on input.  This set union is very fast when
\verb'q' is very sparse.  The pull step relies on a sequence of dot product
computations, one per possible entry in the output \verb'q', and it uses the
matrix \verb"AT" which is a row-oriented copy of the explicit transpose of the
adjacency matrix \verb'A'.

Mathematically, the results of the two methods are identical, but internally,
the data format of the input matrices is very different (using \verb'A' held
by row, or \verb'AT' held by row which is the same as a copy of \verb'A' that
is held by column), and the algorithms used are very different.

%-------------------------------------------------------------------------------
\subsection{Computing with full matrices and vectors}
%-------------------------------------------------------------------------------

Sometimes the best approach to getting the highest performance is to use dense
vectors, and occassionaly dense matrices are tall-and-thin or short-and-fat.
Packages such as Julia, Octave, or MATLAB, when dealing with the conventional
plus-times semirings, assume that multiplying a sparse matrix \verb'A' times a
dense vector \verb'x', \verb'y=A*x', will result in a dense vector \verb'y'.
This is not always the case, however. GraphBLAS must always return a result
that respects the sparsity structure of the output matrix or vector.  If the
$i$th row of \verb'A' has no entries then \verb'y(i)' must not appear as an
entry in the vector \verb'y', so it cannot be held as a full vector.  As a
result, the following computation can be slower than it could be:

    {\scriptsize
    \begin{verbatim}
    GrB_mxv (y, NULL, NULL, semiring, A, x, NULL) ; \end{verbatim}}

SuiteSparse must do extra work to compute the sparsity of this vector \verb'y',
but if this is not needed, and \verb'y' can be padded with zeros (or 
the identity value of the monoid, to be precise), a faster method can be used,
by relying on the accumulator.  Instead of computing \verb'y=A*x', set all
entries of \verb'y' to zero first, and then compute \verb'y+=A*x' where the
accumulator operator and type matches the monoid of the semiring.  SuiteSparse
has special kernels for this case; you can see them in the burble as
\verb'F+=S*F' for example.

    {\scriptsize
    \begin{verbatim}
    // y = 0
    GrB_assign (y, NULL, NULL, 0, GrB_ALL, n, NULL) ;
    // y += A*x
    GrB_mxv (y, NULL, GrB_PLUS_FP32, GrB_PLUS_TIMES_SEMIRING_FP32, A, x, NULL) ; \end{verbatim}}

You can see this computation in the LAGraph PageRank method, where all
entries of \verb'r' are set to the \verb'teleport' scalar first.

    {\scriptsize
    \begin{verbatim}
    for (iters = 0 ; iters < itermax && rdiff > tol ; iters++)
    {
        // swap t and r ; now t is the old score
        GrB_Vector temp = t ; t = r ; r = temp ;
        // w = t ./ d
        GrB_eWiseMult (w, NULL, NULL, GrB_DIV_FP32, t, d, NULL) ;
        // r = teleport
        GrB_assign (r, NULL, NULL, teleport, GrB_ALL, n, NULL) ;
        // r += A'*w
        GrB_mxv (r, NULL, GrB_PLUS_FP32, LAGraph_plus_second_fp32, AT, w, NULL) ;
        // t -= r
        GrB_assign (t, NULL, GrB_MINUS_FP32, r, GrB_ALL, n, NULL) ;
        // t = abs (t)
        GrB_apply (t, NULL, NULL, GrB_ABS_FP32, t, NULL) ;
        // rdiff = sum (t)
        GrB_reduce (&rdiff, NULL, GrB_PLUS_MONOID_FP32, t, NULL) ;
    } \end{verbatim}}

SuiteSparse exploits the iso-valued property of the scalar-to-vector assignment
of \verb'y=0', or \verb'r=teleport', and performs these assignments in O(1)
time and space.  Because the \verb'r' vector start out as full on input to
\verb'GrB_mxv', and because there is an accumulatr with no mask, no entries in
the input/output vector \verb'r' will be deleted, even if \verb'A' has empty
rows.  The call to \verb'GrB_mxv' exploits this, and is able to use a fast
kernel for this computation.  SuiteSparse does not need to compute the sparsity
pattern of the vector \verb'r'.

%-------------------------------------------------------------------------------
\subsection{Iso-valued matrices and vectors}
%-------------------------------------------------------------------------------

Using iso-valued matrices and vectors is always faster than using matrices and
vectors whose entries can have different values.  Iso-valued matrices are very
important in graph algorithms.  For example, an unweighted graph is best
represented as an iso-valued sparse matrix, and unweighted graphs are very
common.  The burble output, or the \verb'GxB_print', \verb'GxB_Matrix_iso', or
\verb'GxB_Vector_iso' can all be used to report whether or not your matrix or
vector is iso-valued.

Sometimes a matrix or vector may have values that are all the same, but
SuiteSparse hasn't detected this.  If this occurs, you can force a matrix
or vector to be iso-valued by assigning a single scalar to all its entries.

    {\scriptsize
    \begin{verbatim}
    // C<s(C)> = 3.14159
    GrB_assign (C, C, NULL, 3.14159, GrB_ALL, m, GrB_ALL, n, GrB_DESC_S) ; \end{verbatim}}

The matrix \verb'C' is used as its own mask.  The descriptor is essential here,
telling the mask to be used in a structural sense, without regard to the values
of the entries in the mask.  This assignment sets all entries that already
exist in \verb'C' to be equal to a single value, 3.14159. The sparsity
structure of \verb'C' does not change.  Of course, any scalar can be used; the
value 1 is common for unweighted graphs.  SuiteSparse:GraphBLAS performs the
above assignment in O(1) time and space, independent of the dimension of
\verb'C' or the number of entries in contains.

%-------------------------------------------------------------------------------
\subsection{User-defined types and operators}
%-------------------------------------------------------------------------------

These are currently slow.  Once SuiteSparse:GraphBLAS employs a JIT
accelerator, these data types and operators will be just as fast as built-in
types and operators.  This work is in progress for the GPU, in CUDA, in
collaboration with Joe Eaton and Corey Nolet.

%-------------------------------------------------------------------------------
\subsection{About NUMA systems}
%-------------------------------------------------------------------------------

I have tested this package extensively on multicore single-socket systems, but
have not yet optimized it for multi-socket systems with a NUMA architecture.
That will be done in a future release.  If you publish benchmarks
with this package, please state the SuiteSparse:GraphBLAS version, and a caveat
if appropriate.  If you see significant performance issues when going from a
single-socket to multi-socket system, I would like to hear from you so I can
look into it.

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

Several examples of how to use GraphBLAS are listed below.  They all
appear in the \verb'Demo' folder of SuiteSparse:GraphBLAS.  Programs in
the \verb'Demo' folder are meant as simple examples; for the fastest methods,
see LAgraph (Section~\ref{lagraph}).

\begin{enumerate}
\item creating a random matrix
\item creating a finite-element matrix
\item reading a matrix from a file
\item complex numbers as a user-defined type
\item matrix import/export
\end{enumerate}

Additional examples appear in the newly created LAGraph project, currently in
progress.

%-------------------------------------------------------------------------------
\subsection{LAGraph}
%-------------------------------------------------------------------------------
\label{lagraph}

The LAGraph project is a community-wide effort to create graph algorithms based
on GraphBLAS (any implementation of the API, not just SuiteSparse: GraphBLAS).
Some of the algorithms and utilities in LAGraph are listed in the table below.
Many additional algorithms are planned.  Refer to
\url{https://github.com/GraphBLAS/LAGraph} for a current list of algorithms. All
functions in the \verb'Demo/' folder in SuiteSparse:GraphBLAS will eventually
be translated into algorithms or utilities for LAGraph, and then removed
from \verb'GraphBLAS/Demo'.

To use LAGraph with SuiteSparse:GraphBLAS, place the two folders \verb'LAGraph'
and \verb'GraphBLAS' in the same parent directory.  This allows the
\verb'cmake' script in LAGraph to find the copy of GraphBLAS.  Alternatively,
the GraphBLAS source could be placed anywhere, as long as
\verb'sudo make install' is performed.

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

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

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

In SuiteSparse:GraphBLAS, the performance of both methods is essentially
identical, and roughly as fast as \verb'sparse' in MATLAB.  Inside
SuiteSparse:GraphBLAS, \verb'GrB_assign' is doing the same thing. When
performing \verb'A(I,J)=A(I,J)+F', if it finds that it cannot quickly insert an
update into the \verb'A' matrix, it creates a list of pending tuples to be
assembled later on.   When the matrix is ready for use in a subsequent
GraphBLAS operation (one that normally cannot use a matrix with pending
computations), the tuples are assembled all at once via
\verb'GrB_Matrix_build'.

GraphBLAS operations on other matrices have no effect on when the pending
updates of a matrix are completed.  Thus, any GraphBLAS method or operation can
be used to construct the \verb'F' matrix in the example above, without
affecting when the pending updates to \verb'A' are completed.

The MATLAB \verb'wathen.m' script is part of Higham's \verb'gallery' of
matrices \cite{Higham}.  It creates a finite-element matrix with random
coefficients for a 2D mesh of size \verb'nx'-by-\verb'ny', a matrix formulation
by Wathen \cite{Wathen}.  The pattern of the matrix is fixed; just the values
are randomized.  The GraphBLAS equivalent can use either
\verb'GrB_Matrix_build', or \verb'GrB_assign'.  Both methods have good
performance.  The \verb'GrB_Matrix_build' version below is about 15\% to 20\%
faster than the MATLAB \verb'wathen.m' function, regardless of the problem
size.  It uses the identical algorithm as \verb'wathen.m'.

    {\footnotesize
    \begin{verbatim}
    int64_t ntriplets = nx*ny*64 ;
    I = malloc (ntriplets * sizeof (int64_t)) ;
    J = malloc (ntriplets * sizeof (int64_t)) ;
    X = malloc (ntriplets * sizeof (double )) ;
    if (I == NULL || J == NULL || X == NULL)
    {
        FREE_ALL ;
        return (GrB_OUT_OF_MEMORY) ;
    }
    ntriplets = 0 ;
    for (int j = 1 ; j <= ny ; j++)
    {
        for (int i = 1 ; i <= nx ; i++)
        {
            nn [0] = 3*j*nx + 2*i + 2*j + 1 ;
            nn [1] = nn [0] - 1 ;
            nn [2] = nn [1] - 1 ;
            nn [3] = (3*j-1)*nx + 2*j + i - 1 ;
            nn [4] = 3*(j-1)*nx + 2*i + 2*j - 3 ;
            nn [5] = nn [4] + 1 ;
            nn [6] = nn [5] + 1 ;
            nn [7] = nn [3] + 1 ;
            for (int krow = 0 ; krow < 8 ; krow++) nn [krow]-- ;
            for (int krow = 0 ; krow < 8 ; krow++)
            {
                for (int kcol = 0 ; kcol < 8 ; kcol++)
                {
                    I [ntriplets] = nn [krow] ;
                    J [ntriplets] = nn [kcol] ;
                    X [ntriplets] = em (krow,kcol) ;
                    ntriplets++ ;
                }
            }
        }
    }
    // A = sparse (I,J,X,n,n) ;
    GrB_Matrix_build (A, I, J, X, ntriplets, GrB_PLUS_FP64) ; \end{verbatim}}

The \verb'GrB_assign' version has the advantage of not requiring the
user application to construct the tuple list, and is almost as fast as using
\verb'GrB_Matrix_build'.  The code is more elegant than either the MATLAB
\verb'wathen.m' function or its GraphBLAS equivalent above.  Its performance is
comparable with the other two methods, but slightly slower, being about 5\%
slower than the MATLAB \verb'wathen', and 20\% slower than the GraphBLAS
method above.

    {\footnotesize
    \begin{verbatim}
    GrB_Matrix_new (&F, GrB_FP64, 8, 8) ;
    for (int j = 1 ; j <= ny ; j++)
    {
        for (int i = 1 ; i <= nx ; i++)
        {
            nn [0] = 3*j*nx + 2*i + 2*j + 1 ;
            nn [1] = nn [0] - 1 ;
            nn [2] = nn [1] - 1 ;
            nn [3] = (3*j-1)*nx + 2*j + i - 1 ;
            nn [4] = 3*(j-1)*nx + 2*i + 2*j - 3 ;
            nn [5] = nn [4] + 1 ;
            nn [6] = nn [5] + 1 ;
            nn [7] = nn [3] + 1 ;
            for (int krow = 0 ; krow < 8 ; krow++) nn [krow]-- ;
            for (int krow = 0 ; krow < 8 ; krow++)
            {
                for (int kcol = 0 ; kcol < 8 ; kcol++)
                {
                    // F (krow,kcol) = em (krow, kcol)
                    GrB_Matrix_setElement (F, em (krow,kcol), krow, kcol) ;
                }
            }
            // A (nn,nn) += F
            GrB_assign (A, NULL, GrB_PLUS_FP64, F, nn, 8, nn, 8, NULL) ;
        }
    } \end{verbatim}}

Since there is no \verb'Mask', and since \verb'GrB_REPLACE' is not used, the call
to \verb'GrB_assign' in the example above is identical to \verb'GxB_subassign'.
Either one can be used, and their performance would be identical.

Refer to the \verb'wathen.c' function in the \verb'Demo' folder, which
uses GraphBLAS to implement the two methods above, and two additional ones.

%-------------------------------------------------------------------------------
\subsection{Reading a matrix from a file}
%-------------------------------------------------------------------------------
\label{read}

See also \verb'LAGraph_mmread' and \verb'LAGraph_mmwrite', which
can read and write any matrix in Matrix Market format, and
\verb'LAGraph_binread' and \verb'LAGraph_binwrite', which read/write a matrix
from a binary file.  The binary file I/O functions are much faster than
the \verb'read_matrix' function described here, and also much faster than
\verb'LAGraph_mmread' and \verb'LAGraph_mmwrite'.

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.
Section~\ref{random} has already compared
\verb'build' versus \verb'setElement'.

The function can return the matrix as-is, which may be rectangular or
unsymmetric.  If an input parameter is set to make the matrix symmetric,
\verb'read_matrix' computes \verb"A=(A+A')/2" if \verb'A' is square (turning
all directed edges into undirected ones).  If \verb'A' is rectangular, it
creates a bipartite graph, which is the same as the augmented matrix,
\verb"A = [0 A ; A' 0]".
If \verb'C' is an \verb'n'-by-\verb'n' matrix, then \verb"C=(C+C')/2" can be
computed as follows in GraphBLAS, (the \verb'scale2' function divides an entry
by 2):

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    GrB_Descriptor_new (&dt2) ;
    GrB_Descriptor_set (dt2, GrB_INP1, GrB_TRAN) ;
    GrB_Matrix_new (&A, GrB_FP64, n, n) ;
    GrB_eWiseAdd (A, NULL, NULL, GrB_PLUS_FP64, C, C, dt2) ;    // A=C+C'
    GrB_free (&C) ;
    GrB_Matrix_new (&C, GrB_FP64, n, n) ;
    GrB_UnaryOp_new (&scale2_op, scale2, GrB_FP64, GrB_FP64) ;
    GrB_apply (C, NULL, NULL, scale2_op, A, NULL) ;             // C=A/2
    GrB_free (&A) ;
    GrB_free (&scale2_op) ; \end{verbatim}}

This is of course not nearly as elegant as \verb"A=(A+A')/2" in MATLAB, but
with minor changes it can work on any type and use any built-in operators
instead of \verb'PLUS', or it can use any user-defined operators and types.
The above code in SuiteSparse:GraphBLAS takes 0.60 seconds for the
\verb'Freescale2' matrix, slightly slower than MATLAB (0.55 seconds).

Constructing the augmented system is more complicated using the GraphBLAS C API
Specification since it does not yet have a simple way of specifying a range of
row and column indices, as in \verb'A(10:20,30:50)' in MATLAB (\verb'GxB_RANGE'
is a SuiteSparse:GraphBLAS extension that is not in the Specification).  Using
the C API in the Specification, the application must instead build a list of
indices first, \verb'I=[10, 11' \verb'...' \verb'20]'.

Thus, to compute the MATLAB equivalent of \verb"A = [0 A ; A' 0]", index lists
\verb'I' and \verb'J' must first be constructed:

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    int64_t n = nrows + ncols ;
    I = malloc (nrows * sizeof (int64_t)) ;
    J = malloc (ncols * sizeof (int64_t)) ;
    // I = 0:nrows-1
    // J = nrows:n-1
    if (I == NULL || J == NULL)
    {
        if (I != NULL) free (I) ;
        if (J != NULL) free (J) ;
        return (GrB_OUT_OF_MEMORY) ;
    }
    for (int64_t k = 0 ; k < nrows ; k++) I [k] = k ;
    for (int64_t k = 0 ; k < ncols ; k++) J [k] = k + nrows ; \end{verbatim}}

Once the index lists are generated, however, the resulting GraphBLAS operations
are fairly straightforward, computing \verb"A=[0 C ; C' 0]".

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    GrB_Descriptor_new (&dt1) ;
    GrB_Descriptor_set (dt1, GrB_INP0, GrB_TRAN) ;
    GrB_Matrix_new (&A, GrB_FP64, n, n) ;
    // A (nrows:n-1, 0:nrows-1) = C'
    GrB_assign (A, NULL, NULL, C, J, ncols, I, nrows, dt1) ;
    // A (0:nrows-1, nrows:n-1) = C
    GrB_assign (A, NULL, NULL, C, I, nrows, J, ncols, NULL) ; \end{verbatim}}

This takes 1.38 seconds for the \verb'Freescale2' matrix, almost as fast as \newline
\verb"A=[sparse(m,m) C ; C' sparse(n,n)]" in MATLAB (1.25 seconds).
The \verb'GxB_Matrix_concat' function would be faster still (this example
was written prior to \verb'GxB_Matrix_concat' was added to SuiteSparse:GraphBLAS).

Both calls to \verb'GrB_assign' use no accumulator, so the second one
causes the partial matrix \verb"A=[0 0 ; C' 0]" to be built first, followed by
the final build of \verb"A=[0 C ; C' 0]".  A better method, but not an obvious
one, is to use the \verb'GrB_FIRST_FP64' accumulator for both assignments.  An
accumulator enables SuiteSparse:GraphBLAS to determine that that entries
created by the first assignment cannot be deleted by the second, and thus it
need not force completion of the pending updates prior to the second
assignment.

SuiteSparse:GraphBLAS also adds a \verb'GxB_RANGE' mechanism that mimics
the MATLAB colon notation.  This speeds up the method and simplifies the
code the user needs to write to compute \verb"A=[0 C ; C' 0]":

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    int64_t n = nrows + ncols ;
    GrB_Matrix_new (&A, xtype, n, n) ;
    GrB_Index I_range [3], J_range [3] ;
    I_range [GxB_BEGIN] = 0 ;
    I_range [GxB_END  ] = nrows-1 ;
    J_range [GxB_BEGIN] = nrows ;
    J_range [GxB_END  ] = ncols+nrows-1 ;
    // A (nrows:n-1, 0:nrows-1) += C'
    GrB_assign (A, NULL, GrB_FIRST_FP64, // or NULL,
        C, J_range, GxB_RANGE, I_range, GxB_RANGE, dt1) ;
    // A (0:nrows-1, nrows:n-1) += C
    GrB_assign (A, NULL, GrB_FIRST_FP64, // or NULL,
        C, I_range, GxB_RANGE, J_range, GxB_RANGE, NULL) ; \end{verbatim}}

Any operator will suffice because it is not actually applied.  An operator is
only applied to the set intersection, and the two assignments do not overlap.
If an \verb'accum' operator is used, only the final matrix is built, and the
time in GraphBLAS drops slightly to 1.25 seconds.  This is a very small
improvement because in this particular case, SuiteSparse:GraphBLAS is able to
detect that no sorting is required for the first build, and the second one is a
simple concatenation.  In general, however, allowing GraphBLAS to postpone
pending updates can lead to significant reductions in run time.

%-------------------------------------------------------------------------------
\subsection{User-defined types and operators}
%-------------------------------------------------------------------------------
\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:}
Prior to v3.3, GraphBLAS did not have a native complex type.  It now appears as
the \verb'GxB_FC64' predefined type, but a complex type can also 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.
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/Octave & 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.
NOTE: the \verb'Complex' type is not supported in this Demo in Microsoft
Visual Studio.

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

%-------------------------------------------------------------------------------
\subsection{User applications using OpenMP or other threading models}
%-------------------------------------------------------------------------------
\label{threads}

An example demo program (\verb'openmp_demo') is included that illustrates how a
multi-threaded user application can use GraphBLAS.

The results from the \verb'openmp_demo' program may appear out of order.  This
is by design, simply to show that the user application is running in parallel.
The output of each thread should be the same.  In particular, each thread
generates an intentional error, and later on prints it with \verb'GrB_error'.
It will print its own error, not an error from another thread.  When all the
threads finish, the leader thread prints out each matrix generated by each
thread.

GraphBLAS can also be combined with user applications that rely on MPI, the
Intel TBB threading library, POSIX pthreads, Microsoft Windows threads, or any
other threading library.  If GraphBLAS itself is compiled with OpenMP,
it will be thread safe when combined with other libraries.
See Section~\ref{omp_parallelism} for thread-safety issues that can occur
if GraphBLAS is compiled without OpenMP.

\newpage
%-------------------------------------------------------------------------------
\section{Compiling and Installing SuiteSparse:GraphBLAS}
%-------------------------------------------------------------------------------
\label{sec:install}

%----------------------------------------
\subsection{On Linux and Mac}
%----------------------------------------

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 to use
all features of GraphBLAS. 

{\bf Any version of the Intel \verb'icx' compiler is highly recommended.} In
most cases, the Intel \verb'icx' and the Intel OpenMP library (\verb'libiomp')
result in the best performance.  The \verb'gcc' and the GNU OpenMP library
(\verb'libgomp') generally gives good performance: typically on par with icx
but in a few special cases significantly slower.  The Intel \verb'icc' compiler
is not recommended; it results in poor performance for
\verb'#pragma omp atomic'.

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, but best
performance is obtained in 9.3 or later.  Version 3.13 or later of \verb'cmake'
is required; version 3.17 is preferred.

If you are using a pre-C11 ANSI C compiler, such as Microsoft Visual Studio,
then the \verb'_Generic' keyword is not available.  SuiteSparse:GraphBLAS
will still compile, but you will not have access to polymorphic functions
such as \verb'GrB_assign'.  You will need to use the non-polymorphic functions
instead.

To compile SuiteSparse:GraphBLAS, simply type \verb'make' in the main GraphBLAS
folder, which compiles the library with your default system compiler.  This
compile GraphBLAS using 8 threads, which will take a long time.  To compile with
more threads (40, for this example), use:

    {\small
    \begin{verbatim}
    make JOBS=40 \end{verbatim} }

To use a non-default compiler with 4 threads:

    {\small
    \begin{verbatim}
    make CC=icx CXX=icpx JOBS=4 \end{verbatim} }

GraphBLAS v6.1.3 and later use the \verb'cpu_features' package by Google to
determine if the target architecture supports AVX2 and/or AVX512F (on Intel
x86\_64 architectures only).  In case you have build issues with this package,
you can compile without it (and then AVX2 and AVX512F acceleration will not
be used):

    {\small
    \begin{verbatim}
    make CMAKE_OPTIONS='-DGBNCPUFEAT=1'  \end{verbatim} }

Without \verb'cpu_features', it is still possible to enable AVX2 and AVX512F.
Rather than relying on run-time tests, you can use these flags to enable
both AVX2 and AVX512F, without relying on \verb'cpu_features':

    {\small
    \begin{verbatim}
    make CMAKE_OPTIONS='-DGBNCPUFEAT=1 -DGBAVX2=1 -DGBAVX512F=1' \end{verbatim} }

To use multiple options, separate them by a space.  For example, to build
just the library but not \verb'cpu_features', and to enable
AVX2 but not AVX512F, and use 40 threads to compile:

    {\small
    \begin{verbatim}
    make CMAKE_OPTIONS='-DGBNCPUFEAT=1 -DGBAVX2=1' JOBS=40 \end{verbatim} }

After compiling the library, you can compile the demos with
\verb'make all' and then \verb'make demos' while in the top-level
GraphBLAS folder.

If \verb'cmake' or \verb'make' fail, it might be that your default compiler
does not support ANSI C11.  Try another compiler.  For example, try one of
these options.  Go into the \verb'build' directory and type one of these:

    {\small
    \begin{verbatim}
    CC=gcc cmake ..
    CC=gcc-11 cmake ..
    CC=xlc cmake ..
    CC=icx cmake ..  \end{verbatim} }

You can also do the following in the top-level GraphBLAS folder instead:

    {\small
    \begin{verbatim}
    CC=gcc make
    CC=gcc-11 make
    CC=xlc make
    CC=icx make \end{verbatim} }

For faster compilation, you can specify a parallel make.  For example,
to use 32 parallel jobs and the \verb'gcc' compiler, do the following:

    {\small
    \begin{verbatim}
    JOBS=32 CC=gcc make \end{verbatim} }

If you do not have \verb'cmake', refer to Section~\ref{altmake}.

%----------------------------------------
\subsection{More details on the Mac}
%----------------------------------------

SuiteSparse:GraphBLAS requires OpenMP for its internal parallelism, but
OpenMP is not on the Mac by default.

If you have the Intel compiler and OpenMP library, then use the following
in the top-level \verb'GraphBLAS' folder.  OpenMP will be found automatically:

    {\small
    \begin{verbatim}
    make CC=icc CXX=icpc \end{verbatim} }

The following instructions work on MacOS Big Sur (v11.3)
and MacOS Monterey (12.1), using
cmake 3.13 or later:

First install Xcode (see \url{https://developer.apple.com/xcode}),
and then install the command line tools for Xcode:

    {\small
    \begin{verbatim}
    cd /Applications/Utilities
    xcode-select —install \end{verbatim} }

Next, install brew, at \url{https://brew.sh}.

If not used for the MATLAB mexFunction interface, a recent update of the Apple
Clang compiler now works with \verb'libomp' and the
\verb'GraphBLAS/CMakeLists.txt'.  To use the MATLAB mexFunction, however, you
must use \verb'gcc' (\verb'gcc-11' is recommended).  Using Clang will result in
a segfault when you attempt to use the \verb'@GrB' interface in MATLAB.

With MacOS Big Sur install \verb'gcc-11', \verb'cmake', and OpenMP, and then
compile GraphBLAS.  cmake 3.13 or later is required.  For the MATLAB
mexFunctions, you must use \verb'gcc-11'; the \verb'libomp' from \verb'brew'
will allow you to compile the mexFunctions but they will not work properly.

    {\small
    \begin{verbatim}
    brew install cmake
    brew install libomp
    brew install gcc
    cd GraphBLAS/GraphBLAS
    make CC=gcc-11 CXX=g++-11 JOBS=8 \end{verbatim} }

The above instructions assume MATLAB, using
\verb'libgraphblas_matlab.dylib', since MATLAB includes its
own copy of SuiteSparse:GraphBLAS (\verb'libmwgraphblas.dylib') but at version
v3.3.3, not the latest version.

Next, compile the MATLAB mexFunctions.  I had to edit this file first:

{\small
\begin{verbatim}
/Users/davis/Library/Application Support/MathWorks/MATLAB/R2021a/mex_C_maci64.xml \end{verbatim} }

where you would replace \verb'davis' with your MacOS user name.
Change lines 4 and 18, where both cases of \verb'MACOSX_DEPLOYMENT_TARGET=10.14'
must become \verb"MACOSX_DEPLOYMENT_TARGET=11.3".  Otherwise, MATLAB
complains that the \verb'libgraphblas_matlab.dylib' was built for 11.3 but
linked for 10.14.

Next, type the following in the MATLAB Command Window:

    {\small
    \begin{verbatim}
    cd GraphBLAS/GraphBLAS/@GrB/private
    gbmake \end{verbatim} }

Then add the paths to your \verb'startup.m' file (usually in
\verb'~/Documents/MATLAB/startup.m').  For example, my path is:

    {\small
    \begin{verbatim}
    addpath ('/Users/davis/GraphBLAS/GraphBLAS') ;
    addpath ('/Users/davis/GraphBLAS/GraphBLAS/build') ; \end{verbatim} }

Finally, you can run the tests to see if your installation works:

    {\small
    \begin{verbatim}
    cd ../../test
    gbtest \end{verbatim} }

%----------------------------------------
\subsection{On the ARM64 architecture}
%----------------------------------------

You may encounter a compiler error on the ARM64 architecture when using the
\verb'gcc' compiler, versions 6.x and earlier.  This error was encountered on
ARM64 Linux with gcc 6.x:

\begin{verbatim}
`In function GrB_Matrix_apply_BinaryOp1st_Scalar.part.1':
GrB_Matrix_apply.c:(.text+0x210): relocation truncated to
fit: R_AARCH64_CALL26 against `.text.unlikely'
\end{verbatim}

For the ARM64, this error is silenced with gcc v7.x and later, at least on
Linux.

%----------------------------------------
\subsection{On Microsoft Windows}
\label{sec:windows}
%----------------------------------------

SuiteSparse:GraphBLAS is now ported to Microsoft Visual Studio.  However, that
compiler is not ANSI C11 compliant. As a result, GraphBLAS on Windows will have
a few minor limitations.

\begin{itemize}
\item The MS Visual Studio compiler does not support the \verb'_Generic'
keyword, required for the polymorphic GraphBLAS functions.  So for example, you
will need to use \verb'GrB_Matrix_free' instead of just \verb'GrB_free'.

\item Variable-length arrays are not supported, so user-defined
types are limited to 128 bytes in size.  This can be changed by editing
\verb'GB_VLA_MAXSIZE' in \verb'Source/GB_compiler.h', and recompiling
SuiteSparse:GraphBLAS.

\item AVX acceleration is not enabled.
\end{itemize}

If you use a recent \verb'gcc' or \verb'icx' compiler on Windows other than the
Microsoft Compiler (\verb'cl'), these limitations can be avoided.

The following instructions apply to Windows 10, CMake 3.16, and
Visual Studio 2019, but may work for earlier versions.

\begin{enumerate}

\item Install CMake 3.16 or later, if not already installed.
    See \url{https://cmake.org/} for details.

\item Install Microsoft Visual Studio, if not already installed.
    See \url{https://visualstudio.microsoft.com/} for details.
    Version 2019 is preferred, but earlier versions may also work.

\item Open a terminal window and type this in the
    \verb'SuiteSparse/GraphBLAS/build' folder:

    \vspace{-0.1in}
    {\small
    \begin{verbatim}
    cmake ..  \end{verbatim} }
    \vspace{-0.1in}

\item The \verb'cmake' command generates many files in
    \verb'SuiteSparse/GraphBLAS/build', and the file \verb'graphblas.sln' in
    particular.  Open the generated \verb'graphblas.sln' file in Visual Studio.

\item Optionally: right-click \verb'graphblas' in the left panel (Solution
    Explorer) and select properties; then navigate to \verb'Configuration'
    \verb'Properties', \verb'C/C++', \verb'General' and change the parameter
    \verb'Multiprocessor Compilation' to \verb'Yes (/MP)'.  Click \verb'OK'.
    This will significantly speed up the compilation of GraphBLAS.

\item Select the \verb'Build' menu item at the top of the window and
    select \verb'Build Solution'.  This should create a folder called
    \verb'Release' and place the compiled \verb'graphblas.dll',
    \verb'graphblas.lib', and \verb'graphblas.exp' files there.  Please be
    patient; some files may take a while to compile and sometimes may appear to
    be stalled.  Just wait.

    % Alternatively, type this command in the terminal window:
    % {\small
    % \begin{verbatim}
    % devenv graphblas.sln /build "release|x64" /project graphblas \end{verbatim}}

\item Add the \verb'GraphBLAS/build/Release' folder to the Windows System path:

    \begin{itemize}
    \item Open the \verb'Start Menu' and type \verb'Control Panel'.
    \item Select the \verb'Control Panel' app.
    \item When the app opens, select \verb'System and Security'.
    \item Under \verb'System and Security', select \verb'System'.
    \item From the top left side of the \verb'System' window, select
        \verb'Advanced System Settings'.  You may have to authenticate
        at this step.
    \item The \verb'Systems Properties' window should appear with the
        \verb'Advanced' tab selected;
        select \verb'Environment Variables'.
    \item The \verb'Environment Variables' window displays 2 sections, one for
        \verb'User' variables and the other for \verb'System' variables.  Under
        the \verb'Systems' variable section, scroll to and select \verb'Path',
        then select \verb'Edit'.   A editor window appears allowing to add,
        modify, delete or re-order the parts of the \verb'Path'.
    \item Add the full path of the \verb'GraphBLAS\build\Release' folder
        (typically starting with \verb'C:\Users\you\'..., where \verb'you' is
        your Windows username) to the \verb'Path'.
    \item If the above steps do not work, you can instead copy the
        \verb'graphblas.*' files from \verb'GraphBLAS\build\Release' into any
        existing folder listed in your \verb'Path'. 
    \end{itemize}

\item The \verb'GraphBLAS/Include/GraphBLAS.h' file must be included in user
    applications via \verb'#include "GraphBLAS.h"'.  This is already done for
    you in the MATLAB/Octave interface discussed in the next section.

\end{enumerate}

%----------------------------------------
\subsection{Compiling the MATLAB/Octave interface (for Octave)}
%----------------------------------------
\label{gbmake}

I'm working closely with John Eaton (the primary developer of Octave) to
enable SuiteSparse:GraphBLAS to work with Octave, and thus Octave 7 is
required.  The latest version of Octave is 6.4.0, so you need to download and
install the development version of Octave 7 to use SuiteSparse:GraphBLAS within
Octave.

First, compile the SuiteSparse:GraphBLAS dynamic library
(\verb'libgraphblas.so' for Linux, \verb'libgraphblas.dylib' for Mac,
or \verb'graphblas.dll' for Windows), as described in the prior two
subsections.

On the Mac, SuiteSparse:GraphBLAS v6.1.4 and Octave 7 will work 
Apple Silicon (thanks to G{\'{a}}bor Sz{\'{a}}rnyas).  Here are his instructions
(replicated from
\url{https://github.com/DrTimothyAldenDavis/GraphBLAS/issues/90}); do
these in your Mac Terminal:

\begin{itemize}
\item Building Octave.  Grab the brew formula:

    {\scriptsize
    \begin{verbatim}
    wget https://raw.githubusercontent.com/Homebrew/homebrew-core/master/Formula/octave.rb
    \end{verbatim} }

\item Edit \verb'octave.rb'.

   Add \verb`"disable-docs"` to \verb`args` (or ensure that you have a working
   texinfo installation).
   Edit Mercurial (\verb`hg`) repository: switch from the \verb`default` branch
   (containing code for Octave v8.0) to \verb`stable` (v7.0).  Then do:

    {\small
    \begin{verbatim}
    brew install --head ./octave.rb
    \end{verbatim} }

\item Building the tests (\verb'gbmake').
    Grab the OpenMP binaries as described at
    \url{https://mac.r-project.org/openmp/}

    {\scriptsize
    \begin{verbatim}
    curl -O https://mac.r-project.org/openmp/openmp-13.0.0-darwin21-Release.tar.gz
    sudo tar fvxz openmp-13.0.0-darwin21-Release.tar.gz -C /
    \end{verbatim} }

\item Do the following to edit \verb'gbmake.m':

    {\scriptsize
    \begin{verbatim}
    sed -i.bkp 's/-fopenmp/-Xclang -fopenmp/g' @GrB/private/gbmake.m
    \end{verbatim} }

\end{itemize}

Once Octave 7 and SuiteSparse:GraphBLAS are compiled and installed,
and \verb'gbmake.m' is modified if needed for Octave 7 on the Mac,
(or if using MATLAB) continue with the following instructions:

\begin{enumerate}
\item In the MATLAB/Octave command window:

    {\small
    \begin{verbatim}
    cd GraphBLAS/GraphBLAS/@GrB/private
    gbmake \end{verbatim} }

\item Follow the remaining instructions in the
    \verb'GraphBLAS/GraphBLAS/README.md' file, to revise your
    MATLAB/Octave path and \verb'startup.m' file.

\item As a quick test, try the command \verb'GrB(1)', which
    creates and displays a 1-by-1 GraphBLAS matrix.  For a longer test, do the
    following:

    {\small
    \begin{verbatim}
    cd GraphBLAS/GraphBLAS/test
    gbtest \end{verbatim} }

\item In Windows, if the tests fail with an error stating that the
    mex file is invalid because the module could not be found, it means
    that MATLAB could not find the compiled \verb'graphblas.lib', \verb'*.dll'
    or \verb'*.exp' files in the \verb'build/Release' folder.  This can happen
    if your Windows System path is not set properly, or if Windows is not
    recognizing the \verb'GraphBLAS/build/Release' folder (see
    Section~\ref{sec:windows})  Or, you might not have permission to change your
    Windows System path.  In this case, do the following in the MATLAB Command
    \vspace{-0.1in}
    Window:

    \vspace{-0.1in}
    {\small
    \begin{verbatim}
    cd GraphBLAS/build/Release
    GrB(1) \end{verbatim} }

    \vspace{-0.1in}
    After this step, the GraphBLAS library will be loaded into MATLAB.  You may
    need to add the above lines in your \verb'Documents/MATLAB/startup.m' file,
    so that they are done each time MATLAB starts.  You will also need to do
    this after \verb'clear all' or \verb'clear mex', since those MATLAB
    commands remove all loaded libraries from MATLAB.

    You might also get an error ``the specified procedure cannot be found.''
    This can occur if you have upgraded your GraphBLAS library from a prior
    version, and some of the compiled files \verb'@GrB/private/*.mex*'
    are stale.  Try the command \verb'gbmake all' in the MATLAB Command
    Window, which forces all of the MATLAB interface to be recompiled.
    Or, try deleting all \verb'@GrB/private/*.mex*' files and running
    \verb'gbmake' again.

\item On Windows, the \verb'casin', \verb'casinf', \verb'casinh', and
    \verb'casinhf' functions provided by Microsoft do not return the correct
    imaginary part.  As a result, \verb'GxB_ASIN_FC32', \verb'GxB_ASIN_FC64'
    \verb'GxB_ASINH_FC32', and \verb'GxB_ASINH_FC64' do not work properly on
    Windows.  This affects the \verb'GrB/asin', \verb'GrB/acsc',
    \verb'GrB/asinh', and \verb'GrB/acsch', functions in the MATLAB interface.
    See the MATLAB tests bypassed in \verb'gbtest76.m' for details, in the
    \newline
    \verb'GraphBLAS/GraphBLAS/test' folder.
    %% FUTURE: fix asin and acsc on Windows for the complex case.

\end{enumerate}

%----------------------------------------
\subsection{Compiling the MATLAB/Octave interface (for MATLAB)}
\label{R2021a}
%----------------------------------------

MATLAB R2021a includes its own copy of SuiteSparse:GraphBLAS v3.3.3, as the
file \verb'libmwgraphblas.so', which is used for the built-in \verb'C=A*B' when
both \verb'A' and \verb'B' are sparse (see the Release Notes of MATLAB R2021a,
which discusses the performance gained in MATLAB by using GraphBLAS).

That's great news for the impact of GraphBLAS on MATLAB itself, and the domain
of high performance computing in general, but it causes a linking problem when
using this MATLAB interface for GraphBLAS.  The two use different versions of
the same library, and a segfault arises if the MATLAB interface for v4.x (or
later) tries to link with the older GraphBLAS v3.3.3 library.  Likewise, the
built-in \verb'C=A*B' causes a segfault if it tries to use the newer GraphBLAS
v4.x (or later) libraries.

To resolve this issue, a second GraphBLAS library must be compiled,
\verb'libgraphblas_matlab', where the internal symbols are all renamed so they
do not conflict with the \verb'libmwgraphblas' library.  Then both libraries
can co-exist in the same instance of MATLAB.

To do this, go to the \verb'GraphBLAS/GraphBLAS' folder, containing the
MATLAB interface.  That folder contains a \verb'CMakeLists.txt' file to
compile the \verb'libgraphblas_matlab' library.  See the instructions
for how to compile the C library \verb'libgraphblas', and repeat them but
using the folder \newline
\verb'SuiteSparse/GraphBLAS/GraphBLAS/build' instead of \newline
\verb'SuiteSparse/GraphBLAS/build'.

This will compile the renamed SuiteSparse:GraphBLAS dynamic library
(\verb'libgraphblas_matlab.so' for Linux, \verb'libgraphblas_matlab.dylib'
for Mac, or \verb'graphblas_matlab.dll' for Windows).  These can be
placed in the same system-wide location as the standard \verb'libgraphblas'
libraries, such as \verb'/usr/local/lib' for Linux.  The two pairs of
libraries share the identical \verb'GraphBLAS.h' include file.

If you do not have system privileges to install the GraphBLAS compiled
libraries via \verb'sudo make install', then augment your
\verb'LD_LIBRARY_PATH' (Linux) or \verb'DYLD_LIBRARY_PATH' (MacOS) to point to
your personal copy \verb'SuiteSparse/GraphBLAS/GraphBLAS/build' folder.  See
\url{https://www.mathworks.com/help/matlab/matlab_external/building-on-unix-operating-systems.html}
for details. 

Next, compile the MATLAB interface as described in Section~\ref{gbmake}.  For
any instructions in that Section that refer to the \verb'GraphBLAS/build'
folder (Linux and Mac) or \verb'GraphBLAS/build/Release' (Windows), use \newline
\verb'GraphBLAS/GraphBLAS/build' (Linux and Mac) or \newline
\verb'GraphBLAS/GraphBLAS/build/Release' (Windows) instead.

The resulting functions for your \verb'@GrB' object will now work just fine;
no other changes are needed.

%----------------------------------------
\subsection{Setting the C flags and using CMake}
%----------------------------------------

Next, do \verb'make' in the \verb'build' directory.  If this still fails, see
the \verb'CMakeLists.txt' file.  You can edit that file to pass
compiler-specific options to your compiler.  Locate this section in the
\verb'CMakeLists.txt' file.  Use the \verb'set' command in \verb'cmake', as in
the example below, to set the compiler flags you need.

    {\small
    \begin{verbatim}
    # check which compiler is being used.  If you need to make
    # compiler-specific modifications, here is the place to do it.
    if ("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU")
        # cmake 2.8 workaround: gcc needs to be told to do ANSI C11.
        # cmake 3.0 doesn't have this problem.
        set ( CMAKE_C_FLAGS  "${CMAKE_C_FLAGS} -std=c11 -lm " )
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "Intel")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "Clang")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "MSVC")
        ...
    endif ( )
    \end{verbatim} }

To compile SuiteSparse:GraphBLAS without running the demos, use \newline
\verb'make library' in the top-level directory, or \verb'make' in the
\verb'build' directory.

Several compile-time options can be selected by editing the \verb'Source/GB.h'
file, but these are meant only for code development of SuiteSparse:GraphBLAS
itself, not for end-users of SuiteSparse:GraphBLAS.

%----------------------------------------
\subsection{Using a plain makefile}
\label{altmake}
%----------------------------------------

The \verb'GraphBLAS/alternative' directory contains a simple \verb'Makefile'
that can be used to compile SuiteSparse:GraphBLAS.  This is a useful option
if you do not have the required version of \verb'cmake'.  This \verb'Makefile'
can even compile the entire library with a C++ compiler, which cannot be
done with \verb'CMake'.

This alternative \verb'Makefile' does not build the
\verb'libgraphblas_matlab.so' library required for MATLAB (see
Section~\ref{R2021a}).  This can be done by revising the \verb'Makefile',
however:  add the \verb'-DGBRENAME=1' flag, and changing the library name
from \verb'libgraphblas' to \verb'libgraphbas_matlab'.

%----------------------------------------
\subsection{Running the Demos}
%----------------------------------------

After \verb'make' in the top-level directory to compile the library, type
\verb'make demo' to run the demos (also in the top-level directory).
You can also run the demos after compiling with \verb'make all':

    {\small
    \begin{verbatim}
    make all
    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'.

NOTE:
DO NOT publish benchmarks of these demos, and do not link against the
demo library in any user application.  These codes are sometimes slow,
and are meant as simple illustrations only, not for performance.  The fastest
methods are in LAGraph, not in SuiteSparse/GraphBLAS/Demo.  Benchmark LAGraph
instead.  Eventually, all GraphBLAS/Demos methods will be removed, and LAGraph
will serve all uses: for illustration, benchmarking, and production uses.

%----------------------------------------
\subsection{Installing SuiteSparse:GraphBLAS}
%----------------------------------------

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

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

%----------------------------------------
\subsection{Linking issues after installation}
%----------------------------------------

My Linux distro (Ubuntu 18.04) includes a copy of \verb'libgraphblas.so.1',
which is SuiteSparse:GraphBLAS v1.1.2.  After installing SuiteSparse:GraphBLAS
in \verb'/usr/local/lib' (with \verb'sudo make install'), compiling a simple
stand-alone program links against \verb'libgraphblas.so.1' instead of the
latest version, while at the same time accessing the latest version of the
include file as \verb'/usr/local/include/GraphBLAS.h'.  This command fails:

    {\small
    \begin{verbatim}
    gcc prog.c -lgraphblas \end{verbatim} }

Revising my \verb'LD_LIBRARY_PATH' to put \verb'/usr/local/lib' first in the
library directory order didn't help.  If you encounter this problem, try one of
the following options (all four work for me, and link against the proper
version, \verb'/usr/local/lib/libgraphblas.so.6.1.4' for example):

    {\small
    \begin{verbatim}
    gcc prog.c -l:libgraphblas.so.6
    gcc prog.c -l:libgraphblas.so.6.1.4
    gcc prog.c /usr/local/lib/libgraphblas.so
    gcc prog.c -Wl,-v -L/usr/local/lib -lgraphblas \end{verbatim} }

This \verb'prog.c' test program is a trivial one, which works in v1.0 and
later:

    {\small
    \begin{verbatim}
    #include <GraphBLAS.h>
    int main (void)
    {
        GrB_init (GrB_NONBLOCKING) ;
        GrB_finalize ( ) ;
    } \end{verbatim} }

Compile the program above, then use this command to ensure
\verb'libgraphblas.so.6' appears:

    {\small
    \begin{verbatim}
    ldd a.out \end{verbatim} }

%----------------------------------------
\subsection{Running the tests}
%----------------------------------------

To run a short test, type \verb'make demo' at the top-level \verb'GraphBLAS'
folder.  This will run all the demos in \verb'GraphBLAS/Demos'.  MATLAB is not
required.

To perform the extensive tests in the \verb'Test' folder, and the statement
coverage tests in \verb'Tcov', MATLAB R2018a or later is required.  See the
\verb'README.txt' files in those two folders for instructions on how to run the
tests.  The tests in the \verb'Test' folder have been ported to MATLAB on
Linux, MacOS, and Windows.  The \verb'Tcov' tests do not work on Windows.  The
MATLAB interface test (\verb'gbtest') works on all platforms; see the
\verb'GraphBLAS/GraphBLAS' folder for more details.

%----------------------------------------
\subsection{Cleaning up}
%----------------------------------------

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

%-------------------------------------------------------------------------------
\section{Release Notes}
%-------------------------------------------------------------------------------

\begin{itemize}

\item Version 7.4.0 (Dec 23, 2022)

    \begin{itemize}
    \item add non-\verb'va_arg' methods: \verb'va_arg'-based \verb'GxB_get/set'
        methods are ANSI C11 but cause issues for cffi in Python.  As a
        temporary workaround, new methods have been added that do not use
        \verb'va_arg'.  The existing \verb'GxB_get/set' methods are not
        changed.  The new methods are not in the user guide, since all of the
        \verb'GxB_get/set' methods will be superceded with \verb'GrB_get/set'
        in the v2.1 C API.  At that point, all \verb'GxB_get/set' methods will
        become historical (kept, not deprecated, but removed from the user
        guide).
    \end{itemize}

\item Version 7.3.3 (Dec 9, 2022)

    \begin{itemize}
    \item \verb'stdatomic.h': using \verb'#include <stdatomic.h>' and
        \verb'atomic_compare_exchange_weak'
        instead of GCC/clang/icx \verb'__atomic_*' variants.
        Added \verb'-latomic' if required.
    \item chunk factor for C=A*B (saxpy3 method):
        revised for non-builtin-semirings
    \end{itemize}

\item Version 7.3.2 (Nov 12, 2022)

    \begin{packed_itemize}
    \item \verb'cmake_modules': minor revision to build system, to sync 
        with SuiteSparse v6.0.0
    \item Added option \verb'-DNOPENMP=1' to disable OpenMP parallelism.
    \end{packed_itemize}

\item Version 7.3.1 (Oct 21, 2022)

    \begin{packed_itemize}
    \item workaround for a bug in the Microsoft Visual Studio Compiler,
        MSC 19.2x (in vs2019).
    \end{packed_itemize}

\item Version 7.3.0 (Oct 14, 2022)

    \begin{packed_itemize}
    \item \verb'GrB_Matrix': changes to the internal data structure
        \item minor internal changes: \verb'A->nvals' for sparse/hypersparse
        \item more significant changes: added hyper-hash for
        hypersparse case, speeds up many operations on hypersparse matrices.
        Based on \cite{Green19}.
        \item \verb'GxB_unpack_HyperHash' and \verb'GxB_pack_HyperHash':
            to pack/unpack the hyper-hash
    \item \verb'@GrB' MATLAB/Octave interface: changed license to Apache-2.0.
    \item MATLAB library: renamed to \verb'libgraphblas_matlab.so'
    \item performance: faster \verb'C=A*B' when using a single thread and
        \verb'B' is a sparse vector with many entries.
    \end{packed_itemize}

\item Version 7.2.0 (Aug 8, 2022)

    \begin{packed_itemize}
    \item added ZSTD as a compression option for serialize/deserialize:
        Version 1.5.3 by Yann Collet,
        \url{https://github.com/facebook/zstd.git}.
        Copyright (c) 2016-present, Facebook, Inc. All rights reserved.
        Included in SuiteSparse:GraphBLAS via its BSD-3-clause license.
        The default method is now ZSTD, level 1.
    \item \verb'GxB_Matrix_reshape*' added.
    \item MATLAB interface: \verb'reshape', \verb'C(:)=A', \verb'C=A(:)' are
        faster.  Better error messages.
    \end{packed_itemize}

\item Version 7.1.2 (July 8, 2022)

    \begin{packed_itemize}
    \item MATLAB interface: linear indexing added for C(:)=A, C=A(:), and
        single-output I=find(C).  Faster bandwidth, istriu, istril,
        isbanded, isdiag.  C(I,J)=A can now grow the size of A.
    \end{packed_itemize}

\item Version 7.1.1 (June 3, 2022)

    \begin{packed_itemize}
    \item minor updates to documentation and error messages
    \item MATLAB interface: minor revision of GrB.deserialize
    \end{packed_itemize}

\item Version 7.1.0 (May 20, 2022)

    \begin{packed_itemize}
    \item  added cube root: \verb'GxB_CBRT_FP32' and \verb'GxB_CBRT_FP64'
        unary operators
    \item added \verb'GxB_Matrix_isStoredElement'
        and \verb'GxB_Vector_isStoredElement'
    \end{packed_itemize}

\item Version 7.0.4 (Apr 25, 2022)

    \begin{packed_itemize}
    \item (46) bug fix: user-defined type size was incorrectly limited
        to 128 bytes.  Caught by Erik Welch.
    \end{packed_itemize}

\item Version 7.0.3 (Apr 8, 2022)

    \begin{packed_itemize}
    \item faster transpose when using 2 threads
    \end{packed_itemize}

\item Version 7.0.2 (Apr 5, 2022)

    \begin{packed_itemize}
    \item (45) bug fix: vector iterator was broken for iterating across a
        vector in bitmap format.  Caught by Erik Welch.
    \end{packed_itemize}

\item Version 7.0.1 (Apr 3, 2022)

    \begin{packed_itemize}
    \item added revised ACM TOMS submission to the Doc folder
    \end{packed_itemize}

\item Version 7.0.0 (Apr 2, 2022)

    \begin{packed_itemize}
    \item (44) spec bug: \verb'GrB_Matrix_diag'
        was implemented in v5.2.x and v6.x with the wrong signature.
        This fix requires the major release to change, from v6.x to v7.x.
    \item (43) performance bug fix for \verb'GrB_mxm':
        auto selection for saxpy method (Hash vs Gustavson) revised.
    \item \verb'GrB_assign': better performance for \verb'C(i,j)=scalar' and
        \verb'C(i,j)+=scalar' when \verb'i' and \verb'j' have length 1 (scalar
        assigment with no scalar expansion).
    \end{packed_itemize}

\item Version 6.2.5 (Mar 14, 2022)

    \begin{packed_itemize}
    \item For SuiteSparse v5.11.0.
    \end{packed_itemize}

\item Version 6.2.4 (Mar 8, 2022)

    \begin{packed_itemize}
    \item (42) bug fix: \verb'GrB_mxm' with 0-by-0 iso full matrices.
        Caught by Henry Amuasi in the Python
        grblas interface, then triaged and isolated by Erik Welch.
    \end{packed_itemize}

\item Version 6.2.3 (Mar 5, 2022)

    \begin{packed_itemize}
    \item minor update to documentation in \verb'GrB.build':
        no change to any code
    \end{packed_itemize}

\item Version 6.2.2 (Feb 28, 2022)

    \begin{packed_itemize}
    \item revised output of \verb'GxB_*_sort' to return newly created matrices
        C and P as full or bitmap matrices, as appropriate, instead of
        sparse/hypersparse, following their sparsity control settings.
    \end{packed_itemize}

\item Version 6.2.1 (Feb 14, 2022)

    \begin{packed_itemize}
    \item  (41) bug fix: \verb'GxB_Iterator_get' used \verb'(void *) + size'
        arithmetic
    \end{packed_itemize}

\item Version 6.2.0 (Feb 14, 2022)

    \begin{packed_itemize}
    \item added the \verb'GxB_Iterator' object and its methods.  See
        Section~\ref{iter}.
    \item \verb'@GrB' interface: revised sparse-times-full rule for the
        conventional semiring (the syntax \verb'C=A*B'), so that
        sparse-times-full results in \verb'C' as full,
        but hypersparse-times-sparse is not full
        (typically sparse or hypersparse).
    \end{packed_itemize}

\item Version 6.1.4 (Jan 12, 2022)

    \begin{packed_itemize}
    \item added Section~\ref{perf} to User Guide: how to get the best
        performance out of algorithms based on GraphBLAS.
    \item \verb'cpu_features':  no longer built as a separate library,
        but built directly into \verb'libgraphblas.so' and
        \verb'libgraphblas.a'.  Added compile-time flags to
        optionally disable the use of \verb'cpu_features' completely.
    \item Octave 7: port to Apple Silicon (thanks to 
            G{\'{a}}bor Sz{\'{a}}rnyas).
    \item min/max monoids:  real case (FP32 and FP64) no longer terminal
    \item \verb'@GrB' interface: overloaded \verb'C=A*B' syntax where one
        matrix is full always results in a full matrix \verb'C'.
    \item Faster \verb'C=A*B' for sparse-times-full and full-times-sparse
        for \verb'@GrB' interface.
    \end{packed_itemize}

\item Version 6.1.3 (Jan 1, 2022)

    \begin{packed_itemize}
    \item performance: task creation for \verb'GrB_mxm'
        had a minor flaw (results were correct but parallelism suffered).
        Performance improvement of up to 10x when nnz(A)<<nnz(B).
    \end{packed_itemize}

\item Version 6.1.2 (Dec 31, 2021)

    \begin{packed_itemize}
    \item performance: revised \verb'swap_rule' in \verb'GrB_mxm', which decides whether
        to compute \verb"C=A*B" or \verb"C=(B'*A')'", and variants, resulting in up
        to 3x performance gain over v6.1.1 for \verb'GrB_mxm' (observed;
        could be higher in other cases).
    \end{packed_itemize}

\item Version 6.1.1 (Dec 28, 2021) 

    \begin{packed_itemize}
    \item minor revision to AVX2 and AVX512f selection
    \item \verb'cpu_features/Makefile': remove test of \verb'list_cpu_features'
        so that the package can be built when cross-compiling
    \end{packed_itemize}

\item Versions 6.1.0 (Dec 26, 2021)

    \begin{packed_itemize}
    \item added \verb'GxB_get' options: compiler name and version.
    \item added package: \url{https://github.com/google/cpu_features},
        Nov 30, 2021 version.
    \item performance: faster \verb'C+=A*B' when \verb'C' is full,
        \verb'A' is bitmap/full, and \verb'B' is sparse/hyper.  % saxpy5
        Faster \verb"C+=A'*B" when
        \verb'A' is sparse/hyper, and \verb'B' is bitmap/full.  % dot4
    \item (40) bug fix: deserialization of iso and empty matrices/vectors was
        incorrect
    \end{packed_itemize}

\item Versions 6.0.2 and 5.2.2 (Nov 30, 2021)

    \begin{packed_itemize}
    \item (39) bug fix: \verb'GrB_Matrix_export':
        numerical values not properly exported
    \end{packed_itemize}

\item Versions 6.0.1 and 5.2.1 (Nov 27, 2021)

    \begin{packed_itemize}
    \item v6.0.x and v5.2.x (for the same x):
        differ only in \verb'GrB_wait', \verb'GrB_Info',
        \verb'GrB_SCMP', and \verb'GxB_init'.
    \item (38) bug fix:  \verb"C+=A'*B" when the accum operator is the same as
        the monoid and C is iso-full, and \verb'A' or \verb'B' are hypersparse.
        (dot4 method).
    \item performance: \verb'GrB_select' with user-defined
        \verb'GrB_IndexUnaryOp' about 2x faster.
    \item performance: faster \verb'(MIN,MAX)_(FIRSTJ,SECONDI)' semirings
    \end{packed_itemize}

\item Version 6.0.0 (Nov 15, 2021)

    \begin{packed_itemize}
    \item this release contains only a few changes that cause a
        break with backward compatibility.  It is otherwise identical to v5.2.0.
    \item v6.0.0 is fully compliant with the v2.0 C API Specification.
        Three changes from the v2.0 C API Spec are not backward compatible
        (\verb'GrB_*wait', \verb'GrB_Info', \verb'GrB_SCMP').
        \verb'GxB_init' has also changed.
        \begin{packed_itemize}
        \item \verb'GrB_wait (object, mode)': was \verb'GrB_wait (&object)'.
        \item \verb'GrB_Info': changed enum values
        \item \verb'GrB_SCMP': removed
        \item \verb'GxB_init (mode, malloc, calloc, realloc, free, is_thread_safe)':
            the last parameter, \verb'is_thread_safe', is deleted.
            The malloc, calloc, realloc, and free functions must be thread-safe.
        \end{packed_itemize}
    \end{packed_itemize}

\item Version 5.2.0 (Nov 15, 2021)

    \begin{packed_itemize}
    \item Added for the v2.0 C API Specification: only features that are
        backward compatible with SuiteSparse:GraphBLAS v5.x have been
        added to v5.2.0:
        \begin{packed_itemize}
        \item \verb'GrB_Scalar': replaces \verb'GxB_Scalar', \verb'GxB_Scalar_*'
            functions renamed GrB
        \item \verb'GrB_IndexUnaryOp': new, free, fprint, wait
        \item \verb'GrB_select': selection via \verb'GrB_IndexUnaryOp'
        \item \verb'GrB_apply': with \verb'GrB_IndexUnaryOp'
        \item \verb'GrB_reduce': reduce matrix or vector to \verb'GrB_Scalar'
        \item \verb'GrB_assign', \verb'GrB_subassion': with \verb'GrB_Scalar'
            input
        \item \verb'GrB_*_extractElement_Scalar': get \verb'GrB_Scalar'
            from a matrix or vector
        \item \verb'GrB*build': when \verb'dup' is \verb'NULL',
            duplicates result in an error.
        \item \verb'GrB import/export': import/export from/to user-provided
            arrays
        \item \verb'GrB_EMPTY_OBJECT', \verb'GrB_NOT_IMPLEMENTED': error codes
            added
        \item \verb'GrB_*_setElement_Scalar': set an entry in a matrix or
            vector, from a \verb'GrB_Scalar'
        \item \verb'GrB_Matrix_diag': same as
            \verb'GxB_Matrix_diag (C,v,k,NULL)'
        \item \verb'GrB_*_serialize/deserialize': with compression
        \item \verb'GrB_ONEB_T': binary operator, $f(x,y)=1$, the same as
            \verb'GxB_PAIR_T'.
        \end{packed_itemize}
    \item \verb'GxB*import*' and \verb'GxB*export*': now historical; use
        \verb'GxB*pack/unpack*'
    \item \verb'GxB_select': is now historical; use \verb'GrB_select' instead.
    \item \verb'GxB_IGNORE_DUP': special operator for build methods only; if dup
        is this operator, then duplicates are ignored (not an error)
    \item \verb'GxB_IndexUnaryOp_new': create a named index-unary operator
    \item \verb'GxB_BinaryOp_new': create a named binary operator
    \item \verb'GxB_UnaryOp_new': create a named unary operator
    \item \verb'GxB_Type_new': to create a named type
    \item \verb'GxB_Type_name': to query the name of a type
    \item added \verb'GxB_*type_name' methods
        to query the name of a type as a string.
    \item \verb'GxB' methods that query an object return a \verb'GrB_type' such
        as \verb'GxB_Matrix_type' are declared historical; will be kept but not
        recommended (use \verb'GxB_*type_name' methods).
    \item \verb'GxB_Matrix_serialize/deserialize': with compression;
        optional descriptor.
    \item \verb'GxB_Matrix_sort', \verb'GxB_Vector_sort':
        sort a matrix or vector
    \item \verb'GxB_eWiseUnion': like \verb'GrB_eWiseAdd' except for how
        entries in $\bf A\setminus B$ and $\bf B \setminus A$ are computed.
    \item added LZ4/LZ4HC: compression library, \url{http://www.lz4.org} (BSD
        2), v1.9.3, Copyright (c) 2011-2016, Yann Collet.
    \item MIS and pagerank demos: removed; MIS added to LAGraph/experimental
    \item disabled free memory pool if OpenMP not available
    \item (37) bug fix: ewise \verb'C=A+B' when all matrices are full,
        \verb'GBCOMPACT' not used, but \verb'GB_control.h' disabled the
        operator or type.  Caught by Roi Lipman, Redis.
    \item (36) bug fix: \verb'C<M>=Z' not returning \verb'C'
        as iso if \verb'Z 'iso and \verb'C' initially
        empty.  Caught by Erik Welch, Anaconda.
    \item performance improvements: \verb'C=A*B': sparse/hyper times
        bitmap/full, and visa versa, including \verb'C += A*B' when \verb'C' is
        full.
    \end{packed_itemize}

\item Version 5.1.10 (Oct 27, 2021)

    \begin{packed_itemize}
    \item  (35) bug fix: \verb'GB_selector'; \verb'A->plen' and \verb'C->plen'
        not updated correctly.  Caught by Jeffry Lovitz, Redis.
    \end{packed_itemize}

\item Version 5.1.9 (Oct 26, 2021)

    \begin{packed_itemize}
    \item (34) bug fix: in-place test incorrect for \verb"C+=A'*B" using dot4
    \item (33) bug fix: disable free pool if OpenMP not available
    \end{packed_itemize}

\item Version 5.1.8 (Oct 5, 2021)

    \begin{packed_itemize}
    \item (32) bug fix: C=A*B when A is sparse and B is iso and bitmap.
        Caught by Mark Blanco, CMU.
    \end{packed_itemize}

\item Version 5.1.7 (Aug 23, 2021)

    \begin{packed_itemize}
    \item (31) bug fix:  \verb'GrB_apply', when done in-place and matrix starts
        non-iso and becomes iso, gave the wrong iso result.
        Caught by Fabian Murariu.
    \end{packed_itemize}

\item Version 5.1.6 (Aug 16, 2021)

    \begin{packed_itemize}
    \item one-line change to \verb'C=A*B': faster symbolic analysis when a
        vector \verb'C(:,j)' is dense (for CSC) or \verb'C(i,:)' for CSR.
    \end{packed_itemize}

\item Version 5.1.5 (July 15, 2021)

    \begin{packed_itemize}
    \item submission to ACM Transactions on Mathematical Software as
        a Collected Algorithm of the ACM.
    \end{packed_itemize}

\item Version 5.1.4 (July 6, 2021)

    \begin{packed_itemize}
    \item faster Octave interface.  Octave v7 or later is required.
    \item (30) bug fix: 1-based printing not enabled for pending tuples.
        Caught by Will Kimmerer, while working on the Julia interface.
    \end{packed_itemize}

\item Version 5.1.3 (July 3, 2021)

    \begin{packed_itemize}
    \item added \verb'GxB_Matrix_iso' and \verb'GxB_Vector_iso':
        to query if a matrix or vector is held as iso-valued
    \item (29) bug fix: \verb'Matrix_pack_*R' into a matrix previously held by
        column, or \verb'Matrix_pack*C' into a matrix by row, would flip the
        dimensions.
        Caught by Erik Welch, Anaconda.
    \item (28) bug fix: \verb'kron(A,B)' with iso input matrices
        \verb'A' and \verb'B' fixed.
        Caught by Michel Pelletier, Graphegon.
    \item (27) bug fix: v5.1.0 had a wrong version of a file; posted by mistake.
        Caught by Michel Pelletier, Graphegon.
    \end{packed_itemize}

\item Version 5.1.2 (June 30, 2021)

    \begin{packed_itemize}
    \item iso matrices added:  these are matrices and vectors whose
        values in the sparsity pattern are all the same.  This is an internal
        change to the opaque data structures of the \verb'GrB_Matrix' and
        \verb'GrB_Vector' with very little change to the API.
    \item added \verb'GxB_Matrix_build_Scalar'
            and \verb'GxB_Vector_build_Scalar',
            which always build iso matrices and vectors.
    \item import/export methods can now import/export iso matrices and vectors.
    \item added \verb'GrB.argmin/argmax' to MATLAB/Octave interface
    \item added \verb'GxB_*_pack/unpack' methods as alternatives to
        import/export.
    \item added \verb'GxB_PRINT_1BASED' to the global settings.
    \item added \verb'GxB_*_memoryUsage'
    \item port to Octave:  \verb'gbmake' and \verb'gbtest'
        work in Octave7 to build and test
        the \verb'@GrB' interface to GraphBLAS.  Octave 7.0.0 is required.
    \end{packed_itemize}

\item Version 5.0.6 (May 24, 2021)

    \begin{packed_itemize}
    \item BFS and triangle counting demos removed from GraphBLAS/Demo:
        see LAGraph for these algorithms.  Eventually, all of GraphBLAS/Demo
        will be deleted, once LAGraph includes all the methods included there.
    \end{packed_itemize}

\item Version 5.0.5 (May 17, 2021)

    \begin{packed_itemize}
    \item (26) performance bug fix:  reduce-to-vector where \verb'A' is
        hypersparse CSR with a transposed descriptor (or CSC with no
        transpose), and some cases for \verb'GrB_mxm/mxv/vxm' when computing
        \verb'C=A*B' with A hypersparse CSC and \verb'B' bitmap/full (or
        \verb'A' bitmap/full and \verb'B' hypersparse CSR), the wrong internal
        method was being selected via the auto-selection strategy, resulting in
        a significant slowdown in some cases.
    \end{packed_itemize}

\item Version 5.0.4 (May 13, 2021)

    \begin{packed_itemize}
    \item \verb'@GrB' MATLAB/Octave interface: changed license
        to GNU General Public License v3.0 or later.
        It was licensed under Apache-2.0 in Version 5.0.3 and earlier.
        Changed back to Apache-2.0 for Version 7.3.0; see above.
    \end{packed_itemize}

\item Version 5.0.3 (May 12, 2021)

    \begin{packed_itemize}
    \item (25) bug fix: disabling \verb'ANY_PAIR' semirings by editing
        \verb'Source/GB_control.h' would cause a segfault if those disabled
        semirings were used.
    \item demos are no longer built by default
    \item (24) bug fix: new functions in v5.0.2 not declared as \verb'extern'
        in \verb'GraphBLAS.h'.
    \item \verb'GrB_Matrix_reduce_BinaryOp' reinstated from v4.0.3;
        same limit on built-in ops that correspond to known monoids.
    \end{packed_itemize}

\item Version 5.0.2 (May 5, 2021)

    \begin{packed_itemize}
    \item (23) bug fix: \verb'GrB_Matrix_apply_BinaryOp1st' and \verb'2nd'
        were using the
        wrong descriptors for \verb'GrB_INP0' and \verb'GrB_INP1'.
        Caught by Erik Welch, Anaconda.
    \item memory pool added for faster allocation/free of small blocks
    \item \verb'@GrB' interface ported to MATLAB R2021a.
    \item \verb'GxB_PRINTF' and \verb'GxB_FLUSH' global options added.
    \item \verb'GxB_Matrix_diag': construct a diagonal matrix from a vector
    \item \verb'GxB_Vector_diag': extract a diagonal from a matrix
    \item \verb'concat/split': methods to concatenate and split matrices.
    \item \verb'import/export':
        size of arrays now in bytes, not entries.  This change
        is required for better internal memory management, and it is not
        backward compatible with the \verb'GxB*import/export' functions in v4.0.
        A new parameter, \verb'is_uniform', has been added to all import/export
        methods, which indicates that the matrix values are all the same.
    \item (22) bug fix: SIMD vectorization was missing
        \verb'reduction(+,task_cnvals)' in
        \verb'GB_dense_subassign_06d_template.c'.  Caught by Jeff Huang, Texas
        A\&M, with his software package for race-condition detection.
    \item \verb'GrB_Matrix_reduce_BinaryOp': removed.  Use a monoid instead,
        with \verb'GrB_reduce' or \verb'GrB_Matrix_reduce_Monoid'.
    \end{packed_itemize}

\item Version 4.0.3 (Jan 19, 2021)

    \begin{packed_itemize}
    \item faster min/max monoids
    \item \verb'G=GrB(G)' converts \verb'G' from v3 object to v4
    \end{packed_itemize}

\item Version 4.0.2 (Jan 13, 2021)

    \begin{packed_itemize}
    \item ability to load \verb'*.mat' files saved with the v3 \verb'GrB'
    \end{packed_itemize}

\item Version 4.0.1 (Jan 4, 2021)

    \begin{packed_itemize}
    \item significant performance improvements: compared with v3.3.3,
        up to 5x faster in breadth-first-search (using 
        \verb'LAGraph_bfs_parent2'), and 2x faster in
        Betweenness-Centrality (using \verb'LAGraph_bc_batch5').
    \item \verb'GrB_wait(void)', with no inputs: removed
    \item \verb'GrB_wait(&object)': polymorphic function added
    \item \verb'GrB_*_nvals': no longer guarantees completion;
        use \verb'GrB_wait(&object)'
        or non-polymorphic \verb'GrB_*_wait (&object)' instead
    \item \verb'GrB_error': now has two parameters: a string
        (\verb'char **') and an object.
    \item \verb'GrB_Matrix_reduce_BinaryOp' limited to built-in operators that
        correspond to known monoids.
    \item \verb'GrB_*_extractTuples': may return indices out of order
    \item removed internal features: GBI iterator, slice and hyperslice matrices
    \item bitmap/full matrices and vectors added
    \item positional operators and semirings:
        \verb'GxB_FIRSTI_INT32' and related ops
    \item jumbled matrices: sort left pending, like zombies and pending tuples
    \item \verb'GxB_get/set': added \verb'GxB_SPARSITY_*'
        (hyper, sparse, bitmap, or full) and \verb'GxB_BITMAP_SWITCH'.
    \item \verb'GxB_HYPER': enum renamed to \verb'GxB_HYPER_SWITCH'
    \item \verb'GxB*import/export': API modified
    \item \verb'GxB_SelectOp': \verb'nrows' and \verb'ncols' removed
        from function signature.
    \item OpenMP tasking removed from mergesort and replaced with parallel
        for loops.  Just as fast on Linux/Mac; now the performance ports to
        Windows.
    \item \verb'GxB_BURBLE' added as a supported feature.  This was an
        undocumented feature of prior versions.
    \item bug fix: \verb'A({lo,hi})=scalar'
        \verb'A(lo:hi)=scalar' was OK
    \end{packed_itemize}

\item Version 3.3.3 (July 14, 2020).
    Bug fix: \verb'w<m>=A*u' with mask non-empty and u empty.

\item Version 3.3.2 (July 3, 2020).  Minor changes to build system.

\item Version 3.3.1 (June 30, 2020).  Bug fix to \verb'GrB_assign' and
    \verb'GxB_subassign' when the assignment is simple (\verb'C=A') but
    with typecasting.

\item Version 3.3.0 (June 26, 2020).  Compliant with V1.3 of the C API
    (except that the polymorphic \verb'GrB_wait(&object)' doesn't appear yet;
    it will appear in V4.0).

    Added complex types (\verb'GxB_FC32' and \verb'GxB_FC64'), many unary
    operators, binary operators, monoids, and semirings.  Added bitwise
    operators, and their monoids and semirings.  Added the predefined monoids
    and semirings from the v1.3 specification.  \verb'@GrB' interface: added complex
    matrices and operators, and changed behavior of integer operations to more
    closely match the behavior on built-in integer matrices.  The rules for
    typecasting large floating point values to integers has changed.  The
    specific object-based \verb'GrB_Matrix_wait', \verb'GrB_Vector_wait', etc,
    functions have been added.  The no-argument \verb'GrB_wait()' is
    deprecated.  Added \verb'GrB_getVersion', \verb'GrB_Matrix_resize',
    \verb'GrB_Vector_resize', \verb'GrB_kronecker', \verb'GrB_*_wait', scalar
    binding with binary operators for \verb'GrB_apply', \newline
    \verb'GrB_Matrix_removeElement', and \verb'GrB_Vector_removeElement'.

\item Version 3.2.0 (Feb 20, 2020).  Faster \verb'GrB_mxm', \verb'GrB_mxv', and
    \verb'GrB_vxm', and faster operations on dense matrices/vectors.  Removed
    compile-time user objects (\verb'GxB_*_define'), since these were not
    compatible with the faster matrix operations.  Added the \verb'ANY' and
    \verb'PAIR' operators.  Added the predefined descriptors,
    \verb'GrB_DESC_*'.  Added the structural mask option.  Changed default
    chunk size to 65,536.  \verb'@GrB' interface modified:  \verb'GrB.init' is
    now optional.

\item Version 3.1.2 (Dec, 2019).  Changes to allow SuiteSparse:GraphBLAS
    to be compiled with the Microsoft Visual Studio compiler.  This compiler
    does not support the \verb'_Generic' keyword, so the polymorphic functions
    are not available.  Use the equivalent non-polymorphic functions instead,
    when compiling GraphBLAS with MS Visual Studio.  In addition,
    variable-length arrays are not supported, so user-defined types are limited
    to 128 bytes in size.  These changes have no effect if you have an ANSI C11
    compliant compiler.

    \verb'@GrB' interface modified:  \verb'GrB.init' is now required.

\item Version 3.1.0 (Oct 1, 2019).  \verb'@GrB' interface added.  See the
    \newline \verb'GraphBLAS/GraphBLAS' folder for details and documentation,
    and Section~\ref{octave}.

\item Version 3.0 (July 26, 2019), with OpenMP parallelism.

The version number is increased to 3.0, since
this version is not backward compatible with V2.x.  The \verb'GxB_select'
operation changes; the \verb'Thunk' parameter was formerly a
\verb'const void *' pointer, and is now a \verb'GxB_Scalar'.  A new parameter
is added to \verb'GxB_SelectOp_new', to define the expected type of
\verb'Thunk'.  A new parameter is added to \verb'GxB_init', to specify whether
or not the user-provided memory management functions are thread safe.

The remaining changes add new features, and are upward compatible with V2.x.
The major change is the addition of OpenMP parallelism.  This addition has no
effect on the API, except that round-off errors can differ with the number of
threads used, for floating-point types.  \verb'GxB_set' can optionally define
the number of threads to use (the default is \verb'omp_get_max_threads').  The
number of threads can also defined globally, and/or in the
\verb'GrB_Descriptor'.  The \verb'RDIV' and \verb'RMINUS' operators are added,
which are defined as $f(x,y)=y/x$ and $f(x,y)=y-x$, respectively.  Additional
options are added to \verb'GxB_get'.

\item Version 2.3.3 (May 2019): Collected Algorithm of the ACM.
No changes from V2.3.2 other than the documentation.

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

\item
Version 2.2 (Nov 2018)
adds user-defined objects at compile-time, via user \verb'*.m4' files placed in
\verb'GraphBLAS/User', which use the \verb'GxB_*_define' macros 
(NOTE: feature removed in v3.2).
The default matrix format is now \verb'GxB_BY_ROW'.
Also added are the \verb'GxB_*print' methods for printing the contents of each
GraphBLAS object (Section~\ref{fprint}).   PageRank demos have been added to
the \verb'Demos' folder.

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

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

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

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

%-------------------------------------------------------------------------------
\subsection{Regarding historical and deprecated functions and symbols}
%-------------------------------------------------------------------------------

When a \verb'GxB*' function or symbol is added to the C API Specification with
a \verb'GrB*' name, the new \verb'GrB*' name should be used instead, if
possible.  However, the old \verb'GxB*' name will be kept as long as possible
for historical reasons.  Historical functions and symbols will not always be
documented here in the SuiteSparse:GraphBLAS User Guide, but they will be kept
in \verb'GraphbBLAS.h' and kept in good working order in the library.
Historical functions and symbols would only be removed in the very unlikely
case that they cause a serious conflict with future methods.

The only methods that have been fully deprecated and removed are the older
versions of \verb'GrB_wait' and \verb'GrB_error' methods, which are
incompatible with the latest versions.

% \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), Carl Yang (UC Davis), and Benjamin Brock (UC Berkeley), for
creating the GraphBLAS specification and for patiently answering my many
questions while I was implementing it.

I would like to thank Tim Mattson and Henry Gabb, Intel, Inc., for their
collaboration and for the support of Intel.

I would like to thank Joe Eaton and Corey Nolet for their collaboration on the
CUDA kernels (still in progress), and for the support of NVIDIA.

I would like to thank Pat Quillen for his
collaboration and for the support of MathWorks.

I would like to thank John Eaton for his collaboration on the integration
with Octave 7.

I would like to thank Michel Pelletier for his collaboration and work on the
pygraphblas interface, and Jim Kitchen and Erik Welch for their work on
Anaconda's python interface.

I would like to thank Will Kimmerer for his collaboration and work on the
Julia interface.

I would like to thank John Gilbert (UC Santa Barbara) for our many discussions
on GraphBLAS, and for our decades-long conversation and collaboration on sparse
matrix computations.

I would like to thank S\'ebastien Villemot (Debian Developer,
\url{http://sebastien.villemot.name}) for helping me with various build issues
and other code issues with GraphBLAS (and all of SuiteSparse) for its packaging
in Debian Linux.

I would like to thank G{\'{a}}bor Sz{\'{a}}rnyas for porting the \verb'@GrB'
interface to Octave 7 on Apple Silicon.

I would like to thank Roi Lipman, Redis (\url{https://redislabs.com}), for
our many discussions on GraphBLAS and for enabling its use in RedisGraph
(\url{https://redislabs.com/redis-enterprise/technology/redisgraph/}), a graph
database module for Redis.  Based on SuiteSparse:GraphBLAS, RedisGraph is up
600x faster than the fastest graph databases ({\footnotesize
\url{https://youtu.be/9h3Qco_x0QE} \newline
\url{https://redislabs.com/blog/new-redisgraph-1-0-achieves-600x-faster-performance-graph-databases/}}).

SuiteSparse:GraphBLAS was developed with support from
NVIDIA, Intel, MIT Lincoln Lab, MathWorks, Redis, IBM,
the National Science Foundation (1514406, 1835499), and Julia Computing.

%-------------------------------------------------------------------------------
\section{Additional Resources}
%-------------------------------------------------------------------------------

See \url{http://graphblas.org} for the GraphBLAS community page.  See
\url{https://github.com/GraphBLAS/GraphBLAS-Pointers} for an up-to-date list of
additional resources on GraphBLAS, maintained by G{\'{a}}bor Sz{\'{a}}rnyas.

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