File: GraphBLAS_UserGuide.tex

package info (click to toggle)
suitesparse 1%3A5.8.1%2Bdfsg-2
links: PTS, VCS
area: main
in suites: bullseye
size: 152,716 kB
sloc: ansic: 774,385; cpp: 24,213; makefile: 6,310; fortran: 1,927; java: 1,826; csh: 1,686; ruby: 725; sh: 535; perl: 225; python: 209; sed: 164; awk: 60
file content (11575 lines) | stat: -rw-r--r-- 534,764 bytes
\documentclass[12pt]{article}
\usepackage{url}
\urlstyle{sf}
\usepackage[svgnames]{xcolor}
\usepackage[colorlinks,linkcolor=Blue,citecolor=Blue,urlcolor=Blue]{hyperref}
\usepackage{amssymb}
\usepackage{amsmath}
\usepackage{framed}
\usepackage{mdframed}
% \usepackage{geometry}
% \usepackage{pdflscape}
\newmdenv[backgroundcolor=white]{spec}
\newmdenv[backgroundcolor=yellow]{specbeta}
\hyphenation{Suite-Sparse}
\hyphenation{Graph-BLAS}
\hyphenation{Suite-Sparse-Graph-BLAS}

\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
http://suitesparse.com and http://aldenmath.com
}

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

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

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

\newpage
{\small
\tableofcontents
}

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

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

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

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

For more details on SuiteSparse:GraphBLAS, and its use in LAGraph, see
\cite{Davis18,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, and Carl Yang} \cite{BulucMattsonMcMillanMoreiraYang17,spec},
based on {\em GraphBLAS Mathematics} by Jeremy Kepner \cite{Kepner2017}.  The
GraphBLAS C API Specification is available at \url{http://graphblas.org}.  This
version of SuiteSparse:GraphBLAS conforms to Version
\input{GraphBLAS_API_version.tex}
of {\em The GraphBLAS C API specification}, with one exception:
% TODO in 4.0: Remove when GrB_wait() is removed:
the single-input polymorphic function \verb'GrB_wait(&object)' does not appear
in this version, since it conflicts with the no-input \verb'GrB_wait()'.  Use
the non-polymorphic versions instead (\verb'GrB_Matrix_wait(&C)' for example).

In this User Guide, aspects of the GraphBLAS specification that would be true
for any GraphBLAS implementation are simply called ``GraphBLAS.'' Details
unique to this particular implementation are referred to as
SuiteSparse:GraphBLAS.

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

\newpage
\subsection{Future plans:}

\begin{itemize}

\item Version 4.0.0 (likely in July, 2020), will follow the V2.0 of the C API.
    The following changes are tentative, and depend on the final release of the
    V2.0 C API.

    % TODO in 4.0: revise this as needed:
    \verb'GrB_wait()', with no inputs: will be removed.
    \verb'GrB_wait(&object)': polymorphic function will be added.
    \verb'GrB_*_nvals' and related functions:
        will no longer guarantee completion
        (per the v1.3 C API);
        use \verb'GrB_wait(&object)'
        or non-polymorphic \verb'GrB_*_wait(&object)' instead.
    \verb'GrB_error' will change; it will take two parameters,
    \verb'GrB_error(&s,C)' where \verb's' is the error string generated
    when \verb'C' was last operated on.
    V4.0 will otherwise be identical to V3.3.1.

\end{itemize}

\subsection{Release Notes:}
\begin{itemize}

\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 spec.  MATLAB interface: added complex matrices
    and operators, and changed behavior of integer operations to more closely
    match the behavior on MATLAB 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', \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 descriptor, \verb'GrB_DESC_*'.
    Added the structural mask option.  Changed default chunk size to 65,536.
    Note that v3.2.0 is not compatible with the MS Visual Studio compiler; use
    v3.1.2 instead.
    MATLAB 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.

    MATLAB interface modified:  \verb'GrB.init' is now required.

\item Version 3.1.0 (Oct 1, 2019).  MATLAB interface added.  See the \newline
    \verb'GraphBLAS/GraphBLAS' folder for details and documentation,
    and Section~\ref{matlab}.

\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{import_export}), in support of the new LAGraph project
(\url{https://github.com/GraphBLAS/LAGraph}, see also Section~\ref{lagraph}).
LAGraph includes a push-pull BFS in GraphBLAS that is faster than two versions
in the \verb'Demo' folder.  \verb'GxB_init' was added to allow the memory
manager functions (\verb'malloc', etc) to be specified.

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

GraphBLAS provides a collection of {\em methods} to create, query, and free its
of objects: sparse matrices, sparse vectors, sparse 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 analog is given in the table below.

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

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

GraphBLAS has 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.
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 2,438 unique semirings.  With typecasting, any of these 2,438
semirings can be applied to matrices \verb'C', \verb'A', and \verb'B'
of 13 predefined types, in any combination.  This gives over 5 million 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}.  A GraphBLAS operation starts with its primary
computation, producing a result \verb'T'; for matrix multiply, \verb'T=A*B', or
if \verb'A' is transposed first, \verb"T=A'*B", for example.  Applying the
accumulator, mask (or its complement) to obtain the final result matrix
\verb'C' can be expressed in the MATLAB \verb'accum_mask' function shown in the
figure.  This function is an exact, fully functional, and nearly-complete
description of the GraphBLAS accumulator/mask operation.  The only aspects it
does not consider are typecasting (see Section~\ref{typecasting}), and the
value of the implicit identity (for those, see another version in the
\verb'Test' folder).

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

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

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

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

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

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

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

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

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{spec}
{\bf SPEC:} the GraphBLAS API states that typecasting follows the rules of ANSI
C.  Yet C leaves some typecasting undefined.  SuiteSparse:GraphBLAS provides a
precise definition for all typecasting as an extension to the spec.
\end{spec}

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

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

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

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.

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

The MATLAB interface to SuiteSparse:GraphBLAS is included with this
distribution, described in Section~\ref{matlab}.
It is fully polished, and fully tested, but does have
some limitations that will be addressed in future releases.

A beta version of a Python interface is 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 Interface}
\label{matlab}

As of Version 3.1, a MATLAB interface is now available.  Refer to 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 interface adds the \verb'GrB' class, which is an opaque MATLAB
object that contains a GraphBLAS matrix, either double or single precision
(real or complex), boolean, or any of the built-in integer types.  MATLAB
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, or \verb'help GrB' for more details.

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

\begin{packed_itemize}
    \item Saving a GrB matrix object from MATLAB can be done, but the
        resulting \verb'*.mat' file must be read in by the same version
        of GraphBLAS.
    \item \verb'GrB' matrices with dimension larger than \verb'2^53' do not
        display properly in the MATLAB \verb'whos' command.  MATLAB gets this
        information from \verb'size(A)', which returns a correct result, but
        MATLAB rounds it to double before displaying it.  The size is displayed
        correctly with \verb'disp' or \verb'display'.
    \item Non-blocking mode is not exploited; this would require
        a MATLAB mexFunction to modify its inputs, which is
        technically possible but not permitted by the MATLAB API.
        This can have significant impact on performance, if a MATLAB
        m-file makes many repeated tiny changes to a matrix.  This kind of
        computation can often be done with good performance in the C API,
        but will be very slow in MATLAB.
    \item Linear indexing, or \verb'A(:)' for a 2D matrix, and
        a single output of \verb'I=find(A)'.
    \item The second output for \verb'min' and \verb'max',
        and the \verb'includenan' option.
    \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.
        Saturating binary operators could be added in the future,
        so that \verb"GrB.eadd (A, '+saturate', B)" could return the
        MATLAB result.
    \item Solvers, so that \verb'x=A\b' could return a GF(2) solution,
        for example.
    \item Sparse matrices with dimension higher than 2.  It would be
        possible to map an N-dimensional matrix to a large 2D
        hypersparse GraphBLAS matrix.
\end{packed_itemize}

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

See Michel Pelletier's Python interface at
\href{https://github.com/michelp/pygraphblas}{https://github.com/michelp/pygraphblas}.
Anaconda is also developing a Python interface to SuiteSparse:GraphBLAS.

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

See Abhinav Mehndiratta's Julia interface at  \\
\href{https://github.com/abhinavmehndiratta/SuiteSparseGraphBLAS.jl}{https://github.com/abhinavmehndiratta/SuiteSparseGraphBLAS.jl}.

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

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

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

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

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

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

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

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

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

{\footnotesize
\begin{verbatim}
    #if GxB_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 (1,4,0)
    ... use features from version 1.4.0 of a specific GraphBLAS implementation
    #endif \end{verbatim}}


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

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
Macro                & purpose                                      \\
\hline
\verb'GxB_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.  The
SuiteSparse:GraphBLAS name is provided in its \verb'GraphBLAS.h' file as:

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

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

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

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

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

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS function   & purpose                                      & Section \\
\hline
\verb'GrB_init'      & start up GraphBLAS                           & \ref{init} \\
\verb'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\_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 to the user application.  This allows GraphBLAS to
postpone operations and then do them later in a more efficient manner by
rearranging them and grouping them together.  In non-blocking mode, the
computations required to construct an opaque GraphBLAS object might not be
finished when the GraphBLAS method or operation returns to the user.  However,
user-provided arrays are not opaque, and GraphBLAS methods and operations that
read them (such as \verb'GrB_Matrix_build') or write to them (such as
\verb'GrB_Matrix_extractTuples') always finish reading them, or creating them,
when the method or operation returns to the user application.

% TODO in 4.0: Revise for v4.0:
In addition, all methods and operations that extract values from a GraphBLAS
object and return them into non-opaque user arrays always ensure that the
computations for that object are completed when the method returns, namely:
\verb'GrB_*_nvals', \verb'GrB_*_extractElement', \verb'GrB_*_extractTuples',
and \verb'GrB_*_reduce' (to scalar).
{\bf NOTE: this behavior will change in SuiteSparse:GraphBLAS v4.0.  These
functions will only guarantee that the user-visible arrays are fully populated;
they will not guarantee completion.  Use \verb'GrB_*_wait(&object)' 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_Matrix_wait' or \verb'GrB_Vector_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(&object)' 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.

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

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

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

This version of SuiteSparse:GraphBLAS supports
\input{GraphBLAS_API_version.tex}
of the C API Specification,
% TODO in 4.0: Remove when GrB_wait(no inputs) is removed;
except for the polymorphic \verb'GrB_wait(&object)' with one input.
That method will appear in SuiteSparse:GraphBLAS V4.0.0.  In the meantime, use
the non-polymorphic methods \verb'GrB_Matrix_wait(&C)',
\verb'GrB_Vector_wait(&v)', and so on.

%===============================================================================
\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, etc
(
    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 *),
    bool user_malloc_is_thread_safe
) ;
\end{verbatim}
}\end{mdframed}

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

These
functions can only be set once, when GraphBLAS starts.   Either \verb'GrB_init'
or \verb'GxB_init' must be called before any other GraphBLAS operation, but
not both.  The last argument to \verb'GxB_init' informs GraphBLAS as to
whether or not the functions are thread-safe.  The ANSI C and Intel TBB
functions are thread-safe, but the MATLAB \verb'mxMalloc' and related
functions are not thread-safe.  If not thread-safe, GraphBLAS calls
the functions from inside an OpenMP critical section.

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

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

SuiteSparse:GraphBLAS can be compiled as normal (outside of MATLAB) and then
linked into a MATLAB \verb'mexFunction'.  However, a \verb'mexFunction' should
use the MATLAB memory managers.  To do this, use the following instead of
\verb'GrB_init(mode)' in a MATLAB \verb'mexFunction', with the flag
\verb'false' since these functions are not thread-safe:

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

Passing in the last parameter as \verb'false' requires that GraphBLAS be
compiled with OpenMP.  Internally, SuiteSparse:GraphBLAS never calls any memory
management function inside a parallel region.  Results are undefined if all
three of the following conditions hold: (1) the user application calls
GraphBLAS in parallel from multiple user-level threads, (2) the memory
functions are not thread-safe, and (3) GraphBLAS is not compiled with OpenMP.
Safety is guaranteed if at least one of those conditions is false.

To use the scalable Intel TBB memory manager:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

% TODO in 4.0: revise this statement when the change to the API is finalized:
{\bf NOTE:} \verb'GrB_error' may change in the future.  It may have the signature
\verb'GrB_error(&s,C)' where \verb's' is the error string that describes the
error when \verb'C' is the output object of a GraphBLAS method.  This change to
the C API is tentative.  If this change is made, it will be reflected in
SuiteSparse:GraphBLAS v4.0.

\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 eight different objects to represent matrices and vectors,
their scalar data type (or domain), binary and unary operators on scalar types,
monoids, semirings, and a {\em descriptor} object used to specify optional
parameters that modify the behavior of a GraphBLAS operation.
SuiteSparse:GraphBLAS adds two additional objects: a sparse scalar
(\verb'GxB_Scalar'), and an operator for selecting entries from a matrix or
vector (\verb'GxB_SelectOp').

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

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

\begin{spec}
{\bf SPEC:} \verb'GxB_SelectOp' and \verb'GxB_Scalar' are extensions to
GraphBLAS.
\end{spec}

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

A GraphBLAS \verb'GrB_Type' defines the type of scalar values that a matrix or
vector contains, and the type of scalar operands for a unary or binary
operator.  There are 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 (\verb'#include <stdbool.h>' and \verb'#include <stdint.h>'), and the
classes in MATLAB, as listed in the following table.

MATLAB allows for \verb'double complex' sparse matrices, but the
\verb'class(A)' for such a matrix is just \verb'double'.  MATLAB treats
the complex types as properties of a class.

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lllll}
\hline
GraphBLAS         & C type           & MATLAB         & description              & range \\
type              &                  & class          &                          & \\
\hline
\verb'GrB_BOOL'   & \verb'bool'      & \verb'logical' & Boolean                  & true (1), false (0) \\
\hline
\verb'GrB_INT8'   & \verb'int8_t'    & \verb'int8'    & 8-bit signed integer     & -128 to 127 \\
\verb'GrB_INT16'  & \verb'int16_t'   & \verb'int16'   & 16-bit integer           & $-2^{15}$ to $2^{15}-1$ \\
\verb'GrB_INT32'  & \verb'int32_t'   & \verb'int32'   & 32-bit integer           & $-2^{31}$ to $2^{31}-1$ \\
\verb'GrB_INT64'  & \verb'int64_t'   & \verb'int64'   & 64-bit integer           & $-2^{63}$ to $2^{63}-1$ \\
\hline
\verb'GrB_UINT8'  & \verb'uint8_t'   & \verb'uint8'   & 8-bit unsigned integer   & 0 to 255 \\
\verb'GrB_UINT16' & \verb'uint16_t'  & \verb'uint16'  & 16-bit unsigned integer  & 0 to $2^{16}-1$ \\
\verb'GrB_UINT32' & \verb'uint32_t'  & \verb'uint32'  & 32-bit unsigned integer  & 0 to $2^{32}-1$ \\
\verb'GrB_UINT64' & \verb'uint64_t'  & \verb'uint64'  & 64-bit unsigned integer  & 0 to $2^{64}-1$ \\
\hline
\verb'GrB_FP32'   & \verb'float'     & \verb'single'  & 32-bit IEEE 754          & \verb'-Inf' to \verb'+Inf'\\
\verb'GrB_FP64'   & \verb'double'    & \verb'double'  & 64-bit IEEE 754          & \verb'-Inf' to \verb'+Inf'\\
\hline
\verb'GxB_FC32'   & \verb'float complex'  & \verb'single'      & 32-bit IEEE 754  & \verb'-Inf' to \verb'+Inf'\\
                  &                       & \verb'~isreal(.)'  & complex          &                           \\
\hline
\verb'GxB_FC64'   & \verb'double complex' & \verb'double'      & 64-bit IEEE 754  & \verb'-Inf' to \verb'+Inf'\\
                  &                       & \verb'~isreal(.)'  & complex          &                           \\
\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.  For
example, a user-defined \verb'GrB_Type' could be created to hold any C
\verb'struct' whose content is self-contained.  A C \verb'struct' containing
pointers might be problematic because GraphBLAS would not know to dereference
the pointers to traverse the entire ``scalar'' entry, but this can be done if
the objects referenced by these pointers are not moved.  A user-defined complex
type with real and imaginary types can be defined, or even a ``scalar'' type
containing a fixed-sized dense matrix (see Section~\ref{type_new}).  The
possibilities are endless.  GraphBLAS can create and operate on sparse matrices
and vectors in any of these types, including any user-defined ones.  For
user-defined types, GraphBLAS simply moves the data around itself (via
\verb'memcpy'), and then passes the values back to user-defined functions when
it needs to do any computations on the type.  The next sections describe the
methods for the \verb'GrB_Type' object:

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

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

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

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

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

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

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Type_wait          // wait for a user-defined type
(
    GrB_Type *type              // type to wait for
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined type, a GraphBLAS library may choose to exploit
non-blocking mode to delay its creation.  \verb'GrB_Type_wait(&type)' ensures
the \verb'type' is completed.  SuiteSparse:GraphBLAS currently does nothing for
\verb'GrB_Type_wait(&type)', except to ensure that \verb'type' is valid.

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

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

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

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

%-------------------------------------------------------------------------------
\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'),
and $Z$ refers to any complex floating point type
(\verb'FC32' or \verb'FC64').

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}

\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|}{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_LGAMMA_'$F$   & $F \rightarrow F$ & $z = \log(|\Gamma (x)|)$  & log of gamma function \\
\verb'GxB_TGAMMA_'$F$   & $F \rightarrow F$ & $z = \Gamma(x)$        & gamma function \\
\verb'GxB_ERF_'$F$      & $F \rightarrow F$ & $z = \erf(x)$          & error function \\
\verb'GxB_ERFC_'$F$     & $F \rightarrow F$ & $z = \erfc(x)$         & complimentary error function \\
\hline
\verb'GxB_FREXPX_'$F$   & $F \rightarrow F$ & $z = \mbox{frexpx}(x)$  & normalized fraction \\
\verb'GxB_FREXPE_'$F$   & $F \rightarrow F$ & $z = \mbox{frexpe}(x)$  & normalized exponent \\
\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}

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

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

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

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_UnaryOp_new            // create a new user-defined unary operator
(
    GrB_UnaryOp *unaryop,           // handle for the new unary operator
    void *function,                 // pointer to the unary function
    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.
% V2.1 and later:
{\bf NOTE:}
The pointers 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.

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_UnaryOp_wait       // wait for a user-defined unary operator
(
    GrB_UnaryOp *unaryop        // unary operator to wait for
) ;
\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.
\verb'GrB_UnaryOp_wait(&unaryop)' ensures the \verb'op' is completed.
SuiteSparse:GraphBLAS currently does nothing for
\verb'GrB_UnaryOp_wait(&unaryop)', except to ensure that the \verb'unaryop' is
valid.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A binary operator is a scalar function of the form $z=f(x,y)$.  The types of
$z$, $x$, and $y$ need not be the same.  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 six \verb'GxB_IS*' comparison operators 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 comparison operators 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'GxB_PAIR_'$T$   & $T \times T \rightarrow T$ & $z = 1$         & one \\
\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 comparison
\verb'GxB_ISEQ_'$T$   & $T \times T \rightarrow T$ & $z = (x == y)$  & equal \\
\verb'GxB_ISNE_'$T$   & $T \times T \rightarrow T$ & $z = (x \ne y)$ & not equal \\
\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', and
relative comparisons 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 comparison
\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 comparison operators 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 comparison operators are useful as ``multiply''
operators for creating semirings with Boolean monoids.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{|llll|}
\hline
\multicolumn{4}{|c|}{Binary comparison operators for all 13 types} \\
\hline
GraphBLAS name        & types (domains)            & $z=f(x,y)$      & description \\
\hline
% 6 TxT->bool comparison
\verb'GrB_EQ_'$T$     & $T \times T \rightarrow $\verb'bool' & $z = (x == y)$  & equal \\
\verb'GrB_NE_'$T$     & $T \times T \rightarrow $\verb'bool' & $z = (x \ne y)$ & not equal \\
\hline
\multicolumn{4}{ }{\mbox{ }} \\
\hline
\multicolumn{4}{|c|}{Binary comparison operators 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.

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

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

Likewise, SuiteSparse:GraphBLAS has two sets of logical OR, AND, and XOR
operators.  Without the \verb'_'$T$ suffix, the three operators \verb'GrB_LOR',
\verb'GrB_LAND', and \verb'GrB_LXOR' operate purely in the Boolean domain,
where all input and output types are \verb'GrB_BOOL'.  The second set
(\verb'GxB_LOR_'$T$ \verb'GxB_LAND_'$T$ and \verb'GxB_LXOR_'$T$) provides
Boolean operators to all 11 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.

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

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_BinaryOp_new
(
    GrB_BinaryOp *binaryop,         // handle for the new binary operator
    void *function,                 // pointer to the binary function
    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.
% V2.1 and later:
{\bf NOTE:} SuiteSparse:GraphBLAS may call the function with the pointers
\verb'z' and \verb'x' equal to one another, in which case \verb'z=f(z,y)'
should be computed.  Future versions may use additional pointer aliasing.

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_BinaryOp_wait      // wait for a user-defined binary operator
(
    GrB_BinaryOp *binaryop      // binary operator to wait for
) ;
\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.
\verb'GrB_BinaryOp_wait(&binaryop)' ensures the \verb'binaryop' is completed.
SuiteSparse:GraphBLAS currently does nothing for
\verb'GrB_BinaryOp_wait(&binaryop)', except to ensure that the \verb'binaryop'
is valid.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SuiteSparse:GraphBLAS v3.2.0 adds two new operators, \verb'ANY' and
\verb'PAIR'.

The \verb'PAIR' operator 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 symbolic 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 have to access
the values of the matrix, so it is a very fast operator to use.

The \verb'ANY' operator is very unusual, but very powerful.  It is the function
$f(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, 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 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.

The result of the \verb'ANY' monoid is 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(1,1)$ is always 1, for the \verb'ANY' operator $f(x,y)$.

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{SuiteSparse:GraphBLAS select operators: {\sf GxB\_SelectOp}} %======
%===============================================================================
\label{selectop}

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

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

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

Operators can be used on any type, including user-defined types, except that
the comparisons \verb'GT', \verb'GE', \verb'LT', and \verb'LE' can only be used
with built-in types.  User-defined select operators can also be created.

\vspace{0.2in}
{\footnotesize
\begin{tabular}{lll}
\hline
GraphBLAS name          & MATLAB            & description \\
                        & analog            & \\
\hline
\verb'GxB_TRIL'         & \verb'C=tril(A,k)'   & true for \verb'A(i,j)' if \verb'(j-i) <= k' \\
\verb'GxB_TRIU'         & \verb'C=triu(A,k)'   & true for \verb'A(i,j)' if \verb'(j-i) >= k' \\
\verb'GxB_DIAG'         & \verb'C=diag(A,k)'   & true for \verb'A(i,j)' if \verb'(j-i) == k' \\
\verb'GxB_OFFDIAG'      & \verb'C=A-diag(A,k)' & true for \verb'A(i,j)' if \verb'(j-i) != k' \\
\hline
\verb'GxB_NONZERO'      & \verb'C=A(A~=0)'     & true if \verb'A(i,j)' is nonzero\\
\verb'GxB_EQ_ZERO'      & \verb'C=A(A==0)'     & true if \verb'A(i,j)' is zero\\
\verb'GxB_GT_ZERO'      & \verb'C=A(A>0)'      & true if \verb'A(i,j)' is greater than zero \\
\verb'GxB_GE_ZERO'      & \verb'C=A(A>=0)'     & true if \verb'A(i,j)' is greater than or equal to zero \\
\verb'GxB_LT_ZERO'      & \verb'C=A(A<0)'      & true if \verb'A(i,j)' is less than zero \\
\verb'GxB_LE_ZERO'      & \verb'C=A(A<=0)'     & true if \verb'A(i,j)' is less than or equal to zero \\
\hline
\verb'GxB_NE_THUNK'     & \verb'C=A(A~=k)'     & true if \verb'A(i,j)' is not equal to \verb'k'\\
\verb'GxB_EQ_THUNK'     & \verb'C=A(A==k)'     & true if \verb'A(i,j)' is equal to \verb'k'\\
\verb'GxB_GT_THUNK'     & \verb'C=A(A>k)'      & true if \verb'A(i,j)' is greater than \verb'k' \\
\verb'GxB_GE_THUNK'     & \verb'C=A(A>=k)'     & true if \verb'A(i,j)' is greater than or equal to \verb'k' \\
\verb'GxB_LT_THUNK'     & \verb'C=A(A<k)'      & true if \verb'A(i,j)' is less than \verb'k' \\
\verb'GxB_LE_THUNK'     & \verb'C=A(A<=k)'     & true if \verb'A(i,j)' is less than or equal to \verb'k' \\
%
\hline
\end{tabular}
}
\vspace{0.2in}

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

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

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

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

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

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

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

The type \verb'xtype' is the GraphBLAS type of the input $x$ of the
user-defined function $z=f(i,j,m,n,x,\mbox{thunk})$.  The type may be built-in
or user-defined, or it may even be \verb'GrB_NULL'.  If the \verb'xtype' is
\verb'GrB_NULL', then the \verb'selectop' is type-generic.

The type \verb'ttype' is the GraphBLAS type of the input {\em thunk} of the
user-defined function $z=f(i,j,m,n,x,\mbox{thunk})$.  The type may be built-in
or user-defined, or it may even be \verb'GrB_NULL'.  If the \verb'ttype' is
\verb'GrB_NULL', then the \verb'selectop' does not access this parameter.
The \verb'const void *thunk' parameter on input to the user \verb'function'
will be passed as \verb'NULL'.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GB\_SelectOp\_wait:} wait for a select operator}
%-------------------------------------------------------------------------------

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_SelectOp_wait      // wait for a user-defined select operator
(
    GxB_SelectOp *selectop      // select operator to wait for
) ;
\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.
\verb'GxB_SelectOp_wait(&selectop)' ensures the \verb'selectop' is completed.
SuiteSparse:GraphBLAS currently does nothing for
\verb'GxB_SelectOp_wait(&selectop)', except to ensure that the \verb'selectop'
is valid.

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

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

\end{verbatim}
}\end{mdframed}

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

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_SelectOp\_ttype:} return the type of the {\em thunk}}
%-------------------------------------------------------------------------------
\label{selectop_ttype}

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

\end{verbatim}
}\end{mdframed}

\verb'GxB_SelectOp_ttype' returns the \verb'ttype' of the select operator,
which is the type of {\em thunk} in the function $z=f(i,j,m,n,x,\mbox{thunk})$.
If the select operator does not use this parameter, \verb'ttype' is returned as
\verb'GrB_NULL'.  This is not an error condition, but simply indicates that the
\verb'selectop' does not use this parameter.

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

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

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

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

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

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

A {\em monoid} is defined on a single domain (that is, a single type), $T$.  It
consists of an associative binary operator $z=f(x,y)$ whose three operands $x$,
$y$, and $z$ are all in this same domain $T$ (that is $T \times T \rightarrow
T$).  The associative operator must also have an identity element, or ``zero''
in this domain, such that $f(x,0)=f(0,x)=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.

Predefined binary operators that can be used to form monoids are listed in the
table below.  Most of these are the binary operators of predefined monoids,
except that the bitwise monoids are predefined only for the unsigned integer
types, not the signed integers.

\vspace{0.2in}
\noindent
{\footnotesize
\begin{tabular}{lllll}
\hline
GraphBLAS             & types (domains)            & expression      & identity  & terminal \\
operator              &                            & $z=f(x,y)$      &           & \\
\hline
% numeric TxT->T
\verb'GrB_PLUS_'$T$   & $T \times T \rightarrow T$ & $z = x+y$       & 0         & none \\
\verb'GrB_TIMES_'$T$  & $T \times T \rightarrow T$ & $z = xy$        & 1         & 0 (not $F$) \\
\verb'GxB_ANY_'$T$    & $T \times T \rightarrow T$ & $z = x$ or $y$  & any       & any        \\
\hline
\verb'GrB_MIN_'$R$    & $R \times R \rightarrow R$ & $z = \min(x,y)$ & $+\infty$ & $-\infty$ \\
\verb'GrB_MAX_'$R$    & $R \times R \rightarrow R$ & $z = \max(x,y)$ & $-\infty$ & $+\infty$ \\
\hline
% bool x bool -> bool
\verb'GrB_LOR'        & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \vee    y $ & false & true  \\
\verb'GrB_LAND'       & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \wedge  y $ & true  & false \\
\verb'GrB_LXOR'       & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z = x \veebar y $ & false & none \\
\verb'GrB_LXNOR'      & \verb'bool' $\times$ \verb'bool' $\rightarrow$ \verb'bool' & $z =(x ==      y)$ & true  & none \\
\hline
% bitwise
\verb'GrB_BOR_'$I$    & $I$ $\times$ $I$ $\rightarrow$ $I$ & \verb'z=x|y'    & all bits zero & all bits one  \\
\verb'GrB_BAND_'$I$   & $I$ $\times$ $I$ $\rightarrow$ $I$ & \verb'z=x&y'    & all bits one  & all bits zero \\
\verb'GrB_BXOR_'$I$   & $I$ $\times$ $I$ $\rightarrow$ $I$ & \verb'z=x^y'    & all bits zero & none \\
\verb'GrB_BXNOR_'$I$  & $I$ $\times$ $I$ $\rightarrow$ $I$ & \verb'z=~(x^y)' & all bits one  & none \\
\hline
\end{tabular}
}
\vspace{0.2in}

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

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

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

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.

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

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

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Monoid_wait        // wait for a user-defined monoid
(
    GrB_Monoid *monoid          // monoid to wait for
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined monoid, a GraphBLAS library may choose to exploit
non-blocking mode to delay its creation.  \verb'GrB_Monoid_wait(&monoid)'
ensures the \verb'monoid' is completed.  SuiteSparse:GraphBLAS currently does
nothing for \verb'GrB_Monoid_wait(&monoid)', 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 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.  To create a monoid that can
terminate early, create a user-defined operator that computes the same thing as
\verb'GrB_MIN_FP32', and then create a monoid based on this user-defined
operator with a terminal value of zero and an identity of \verb'+INFINITY'.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A {\em semiring} defines all the operators required to define the
multiplication of two sparse matrices in GraphBLAS, ${\bf C=AB}$.  The ``add''
operator is a commutative and associative monoid, and the binary ``multiply''
operator defines a function $z=fmult(x,y)$ where the type of $z$ matches the
exactly with the monoid type.  SuiteSparse:GraphBLAS includes 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}{ll}
\hline
\verb'GrB_Semiring_new'       & create a user-defined semiring \\
\verb'GrB_Semiring_wait'      & wait for a user-defined semiring \\
\verb'GxB_Semiring_add'       & return the additive monoid of a semiring \\
\verb'GxB_Semiring_multiply'  & return the binary operator of a semiring \\
\verb'GrB_Semiring_free'      & free a semiring \\
\hline
\end{tabular}
}

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Semiring_new           // create a semiring
(
    GrB_Semiring *semiring,         // handle of semiring to create
    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.  Using
built-in types and operators, 2,438 semirings can be built.  This count
excludes redundant Boolean operators (for example \verb'GrB_TIMES_BOOL' and
\verb'GrB_LAND' are different operators but they are redundant since they
always return the same result).

The v1.3 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,473 of the 2,438 unique semirings that can
be constructed from built-in types and operators, listed below, as an extension
to the spec.  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 add monoids (\verb'MIN', \verb'MAX', \verb'PLUS', \verb'TIMES', \verb'ANY')
    \item 20 multiply operators
    (\verb'FIRST', \verb'SECOND', \verb'PAIR', \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 comparison operator $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 add 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 add monoids
    (\verb'LAND', \verb'LOR', \verb'LXOR', \verb'EQ', \verb'ANY')
    \item 11 multiply operators
    (\verb'FIRST', \verb'SECOND', \verb'PAIR', \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', \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}

\end{itemize}

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Semiring_wait      // wait for a user-defined semiring
(
    GrB_Semiring *semiring      // semiring to wait for
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined semiring, a GraphBLAS library may choose to
exploit non-blocking mode to delay its creation.
\verb'GrB_Semiring_wait(&semiring)' ensures the \verb'semiring' is completed.
SuiteSparse:GraphBLAS currently does nothing for
\verb'GrB_Semiring_wait(&semiring)', 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.

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

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

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

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

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


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

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

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

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

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

\newpage
%===============================================================================
\subsection{GraphBLAS scalars: {\sf GxB\_Scalar}} %=============================
%===============================================================================
\label{scalar}

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

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

\vspace{0.2in}
{\footnotesize
\begin{tabular}{ll}
\hline
\verb'GxB_Scalar_new'            & create a sparse scalar \\
\verb'GxB_Scalar_wait'           & wait for a scalar \\
\verb'GxB_Scalar_dup'            & copy a sparse scalar \\
\verb'GxB_Scalar_clear'          & clear a sparse scalar of its entry \\
\verb'GxB_Scalar_nvals'          & return the number of entries in a
                                   sparse scalar (0 or 1) \\
\verb'GxB_Scalar_type'           & return the type of a sparse scalar \\
\verb'GxB_Scalar_setElement'     & set the single entry of a sparse scalar \\
\verb'GxB_Scalar_extractElement' & get the single entry from a sparse scalar \\
\verb'GxB_Scalar_free'           & free a sparse scalar \\
\hline
\end{tabular}
}

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

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

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

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Scalar\_wait:} wait for a scalar}
%-------------------------------------------------------------------------------

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Scalar_wait        // wait for a scalar
(
    GxB_Scalar *s               // scalar to wait for
) ;
\end{verbatim}
}\end{mdframed}

In non-blocking mode, the computations for a \verb'GxB_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'GxB_Scalar_wait(&s)'.  After this call, different user threads may safely
call GraphBLAS operations that use the scalar \verb's' as an input parameter.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Scalar\_dup:} copy a sparse scalar}
%-------------------------------------------------------------------------------
\label{scalar_dup}

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

\verb'GxB_Scalar_dup' makes a deep copy of a sparse scalar, like \verb's=t' in
MATLAB.  In GraphBLAS, it is possible, and valid, to write the following:

    {\footnotesize
    \begin{verbatim}
    GxB_Scalar t, s ;
    GxB_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 sparse scalars are needed, then this should be used instead:

    {\footnotesize
    \begin{verbatim}
    GxB_Scalar t, s ;
    GxB_Scalar_new (&t, GrB_FP64) ;
    GxB_Scalar_dup (&s, t) ;        // like s = t, but making a deep copy \end{verbatim}}

Then \verb's' and \verb't' are two different sparse 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 GxB\_Scalar\_clear:} clear a sparse scalar of its entry}
%-------------------------------------------------------------------------------
\label{scalar_clear}

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

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

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

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

\verb'GxB_Scalar_nvals' returns the number of entries in a sparse scalar, which
is either 0 or 1.  Roughly analogous to \verb'nvals = nnz(s)' 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.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Scalar\_type:} return the type of a sparse scalar}
%-------------------------------------------------------------------------------
\label{scalar_type}

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

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

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

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

\verb'GxB_Scalar_setElement' sets the single entry in a sparse scalar, like
\verb's = sparse(x)' in MATLAB notation.  For further details of this function,
see \verb'GxB_Matrix_setElement' in Section~\ref{matrix_setElement}.

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

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

\verb'GxB_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
sparse scalar \verb's', then \verb'x' is not modified, and the return value of
\verb'GxB_Scalar_extractElement' is \verb'GrB_NO_VALUE'.

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

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

\verb'GxB_Scalar_free' frees a sparse scalar.  Either usage:

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

\noindent
frees the sparse 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 sparse scalar are abandoned.

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

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

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

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

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

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


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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_new     // create a new vector with no entries
(
    GrB_Vector *v,          // handle of vector to create
    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 statement
\verb'v = sparse (n,1)', except that GraphBLAS can create sparse vectors any
type.  The pattern of the new vector is empty.

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_wait        // wait for a vector
(
    GrB_Vector *w               // vector to wait for
) ;
\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)'.  After this call, different user threads may safely
call GraphBLAS operations that use the vector \verb'w' as an input parameter.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_setElement          // w(i) = x
(
    GrB_Vector w,                       // vector to modify
    <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}.

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Vector_extractElement  // x = v(i)
(
    <type> *x,                      // scalar extracted
    const GrB_Vector v,             // vector to extract an entry from
    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, so further details of this
method are discussed in Section~\ref{matrix_extractElement}, which discusses
\verb'GrB_Matrix_extractElement'.  In this case, the column index is implicitly
\verb'j=0'.
{\bf NOTE: }  if no entry is present at \verb'v(i)', then
\verb'x' is not modified, and the return value of
\verb'GrB_Vector_extractElement' is \verb'GrB_NO_VALUE'.

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

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

\verb'GrB_Vector_removeElement' removes a single entry \verb'v(i)' from a vector.
If no entry is present at \verb'v(i)', then the vector is not modified.

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

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_new     // create a new matrix with no entries
(
    GrB_Matrix *A,          // handle of matrix to create
    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.

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

% GB_PUBLIC GrB_Info GrB_Descriptor_wait (GrB_Descriptor *desc    ) ;

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_wait        // wait for a matrix
(
    GrB_Matrix *C               // matrix to wait for
) ;
\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)'.  After this call, different user threads may safely
call GraphBLAS operations that use the matrix \verb'C' as an input parameter.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

However, SuiteSparse:GraphBLAS guarantees this ordering, 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.

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_setElement          // C (i,j) = x
(
    GrB_Matrix C,                       // matrix to modify
    <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.

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Matrix_extractElement      // x = A(i,j)
(
    <type> *x,                          // extracted scalar
    const GrB_Matrix A,                 // matrix to extract a scalar from
    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'.

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

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

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

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

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.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_removeElement:} remove a single 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.

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

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

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

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

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

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

%-------------------------------------------------------------------------------
\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{GraphBLAS matrix and vector import/export} %========================
%===============================================================================
\label{import_export}

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

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

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

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

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

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

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

The vector import/export methods use a single format for a \verb'GrB_Vector'.
Four different formats are provided for the import/export of a
\verb'GrB_Matrix'.  For each format, the \verb'Ax' array has a C type
corresponding to one of the 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 on import or
export.

The table below lists the methods presented in this section.

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

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

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

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

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

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

is identical to the following:

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

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

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

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

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

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

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

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

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

is analogous to:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

is held in CSC form as follows:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
}
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_HEAP      = 1002,   // heap-based saxpy method
    GxB_AxB_DOT       = 1003,   // dot product
    GxB_AxB_HASH      = 1004,   // hash-based saxpy method
    GxB_AxB_SAXPY     = 1005    // saxpy method (any kind)
}
GrB_Desc_Value ;
\end{verbatim} } \end{mdframed}

\newpage

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

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

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

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

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

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

    If the \verb'desc [GrB_MASK]' parameter is set to \verb'GrB_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'desc [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 spec).

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

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

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

    Vectors 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'desc [GrB_INP0]' modifies the matrix parameter and
    \verb'desc [GrB_INP1]' is ignored.  If a method's first parameter is a
    vector or scalar and the second a matrix, then \verb'desc [GrB_INP1]'
    modifies the matrix parameter and \verb'desc [GrB_INP0]' is ignored.

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

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

    \begin{itemize}

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

    \item \verb'GxB_AxB_SAXPY': select any saxpy-based method:
        \verb'GxB_AxB_GUSTAVSON', \verb'GxB_AxB_HEAP', and/or
        \verb'GxB_AxB_HASH', or any mix of the three,
        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)').  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.  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,
    corresponding to the number of columns of \verb'C'.

    \item \verb'GxB_AxB_HEAP': no longer appears in SuiteSparse:GraphBLAS, but
    may be reintroduced in a future version.  This is silently replaced with
    \verb'GxB_AxB_HASH'.

    \item \verb'GxB_AxB_HASH':  a hash-based method, based on
        \cite{10.1145/3229710.3229720}.  Very efficient for hypersparse
        matrices, matrix-vector-multiply, and when $|{\bf B}|$ is small.

% [2] Yusuke Nagasaka, Satoshi Matsuoka, Ariful Azad, and Aydın Buluç. 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, or when \verb'C' is tiny.  For example, it works very well
    when \verb'A' and \verb'B' are tall and thin, and \verb"C<M>=A*B'" or
    \verb"C=A*B'" are computed.  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}

\end{itemize}

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

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

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_Descriptor_wait        // wait for a descriptor
(
    GrB_Descriptor *descriptor      // descriptor to wait for
) ;
\end{verbatim}
}\end{mdframed}

After creating a user-defined descriptor, a GraphBLAS library may choose to
exploit non-blocking mode to delay its creation.
\verb'GrB_Descriptor_wait(&d)' ensures the descriptor \verb'd' is completed.
SuiteSparse:GraphBLAS currently does nothing for
\verb'GrB_Descriptor_wait(&d)', 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 (\verb'GxB_DEFAULT', \verb'GrB_COMP',
\verb'GrB_STRUCTURE', \verb'GrB_COMP+GrB_STRUCTURE', \verb'GrB_TRAN',
\verb'GrB_REPLACE', \verb'GxB_AxB_GUSTAVSON', \verb'GxB_AxB_HEAP',
\verb'GxB_AxB_HASH',
\verb'GxB_AxB_SAXPY',
or
\verb'GxB_AxB_DOT').

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

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

\hline

\verb'GrB_MASK'
    & \verb'GxB_DEFAULT':
    The Mask is not complemented.  \verb'Mask(i,j)=1' means the value $C_{ij}$
    can be modified by the operation, while \verb'Mask(i,j)=0' means the value
    $C_{ij}$ shall not be modified by the operation.
    & \verb'GrB_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.  \\

\hline

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

\hline

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

\hline

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

\hline
\end{tabular}
}

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Desc_set           // set a parameter in a descriptor
(
    GrB_Descriptor desc,        // descriptor to modify
    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 descriptor settings that do not have the type \verb'GrB_Desc_Value'.
See also \verb'GxB_set' described in Section~\ref{options}.

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

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Desc_get           // get a parameter from a descriptor
(
    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}.

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

%-------------------------------------------------------------------------------
\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\_*:}  predefined descriptors}
%-------------------------------------------------------------------------------
\label{descriptor_predefined}

Version 1.3 of the GraphBLAS C API Specification adds predefined descriptors,
and these have been added as of v3.2.0 of SuiteSparse:GraphBLAS.  They are
listed in the table below.  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.

\vspace{0.02in}
\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 returns
\verb'GrB_SUCCESS' or \verb'GrB_PANIC' in the unlikely event of a failure.
% TODO in 4.0: GrB_PANIC will not be returned.

\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 complemeted, 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    &   \\
\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    &   \\
\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    &   \\
\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    &   \\
\hline
\hline
    -  &-   & $c_{ij}$ & $t_{ij}$  & 0    &   \\
    -  &-   &  -       & $t_{ij}$  & 0    &   \\
    -  &-   & $c_{ij}$ &  -        & 0    &   \\
    -  &-   &  -       &  -        & 0    &   \\
\hline
    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}$  & 0    &   \\
    -  &yes &  -       & $t_{ij}$  & 0    &   \\
    -  &yes & $c_{ij}$ &  -        & 0    &   \\
    -  &yes &  -       &  -        & 0    &   \\
\hline
    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}


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

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

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

\begin{itemize}

\item \verb'GxB_set (field, value)' provides hints to
    SuiteSparse:GraphBLAS on how it should store all matrices created after
    calling this function:  by row, by column, and whether or not to use a {\em
    hypersparse} format \cite{BulucGilbert08,BulucGilbert12}.  These are global
    options that modify all matrices created after calling this method.
    The global settings also control the number of threads used, and the
    heuristic for selecting the number of threads for small problems.

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

\item \verb'GxB_set (GrB_Descriptor desc, field, value)' is another way to
    set the value of a field in a \verb'GrB_Descriptor'.  It is identical to \\
    \verb'GrB_Descriptor_set', just with a generic name.

\end{itemize}

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

\begin{itemize}

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

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

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

\end{itemize}

%-------------------------------------------------------------------------------
\subsection{OpenMP parallelism}
%-------------------------------------------------------------------------------

SuiteSparse:GraphBLAS Version 3 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.

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

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

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

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

If this is done, and no other \verb'GxB_set' calls are made with
\verb'GxB_FORMAT', all matrices will be stored by column.  Alternatively,
SuiteSparse:GraphBLAS can be compiled with \verb'-DBYCOL', which changes the
default format to \verb'GxB_BY_COL', with no calls to any \verb'GxB_*'
function.  The default format is now \verb'GxB_BY_ROW'.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

This changes the matrix \verb'A' so that it is stored by row, and it is
converted from non-hypersparse to hypersparse format if it has fewer than 10\%
non-empty columns.  If it is hypersparse, it is a candidate for conversion to
non-hypersparse if has 20\% or more non-empty columns.  If it has between 10\%
and 20\% non-empty columns, it remains in 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, GxB_NEVER_HYPER) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
    // no subsequent use of GxB_HYPER or GxB_FORMAT
\end{verbatim} }

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

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

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

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

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

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

SuiteSparse:GraphBLAS multi-threaded, using only OpenMP for its internal
parallelism.  It is also thread-safe if it is compiled with OpenMP or POSIX
pthreads, and if the user application threads do not operate on the same
matrices at the same time.  The user threads may use OpenMP or POSIX pthreads.
If multiple user threads make simultaneous calls to GraphBLAS, then output
matrices and vectors used by different threads must be different, and input
matrices and vectors can be safely used only if any pending computations on
them have finished, via \verb'GrB_Matrix_wait', \verb'GrB_Vector_wait', or
\verb'GxB_Scalar_wait'.

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

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

The \verb'GxB_THREADING' option returns the internal parallelism used inside
SuiteSparse:GraphBLAS, depending on how the library was compiled:

{\footnotesize
\begin{verbatim}
    GxB_Thread_Model threading ;
    GxB_get (GxB_THREADING, &threading) ;
    if (threading == GxB_THREAD_NONE)
    {
        printf ("GraphBLAS is single-threaded, internally.\n") ;
    }
    else
    {
        printf ("GraphBLAS is multi-threaded, internally, using OpenMP.\n") ;
    }
\end{verbatim} }

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

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

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

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

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, and the chunk size to 10000.
No existing matrices are changed.

{\footnotesize
\begin{verbatim}
    GxB_set (GxB_HYPER, 0.2) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
    GxB_set (GxB_NTHREADS, 4) ;
    GxB_set (GxB_CHUNK, (double) 10000) ;
\end{verbatim} }

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

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

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

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

{\footnotesize
\begin{verbatim}
    GxB_set (A, GxB_HYPER, 0.2) ;
    GxB_set (A, GxB_FORMAT, GxB_BY_COL) ;
\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.

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

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

This usage is 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', or
\verb'GxB_CHUNK'.  Refer to Sections~\ref{descriptor_set}~and~\ref{desc_set}
for details.

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

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

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

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

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

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

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

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

%===============================================================================
\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', \verb'GxB_IS_HYPER',
or \verb'GxB_FORMAT'.
For example:

\vspace{-0.1in}
{\footnotesize
\begin{verbatim}
    double h ;
    bool is_hyper ;
    GxB_get (A, GxB_IS_HYPER, &is_hyper) ;
    GxB_get (A, GxB_HYPER, &h) ;
    printf ("matrix A has hyper_ratio = %g\n", h) ;
    printf ("matrix A is currently %shypersparse\n", is_hyper ? "not " : " ") ; 
    GxB_Format_Value s ;
    GxB_get (A, GxB_FORMAT, &s) ;
    printf ("matrix A is stored by %s\n", (s == GxB_BY_COL) ? "col" : "row") ; \end{verbatim} }

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

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_get                // get a parameter from a descriptor
(
    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', or \verb'GxB_CHUNK'.
Refer to Section~\ref{desc_get} for details.

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

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

\noindent
To set/get the global options:

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

    GxB_set (GxB_FORMAT, GxB_BY_ROW) ;
    GxB_set (GxB_FORMAT, GxB_BY_COL) ;
    GxB_get (GxB_FORMAT, GxB_Format_Value *s) ;

    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) ; \end{verbatim} }

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

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

\noindent
To set/get a matrix option:

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

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

\noindent
To get the hypersparse status of a matrix:

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

\newpage
\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_HEAP) ;
    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) ; \end{verbatim} }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

\end{enumerate}

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

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

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

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

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

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

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

\newpage
%===============================================================================
\subsection{{\sf GrB\_vxm:} vector-matrix multiply} %===========================
%===============================================================================
\label{vxm}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_vxm                    // w'<mask> = accum (w, u'*A)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GrB_Semiring semiring,    // defines '+' and '*' for u'*A
    const GrB_Vector u,             // first input:  vector u
    const GrB_Matrix A,             // second input: matrix A
    const GrB_Descriptor desc       // descriptor for w, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_vxm' multiplies a row vector \verb"u'" times a matrix \verb'A'.  The
matrix \verb'A' may be first transposed according to \verb'desc' (as the second
input, \verb'GrB_INP1'); the column vector \verb'u' is never transposed via the
descriptor.  The inputs \verb'u' and \verb'A' are typecasted to match the
\verb'xtype' and \verb'ytype' inputs, respectively, of the multiply operator of
the \verb'semiring'.  Next, an intermediate column vector \verb"t=A'*u" is
computed on the \verb'semiring' using the same method as \verb'GrB_mxm'.
Finally, the column vector \verb't' is typecasted from the \verb'ztype' of the
multiply operator of the \verb'semiring' into the type of \verb'w', and the
results are written back into \verb'w' using the optional accumulator
\verb'accum' and \verb'mask'.

The last step is ${\bf w \langle m \rangle  = w \odot t}$, as described
in Section~\ref{accummask}, except that all the
terms are column vectors instead of matrices.

\paragraph{\bf Performance considerations:} % u'=u'*A
If the \verb'GxB_FORMAT' of \verb'A' is \verb'GxB_BY_ROW', and the default
descriptor is used (\verb'A' is not transposed), then \verb'GrB_vxm' is faster
than than \verb'GrB_mxv' with its default descriptor, when the vector \verb'u'
is very sparse.
However, if the \verb'GxB_FORMAT' of \verb'A' is \verb'GxB_BY_COL', then
\verb'GrB_mxv' with its default descriptor is faster than \verb'GrB_vxm' with
its default descriptor, when the vector \verb'u' is very sparse.
Using the non-default \verb'GrB_TRAN' descriptor for \verb'A' makes the
\verb'GrB_vxm' operation equivalent to \verb'GrB_mxv' with its default
descriptor (with the operands reversed in the multiplier, as well).  The
reverse is true as well; \verb'GrB_mxv' with \verb'GrB_TRAN' is the same as
\verb'GrB_vxm' with a default descriptor.

The breadth-first search presented in Section~\ref{bfs} of this User Guide uses
\verb'GrB_vxm' instead of \verb'GrB_mxv', since the default format in
SuiteSparse:GraphBLAS is \verb'GxB_BY_ROW'.  If the matrix is stored by column,
then use \verb'GrB_mxv' instead.

\newpage
%===============================================================================
\subsection{{\sf GrB\_mxv:} matrix-vector multiply} %===========================
%===============================================================================
\label{mxv}

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

\verb'GrB_mxv' multiplies a matrix \verb'A' times a column vector \verb'u'.
The matrix \verb'A' may be first transposed according to \verb'desc' (as the
first input); the column vector \verb'u' is never transposed via the
descriptor.  The inputs \verb'A' and \verb'u' are typecasted to match the
\verb'xtype' and \verb'ytype' inputs, respectively, of the multiply operator of
the \verb'semiring'. Next, an intermediate column vector \verb't=A*u' is
computed on the \verb'semiring' using the same method as \verb'GrB_mxm'.
Finally, the column vector \verb't' is typecasted from the \verb'ztype' of the
multiply operator of the \verb'semiring' into the type of \verb'w', and the
results are written back into \verb'w' using the optional accumulator
\verb'accum' and \verb'mask'.

The last step is ${\bf w \langle m \rangle  = w \odot t}$, as described
in Section~\ref{accummask}, except that all the terms are column vectors instead
of matrices.

\paragraph{\bf Performance considerations:} % u=A*u
Refer to the discussion of \verb'GrB_vxm'.  In SuiteSparse:GraphBLAS,
\verb'GrB_mxv' is very efficient when \verb'u' is sparse or dense, when the
default descriptor is used, and when the matrix is \verb'GxB_BY_COL'.  When
\verb'u' is very sparse and \verb'GrB_INP0' is set to its non-default
\verb'GrB_TRAN', then this method is not efficient if the matrix is in
\verb'GxB_BY_COL' format.  If an application needs to perform \verb"A'*u"
repeatedly where \verb'u' is very sparse, then use the \verb'GxB_BY_ROW' format
for \verb'A' instead.

\newpage
%===============================================================================
\subsection{{\sf GrB\_eWiseMult:} element-wise operations, set intersection} %==
%===============================================================================
\label{eWiseMult}

Element-wise ``multiplication'' is shorthand for applying a binary operator
element-wise on two matrices or vectors \verb'A' and \verb'B', for all entries
that appear in the set intersection of the patterns of \verb'A' and \verb'B'.
This is like \verb'A.*B' for two sparse matrices in MATLAB, except that in
GraphBLAS any binary operator can be used, not just multiplication.

The pattern of the result of the element-wise ``multiplication'' is exactly
this set intersection.  Entries in \verb'A' but not \verb'B', or visa versa, do
not appear in the result.

Let $\otimes$ denote the binary operator to be used.  The computation ${\bf T =
A \otimes B}$ is given below.  Entries not in the intersection of ${\bf A}$ and
${\bf B}$ do not appear in the pattern of ${\bf T}$.  That is:
    \vspace{-0.2in}
    {\small
    \begin{tabbing}
    \hspace{2em} \= \hspace{2em} \= \hspace{2em} \= \\
    \> for all entries $(i,j)$ in ${\bf A \cap B}$ \\
    \> \> $t_{ij} = a_{ij} \otimes b_{ij}$ \\
    \end{tabbing} }
    \vspace{-0.2in}

Depending on what kind of operator is used and what the implicit value is
assumed to be, this can give the Hadamard product.  This is the case for
\verb'A.*B' in MATLAB since the implicit value is zero.  However, computing a
Hadamard product is not necessarily the goal of the \verb'eWiseMult' operation.
It simply applies any binary operator, built-in or user-defined, to the set
intersection of \verb'A' and \verb'B', and discards any entry outside this
intersection.  Its usefulness in a user's application does not depend upon it
computing a Hadamard product in all cases.  The operator need not be
associative, commutative, nor have any particular property except for type
compatibility with \verb'A' and \verb'B', and the output matrix \verb'C'.

The generic name for this operation is \verb'GrB_eWiseMult', which can be used
for both matrices and vectors.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_eWiseMult\_Vector:} element-wise vector multiply}
%-------------------------------------------------------------------------------
\label{eWiseMult_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_eWiseMult              // w<mask> = accum (w, u.*v)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const <operator> multiply,      // defines '.*' for t=u.*v
    const GrB_Vector u,             // first input:  vector u
    const GrB_Vector v,             // second input: vector v
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim}
} \end{mdframed}

\verb'GrB_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\_eWiseMult\_Matrix:} element-wise matrix multiply}
%-------------------------------------------------------------------------------
\label{eWiseMult_matrix}

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

\verb'GrB_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\_eWiseAdd\_Vector:} element-wise vector addition}
%-------------------------------------------------------------------------------
\label{eWiseAdd_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_eWiseAdd               // w<mask> = accum (w, u+v)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const <operator> add,           // defines '+' for t=u+v
    const GrB_Vector u,             // first input:  vector u
    const GrB_Vector v,             // second input: vector v
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_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\_eWiseAdd\_Matrix:} element-wise matrix addition}
%-------------------------------------------------------------------------------
\label{eWiseAdd_matrix}

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

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

\begin{spec}
{\bf SPEC:} All variants of \verb'GxB_subassign' are extensions to the spec.
\end{spec}

%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_subassign:} assign to a subvector }
%-------------------------------------------------------------------------------
\label{subassign_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // w(I)<mask> = accum (w(I),u)
(
    GrB_Vector w,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for w(I), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),t)
    const GrB_Vector u,             // first input:  vector u
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w(I) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_subassign' operates on a subvector \verb'w(I)' of \verb'w',
modifying it with the vector \verb'u'.  The method is identical to
\verb'GxB_Matrix_subassign' described in Section~\ref{subassign_matrix}, where
all matrices have a single column each.  The \verb'mask' has the same size as
\verb'w(I)' and \verb'u'.  The only other difference is that the input \verb'u'
in this method is not transposed via the \verb'GrB_INP0' descriptor.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_subassign:} assign to a submatrix }
%-------------------------------------------------------------------------------
\label{subassign_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_subassign              // C(I,J)<Mask> = accum (C(I,J),A)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C(I,J), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C(I,J),T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(I,J), Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_subassign' operates only on a submatrix \verb'S' of \verb'C',
modifying it with the matrix \verb'A'.   For this operation, the result is not
the entire matrix \verb'C', but a submatrix \verb'S=C(I,J)' of \verb'C'.  The
steps taken are as follows, except that ${\bf A}$ may be optionally transposed
via the \verb'GrB_INP0' descriptor option.

\vspace{0.1in}
\begin{tabular}{lll}
\hline
Step & GraphBLAS & description \\
     & notation  & \\
\hline
1 & ${\bf S} = {\bf C(I,J)}$                             & extract the ${\bf C(I,J)}$ submatrix \\
2 & ${\bf S \langle M \rangle} = {\bf S} \odot {\bf A}$  & apply the accumulator/mask to the submatrix ${\bf S}$\\
3 & ${\bf C(I,J)}= {\bf S}$                              & put the submatrix ${\bf S}$ back into ${\bf C(I,J)}$ \\
\hline
\end{tabular}
\vspace{0.1in}

The accumulator/mask step in Step 2 is the same as for all other GraphBLAS
operations, described in Section~\ref{accummask}, except that for
\verb'GxB_subassign', it is applied to just the submatrix ${\bf S} = {\bf
C(I,J)}$, and thus the \verb'Mask' has the same size as ${\bf A}$,
${\bf S}$, and ${\bf C(I,J)}$.

The \verb'GxB_subassign' operation is the reverse of matrix extraction:

\begin{itemize}
\item
For submatrix extraction, \verb'GrB_Matrix_extract',
the submatrix \verb'A(I,J)' appears on the right-hand side of the assignment,
\verb'C=A(I,J)', and entries outside of the submatrix are not accessed and do
not take part in the computation.

\item
For submatrix assignment, \verb'GxB_Matrix_subassign',
the submatrix \verb'C(I,J)' appears on the left-hand-side of the assignment,
\verb'C(I,J)=A', and entries outside of the submatrix are not accessed and do
not take part in the computation.

\end{itemize}

In both methods, the accumulator and mask modify the submatrix of the
assignment; they simply differ on which side of the assignment the submatrix
resides on.  In both cases, if the \verb'Mask' matrix is present it is the same
size as the submatrix:

\begin{itemize}

\item
For submatrix extraction,
${\bf C \langle M \rangle = C \odot A(I,J)}$ is computed,
where the submatrix is on the right.
The mask ${\bf M}$ has the same size as the submatrix ${\bf A(I,J)}$.

\item
For submatrix assignment,
${\bf C(I,J) \langle M \rangle = C(I,J) \odot A}$ is computed,
where the submatrix is on the left.
The mask ${\bf M}$ has the same size as the submatrix ${\bf C(I,J)}$.

\end{itemize}

In Step 1, the submatrix \verb'S' is first computed by the
\verb'GrB_Matrix_extract' operation, \verb'S=C(I,J)'.

Step 2 accumulates the results ${\bf S \langle M \rangle  = S \odot T}$,
exactly as described in Section~\ref{accummask}, but operating on the submatrix
${\bf S}$, not ${\bf C}$, using the optional \verb'Mask' and \verb'accum'
operator.  The matrix ${\bf T}$ is simply ${\bf T}={\bf A}$, or ${\bf T}={\bf
A}^{\sf T}$ if ${\bf A}$ is transposed via the \verb'desc' descriptor,
\verb'GrB_INP0'.  The \verb'GrB_REPLACE' option in the descriptor clears ${\bf
S}$ after computing ${\bf Z = T}$ or ${\bf Z = C \odot T}$, not all of ${\bf
C}$ since this operation can only modify the specified submatrix of ${\bf C}$.

Finally, Step 3 writes the result (which is the modified submatrix \verb'S' and
not all of \verb'C') back into the \verb'C' matrix that contains it, via the
assignment \verb'C(I,J)=S', using the reverse operation from the method
described for matrix extraction:

    {\footnotesize
    \begin{verbatim}
    for i = 1:ni
        for j = 1:nj
            if (S (i,j).pattern)
                C (I(i),J(j)).matrix = S (i,j).matrix ;
                C (I(i),J(j)).pattern = true ;
            end
        end
    end \end{verbatim}}

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

\paragraph{\bf Performance considerations:} % C(I,J) = scalar
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%===============================================================================
\subsection{{\sf GrB\_assign:} submatrix assignment} %==========================
%===============================================================================
\label{assign}

The methods described in this section are all variations of the form
\verb'C(I,J)=A', which modifies a submatrix of the matrix \verb'C'.  All
methods can be used in their generic form with the single name
\verb'GrB_assign'.  These methods are very similar to their
\verb'GxB_subassign' counterparts in Section~\ref{subassign}.  They differ
primarily in the size of the \verb'Mask', and how the \verb'GrB_REPLACE' option
works.  Refer to Section~\ref{compare_assign} for a complete comparison of
\verb'GxB_subassign' and \verb'GrB_assign'.

See Section~\ref{colon} for a description of
\verb'I', \verb'ni', \verb'J', and \verb'nj'.

%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_assign:} assign to a subvector }
%-------------------------------------------------------------------------------
\label{assign_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // w<mask>(I) = accum (w(I),u)
(
    GrB_Vector w,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),t)
    const GrB_Vector u,             // first input:  vector u
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_assign' operates on a subvector \verb'w(I)' of \verb'w',
modifying it with the vector \verb'u'.  The \verb'mask' vector has the same
size as \verb'w'.  The method is identical to \verb'GrB_Matrix_assign'
described in Section~\ref{assign_matrix}, where all matrices have a single
column each.  The only other difference is that the input \verb'u' in this
method is not transposed via the \verb'GrB_INP0' descriptor.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_assign:} assign to a submatrix }
%-------------------------------------------------------------------------------
\label{assign_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<Mask>(I,J) = accum (C(I,J),A)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C(I,J),T)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C, Mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_assign' operates on a submatrix \verb'S' of \verb'C',
modifying it with the matrix \verb'A'.  It may also modify all of \verb'C',
depending on the input descriptor \verb'desc' and the \verb'Mask'.

\vspace{0.1in}
\begin{tabular}{lll}
\hline
Step & GraphBLAS & description \\
     & notation  & \\
\hline
1 & ${\bf S} = {\bf C(I,J)}$                & extract ${\bf C(I,J)}$ submatrix \\
2 & ${\bf S} = {\bf S} \odot {\bf A}$       & apply the accumulator (but not the mask) to ${\bf S}$\\
3 & ${\bf Z} = {\bf C}$                     & make a copy of ${\bf C}$ \\
4 & ${\bf Z(I,J)} = {\bf S}$                & put the submatrix into ${\bf Z(I,J)}$ \\
5 & ${\bf C \langle M \rangle = Z}$         & apply the mask/replace phase to all of ${\bf C}$ \\
\hline
\end{tabular}
\vspace{0.1in}

In contrast to \verb'GxB_subassign', the \verb'Mask' has the same as \verb'C'.

Step 1 extracts the submatrix and then Step 2 applies the accumulator
(or ${\bf S}={\bf A}$ if \verb'accum' is \verb'NULL').  The \verb'Mask' is
not yet applied.

Step 3 makes a copy of the ${\bf C}$ matrix, and then Step 4 writes the
submatrix ${\bf S}$ into ${\bf Z}$.  This is the same as Step 3 of
\verb'GxB_subassign', except that it operates on a temporary matrix ${\bf Z}$.

Finally, Step 5 writes ${\bf Z}$ back into ${\bf C}$ via the \verb'Mask', using
the Mask/Replace Phase described in Section~\ref{accummask}.  If
\verb'GrB_REPLACE' is enabled, then all of ${\bf C}$ is cleared prior to
writing ${\bf Z}$ via the mask.  As a result, the \verb'GrB_REPLACE' option can
delete entries outside the ${\bf C(I,J)}$ submatrix.

\paragraph{\bf Performance considerations:} % C(I,J) = A
If \verb'A' is not transposed: if \verb'|I|' is small, then it is fastest if
the format of \verb'C' is \verb'GxB_BY_ROW'; if \verb'|J|' is small, then it is
fastest if the format of \verb'C' is \verb'GxB_BY_COL'.  The opposite is true
if \verb'A' is transposed.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Col\_assign:} assign to a sub-column of a matrix}
%-------------------------------------------------------------------------------
\label{assign_column}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<mask>(I,j) = accum (C(I,j),u)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(:,j), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(I,j),t)
    const GrB_Vector u,             // input vector
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Index j,              // column index
    const GrB_Descriptor desc       // descriptor for C(:,j) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Col_assign' modifies a single sub-column of a matrix \verb'C'.  It is
the same as \verb'GrB_Matrix_assign' where the index vector \verb'J[0]=j' is a
single column index, and where all matrices in \verb'GrB_Matrix_assign' (except
\verb'C') consist of a single column.

Unlike \verb'GrB_Matrix_assign', the \verb'mask' is a vector with the same size
as a single column of \verb'C'.

The input descriptor \verb'GrB_INP0' is ignored; the input vector \verb'u' is
not transposed.  Refer to \verb'GrB_Matrix_assign' for further details.

\paragraph{\bf Performance considerations:} % C(I,j) = u
\verb'GrB_Col_assign' is much faster than \verb'GrB_Row_assign' if the format
of \verb'C' is \verb'GxB_BY_COL'.  \verb'GrB_Row_assign' is much faster than
\verb'GrB_Col_assign' if the format of \verb'C' is \verb'GxB_BY_ROW'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Row\_assign:} assign to a sub-row of a matrix}
%-------------------------------------------------------------------------------
\label{assign_row}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // C<mask'>(i,J) = accum (C(i,J),u')
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Vector mask,          // optional mask for C(i,:), unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(C(i,J),t)
    const GrB_Vector u,             // input vector
    const GrB_Index i,              // row index
    const GrB_Index *J,             // column indices
    const GrB_Index nj,             // number of column indices
    const GrB_Descriptor desc       // descriptor for C(i,:) and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Row_subassign' modifies a single sub-row of a matrix \verb'C'.  It is
the same as \verb'GxB_Matrix_subassign' where the index vector \verb'I[0]=i' is
a single row index, and where all matrices in \verb'GxB_Matrix_subassign'
(except \verb'C') consist of a single row.

Unlike \verb'GrB_Matrix_assign', the \verb'mask' is a vector with the same size
as a single row of \verb'C'.

The input descriptor \verb'GrB_INP0' is ignored; the input vector \verb'u' is
not transposed.  Refer to \verb'GxB_Matrix_subassign' for further details.

\paragraph{\bf Performance considerations:} % C(i,J) = u'
\verb'GrB_Col_assign' is much faster than \verb'GrB_Row_assign' if the format
of \verb'C' is \verb'GxB_BY_COL'.  \verb'GrB_Row_assign' is much faster than
\verb'GrB_Col_assign' if the format of \verb'C' is \verb'GxB_BY_ROW'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_assign\_$<$type$>$:} assign a scalar to a subvector}
%-------------------------------------------------------------------------------
\label{assign_vector_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_assign                 // w<mask>(I) = accum (w(I),x)
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w(I),x)
    const <type> x,                 // scalar to assign to w(I)
    const GrB_Index *I,             // row indices
    const GrB_Index ni,             // number of row indices
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_assign_<type>' assigns a single scalar to an entire subvector
of the vector \verb'w'.  The operation is exactly like setting a single entry
in an \verb'n'-by-1 matrix, \verb'A(I,0) = x', where the column index for a
vector is implicitly \verb'j=0'.  The \verb'mask' vector has the same size as
\verb'w'.  For further details of this function, see
\verb'GrB_Matrix_assign_<type>' in the next section.

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.

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 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 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{spec}
{\bf SPEC:} Providing a well-defined behavior for duplicate
indices with matrix and vector assignment is an extension to the spec.
The spec only defines the behavior when assigning a scalar into a matrix
or vector, and states that duplicate indices otherwise lead to undefined
results.
\end{spec}



\newpage
%===============================================================================
\subsection{Comparing {\sf GrB\_assign} and {\sf GxB\_subassign}} %=============
%===============================================================================
\label{compare_assign}

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

The \verb'GxB_subassign' and \verb'GrB_assign' operations are very similar, but
they differ in 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    &   \\
\hline
    yes&-   & $c_{ij}$ & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, update \\
    yes&-   &  -       & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, insert \\
    yes&-   & $c_{ij}$ &  -          & 1    &  delete $c_{ij}$ because $a_{i'j'}$ not present \\
    yes&-   &  -       &  -          & 1    &   \\
\hline
    -  &yes & $c_{ij}$ & $a_{i'j'}$  & 1    &  $c_{ij} = c_{ij} \odot a_{i'j'}$, apply accumulator \\
    -  &yes &  -       & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, insert \\
    -  &yes & $c_{ij}$ &  -          & 1    &   \\
    -  &yes &  -       &  -          & 1    &   \\
\hline
    yes&yes & $c_{ij}$ & $a_{i'j'}$  & 1    &  $c_{ij} = c_{ij} \odot a_{i'j'}$, apply accumulator \\
    yes&yes &  -       & $a_{i'j'}$  & 1    &  $c_{ij} = a_{i'j'}$, insert \\
    yes&yes & $c_{ij}$ &  -          & 1    &   \\
    yes&yes &  -       &  -          & 1    &   \\
\hline
\hline
    -  &-   & $c_{ij}$ & $a_{i'j'}$  & 0    &   \\
    -  &-   &  -       & $a_{i'j'}$  & 0    &   \\
    -  &-   & $c_{ij}$ &  -          & 0    &   \\
    -  &-   &  -       &  -          & 0    &   \\
\hline
    yes&-   & $c_{ij}$ & $a_{i'j'}$  & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&-   &  -       & $a_{i'j'}$  & 0    &   \\
    yes&-   & $c_{ij}$ &  -          & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&-   &  -       &  -          & 0    &   \\
\hline
    -  &yes & $c_{ij}$ & $a_{i'j'}$  & 0    &   \\
    -  &yes &  -       & $a_{i'j'}$  & 0    &   \\
    -  &yes & $c_{ij}$ &  -          & 0    &   \\
    -  &yes &  -       &  -          & 0    &   \\
\hline
    yes&yes & $c_{ij}$ & $a_{i'j'}$  & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&yes &  -       & $a_{i'j'}$  & 0    &   \\
    yes&yes & $c_{ij}$ &  -          & 0    &  delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
    yes&yes &  -       &  -          & 0    &   \\
\hline
\end{tabular}
}
\caption{Results of assign and subassign for entries in the ${\bf C(I,J)}$ submatrix \label{insubmatrix}}
\end{table}

\newpage
Table~\ref{outsubmatrix} illustrates how \verb'GrB_assign' and
\verb'GxB_subassign' differ for entries outside the submatrix.
\verb'GxB_subassign' never modifies any entry outside the ${\bf C(I,J)}$
submatrix, but \verb'GrB_assign' can modify them in two cases listed in
Table~\ref{outsubmatrix}.  When the \verb'GrB_REPLACE' option is selected, and
when the \verb'Mask(i,j)' for an entry $c_{ij}$ is false (or if the
\verb'Mask(i,j)' is true and \verb'GrB_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 &  \\
\hline
   yes &  -   & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   yes &  -   &    -     &     -    & 1 &  \\
\hline
   -   &yes   & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   -   &yes   &    -     &  -       & 1 &  \\
\hline
   yes &  yes & $c_{ij}$ & $c_{ij}$ & 1 &  \\
   yes &  yes &   -      &  -       & 1 &  \\
\hline
\hline
   -   &-     & $c_{ij}$ & $c_{ij}$ & 0 &  \\
   -   &-     &  -       & -        & 0 &  \\
\hline
   yes &  -   & $c_{ij}$ & $c_{ij}$ & 0 & delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
   yes &  -   &    -     &  -       & 0 &  \\
\hline
   -   &yes   & $c_{ij}$ & $c_{ij}$ & 0 &  \\
   -   &yes   &    -     &  -       & 0 &  \\
\hline
   yes &  yes & $c_{ij}$ & $c_{ij}$ & 0 & delete $c_{ij}$  (because of \verb'GrB_REPLACE') \\
   yes &  yes &   -      &  -       & 0 &  \\
\hline
\end{tabular}
}
\caption{Results of assign for entries outside the
${\bf C(I,J)}$ submatrix.  Subassign has no effect on these entries. \label{outsubmatrix}}
\end{table}

%-------------------------------------------------------------------------------
\subsubsection{Example}
%-------------------------------------------------------------------------------

The difference between \verb'GxB_subassign' and \verb'GrB_assign' is
illustrated in the following example.  Consider the 2-by-2 matrix ${\bf C}$
where all entries are present.

\[
{\bf C} = \left[
    \begin{array}{rr}
    11 & 12 \\
    21 & 22 \\
    \end{array}
    \right]
\]

Suppose \verb'GrB_REPLACE' is true, and \verb'GrB_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 500x faster than MATLAB
R2019b, or even higher depending on the kind of matrix assignment.
MATLAB logical indexing (the mask of GraphBLAS) is much faster with
GraphBLAS than in MATLAB R2019b; differences of up to 100,000x have been
observed.

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 or binary operator} %===============
%===============================================================================
\label{apply}

\verb'GrB_apply' is the generic name for 62 specific functions.
\verb'GrB_Vector_apply' and \verb'GrB_Matrix_apply' apply a unary operator to
the entries of a matrix.  \verb'GrB_*_apply_BinaryOp1st*' applies a binary
operator where a single scalar is provided as the $x$ input to the binary
operator.  \verb'GrB_*_apply_BinaryOp2nd*' applies a binary operator where a
single scalar is provided as the $y$ input to the binary operator.  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.  It is otherwise identical to \verb'GrB_Vector_apply'.  With no
suffix, \verb'GxB_Vector_apply_BinaryOp1st' takes as input a \verb'GxB_Scalar'. 

%===============================================================================
\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.  It is otherwise identical to \verb'GrB_Vector_apply'.  With no
suffix, \verb'GxB_Vector_apply_BinaryOp2nd' takes as input a \verb'GxB_Scalar'. 

\newpage
%===============================================================================
\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.  It is otherwise identical to \verb'GrB_Matrix_apply'.  With no
suffix, \verb'GxB_Matrix_apply_BinaryOp1st' takes as input a \verb'GxB_Scalar'. 
To transpose the input matrix, use the \verb'GrB_INP0' descriptor setting.

%===============================================================================
\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.  It is otherwise identical to \verb'GrB_Matrix_apply'.  With no
suffix, \verb'GxB_Matrix_apply_BinaryOp2nd' takes as input a \verb'GxB_Scalar'. 
To transpose the input matrix, use the \verb'GrB_INP1' descriptor setting.

\newpage
%===============================================================================
\subsection{{\sf GxB\_select:} apply a select operator} %=======================
%===============================================================================
\label{select}

The \verb'GxB_select' function is the generic name for two specific functions:
\\ \verb'GxB_Vector_select' and  \verb'GxB_Matrix_select'.  The generic name
appears in the function prototypes, but the specific function name is used when
describing each variation.  When discussing features that apply to both
versions, the simple name \verb'GxB_select' is used.

\begin{spec}
{\bf SPEC:} The \verb'GxB_select' operation and \verb'GxB_SelectOp' operator
are extensions to the spec.
\end{spec}

% \newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Vector\_select:} apply a select operator to a vector}
%-------------------------------------------------------------------------------
\label{select_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_select                 // w<mask> = accum (w, op(u,k))
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const GxB_SelectOp op,          // operator to apply to the entries
    const GrB_Vector u,             // first input:  vector u
    const GxB_Scalar Thunk,         // optional input for the select operator
    const GrB_Descriptor desc       // descriptor for w and mask
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Vector_select' applies a select operator to the entries of a vector,
analogous to \verb't = u.*op(u)'  in MATLAB except the operator \verb'op' is
only applied to entries in the pattern of \verb'u'.  Implicit values outside
the pattern of \verb'u' are not affected.  If the operator is not type-generic,
the entries in \verb'u' are typecasted into the \verb'xtype' of the select
operator.  The vector \verb't' has the same type and size as \verb'u'.  The
final step is ${\bf w \langle m \rangle  = w \odot t}$, as described in
Section~\ref{accummask}, except that all the terms are column vectors instead
of matrices.

This operation operates on vectors just as if they were \verb'm'-by-1 matrices,
except that GraphBLAS never transposes a vector via the descriptor.  The
\verb'op' is passed \verb'n=1' as the number of columns.  Refer to the next
section on \verb'GxB_Matrix_select' for more details.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GxB\_Matrix\_select:} apply a select operator to a matrix}
%-------------------------------------------------------------------------------
\label{select_matrix}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_select                 // C<Mask> = accum (C, op(A,k)) or op(A',k)
(
    GrB_Matrix C,                   // input/output matrix for results
    const GrB_Matrix Mask,          // optional mask for C, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for Z=accum(C,T)
    const GxB_SelectOp op,          // operator to apply to the entries
    const GrB_Matrix A,             // first input:  matrix A
    const GxB_Scalar Thunk,         // optional input for the select operator
    const GrB_Descriptor desc       // descriptor for C, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GxB_Matrix_select' applies a select operator to the entries of a matrix,
analogous to \verb'T = A .* op(A)'  in MATLAB except the operator \verb'op' is
only applied to entries in the pattern of \verb'A'.  Implicit values outside
the pattern of \verb'A' are not affected.  The input matrix \verb'A' may be
transposed first.  If the operator is not type-generic, the entries in \verb'A'
are typecasted into the \verb'xtype' of the select operator.  The final step is
${\bf C \langle M \rangle  = C \odot T}$, as described in
Section~\ref{accummask}.

The matrix \verb'T' has the same size and type as \verb'A' (or the transpose of
\verb'A' if the input is transposed via the descriptor).  The entries of
\verb'T' are a subset of those of \verb'A'.  Each entry \verb'A(i,j)' of
\verb'A' is passed to the \verb'op', as $z=f(i,j,m,n,a_{ij},\mbox{thunk})$,
where \verb'A' is $m$-by-$n$.  If \verb'A' is transposed first then the
operator is applied to entries in the transposed matrix, \verb"A'".  If $z$ is
returned as true, then the entry is copied into \verb'T', unchanged.  If it
returns false, the entry does not appear in \verb'T'.

If \verb'Thunk' is not \verb'NULL', it must be a valid \verb'GxB_Scalar'.
If it has no entry, it is treated as if it had a single entry equal to zero,
for built-in types (not user-defined types).

For user-defined select operators, the entry
is passed to the user-defined select operator, with no typecasting.
Its type must be identical to  \verb'ttype' of the select operator.

For the \verb'GxB_TRIL', \verb'GxB_TRIU', \verb'GxB_DIAG', and
\verb'GxB_OFFDIAG', the \verb'Thunk' parameter may be \verb'NULL', or it may be
present but contain no entry.  In this case, these operators use the value of
\verb'k=0', the main diagonal.  If present, the \verb'Thunk' can be any
built-in type.  The value of this entry is typecasted:
\verb'k = (int64_t) Thunk'.  The value \verb'k=0' specifies the main
diagonal of the matrix, \verb'k=1' is the +1 diagonal (the entries just above
the main diagonal), \verb'k=-1' is the -1 diagonal, and so on.

For the \verb'GxB_*ZERO' select operators, \verb'Thunk' is ignored, and may be
\verb'NULL'.  For built-in types, with the \verb'GxB_*THUNK' operators, the
value of \verb'Thunk' is typecasted to the same type as the \verb'A' matrix.
For user-defined types, \verb'Thunk' is passed to the select operator without
typecasting.

The action of \verb'GxB_select' with the built-in select operators is described
in the table below.  The MATLAB analogs are precise for \verb'tril' and
\verb'triu', but shorthand for the other operations.  The MATLAB \verb'diag'
function returns a column with the diagonal, if \verb'A' is a matrix, whereas
the matrix \verb'T' in \verb'GxB_select' always has 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'GxB_select',
where \verb'T' is a matrix.

The following operators may be used on matrices with a user-defined type:
\verb'GxB_TRIL',
\verb'GxB_TRIU',
\verb'GxB_DIAG',
\verb'GxB_OFFIAG',
\verb'GxB_NONZERO',
\verb'GxB_EQ_ZERO',
\verb'GxB_NE_THUNK',
and
\verb'GxB_EQ_THUNK'.

The comparators \verb'GxB_GT_*' \verb'GxB_GE_*' \verb'GxB_LT_*', and
\verb'GxB_LE_*' only work for built-in types.  All other built-in select
operators can be used for any type, both built-in and any user-defined type.

{\bf NOTE:} For floating-point values, comparisons with \verb'NaN' always return
false.  The built-in select operators should not be used with a scalar
\verb'thunk' 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}
{\small
\begin{tabular}{llp{3in}}
\hline
GraphBLAS               & MATLAB            & \\
name                    & analog            & \\
\hline
\verb'GxB_TRIL'         & \verb'T=tril(A,k)'   &
    Entries in \verb'T' are the entries on and below the \verb'k'th diagonal of \verb'A'. \\
\verb'GxB_TRIU'         & \verb'T=triu(A,k)'   &
    Entries in \verb'T' are the entries on and above the \verb'k'th diagonal of \verb'A'. \\
\verb'GxB_DIAG'         & \verb'T=diag(A,k)'   &
    Entries in \verb'T' are the entries on the \verb'k'th diagonal of \verb'A'. \\
\verb'GxB_OFFDIAG'      & \verb'T=A-diag(A,k)' &
    Entries in \verb'T' are all entries not on the \verb'k'th diagonal of \verb'A'. \\
\hline
\verb'GxB_NONZERO'      & \verb'T=A(A~=0)'     &
    Entries in \verb'T' are all entries in \verb'A' that have nonzero value. \\
\verb'GxB_EQ_ZERO'      & \verb'T=A(A==0)'     &
    Entries in \verb'T' are all entries in \verb'A' that are equal to zero. \\
\verb'GxB_GT_ZERO'      & \verb'T=A(A>0)'      &
    Entries in \verb'T' are all entries in \verb'A' that are greater than zero. \\
\verb'GxB_GE_ZERO'      & \verb'T=A(A<=0)'     &
    Entries in \verb'T' are all entries in \verb'A' that are greater than or equal to zero. \\
\verb'GxB_LT_ZERO'      & \verb'T=A(A<0)'      &
    Entries in \verb'T' are all entries in \verb'A' that are less than zero. \\
\verb'GxB_LE_ZERO'      & \verb'T=A(A<=0)'     &
    Entries in \verb'T' are all entries in \verb'A' that are less than or equal to zero. \\
\hline
\verb'GxB_NE_THUNK'     & \verb'T=A(A~=k)'     &
    Entries in \verb'T' are all entries in \verb'A' that are not equal to \verb'k'. \\
\verb'GxB_EQ_THUNK'     & \verb'T=A(A==k)'     &
    Entries in \verb'T' are all entries in \verb'A' that are equal to \verb'k'. \\
\verb'GxB_GT_THUNK'     & \verb'T=A(A>k)'      &
    Entries in \verb'T' are all entries in \verb'A' that are greater than \verb'k'. \\
\verb'GxB_GE_THUNK'     & \verb'T=A(A>=k)'     &
    Entries in \verb'T' are all entries in \verb'A' that are greater than or equal to \verb'k'. \\
\verb'GxB_LT_THUNK'     & \verb'T=A(A<k)'      &
    Entries in \verb'T' are all entries in \verb'A' that are less than \verb'k'. \\
\verb'GxB_LE_THUNK'     & \verb'T=A(A<=k)'     &
    Entries in \verb'T' are all entries in \verb'A' that are less than or equal to \verb'k'. \\
\hline
\end{tabular}
}
\vspace{0.2in}

\newpage
%===============================================================================
\subsection{{\sf GrB\_reduce:} reduce to a vector or scalar} %==================
%===============================================================================
\label{reduce}

The generic function name \verb'GrB_reduce' may be used for all specific
functions discussed in this section.  When the details of a specific function
are discussed, the specific name is used for clarity.


%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_reduce\_$<$op$>$:} reduce a matrix to a vector}
%-------------------------------------------------------------------------------
\label{reduce_to_vector}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_reduce                 // w<mask> = accum (w,reduce(A))
(
    GrB_Vector w,                   // input/output vector for results
    const GrB_Vector mask,          // optional mask for w, unused if NULL
    const GrB_BinaryOp accum,       // optional accum for z=accum(w,t)
    const <operator> reduce,        // reduce operator for t=reduce(A)
    const GrB_Matrix A,             // first input:  matrix A
    const GrB_Descriptor desc       // descriptor for w, mask, and A
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_reduce_<op>' is a generic name for two specific methods.  Both
methods reduce a matrix to a column vector using an operator, roughly analogous
to \verb"t = sum (A')" in MATLAB, in the default case, where \verb't' is a
column vector.  By default, the method reduces across the rows to
obtain a column vector; use \verb'GrB_TRAN' to reduce down the columns.

\verb'GrB_Matrix_reduce_BinaryOp' relies on a binary operator for the
reduction: the fourth argument \verb'reduce', a \verb'GrB_BinaryOp'.  All three
domains of the operator must be the same.  \verb'GrB_Matrix_reduce_Monoid'
performs the same reduction using a \verb'GrB_Monoid' as its fourth argument.
In both cases the reduction operator must be commutative and associative.
Otherwise the results are undefined.

The input matrix \verb'A' may be transposed first.  Its entries are then
typecast into the type of the \verb'reduce' operator or monoid.  The reduction
is applied to all entries in \verb'A (i,:)' to produce the scalar \verb't (i)'.
This is done without the use of the identity value of the monoid.  If the
\verb'i'th row \verb'A (i,:)' has no entries, then \verb'(i)' is not an entry
in \verb't' and its value is implicit.  If \verb'A (i,:)' has a single entry,
then that is the result \verb't (i)' and \verb'reduce' is not applied at all
for the \verb'i'th row.  Otherwise, multiple entries in row \verb'A (i,:)' are
reduced via the \verb'reduce' operator or monoid to obtain a single scalar,
the result \verb't (i)'.

The final step is ${\bf w \langle m \rangle  = w \odot t}$, as described
in Section~\ref{accummask}, except that all the
terms are column vectors instead of matrices.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Vector\_reduce\_$<$type$>$:} reduce a vector to a scalar}
%-------------------------------------------------------------------------------
\label{reduce_vector_to_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_reduce                 // c = accum (c, reduce_to_scalar (u))
(
    <type> *c,                      // result scalar
    const GrB_BinaryOp accum,       // optional accum for c=accum(c,t)
    const GrB_Monoid monoid,        // monoid to do the reduction
    const GrB_Vector u,             // vector to reduce
    const GrB_Descriptor desc       // descriptor (currently unused)
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Vector_reduce_<type>'
reduces a vector to a scalar, analogous to \verb't = sum (u)' in MATLAB,
except that in GraphBLAS any commutative and associative monoid can be used
in the reduction.

% There is no mask since the output is a mere scalar, not a GraphBLAS vector or
% matrix.  The result does not depend on whether or not the input can be
% transposed (and vectors cannot be transposed in any case).  The
% \verb'replace' option is not implemented for this function.  Thus, no
% parameters from the descriptor are used.

The reduction operator is a commutative and associative monoid with an identity
value.  Results are undefined if the monoid does not have these properties.
This function differs from \verb'GrB_Matrix_reduce_BinaryOp' (which reduces
a matrix to a vector) in that it requires a
valid monoid additive identity value.  If the vector \verb'u' has no entries,
that identity value is copied into the scalar \verb't'.  Otherwise, all of the
entries in the vector are reduced to a single scalar using the \verb'reduce'
operator.

The scalar type is any of the built-in types, or a user-defined type.  In the
function signature it is a C type: \verb'bool', \verb'int8_t', ...
\verb'float', \verb'double', or \verb'void *' for a user-defined type.
The user-defined type must be identical to the type of the vector \verb'u'.
This cannot be checked by GraphBLAS and thus results are undefined if the
types are not the same.

The descriptor is unused, but it appears in case it is needed in future
versions of the GraphBLAS API.
This function has no mask so its accumulator/mask step differs from the other
GraphBLAS operations.  It does not use the methods described in
Section~\ref{accummask}, but uses the following method instead.

If \verb'accum' is \verb'NULL', then the scalar \verb't' is typecast into the
type of \verb'c', and \verb'c = t' is the final result.  Otherwise, the scalar
\verb't' is typecast into the \verb'ytype' of the \verb'accum' operator, and
the value of \verb'c' (on input) is typecast into the \verb'xtype' of the
\verb'accum' operator.  Next, the scalar \verb'z = accum (c,t)' is computed, of
the \verb'ztype' of the \verb'accum' operator.  Finally, \verb'z' is typecast
into the final result, \verb'c'.

\newpage
%-------------------------------------------------------------------------------
\subsubsection{{\sf GrB\_Matrix\_reduce\_$<$type$>$:} reduce a matrix to a scalar}
%-------------------------------------------------------------------------------
\label{reduce_matrix_to_scalar}

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GrB_reduce                 // c = accum (c, reduce_to_scalar (A))
(
    <type> *c,                      // result scalar
    const GrB_BinaryOp accum,       // optional accum for c=accum(c,t)
    const GrB_Monoid monoid,        // monoid to do the reduction
    const GrB_Matrix A,             // matrix to reduce
    const GrB_Descriptor desc       // descriptor (currently unused)
) ;
\end{verbatim} } \end{mdframed}

\verb'GrB_Matrix_reduce_<type>' reduces a matrix \verb'A' to a scalar, roughly
analogous to \verb't = sum (A (:))' in MATLAB.  This function is identical to
reducing a vector to a scalar, since the positions of the entries in a matrix
or vector have no effect on the result.  Refer to the reduction to scalar
described in the previous Section~\ref{reduce_vector_to_scalar}.

\newpage
%===============================================================================
\subsection{{\sf GrB\_transpose:} transpose a matrix} %=========================
%===============================================================================
\label{transpose}

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

\verb'GrB_transpose'
transposes a matrix \verb'A', just like the array transpose \verb"T = A.'" in
MATLAB.  The internal result matrix \verb"T = A'" (or merely \verb"T = A" if
\verb'A' is transposed via the descriptor) has the same type as \verb'A'.  The
final step is ${\bf C \langle M \rangle  = C \odot T}$, as described in
Section~\ref{accummask}, which typecasts \verb'T' as needed and applies the
mask and accumulator.

To be consistent with the rest of the GraphBLAS API regarding the
descriptor, the input matrix \verb'A' may be transposed first.  It may seem
counter-intuitive, but this has the effect of not doing any transpose at all.
As a result, \verb'GrB_transpose' is useful for more than just transposing a
matrix.  It can be used as a direct interface to the accumulator/mask
operation, ${\bf C \langle M \rangle  = C \odot A}$.  This step also does any
typecasting needed, so \verb'GrB_transpose' can be used to typecast a matrix
\verb'A' into another matrix \verb'C'.  To do this, simply use \verb'NULL' for
the \verb'Mask' and \verb'accum', and provide a non-default descriptor
\verb'desc' that sets the transpose option:

    {\footnotesize
    \begin{verbatim}
    // C = typecasted copy of A
    GrB_Descriptor_set (desc, GrB_INP0, GrB_TRAN) ;
    GrB_transpose (C, NULL, NULL, A, desc) ; \end{verbatim}}

If the types of \verb'C' and \verb'A' match,
then the above two lines of code are the
same as \verb'GrB_Matrix_dup (&C, A)', except that for \verb'GrB_transpose' the
matrix \verb'C' must already exist and be the right size.  If \verb'C' does not
exist, the work of \verb'GrB_Matrix_dup' can be replicated with this:

    {\footnotesize
    \begin{verbatim}
    // C = create an exact copy of A, just like GrB_Matrix_dup
    GrB_Matrix C ;
    GrB_Type type ;
    GrB_Index nrows, ncols ;
    GrB_Descriptor desc ;
    GxB_Matrix_type (&type, A) ;
    GrB_Matrix_nrows (&nrows, A) ;
    GrB_Matrix_ncols (&ncols, A) ;
    GrB_Matrix_new (&C, type, nrows, ncols) ;
    GrB_Descriptor_new (&desc) ;
    GrB_Descriptor_set (desc, GrB_INP0, GrB_TRAN) ;
    GrB_transpose (C, NULL, NULL, A, desc) ; \end{verbatim}}

Since the input matrix \verb'A' is transposed by the descriptor,
SuiteSparse:Graph\-BLAS does the right thing and does not transpose the matrix
at all.  Since \verb'T = A' is not typecasted, SuiteSparse:GraphBLAS can
construct \verb'T' internally in $O(1)$ time and using no memory at all.   This
makes \verb'Grb_transpose' a fast and direct interface to the accumulator/mask
function in GraphBLAS.

This example is of course overkill, since the work can all be done by a
single call to the \verb'GrB_Matrix_dup' function.  However, the
\verb'GrB_Matrix_dup' function can only create \verb'C' as an exact copy of
\verb'A', whereas variants of the code above can do many more things with these
two matrices.  For example, the \verb'type' in the example can be replaced with
any other type, perhaps selected from another matrix or from an operator.

Consider the following code excerpt, which uses \verb'GrB_transpose' to remove
all diagonal entries from a square matrix.  It first creates a diagonal
\verb'Mask', which is complemented so that ${\bf C \langle \neg M \rangle =A}$
does not modify the diagonal of ${\bf C}$.  The \verb'REPLACE' ensures that
\verb'C' is cleared first, and then ${\bf C \langle \neg M \rangle = A}$
modifies all entries in ${\bf C}$ where the mask ${\bf M}$ is false.  These
correspond to all the off-diagonal entries.  The descriptor ensures that ${\bf
A}$ is not transposed at all.  The \verb'Mask' can have any pattern, of course,
and wherever it is set true, the corresponding entries in \verb'A' are
deleted from the copy \verb'C'.

    {\footnotesize
    \begin{verbatim}
    // remove all diagonal entries from the matrix A
    // Mask = speye (n) ;
    GrB_Matrix_new (&Mask, GrB_BOOL, n, n) ;
    for (int64_t i = 0 ; i < n ; i++)
    {
        GrB_Matrix_setElement (Mask, (bool) true, i, i) ;
    }
    // C<~Mask> = A, clearing C first.  No transpose.
    GrB_Descriptor_new (&desc) ;
    GrB_Descriptor_set (desc, GrB_INP0, GrB_TRAN) ;
    GrB_Descriptor_set (desc, GrB_MASK, GrB_COMP) ;
    GrB_Descriptor_set (desc, GrB_OUTP, GrB_REPLACE) ;
    GrB_transpose (A, Mask, NULL, A, desc) ; \end{verbatim}}

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

\begin{spec}
{\bf SPEC:} The GraphBLAS API has no mechanism for printing the contents of
GraphBLAS objects.  This entire section is an extension to the specification.
\end{spec}

The 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_SelectOp_fprint'    & print and check a \verb'GxB_SelectOp' \\
\verb'GxB_Monoid_fprint'      & print and check a \verb'GrB_Monoid' \\
\verb'GxB_Semiring_fprint'    & print and check a \verb'GrB_Semiring' \\
\verb'GxB_Descriptor_fprint'  & print and check a \verb'GrB_Descriptor' \\
\verb'GxB_Matrix_fprint'      & print and check a \verb'GrB_Matrix' \\
\verb'GxB_Vector_fprint'      & print and check a \verb'GrB_Vector' \\
\verb'GxB_Scalar_fprint'      & print and check a \verb'GxB_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.  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', nothing is printed (\verb'pr' is
effectively \verb'GxB_SILENT').  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;
    see the ANSI C \verb'errno' or \verb'GrB_error( )' for details.
\end{packed_itemize}

The content of any GraphBLAS object is opaque, and subject to change.  As a
result, the exact content and format of what is printed is
implementation-dependent, and will change from version to version of
SuiteSparse:GraphBLAS.  Do not attempt to rely on the exact content or format
by trying to parse the resulting output via another program.  The intent of
these functions is to produce a report of an object for visual inspection.  If
the user application needs to extract content from a GraphBLAS matrix or
vector, use \verb'GrB_*_extractTuples' or the import/export methods instead.

\newpage
%===============================================================================
\subsection{{\sf GxB\_fprint:} Print a GraphBLAS object to a file} %============
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_fprint                 // print and check a GraphBLAS object
(
    GrB_<objecttype> object,        // object to print and check
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

The \verb'GxB_fprint' function prints the contents of any of the 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\_SelectOp\_fprint:} Print a {\sf GxB\_SelectOp}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_SelectOp_fprint        // print and check a GxB_SelectOp
(
    GxB_SelectOp selectop,          // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_SelectOp_fprint (GxB_TRIL, "tril", GxB_COMPLETE, f)' prints the
\verb'GxB_TRIL' select operator to the file \verb'f'.

\newpage
%===============================================================================
\subsection{{\sf GxB\_Monoid\_fprint:} Print a {\sf GrB\_Monoid}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Monoid_fprint          // print and check a GrB_Monoid
(
    GrB_Monoid monoid,              // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Monoid_fprint (GxB_PLUS_FP64_MONOID, "plus monoid",'
\verb'GxB_COMPLETE, f)'
prints the predefined \verb'GxB_PLUS_FP64_MONOID' (based on the binary
operator \verb'GrB_PLUS_FP64') to the file \verb'f'.

%===============================================================================
\subsection{{\sf GxB\_Semiring\_fprint:} Print a {\sf GrB\_Semiring}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Semiring_fprint        // print and check a GrB_Semiring
(
    GrB_Semiring semiring,          // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Semiring_fprint (GxB_PLUS_TIMES_FP64, "standard",'
\verb'GxB_COMPLETE, f)'
prints the predefined \verb'GxB_PLUS_TIMES_FP64' semiring to the file \verb'f'.

%===============================================================================
\subsection{{\sf GxB\_Descriptor\_fprint:} Print a {\sf GrB\_Descriptor}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Descriptor_fprint      // print and check a GrB_Descriptor
(
    GrB_Descriptor descriptor,      // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example,
\verb'GxB_Descriptor_fprint (d, "descriptor", GxB_COMPLETE, f)'
prints the descriptor \verb'd' to the file \verb'f'.

\newpage
%===============================================================================
\subsection{{\sf GxB\_Matrix\_fprint:} Print a {\sf GrB\_Matrix}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Matrix_fprint          // print and check a GrB_Matrix
(
    GrB_Matrix A,                   // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example, \verb'GxB_Matrix_fprint (A, "my matrix", GxB_SHORT, f)'
prints about 30 entries from the matrix \verb'A' to the file \verb'f'.


%===============================================================================
\subsection{{\sf GxB\_Vector\_fprint:} Print a {\sf GrB\_Vector}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Vector_fprint          // print and check a GrB_Vector
(
    GrB_Vector v,                   // object to print and check
    const char *name,               // name of the object
    GxB_Print_Level pr,             // print level
    FILE *f                         // file for output
) ;
\end{verbatim} } \end{mdframed}

For example, \verb'GxB_Vector_fprint (v, "my vector", GxB_SHORT, f)'
prints about 30 entries from the vector \verb'v' to the file \verb'f'.

%===============================================================================
\subsection{{\sf GxB\_Scalar\_fprint:} Print a {\sf GxB\_Scalar}}
%===============================================================================

\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
GrB_Info GxB_Scalar_fprint          // print and check a GrB_Scalar
(
    GxB_Sclarr 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 sparse 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{Examples} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{examples}

Several examples of how to use GraphBLAS are listed below.  They all
appear in the \verb'Demo' folder of SuiteSparse:GraphBLAS.

\begin{enumerate}
\item performing a breadth-first search,
\item finding a maximal independent set,
\item creating a random matrix,
\item creating a finite-element matrix,
\item reading a matrix from a file, and
\item complex numbers as a user-defined type.
\item triangle counting
\item PageRank
\item matrix import/export
\end{enumerate}

Additional examples appear in the newly created LAGraph project, currently in
progress.  Finally, the \verb'Extras' folder includes triangle counting and
k-truss algorithms in GraphBLAS, and methods that do not GraphBLAS (both simple
sequential methods, and methods that use OpenMP).

%-------------------------------------------------------------------------------
\subsection{LAGraph}
%-------------------------------------------------------------------------------
\label{lagraph}

The LAGraph project is a community-wide effort to create graph algorithms based
on GraphBLAS (any implementation of the API, not just SuiteSparse: GraphBLAS).
As of Oct, 2019, the library includes the algorithms and utilities listed in
the table below.  Many additional algorithms are planned, such as betweenness
centrality, PageRank, single-source shortest path (via delta stepping), minimum
spanning trees, connected components, and many more.  Refer to
\url{https://github.com/GraphBLAS/LAGraph} for a current list of algorithms
(the one below will soon be out of date).  Most of the functions in the
\verb'Demo/' and the \verb'Extras' folder in SuiteSparse:GraphBLAS will
eventually be translated into algorithms or utilities for LAGraph.

To use LAGraph with SuiteSparse:GraphBLAS, place the two folders \verb'LAGraph'
and \verb'GraphBLAS' in the same parent directory.  This allows the
\verb'cmake' script in LAGraph to find the copy of GraphBLAS.  Alternatively,
the GraphBLAS source could be placed anywhere, as long as
\verb'sudo make install' is performed.

Build \verb'GraphBLAS' first, then the \verb'LAGraph' library, and then the
tests in \verb'LAGraph/Test'.

Many of these algorithms are described in \cite{Davis20}.

\vspace{0.1in}
{\small
\begin{tabular}{ll}
\hline
\hline
Algorithms & description \\
\hline
\hline
\verb'LAGraph_bfs_pushpull' & a direction-optimized BFS
                                \cite{Beamer:2012:DOB,Yang:2018:IPE}, \\
                            & typically 2x faster than \verb'bfs5m' \\
\verb'LAGraph_bfs_simple'   & a simple BFS (about the same as \verb'bfs5m') \\
\verb'LAGraph_bc_batch'     & batched betweenness-centrality \\
\verb'LAGraph_bc'           & betweenness-centrality \\
\verb'LAGraph_cdlp'         & community detection via label propagation \\
\verb'LAGraph_cc'           & connected components \\
\verb'LAGraph_BF_*'         & three variants of Bellman-Ford \\
\verb'LAGraph_allktruss'    & construct all $k$-trusses \\
\verb'LAGraph_dnn'          & sparse deep neural network \cite{DavisAznavehKolodziej19} \\
\verb'LAGraph_ktruss'       & construct a $k$-trusses \\
\verb'LAGraph_lcc'          & local clustering coefficient \\
\verb'LAGraph_pagerank'     & PageRank \\
\verb'LAGraph_pagerank2'    & PageRank variant \\
\verb'LAGraph_tricount'     & triangle counting \\
\end{tabular}}

\vspace{0.1in}
{\small
\begin{tabular}{ll}
\hline
\hline
Utilities & description \\
\hline
\hline
\verb'LAGraph_Vector_isall'     & tests 2 vectors with a binary operator \\
\verb'LAGraph_Vector_isequal'   & tests if 2 vectors are equal \\
\verb'LAGraph_Vector_to_dense'  & converts a vector to dense \\
\verb'LAGraph_alloc_global'     & types, operators, monoids, and semirings \\
\verb'LAGraph_finalize'         & ends LAGraph \\
\verb'LAGraph_free'             & wrapper for \verb'free' \\
\verb'LAGraph_free_global'      & frees objects created by \verb'_alloc_global'\\
\verb'LAGraph_get_nthreads'     & get \# of threads used \\
\verb'LAGraph_grread'           & read a binary matrix in Galois format \\
\verb'LAGraph_init'             & starts LAGraph \\
\verb'LAGraph_isall'            & tests 2 matrices with a binary operator \\
\verb'LAGraph_isequal'          & tests if 2 matrices are equal \\
\verb'LAGraph_ispattern'        & tests if all entries in a matrix are 1 \\
\verb'LAGraph_malloc'           & wrapper for \verb'malloc' \\
\verb'LAGraph_mmread'           & read a Matrix Market file \\
\verb'LAGraph_mmwrite'          & write a Matrix Market file \\
\verb'LAGraph_pattern'          & extracts the pattern of a matrix \\
\verb'LAGraph_prune_diag'       & diagonal entries from a matrix \\
\verb'LAGraph_rand'             & simple random number generator \\
\verb'LAGraph_rand64'           & \verb'int64_t' random number generator \\
\verb'LAGraph_random'           & random matrix generator \\
\verb'LAGraph_randx'            & \verb'double' random number generator \\
\verb'LAGraph_set_nthreads'     & set \# of threads to use \\
\verb'LAGraph_tic'              & start a timer \\
\verb'LAGraph_toc'              & end a timer \\
\verb'LAGraph_tsvread'          & read a TSV file \\
\verb'LAGraph_xinit'            & starts LAGraph, with different malloc \\
\verb'LAgraph_1_to_n'           & construct the vector \verb'1:n' \\
\verb'GB_*sort*'                & sorting for \verb'LAGraph_cdlp' \\
% \verb'LAGraph_internal.h'
\end{tabular}}


\newpage
%-------------------------------------------------------------------------------
\subsection{Breadth-first search}
%-------------------------------------------------------------------------------
\label{bfs}

The \verb'bfs' examples in the \verb'Demo' folder provide several examples of
how to compute a breadth-first search (BFS) in GraphBLAS.  Additional BFS
examples are in LAGraph, shown below.  The \verb'LAGraph_bfs_simple' function
starts at a given source node \verb's' of an undirected graph with \verb'n'
nodes.  The graph is represented as an \verb'n'-by-\verb'n' matrix, \verb'A',
where \verb'A(i,j)' is the edge $(i,j)$.  The matrix \verb'A' can have any type
(even a user-defined type), since the \verb'PAIR' operator does not access its
values.  No typecasting will be done.

The vector \verb'v' of size \verb'n' holds the level of each node in the BFS,
where \verb'v(i)=0' if the node has not yet been seen.  This particular value
makes \verb'v' useful for another role.  It can be used as a Boolean mask,
since \verb'0' is \verb'false' and nonzero is \verb'true'.  Initially the
entire \verb'v' vector is zero.  It is initialized as a dense vector, with all
entries present, to improve performance (otherwise, it will slowly grow,
incrementally, and this will take a lot of time if the number of BFS levels is
high).

The vector \verb'q' is the set of nodes just discovered at the current level,
where \verb'q(i)=true' if node \verb'i' is in the current level.  It starts out
with just a single entry set to true, \verb'q(s)', the starting node.

Each iteration of the BFS consists of three calls to GraphBLAS.  The first one
uses \verb'q' as a mask.  It modifies all positions in \verb'v' where \verb'q'
has an entry, setting them all to the current \verb'level'.

        {\footnotesize
        \begin{verbatim}
        // v<q> = level, using vector assign with q as the mask
        GrB_assign (v, q, NULL, level, GrB_ALL, n, GrB_DESC_S) ; \end{verbatim}}

The next call to GraphBLAS is the heart of the algorithm:

        {\footnotesize
        \begin{verbatim}
        // q<!v> = q ||.&& A ; finds all the unvisited
        // successors from current q, using !v as the mask
        GrB_vxm (q, v, NULL, GxB_ANY_PAIR_BOOL, q, A, GrB_DESC_RC) ; \end{verbatim}}

The vector \verb'q' is all the set of nodes at the current level.  Suppose
\verb'q(j)' is true, and it has a neighbor \verb'i'.  Then \verb'A(i,j)=1', and
the dot product of \verb'A(i,:)*q' using the \verb'ANY_PAIR' semiring will use
the \verb'PAIR' multiplier on these two terms, \verb'f (A(i,j), q(j))', resulting
in a value \verb'1'.  The \verb'ANY' monoid will ``sum'' up all the results
in this single row \verb'i'; note that the \verb'OR' monoid would compute the
same thing.  If the result is a column vector \verb't=A*q',
then this \verb't(i)' will be true.  The vector \verb't' will be true for
any node adjacent to any node in the set \verb'q'.

Some of these neighbors of the nodes in \verb'q' have already been visited by
the BFS, either in the current level or in a prior level.  These results must
be discarded; what is desired is the set of all nodes \verb'i' for which
\verb't(i)' is true, and yet \verb'v(i)' is still zero.

Enter the mask.  The vector \verb'v' is complemented for use a mask, via the
\verb'desc' descriptor.  This means that wherever the vector is true, that
position in the result is protected and will not be modified by the assignment.
Only where \verb'v' is false will the result be modified.  This is exactly the
desired result, since these represent newly seen nodes for the next level of
the BFS.  A node \verb'k' already visited will have a nonzero \verb'v(k)', and
thus \verb'q(k)' will not be modified by the assignment.

The result \verb't' is written back into the vector \verb'q', through the mask,
but to do this correctly, another descriptor parameter is used:
\verb'GrB_REPLACE'.  The vector \verb'q' was used to compute \verb't=A*q', and
after using it to compute \verb't', the entire \verb'q' vector needs to be
cleared.  Only new nodes are desired, for the next level.  This is exactly what
the \verb'REPLACE' option does.

As a result, the vector \verb'q' now contains the set of nodes at the new
level of the BFS.  It contains all those nodes (and only those nodes)
that are neighbors of the prior set and that have not already been seen in
any prior level.

A single call to \verb'GrB_Vector_nvals' finds how many entries are in the
current level.  If this is zero, the BFS can terminate.

\newpage
\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
#include "LAGraph_internal.h"
#define LAGRAPH_FREE_ALL { GrB_free (&v) ; GrB_free (&q) ; }

GrB_Info LAGraph_bfs_simple     // push-only BFS
(
    GrB_Vector *v_output,   // v(i) is the BFS level of node i in the graph
    GrB_Matrix A,           // input graph, treated as if boolean in semiring
    GrB_Index source        // starting node of the BFS
)
{
    GrB_Info info ;
    GrB_Vector q = NULL ;           // nodes visited at each level
    GrB_Vector v = NULL ;           // result vector
    if (v_output == NULL) LAGRAPH_ERROR ("argument missing", GrB_NULL_POINTER) ;
    GrB_Index n, nvals ;
    GrB_Matrix_nrows (&n, A) ;
    // create an empty vector v, and make it dense
    GrB_Vector_new (&v, (n > INT32_MAX) ? GrB_INT64 : GrB_INT32, n) ;
    GrB_assign (v, NULL, NULL, 0, GrB_ALL, n, NULL) ;
    // create a boolean vector q, and set q(source) to true
    GrB_Vector_new (&q, GrB_BOOL, n) ;
    GrB_Vector_setElement (q, true, source) ;
    // BFS traversal and label the nodes
    for (int64_t level = 1 ; level <= n ; level++)
    {
        // v<q> = level
        GrB_assign (v, q, NULL, level, GrB_ALL, n, GrB_DESC_S) ;
        // break if q is empty
        GrB_Vector_nvals (&nvals, q) ;
        if (nvals == 0) break ;
        // q'<!v> = q'*A
        GrB_vxm (q, v, NULL, GxB_ANY_PAIR_BOOL, q, A, GrB_DESC_RC) ;
    }
    // free workspace and return result
    (*v_output) = v ;       // return result
    v = NULL ;              // set to NULL so LAGRAPH_FREE_ALL doesn't free it
    LAGRAPH_FREE_ALL ;      // free all workspace (except for result v)
    return (GrB_SUCCESS) ;
}
\end{verbatim}}
\end{mdframed}

\newpage
%-------------------------------------------------------------------------------
\subsection{Maximal independent set}
%-------------------------------------------------------------------------------
\label{mis}

The {\em maximal independent set} problem is to find a set of nodes $S$ such
that no two nodes in $S$ are adjacent to each other (an independent set), and
all nodes not in $S$ are adjacent to at least one node in $S$ (and thus $S$ is
maximal since it cannot be augmented by any node while remaining an independent
set).  The \verb'mis' function in the \verb'Demo' folder solves this problem
using Luby's method \cite{Luby86}.  The key operations in the method are
replicated on the next page.

The gist of the algorithm is this.  In each phase, all candidate nodes are
given a random score.  If a node has a score higher than all its neighbors,
then it is added to the independent set.  All new nodes added to the set cause
their neighbors to be removed from the set of candidates.  The process must be
repeated for multiple phases until no new nodes can be added.  This is because
in one phase, a node \verb'i' might not be added because one of its neighbors
\verb'j' has a higher score, yet that neighbor \verb'j' might not be added
because one of its neighbors \verb'k' is added to the independent set instead.
The node \verb'j' is no longer a candidate and can never be added to the
independent set, but node \verb'i' could be added to $S$ in a subsequent phase.

The initialization step, before the \verb'while' loop, computes the degree of
each node with a \verb'PLUS' reduction.  The set of \verb'candidates' is
Boolean vector, the \verb'i'th component is true if node \verb'i' is a
candidate.  A node with no neighbors causes the algorithm to stall, so these
nodes are not candidates.  Instead, they are immediately added to the
independent set, represented by another Boolean vector \verb'iset'.  Both steps
are done with an \verb'assign', using the \verb'degree' as a mask, except the
assignment to \verb'iset' uses the complement of the mask, via the
\verb'sr_desc' descriptor.  Finally, the \verb'GrB_Vector_nvals' statement
counts how many candidates remain.

Each phase of Luby's algorithm consists of 11 calls to GraphBLAS operations,
all of which are either parallel, or take $O(1)$ time.
Not all of them are described here since they are commented in the code itself.
The two matrix-vector multiplications are the important parts and also take the
most time.  They also make interesting use of semirings and masks.  The first
one computes the largest score of all the neighbors of each node in the
candidate set:

        {\footnotesize
        \begin{verbatim}
        // compute the max probability of all neighbors
        GrB_vxm (neighbor_max, candidates, NULL, maxFirst, prob, A, r_desc) ; \end{verbatim}}

\newpage
\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
    // compute the degree of each node
    GrB_reduce (degrees, NULL, NULL, GrB_PLUS_FP64, A, NULL) ;

    // singletons are not candidates; they are added to iset first instead
    // candidates[degree != 0] = 1
    GrB_assign (candidates, degrees, NULL, true, GrB_ALL, n, NULL);

    // add all singletons to iset
    // iset[degree == 0] = 1
    GrB_assign (iset, degrees, NULL, true, GrB_ALL, n, sr_desc) ;

    // Iterate while there are candidates to check.
    GrB_Index nvals ;
    GrB_Vector_nvals (&nvals, candidates) ;

    while (nvals > 0)
    {
        // sparsify the random number seeds (just keep it for each candidate)
        GrB_assign (Seed, candidates, NULL, Seed, GrB_ALL, n, r_desc) ;
        // compute a random probability scaled by inverse of degree
        prand_xget (X, Seed) ;  // two calls to GrB_apply
        GrB_eWiseMult (prob, candidates, NULL, set_random, degrees, X, r_desc) ;
        // compute the max probability of all neighbors
        GrB_vxm (neighbor_max, candidates, NULL, maxFirst, prob, A, r_desc) ;
        // select node if its probability is > than all its active neighbors
        GrB_eWiseAdd (new_members, NULL,NULL, GrB_GT_FP64, prob, neighbor_max,0);
        // add new members to independent set.
        GrB_eWiseAdd (iset, NULL, NULL, GrB_LOR, iset, new_members, NULL) ;
        // remove new members from set of candidates c = c & !new
        GrB_apply (candidates, new_members, NULL, GrB_IDENTITY_BOOL,
            candidates, sr_desc) ;
        GrB_Vector_nvals (&nvals, candidates) ;
        if (nvals == 0) { break ; }                  // early exit condition
        // Neighbors of new members can also be removed from candidates
        GrB_vxm (new_neighbors, candidates, NULL, Boolean,
            new_members, A, NULL) ;
        GrB_apply (candidates, new_neighbors, NULL, GrB_IDENTITY_BOOL,
            candidates, sr_desc) ;
        GrB_Vector_nvals (&nvals, candidates) ;
    }
\end{verbatim}}
\end{mdframed}

\verb'A' is a symmetric Boolean matrix and \verb'prob' is a sparse real vector
(of type \verb'FP32'), where \verb'prob(i)' is nonzero only if node \verb'i' is
a candidate.  The \verb'prob' vector is computed from a random vector computed
by a utility function \verb'prand_xget', in the \verb'Demo' folder.  It uses
two calls to \verb'GrB_apply' to construct \verb'n' random numbers in parallel,
using a repeatable pseudo-random number generator.

The \verb'maxFirst' semiring uses \verb'z=FIRST(x,y)' as the multiplier
operator.  The column \verb'A(:,j)' is the adjacency of node \verb'j', and the
dot product \verb"prob'*A(:,j)" applies the \verb'FIRST' operator on all
entries that appear in the intersection of \verb'prob' and \verb'A(:,j)', where
\verb'z=FIRST(prob(i),A(i,j))' which is just \verb'prob(i)' if \verb'A(i,j)' is
present.  If \verb'A(i,j)' not an explicit entry in the matrix, then this term
is not computed and does not take part in the reduction by the \verb'MAX'
monoid.

Thus, each term \verb'z=FIRST(prob(i),A(i,j))' is the score, \verb'prob(i)',
of all neighbors \verb'i' of node \verb'j' that have a score.  Node \verb'i'
does not have a score if it is not also a candidate and so this is skipped.
These terms are then ``summed'' up by taking the maximum score, using
\verb'MAX' as the additive monoid.

Finally, the results of this matrix-vector multiply are written to the result,
\verb'neighbor_max'.  The \verb'r_desc' descriptor has the \verb'REPLACE'
option enabled.  Since \verb'neighbor_max' does not also take part in the
computation \verb"prob'*A", it is simply cleared first.  Next, is it modified
only in those positions \verb'i' where \verb'candidates(i)' is true, using
\verb'candidates' as a mask.  This sets the \verb'neighbor_max' only for
candidate nodes, and leaves the other components of \verb'neighbor_max' as zero
(implicit values not in the pattern of the vector).

All of the above work is done in a single matrix-vector multiply, with an
elegant use of the \verb'maxFirst' semiring coupled with a mask.  The
matrix-vector multiplication is described above as if it uses dot products of
rows of \verb'A' with the column vector \verb'prob', but SuiteSparse:GraphBLAS
does not compute it that way.  Sparse dot products are much slower the optimal
method for multiplying a sparse matrix times a sparse vector.  The result is
the same, however.

The second matrix-vector multiplication is more straight-forward.  Once the set
of new members in the independent is found, it is used to remove all neighbors
of those new members from the set of candidates.

The resulting method is very efficient.  For the \verb'Freescale2' matrix, the
algorithm finds an independent set of size 1.6 million in 1.7 seconds (on the
same MacBook Pro referred to in Section~\ref{bfs}, using a single core), taking
four iterations of the \verb'while' loop.  For comparison, removing its
diagonal entries (required for the algorithm to work) takes 0.3 seconds in
GraphBLAS (see Section~\ref{transpose}), and simply transposing the matrix
takes 0.24 seconds in both MATLAB and GraphBLAS.

\newpage
%-------------------------------------------------------------------------------
\subsection{Creating a random matrix}
%-------------------------------------------------------------------------------
\label{random}

The \verb'random_matrix' function in the \verb'Demo' folder generates a random
matrix with a specified dimension and number of entries, either symmetric or
unsymmetric, and with or without self-edges (diagonal entries in the matrix).
It relies on \verb'simple_rand*' functions in the \verb'Demo' folder to provide
a portable random number generator that creates the same sequence on any
computer and operating system.

\verb'random_matrix' can use one of two methods: \verb'GrB_Matrix_setElement'
and \verb'GrB_Matrix_build'.  The former method is very simple to use:

    {\footnotesize
    \begin{verbatim}
    GrB_Matrix_new (&A, GrB_FP64, nrows, ncols) ;
    for (int64_t k = 0 ; k < ntuples ; k++)
    {
        GrB_Index i = simple_rand_i ( ) % nrows ;
        GrB_Index j = simple_rand_i ( ) % ncols ;
        if (no_self_edges && (i == j)) continue ;
        double x = simple_rand_x ( ) ;
        // A (i,j) = x
        GrB_Matrix_setElement (A, x, i, j) ;
        if (make_symmetric)
        {
            // A (j,i) = x
            GrB_Matrix_setElement (A, x, j, i) ;
        }
    } \end{verbatim}}

The above code can generate a million-by-million sparse \verb'double' matrix
with 200 million entries in 66 seconds (6 seconds of which is the time to
generate the random \verb'i', \verb'j', and \verb'x'), including the time
to finish all pending computations.  The user application does not need to
create a list of all the tuples, nor does it need to know how many entries will
appear in the matrix.  It just starts from an empty matrix and adds them one at
a time in arbitrary order.  GraphBLAS handles the rest.  This method is not
feasible in MATLAB.

The next method uses \verb'GrB_Matrix_build'.  It is more complex to use than
\verb'setElement' since it requires the user application to allocate and fill
the tuple lists, and it requires knowledge of how many entries will appear in
the matrix, or at least a good upper bound, before the matrix is constructed.
It is slightly faster, creating the same matrix in 60 seconds, 51 seconds
of which is spent in \verb'GrB_Matrix_build'.

\newpage
    {\footnotesize
    \begin{verbatim}
    GrB_Index *I, *J ;
    double *X ;
    int64_t s = ((make_symmetric) ? 2 : 1) * nedges + 1 ;
    I = malloc (s * sizeof (GrB_Index)) ;
    J = malloc (s * sizeof (GrB_Index)) ;
    X = malloc (s * sizeof (double   )) ;
    if (I == NULL || J == NULL || X == NULL)
    {
        // out of memory
        if (I != NULL) free (I) :
        if (J != NULL) free (J) :
        if (X != NULL) free (X) :
        return (GrB_OUT_OF_MEMORY) ;
    }
    int64_t ntuples = 0 ;
    for (int64_t k = 0 ; k < nedges ; k++)
    {
        GrB_Index i = simple_rand_i ( ) % nrows ;
        GrB_Index j = simple_rand_i ( ) % ncols ;
        if (no_self_edges && (i == j)) continue ;
        double x = simple_rand_x ( ) ;
        // A (i,j) = x
        I [ntuples] = i ;
        J [ntuples] = j ;
        X [ntuples] = x ;
        ntuples++ ;
        if (make_symmetric)
        {
            // A (j,i) = x
            I [ntuples] = j ;
            J [ntuples] = i ;
            X [ntuples] = x ;
            ntuples++ ;
        }
    }
    GrB_Matrix_build (A, I, J, X, ntuples, GrB_SECOND_FP64) ; \end{verbatim}}

The equivalent \verb'sprandsym' function in MATLAB takes 150 seconds, but
\verb'sprandsym' uses a much higher-quality random number generator to create
the tuples \verb'[I,J,X]'.  Considering just the time for
\verb'sparse(I,J,X,n,n)' in \verb'sprandsym' (equivalent to
\verb'GrB_Matrix_build'), the time is 70 seconds.  That is, each of these three
methods, \verb'setElement' and \verb'build' in SuiteSparse:GraphBLAS, and
\verb'sparse' in MATLAB, are equally fast.

% It is not possible to build such a matrix one entry at a time in MATLAB.
% using a comparable method.  The MATLAB equivalent to \verb'setElement',
% below, takes 105 seconds for the first 200,000 entries and 381 seconds for
% the last 1,000.  The time complexity is $O(nz^2)$.  Extrapolation from this
% data gives an estimated run time of $4 \times 10^7$ seconds (462 days),
% which is nearly a million times slower than the other three methods.

%
%     {\footnotesize
%     \begin{verbatim}
%     A = sparse (n,n) ;
%     for k = 1:length (I)
%         A (I (k), J (k)) = X (k) ;
%     end \end{verbatim}}

% The problem is not the time spent in interpreting the \verb'for' loop.  A
% \verb'for' loop over 200 million iterations takes only 8 seconds.  The
% problem is that the sparse matrices in MATLAB do not allow computations to be
% left pending.

\newpage
%-------------------------------------------------------------------------------
\subsection{Creating a finite-element matrix}
%-------------------------------------------------------------------------------
\label{fem}

Suppose a finite-element matrix is being constructed, with \verb'k=40,000'
finite-element matrices, each of size \verb'8'-by-\verb'8'.  The following
operations (in pseudo-MATLAB notation) are very efficient in
SuiteSparse:GraphBLAS.

    {\footnotesize
    \begin{verbatim}
    A = sparse (m,n) ; % create an empty n-by-n sparse GraphBLAS matrix
    for i = 1:k
        construct a 8-by-8 sparse or dense finite-element F
        I and J define where the matrix F is to be added:
        I = a list of 8 row indices
        J = a list of 8 column indices
        % using GrB_assign, with the 'plus' accum operator:
        A (I,J) = A (I,J) + F
    end \end{verbatim}}

If this were done in MATLAB or in GraphBLAS with blocking mode enabled, the
computations would be extremely slow.  This example is taken from Loren Shure's
blog on MATLAB Central, {\em Loren on the Art of MATLAB} \cite{Davis07},
which discusses the built-in \verb'wathen' function.  In
MATLAB, a far better approach is to construct a list of tuples \verb'[I,J,X]'
and to use \verb'sparse(I,J,X,n,n)'. This is identical to creating the same
list of tuples in GraphBLAS and using the \verb'GrB_Matrix_build', which is
equally fast.  The difference in time between using \verb'sparse' or
\verb'GrB_Matrix_build', and using submatrix assignment with blocking mode (or
in MATLAB which does not have a nonblocking mode) can be extreme.  For the
example matrix discussed in \cite{Davis07}, using \verb'sparse' instead of
submatrix assignment in MATLAB cut the run time of \verb'wathen' from 305
seconds down to 1.6 seconds.

In SuiteSparse:GraphBLAS, the performance of both methods is essentially
identical, and roughly as fast as \verb'sparse' in MATLAB.  Inside
SuiteSparse:GraphBLAS, \verb'GrB_assign' is doing the same thing. When
performing \verb'A(I,J)=A(I,J)+F', if it finds that it cannot quickly insert an
update into the \verb'A' matrix, it creates a list of pending tuples to be
assembled later on.   When the matrix is ready for use in a subsequent
GraphBLAS operation (one that normally cannot use a matrix with pending
computations), the tuples are assembled all at once via
\verb'GrB_Matrix_build'.

GraphBLAS operations on other matrices have no effect on when the pending
updates of a matrix are completed.  Thus, any GraphBLAS method or operation can
be used to construct the \verb'F' matrix in the example above, without
affecting when the pending updates to \verb'A' are completed.

The MATLAB \verb'wathen.m' script is part of Higham's \verb'gallery' of
matrices \cite{Higham}.  It creates a finite-element matrix with random
coefficients for a 2D mesh of size \verb'nx'-by-\verb'ny', a matrix formulation
by Wathen \cite{Wathen}.  The pattern of the matrix is fixed; just the values
are randomized.  The GraphBLAS equivalent can use either
\verb'GrB_Matrix_build', or \verb'GrB_assign'.  Both methods have good
performance.  The \verb'GrB_Matrix_build' version below is about 15\% to 20\%
faster than the MATLAB \verb'wathen.m' function, regardless of the problem
size.  It uses the identical algorithm as \verb'wathen.m'.

    {\footnotesize
    \begin{verbatim}
    int64_t ntriplets = nx*ny*64 ;
    I = malloc (ntriplets * sizeof (int64_t)) ;
    J = malloc (ntriplets * sizeof (int64_t)) ;
    X = malloc (ntriplets * sizeof (double )) ;
    if (I == NULL || J == NULL || X == NULL)
    {
        FREE_ALL ;
        return (GrB_OUT_OF_MEMORY) ;
    }
    ntriplets = 0 ;
    for (int j = 1 ; j <= ny ; j++)
    {
        for (int i = 1 ; i <= nx ; i++)
        {
            nn [0] = 3*j*nx + 2*i + 2*j + 1 ;
            nn [1] = nn [0] - 1 ;
            nn [2] = nn [1] - 1 ;
            nn [3] = (3*j-1)*nx + 2*j + i - 1 ;
            nn [4] = 3*(j-1)*nx + 2*i + 2*j - 3 ;
            nn [5] = nn [4] + 1 ;
            nn [6] = nn [5] + 1 ;
            nn [7] = nn [3] + 1 ;
            for (int krow = 0 ; krow < 8 ; krow++) nn [krow]-- ;
            for (int krow = 0 ; krow < 8 ; krow++)
            {
                for (int kcol = 0 ; kcol < 8 ; kcol++)
                {
                    I [ntriplets] = nn [krow] ;
                    J [ntriplets] = nn [kcol] ;
                    X [ntriplets] = em (krow,kcol) ;
                    ntriplets++ ;
                }
            }
        }
    }
    // A = sparse (I,J,X,n,n) ;
    GrB_Matrix_build (A, I, J, X, ntriplets, GrB_PLUS_FP64) ; \end{verbatim}}

The \verb'GrB_assign' version has the advantage of not requiring the
user application to construct the tuple list, and is almost as fast as using
\verb'GrB_Matrix_build'.  The code is more elegant than either the MATLAB
\verb'wathen.m' function or its GraphBLAS equivalent above.  Its performance is
comparable with the other two methods, but slightly slower, being about 5\%
slower than the MATLAB \verb'wathen', and 20\% slower than the GraphBLAS
method above.

    {\footnotesize
    \begin{verbatim}
    GrB_Matrix_new (&F, GrB_FP64, 8, 8) ;
    for (int j = 1 ; j <= ny ; j++)
    {
        for (int i = 1 ; i <= nx ; i++)
        {
            nn [0] = 3*j*nx + 2*i + 2*j + 1 ;
            nn [1] = nn [0] - 1 ;
            nn [2] = nn [1] - 1 ;
            nn [3] = (3*j-1)*nx + 2*j + i - 1 ;
            nn [4] = 3*(j-1)*nx + 2*i + 2*j - 3 ;
            nn [5] = nn [4] + 1 ;
            nn [6] = nn [5] + 1 ;
            nn [7] = nn [3] + 1 ;
            for (int krow = 0 ; krow < 8 ; krow++) nn [krow]-- ;
            for (int krow = 0 ; krow < 8 ; krow++)
            {
                for (int kcol = 0 ; kcol < 8 ; kcol++)
                {
                    // F (krow,kcol) = em (krow, kcol)
                    GrB_Matrix_setElement (F, em (krow,kcol), krow, kcol) ;
                }
            }
            // A (nn,nn) += F
            GrB_assign (A, NULL, GrB_PLUS_FP64, F, nn, 8, nn, 8, NULL) ;
        }
    } \end{verbatim}}

Since there is no \verb'Mask', and since \verb'GrB_REPLACE' is not used, the call
to \verb'GrB_assign' in the example above is identical to \verb'GxB_subassign'.
Either one can be used, and their performance would be identical.

Refer to the \verb'wathen.c' function in the \verb'Demo' folder, which
uses GraphBLAS to implement the two methods above, and two additional ones.

\newpage
%-------------------------------------------------------------------------------
\subsection{Reading a matrix from a file}
%-------------------------------------------------------------------------------
\label{read}

{\bf NOTE:} see also \verb'LAGraph_mmread' and \verb'LAGraph_mmwrite', which
can read and write any matrix in Matrix Market format, 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.  A comparison of
\verb'build' versus \verb'setElement' has already been discussed in
Section~\ref{random}.

The function can return the matrix as-is, which may be rectangular or
unsymmetric.  If an input parameter is set to make the matrix symmetric,
\verb'read_matrix' computes \verb"A=(A+A')/2" if \verb'A' is square (turning
all directed edges into undirected ones.  If \verb'A' is rectangular, it
creates a bipartite graph, which is the same as the augmented matrix,
\verb"A = [0 A ; A' 0]".
If \verb'C' is an \verb'n'-by-\verb'n' matrix, then \verb"C=(C+C')/2" can be
computed as follows in GraphBLAS, (the \verb'scale2' function divides an entry
by 2):

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    GrB_Descriptor_new (&dt2) ;
    GrB_Descriptor_set (dt2, GrB_INP1, GrB_TRAN) ;
    GrB_Matrix_new (&A, GrB_FP64, n, n) ;
    GrB_eWiseAdd (A, NULL, NULL, GrB_PLUS_FP64, C, C, dt2) ;    // A=C+C'
    GrB_free (&C) ;
    GrB_Matrix_new (&C, GrB_FP64, n, n) ;
    GrB_UnaryOp_new (&scale2_op, scale2, GrB_FP64, GrB_FP64) ;
    GrB_apply (C, NULL, NULL, scale2_op, A, NULL) ;             // C=A/2
    GrB_free (&A) ;
    GrB_free (&scale2_op) ; \end{verbatim}}

This is of course not nearly as elegant as \verb"A=(A+A')/2" in MATLAB, but
with minor changes it can work on any type and use any built-in operators
instead of \verb'PLUS', or it can use any user-defined operators and types.
The above code in SuiteSparse:GraphBLAS takes 0.60 seconds for the
\verb'Freescale2' matrix, slightly slower than MATLAB (0.55 seconds).

Constructing the augmented system is more complicated using the GraphBLAS C API
Specification since it does not yet have a simple way of specifying a range of
row and column indices, as in \verb'A(10:20,30:50)' in MATLAB (\verb'GxB_RANGE'
is a SuiteSparse:GraphBLAS extension that is not in the Specification).  Using
the C API in the Specification, the application must instead build a list of
indices first, \verb'I=[10, 11' \verb'...' \verb'20]'.

Thus, to compute the MATLAB equivalent of \verb"A = [0 A ; A' 0]", index lists
\verb'I' and \verb'J' must first be constructed:

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    int64_t n = nrows + ncols ;
    I = malloc (nrows * sizeof (int64_t)) ;
    J = malloc (ncols * sizeof (int64_t)) ;
    // I = 0:nrows-1
    // J = nrows:n-1
    if (I == NULL || J == NULL)
    {
        if (I != NULL) free (I) ;
        if (J != NULL) free (J) ;
        return (GrB_OUT_OF_MEMORY) ;
    }
    for (int64_t k = 0 ; k < nrows ; k++) I [k] = k ;
    for (int64_t k = 0 ; k < ncols ; k++) J [k] = k + nrows ; \end{verbatim}}

Once the index lists are generated, however, the resulting GraphBLAS operations
are fairly straightforward, computing \verb"A=[0 C ; C' 0]".

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    GrB_Descriptor_new (&dt1) ;
    GrB_Descriptor_set (dt1, GrB_INP0, GrB_TRAN) ;
    GrB_Matrix_new (&A, GrB_FP64, n, n) ;
    // A (nrows:n-1, 0:nrows-1) = C'
    GrB_assign (A, NULL, NULL, C, J, ncols, I, nrows, dt1) ;
    // A (0:nrows-1, nrows:n-1) = C
    GrB_assign (A, NULL, NULL, C, I, nrows, J, ncols, NULL) ; \end{verbatim}}

This takes 1.38 seconds for the \verb'Freescale2' matrix, almost as fast as
\verb"A=[sparse(m,m) C ; C' sparse(n,n)]" in MATLAB (1.25 seconds).

Both calls to \verb'GrB_assign' use no accumulator, so the second one
causes the partial matrix \verb"A=[0 0 ; C' 0]" to be built first, followed by
the final build of \verb"A=[0 C ; C' 0]".  A better method, but not an obvious
one, is to use the \verb'GrB_FIRST_FP64' accumulator for both assignments.  An
accumulator enables SuiteSparse:GraphBLAS to determine that that entries
created by the first assignment cannot be deleted by the second, and thus it
need not force completion of the pending updates prior to the second
assignment.

SuiteSparse:GraphBLAS also adds a \verb'GxB_RANGE' mechanism that mimics
the MATLAB colon notation.  This speeds up the method and simplifies the
code the user needs to write to compute \verb"A=[0 C ; C' 0]":

    \vspace{-0.05in}
    {\footnotesize
    \begin{verbatim}
    int64_t n = nrows + ncols ;
    GrB_Matrix_new (&A, xtype, n, n) ;
    GrB_Index I_range [3], J_range [3] ;
    I_range [GxB_BEGIN] = 0 ;
    I_range [GxB_END  ] = nrows-1 ;
    J_range [GxB_BEGIN] = nrows ;
    J_range [GxB_END  ] = ncols+nrows-1 ;
    // A (nrows:n-1, 0:nrows-1) += C'
    GrB_assign (A, NULL, GrB_FIRST_FP64, // or NULL,
        C, J_range, GxB_RANGE, I_range, GxB_RANGE, dt1) ;
    // A (0:nrows-1, nrows:n-1) += C
    GrB_assign (A, NULL, GrB_FIRST_FP64, // or NULL,
        C, I_range, GxB_RANGE, J_range, GxB_RANGE, NULL) ; \end{verbatim}}

Any operator will suffice because it is not actually applied.  An operator is
only applied to the set intersection, and the two assignments do not overlap.
If an \verb'accum' operator is used, only the final matrix is built, and the
time in GraphBLAS drops slightly to 1.25 seconds.  This is a very small
improvement because in this particular case, SuiteSparse:GraphBLAS is able to
detect that no sorting is required for the first build, and the second one is a
simple concatenation.  In general, however, allowing GraphBLAS to postpone
pending updates can lead to significant reductions in run time.

%-------------------------------------------------------------------------------
\subsection{PageRank}
%-------------------------------------------------------------------------------
\label{pagerank}

The \verb'Demo' folder contains three methods for computing the PageRank of the
nodes of a graph.  One uses floating-point arithmetic (\verb'GrB_FP64') and two
user-defined unary operators (\verb'dpagerank.c').  The second
(\verb'ipagerank.c') is very similar, relying on integer arithmetic instead
(\verb'GrB_UINT64').  Neither method include a stopping condition.  They simply
compute a fixed number of iterations.  The third example is more extensive
(\verb'dpagerank2.c'), and serves as an example of the power and flexibility of
user-defined types, operators, monoids, and semirings.  It creates a semiring
for the entire PageRank computation.  It terminates if the 2-norm of the change
in the rank vector \verb'r' is below a threshold.

\newpage
%-------------------------------------------------------------------------------
\subsection{Triangle counting}
%-------------------------------------------------------------------------------
\label{triangle}

A triangle in an undirected graph is a clique of size three:  three nodes $i$,
$j$, and $k$ that are all pairwise connected.  There are many ways of counting
the number of triangles in a graph.  Let \verb'A' be a symmetric matrix with
values 0 and 1, and no diagonal entries; this matrix is the adjacency matrix of
the graph.  Let \verb'E' be the edge incidence matrix with exactly two 1's per
column.  A column of \verb'E' with entries in rows \verb'i' and \verb'j'
represents the edge $(i,j)$ in the graph, \verb'A(i,j)=1' where \verb'i<j'.
Let \verb'L' and \verb'U' be the strictly lower and upper triangular parts of
\verb'A', respectively.

The methods are listed in the table below.  Most of them use a form of masked
matrix-matrix multiplication.  The methods are implemented in MATLAB in the
\verb'tricount.m' file, and in GraphBLAS in the \verb'tricount.c' file, both in
the \verb'GraphBLAS/Demo' folder.  Refer to the comments in those two files for
details and derivations on how these methods work.

When the matrix is stored by row, and a mask is present and not complemented,
\verb'GrB_INP1' is \verb'GrB_TRAN', and \verb'GrB_INP0' is \verb'GxB_DEFAULT',
the SuiteSparse:GraphBLAS implementation of \verb'GrB_mxm' always uses a
dot-product formulation.  Thus, the ${\bf C \langle L \rangle} = {\bf L}{\bf
U}^{\sf T}$ method uses dot products.  This provides a mechanism for the
end-user to select a masked dot product matrix multiplication method in
SuiteSparse:GraphBLAS, which is occasionally faster than the outer product
method.  The MATLAB form assumes the matrices are stored by column
(the only option in MATLAB).

Each method is followed by a reduction to a scalar, via \verb'GrB_reduce' in
GraphBLAS or by \verb'nnz' or \verb'sum(sum(...))' in MATLAB.

\vspace{0.05in}
\noindent
{\footnotesize
\begin{tabular}{lll}
\hline
method and     & in MATLAB & in GraphBLAS \\
citation    & & \\
\hline
minitri \cite{WolfBerryStark15} & \verb"nnz(A*E==2)/3"
    & ${\bf C}={\bf AE}$, then \verb'GrB_apply' \\
Burkhardt \cite{Burkhardt16} & \verb"sum(sum((A^2).*A))/6"
    & ${\bf C \langle A \rangle} = {\bf A}^2$ \\
Cohen \cite{AzadBulucGilbert15,Cohen09} & \verb"sum(sum((L*U).*A))/2"
    & ${\bf C \langle A \rangle} = {\bf LU}$ \\
Sandia \cite{WolfDeveciBerryHammondRajamanickam17} & \verb"sum(sum((U*U).*U))"
    & ${\bf C \langle L \rangle} = {\bf LL}$ (outer product) \\
SandiaDot & \verb"sum(sum((U'*L).*L))"
    & ${\bf C \langle U \rangle} = {\bf L}{\bf U}^{\sf T}$ (dot product) \\
Sandia2  & \verb"sum(sum((L*L).*L))"
    & ${\bf C \langle U \rangle} = {\bf UU}$ (outer product) \\
\hline
\end{tabular}
}
\vspace{0.05in}

In general, the Sandia methods are the fastest of the 6 methods when
implemented in GraphBLAS.  For full details on the triangle counting and
$k$-truss algorithms, and performance results, see \cite{Davis18b}, a copy of
which appears in the \verb'SuiteSparse/GraphBLAS/Doc' folder.  The code appears
in \verb'Extras'.  That paper uses an earlier version of SuiteSparse:GraphBLAS
in which all matrices are stored by column.

\newpage
%-------------------------------------------------------------------------------
\subsection{User-defined types and operators}
%-------------------------------------------------------------------------------
\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        & 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.

\newpage
%-------------------------------------------------------------------------------
\subsection{User applications using OpenMP or POSIX pthreads}
%-------------------------------------------------------------------------------
\label{threads}

Two example demo programs are included that illustrate how a multi-threaded
user application can use GraphBLAS:  \verb'openmp_demo' uses OpenMP for its
user threads and \verb'pthread_demo' uses POSIX pthreads.
% TODO in 4.0: delete this note in bold:
{\bf To be thread-safe, SuiteSparse:GraphBLAS must be compiled with a threading
library, either OpenMP or POSIX}.  Either option used inside GraphBLAS can
typically be combined with any user threading model.  See
Section~\ref{sec:install}.

The \verb'openmp_demo' can be compiled without OpenMP, in which case it
becomes single-threaded.  GraphBLAS can be compiled with OpenMP, POSIX
pthreads, or no threading support (and is not thread-safe in this latter
case).  This gives 9 different combinations:

\vspace{0.1in}
{\footnotesize
\begin{tabular}{llll}
\hline
User    & GraphBLAS & \verb'Demo/Output' file & comments \\
applic. &           & & \\
\hline
none    & none      & \verb'user_none_grb_none.out'      & OK \\
none    & OpenMP    & \verb'user_none_grb_openmp.out'    & OK \\
none    & pthread   & \verb'user_none_grb_pthread.out'   & OK \\
\hline
OpenMP  & none      & \verb'user_openmp_grb_none.out'    & fail \\
OpenMP  & OpenMP    & \verb'user_openmp_grb_openmp.out'  & OK, random \\
OpenMP  & pthread   & \verb'user_openmp_grb_pthread.out' & OK, random \\
\hline
pthread & none      & \verb'user_pthread_grb_none.out'   & fail \\
pthread & OpenMP    & \verb'user_pthread_grb_openmp.out' & OK, random \\
pthread & pthread   & \verb'user_pthread_grb_pthread.out'& OK, random \\
\hline
\end{tabular}}
\vspace{0.1in}

\noindent
When the user application is multithreaded, GraphBLAS must be compiled with a
threading library to be thread-safe.  The results listed above as {\em OK,
random} mean that the output of the program will appear out of order.  This is
by design, simply to show that the user application is running in parallel.
The output of each thread should be the same.  In particular, each thread
generates an intentional error, and later on prints it with \verb'GrB_error'.
It will print its own error, not an error from another thread.  When all the
threads finish, the master thread prints out each matrix generated by each
thread, and these results are identical for all 7 cases listed above as OK.

% TODO in 4.0: remove this; GraphBLAS will always be thread-safe:
The GraphBLAS C API requires GraphBLAS to be thread-safe.  If
SuiteSparse:GraphBLAS is not compiled with a threading library it will not be
thread-safe (the two {\em fail} cases above).  For these cases, a thread will
not retrieve its own error, but the last error of any thread.  In addition,
since there is no critical section that SuiteSparse:GraphBLAS can use, the
output will include errors about an invalid state of the global matrix queue.
These errors are to be expected if SuiteSparse:GraphBLAS is not thread-safe.

\newpage
%-------------------------------------------------------------------------------
\section{Compiling and Installing SuiteSparse:GraphBLAS}
%-------------------------------------------------------------------------------
\label{sec:install}

%----------------------------------------
\subsection{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.  On the Mac
(OS X), \verb'clang' 8.0.0 in \verb'Xcode' version 8.2.1 is sufficient,
although earlier versions of \verb'Xcode' may work as well.  For the GNU
\verb'gcc' compiler, version 4.9 or later is required.  For the Intel
\verb'icc' compiler, version 18.0 or later is required.  Version 2.8.12 or
later of \verb'cmake' is required; version 3.0.0 is preferred.

If you are using a pre-C11 ANSI C compiler, or 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.

{\bf NOTE: icc is generally an excellent compiler, but it will generate slower
code than gcc for v3.2.0 and later.  This is merely because of how the two
compilers treat \verb'#pragma omp atomic read' and \verb'#pragma omp atomic write'.
The use of gcc for SuiteSparse:GraphBLAS v3.2.0 and later is recommended.  This
difference in performance should be resolved in a future version.}

To compile SuiteSparse:GraphBLAS and the demo programs, simply type \verb'make'
in the main GraphBLAS folder, which compiles the library.  To use a
non-default compiler:

    {\small
    \begin{verbatim}
    make CC=icc CXX=icc JOBS=4 \end{verbatim} }

After compiling the library, you can run the demos by typing \verb'./demo'
in the Demo 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-6 cmake ..
    CC=xlc cmake ..
    CC=icc cmake ..  \end{verbatim} }

You can also do the following in the top-level GraphBLAS folder instead:

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

For faster compilation, you can specify a parallel make.  For example,
to use 32 parallel jobs and the \verb'gcc' compiler, do the following:

    {\small
    \begin{verbatim}
    JOBS=32 CC=gcc make \end{verbatim} }

%----------------------------------------
\subsection{On Microsoft Windows}
\label{sec:windows}
%----------------------------------------

SuiteSparse:GraphBLAS is now ported to Microsoft Visual Studio.  However, that
compiler is not ANSI C11 compliant and does not support OpenMP v4.0.  As a
result, GraphBLAS on Windows will have a few 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 Another limitation is the lack of support for OpenMP tasking, used in the
parallel sort inside GraphBLAS.  With Microsoft Visual Studio, the sort is
compiled to use just a single thread.  The sort is used for
\verb'GrB_Matrix_build' and \verb'GrB_Vector_build', and for \verb'GrB_assign'
and  \verb'GxB_subassign' when the index lists are unsorted on input.  The
internal sort still works as specified; it will just be single-threaded and
thus these GraphBLAS functions will be slower on Windows as compared to Linux
or MacOS.

\item In addition, variable-length arrays are not supported, so user-defined
types are limited to 128 bytes in size.
\end{itemize}

If you use a recent \verb'gcc' or \verb'icc' 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'.
    \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 interface discussed in the next section.

\end{enumerate}

%----------------------------------------
\subsection{Compiling the MATLAB interface}
%----------------------------------------

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.  Next:

\begin{enumerate}
\item In the MATLAB 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 path and \verb'startup.m' file.

\item As a quick test, try the MATLAB 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 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
    \verb'GraphBLAS/GraphBLAS/test' folder.
    %% FUTURE: fix asin and acsc on Windows for the complex case.

\end{enumerate}

%----------------------------------------
\subsection{Thread-safety in multithreaded user applications}
\label{sec:threads}
%----------------------------------------

% TODO in 4.0: this entire section will likely be deleted, with the
% pending change to GrB_wait and GrB_error.

SuiteSparse:GraphBLAS is parallel, based on OpenMP.  It is thread-safe if
multiple simultaneous calls are made to GraphBLAS functions, from user threads
that rely on either OpenMP or POSIX pthreads.  The output variables of those
calls to GraphBLAS must be unique; you cannot safely modify one GraphBLAS
object in parallel, with two or more simultaneous GraphBLAS functions operating
on the same output object.  In addition, all pending operations of objects that
appear in parallel calls to GraphBLAS must be complete.  This can be done for
all objects via \verb'GrB_Matrix_wait', \verb'GrB_Vector_wait', and
\verb'GxB_Scalar_wait', which force completion of a particular object.  If
multiple parallel calls to GraphBLAS functions operate on unique inputs, then
those input objects can safely have pending operations.

% TODO in 4.0: delete this for V4.0 when GrB_wait is removed:
{\bf NOTE: the following will no longer be required in a future version,
when \verb'GrB_wait()' is removed.}

To use GraphBLAS from a multithreaded user application, GraphBLAS requires
access to a critical section for the (now deprecated) \verb'GrB_wait()' queue
of matrices with pending operations, and to a thread-local storage space so
that each user thread can safely retrieve its own error message with
\verb'GrB_error'.  In v4.0, the no-argument \verb'GrB_wait()' function will be
removed, and thus the user-thread-based critical section will be no longer
needed.

SuiteSparse:GraphBLAS supports the following user threading models.  By
default, the \verb'cmake' script detects the presence of OpenMP and POSIX
pthreads.  If OpenMP is present, it uses OpenMP critical sections for
\verb'GrB_wait()' and OpenMP \verb'threadprivate(...)' for thread-local storage
for \verb'GrB_error'.  Otherwise, if POSIX pthreads are available, it uses a
POSIX \verb'mutex', and POSIX thread-local storage via
\verb'pthread_key_create'.

These methods used inside GraphBLAS can typically inter-operate with any user
threading model.  That is, a user application that relies on POSIX threads,
OpenMP, ANSI C11 threads, or Microsoft Windows threads will find GraphBLAS
thread-safe, even though GraphBLAS uses OpenMP or POSIX internally to
synchronize the user threads.  However, for the most reliable results, the
preferred approach is to use the same threading model in GraphBLAS as is used
in the user application.

You can modify the automatic selection of a user thread synchronization model
by adding the following settings for \verb'cmake'.  This setting does not
determine how SuiteSparse:GraphBLAS creates and exploits multiple threads {\em
inside} any given GraphBLAS operation. Rather, it determines which threading
library it will use to synchronize multiple calls to GraphBLAS from more than
one user thread.

\begin{itemize}
\item OpenMP: this is the default if your compiler supports OpenMP.
    It can also be specified with \verb'cmake -DUSER_OPENMP=1' in the
    \verb'cmake' command line.  Internal parallelism in
    SuiteSparse:GraphBLAS version is based on OpenMP.  This is
    typically safe to use with any user threading models.

\item POSIX: this is used if OpenMP is not available.
    If OpenMP is available but you still want GraphBLAS to use POSIX
    synchronization, compile with \verb'cmake -DUSER_POSIX=1'

\item no user threading:  compile with \verb'cmake -DUSER_NONE=1'.
    {\bf GraphBLAS will not be thread-safe}.

\end{itemize}

%----------------------------------------
\subsection{Default matrix format}
%----------------------------------------

By default, SuiteSparse:GraphBLAS stores its matrices by row, using the
\verb'GxB_BY_ROW' format.  You can change the default at compile time to
\verb'GxB_BY_COL' using \verb'cmake -DBYCOL=1'.  For example:

    {\small
    \begin{verbatim}
    cmake -DBYCOL=1 ..  \end{verbatim} }

The user application can also use \verb'GxB_get' and \verb'GxB_set' to set and
query the global option (see also Sections~\ref{gxbset} and \ref{gxbget}):

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

%----------------------------------------
\subsection{Setting the C flags and using CMake}
%----------------------------------------

The above options can also be combined.  For example, to use the \verb'gcc'
compiler, to change the default format \verb'GxB_FORMAT_DEFAULT' to
\verb'GxB_BY_COL', and to use a POSIX mutex inside GraphBLAS to synchronize
user threads, use the following \verb'cmake' command while in the
\verb'GraphBLAS/build' directory:

    {\small
    \begin{verbatim}
    CC=gcc cmake -DBYCOL=1 -DUSER_POSIX=1 .. \end{verbatim}}

\noindent
Then do \verb'make' in the \verb'build' directory.  If this still fails, see
the \verb'CMakeLists.txt' file.  You can edit that file to pass
compiler-specific options to your compiler.  Locate this section in the
\verb'CMakeLists.txt' file.  Use the \verb'set' command in \verb'cmake', as in
the example below, to set the compiler flags you need.

    {\small
    \begin{verbatim}
    # check which compiler is being used.  If you need to make
    # compiler-specific modifications, here is the place to do it.
    if ("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU")
        # cmake 2.8 workaround: gcc needs to be told to do ANSI C11.
        # cmake 3.0 doesn't have this problem.
        set ( CMAKE_C_FLAGS  "${CMAKE_C_FLAGS} -std=c11 -lm " )
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "Intel")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "Clang")
        ...
    elseif ("${CMAKE_C_COMPILER_ID}" STREQUAL "MSVC")
        ...
    endif ( )
    \end{verbatim} }

To compile SuiteSparse:GraphBLAS without running the demos, use \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.

One particularly useful option is the \verb'BURBLE' setting.  It must be
enabled both at compile time and then at run time with \verb'GxB_set'
\verb'(GxB_BURBLE, true)', or \verb'GrB.burble(1)' in the MATLAB interface.  If
enabled, SuiteSparse:GraphBLAS will print out a report as to 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/Generated', 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/Generated'.  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.

%----------------------------------------
\subsection{Using a plain makefile}
%----------------------------------------

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

%----------------------------------------
\subsection{Running the Demos}
%----------------------------------------

By default, \verb'make' in the top-level directory compiles the library
and runs the demos.  You can also run the demos after compiling:

    {\small
    \begin{verbatim}
    cd Demo
    ./demo \end{verbatim} }

The \verb'./demo' command is a script that runs the demos with various input
matrices in the \verb'Demo/Matrix' folder.  The output of the demos will be
compared with expected output files in \verb'Demo/Output'.

%----------------------------------------
\subsection{Installing SuiteSparse:GraphBLAS}
%----------------------------------------

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

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

%----------------------------------------
\subsection{Running the tests}
%----------------------------------------

To run a short test, type \verb'make run' 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 R2017A 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.

\newpage
%-------------------------------------------------------------------------------
\section{Acknowledgments}
%-------------------------------------------------------------------------------

I would like to thank Jeremy Kepner (MIT Lincoln Laboratory Supercomputing
Center), and the GraphBLAS API Committee: Ayd\i n Bulu\c{c} (Lawrence Berkeley
National Laboratory), Timothy G. Mattson (Intel Corporation) Scott McMillan
(Software Engineering Institute at Carnegie Mellon University), Jos\'e Moreira
(IBM Corporation), and Carl Yang (UC Davis), for creating the GraphBLAS
specification and for patiently answering my many questions while I was
implementing it.

I would like to thank Tim Mattson and Henry Gabb, Intel, Inc., for their
collaboration and for the support of Intel.  In particular, I would like to
thank Tim Mattson for parallelizing the merge sort using OpenMP tasks.  The
parallel merge sort is used for \verb'GrB_Matrix_build',
\verb'GrB_Vector_build', and some instances of \verb'GrB_transpose'

I would like to thank John Gilbert (UC Santa Barbara) for our many discussions
on GraphBLAS, and for our decades-long conversation and collaboration on sparse
matrix computations, and sparse matrices in MATLAB in particular.

I would like to thank Cleve Moler (MathWorks) for our many discussions on
MATLAB, and for creating MATLAB in the first place.  Without MATLAB,
SuiteSparse:GraphBLAS would have been impossible to implement and test.

I would like to thank S\'ebastien Villemot (Debian Developer,
\url{http://sebastien.villemot.name}) for helping me with various build issues
and other code issues with GraphBLAS (and all of SuiteSparse) for its packaging
in Debian Linux.

I would like to thank Roi Lipman, Redis Labs (\url{https://redislabs.com}), for
our many discussions on GraphBLAS and its use in RedisGraph
(\url{https://redislabs.com/redis-enterprise/technology/redisgraph/}), a graph
database module for Redis.  Based on SuiteSparse:GraphBLAS, RedisGraph is up
600x faster than the fastest graph databases ({\footnotesize
\url{https://youtu.be/9h3Qco_x0QE} \newline
\url{https://redislabs.com/blog/new-redisgraph-1-0-achieves-600x-faster-performance-graph-databases/}}).

I would like to thank Lucas Jarman, MathWorks (\url{http://mathworks.com}),
for his help in porting GraphBLAS to Microsoft Windows.

SuiteSparse:GraphBLAS was developed with support from
NVIDIA, Intel, MIT Lincoln Lab, Redis Labs, IBM,
and the National Science Foundation (1514406, 1835499).

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

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