Get/Set Proposal (#73)

- Issue BB-28 (#14), BB-27 (#13), BB-13 (#5), BB-7 (#4): We added a capability for meta-data associated with each GraphBLAS  object and the library implementation (the global scope) as well.   This was done through the new `GrB_get` and `GrB_set` methods with `(field, value)` pairs.  We also needed  a new error code for the case where an attempt is made to write to a write-once feild, `GrB_ALREADY_SET`.

- Issue BB-15 (#7), BB-14 (#6): The definition of meta-data on GraphBLAS objects added the ability to interact  directly with the type system behind these objects.  This required the addition of type codes `(GrB_Type_Code)` and the ability to manage the type system through strings.

- We augmented the deserialization method so if passed a type parameter of `GrB_NULL` it will infer type information needed for deserialization of a GraphBLAS matrix.

- We added a new built-in descriptor `GrB_COMP_STRUCTURE` and an explicit reference to the default value of a descriptor field, `GrB_DEFAULT`

---------

Co-authored-by: Jim Kitchen <[email protected]>
Co-authored-by: Tim Davis <[email protected]>
Co-authored-by: tgmattso <[email protected]>
Co-authored-by: Erik Welch <[email protected]>

Author: 5 people

.gitignore

@@ -0,0 +1,12 @@
+graph-api-c/GraphBLAS_API_C.aux
+graph-api-c/GraphBLAS_API_C.fdb_latexmk
+graph-api-c/GraphBLAS_API_C.fls
+graph-api-c/GraphBLAS_API_C.lof
+graph-api-c/GraphBLAS_API_C.log
+graph-api-c/GraphBLAS_API_C.lot
+graph-api-c/GraphBLAS_API_C.out
+graph-api-c/GraphBLAS_API_C.pdf
+graph-api-c/GraphBLAS_API_C.toc
+graph-api-c/GraphBLAS_API_C.synctex.gz
+# Vi
+*.sw?

graph-api-c/GraphBLAS_API_C.tex

@@ -133,11 +133,10 @@
 \title{
 The GraphBLAS C API Specification
 \footnote{Based on \emph{GraphBLAS Mathematics} by Jeremy Kepner}: \\ 
-{\large Version 2.0.1} \\
-{\normalsize \scott{THIS IS A DRAFT VERION. Update acks and remove DRAFT before release.}}
+{\large Version 2.1} \\
 }
 
-\author{Benjamin Brock, Ayd\i n Bulu\c{c}, Timothy Mattson, Scott McMillan, Jos\'e Moreira}
+\author{Benjamin Brock, Ayd\i n Bulu\c{c}, Raye Kimmerer, Jim Kitchen, Manoj Kumar, Timothy Mattson, Scott McMillan, Jos\'e Moreira, Erik Welch}
 
 \date{Generated on \today\ at \currenttime\ EDT}
 
@@ -149,19 +148,18 @@
 
 \vfill
 
-Copyright \copyright\ 2017-2021 Carnegie Mellon University, The Regents 
+Copyright \copyright\ 2017-2023 Carnegie Mellon University, The Regents
 of the University of California, through Lawrence Berkeley National 
 Laboratory (subject to receipt of any required approvals from the 
 U.S. Dept. of Energy), the Regents of the University of California 
 (U.C. Davis and U.C. Berkeley), Intel Corporation, International Business Machines 
-Corporation, and Massachusetts Institute of Technology Lincoln
-Laboratory. 
+Corporation, NVIDIA Corporation, Anaconda Inc., and Massachusetts Institute of Technology. 
 
 Any opinions, findings and conclusions or recommendations expressed in 
 this material are those of the author(s) and do not necessarily reflect 
 the views of the United States Department of Defense, the United States 
 Department of Energy, Carnegie Mellon University, the Regents of the 
-University of California, Intel Corporation, or the IBM Corporation.  
+University of California, Intel Corporation, NVIDIA Corporation, Anaconda Inc., or IBM Corporation.  
 
 NO WARRANTY. THIS MATERIAL IS FURNISHED ON AN AS-IS BASIS. THE COPYRIGHT 
 OWNERS AND/OR AUTHORS MAKE NO WARRANTIES OF ANY KIND, EITHER EXPRESSED 
@@ -225,6 +223,16 @@ \section*{Acknowledgments}
 This document represents the work of the people who have served on the C API
 Subcommittee of the GraphBLAS Forum.
 
+Those who served as C API Subcommittee members for GraphBLAS 2.1 are (in alphabetical order):
+\begin{itemize}
+\item Raye Kimmerer (MIT)
+\item Jim Kitchen (Anaconda)
+\item Manoj Kumar (IBM)   % FIXME
+\item Timothy G. Mattson (Human Learning Group)
+\item Erik Welch (NVIDIA Corporation)
+\end{itemize}
+
+
 Those who served as C API Subcommittee members for GraphBLAS 2.0 are (in alphabetical order):
 \begin{itemize}
 \item Benjamin Brock (UC Berkeley)
@@ -250,10 +258,12 @@ \section*{Acknowledgments}
 \item Intel Corporation
 \item Department of Defense under Contract No. FA8702-15-D-0002 with Carnegie Mellon University for the operation of the Software Engineering Institute [DM-0003727, DM19-0929, DM21-0090]
 \item International Business Machines Corporation
+\item NVIDIA Corporation
+\item Anaconda Inc.
 \end{itemize}
 
 The following people provided valuable input and feedback during the development of the specification (in alphabetical order): David Bader,
-Hollen Barmer, Bob Cook, Tim Davis, Jeremy Kepner, James Kitchen, Peter Kogge, Manoj Kumar, Roi Lipman, Andrew Mellinger, 
+Hollen Barmer, Bob Cook, Tim Davis, Jeremy Kepner, Jim Kitchen, Peter Kogge, Manoj Kumar, Roi Lipman, Andrew Mellinger,
 Maxim Naumov, Nancy M. Ott, Michel Pelletier, Gabor Szarnyas, Ping Tak Peter Tang, Erik Welch, Michael Wolf, Albert-Jan Yzelman.
 \vfill
 \pagebreak
@@ -337,6 +347,7 @@ \section{Object methods}
 This section describes methods that setup and operate on GraphBLAS opaque objects
 but are not part of the the GraphBLAS math specification.
 
+\input{query_methods.tex}
 \input{algebra_methods}
 \input{scalar_methods}
 \input{vector_matrix_methods}

graph-api-c/algebra_methods.tex

@@ -349,7 +349,7 @@ \subsubsection{{\sf Semiring\_new}: Construct a new GraphBLAS semiring}
 
 %-----------------------------------------------------------------------------
 
-\subsubsection{{\sf IndexUnaryOp\_new}: Construct a new GraphBLAS index unary operator \scott{NEW CONTENT}}
+\subsubsection{{\sf IndexUnaryOp\_new}: Construct a new GraphBLAS index unary operator}
 
 Initializes a new GraphBLAS index unary operator with a specified user-defined 
 function and its types (domains).

graph-api-c/appendices.tex

@@ -2,14 +2,44 @@ \chapter{Revision history}
 \label{Chp:RevHistory}
 %--------------------------------------------------------------
 
-Changes in 2.0.1 (Released: \#\# Xxxxx 2022:
+Changes in 2.1.0 (Released: 22 December 2023):    % FIXME
+\begin{itemize}
+\item (Issue BB-28, BB-27, BB-13, BB-7) We added a capability for meta-data associated with each GraphBLAS 
+object and the library implementation (the global scope) as well.   This was done through the new
+{\sf GrB\_get} and {\sf GrB\_set} methods with {({\sf field}, {\sf value})} pairs.  We also needed
+ a new error code for the case where an attempt is made to write to a write-once feild,
+{\sf GrB\_ALREADY\_SET}  
+
+\item (Issue BB-15, BB-14) The definition of meta-data on GraphBLAS objects added the ability to interact 
+directly with the type system behind these objects.  This required the addition of type 
+codes ({\sf GrB\_Type\_Code}) and the ability to manage the type system through strings.
+
+\item We augmented the deserialization method so if passed a type parameter of {\sf GrB\_NULL}
+it will infer type information needed for deserialization of a GraphBLAS matrix.
+
+\item We added a new built-in descriptor  {\sf GrB\_COMP\_STRUCTURE} and an explicit reference
+to the default value of a descriptor field, {\sf GrB\_DEFAULT}.
+
+%%% Originial Text .... <<<< remove once we finalize on the above text>>>>
+%\item Added {\sf GrB\_get} and {\sf GrB\_set} methods, and associated
+%field values to {\sf GrB\_Field}.
+%\item Added {\sf GrB\_Type\_Code}.
+%\item Added {\sf GrB\_DEFAULT}.
+%\item Added {\sf GrB\_COMP\_STRUCTURE}.
+%\item Added {\sf GrB\_ALREADY\_SET}.
+%\item Allow deserialization when input type parameter is NULL.
+\end{itemize}
+
+%--------------------------------------------------------------
+
+Changes in 2.0.1 (Released: 9 December 2022):    % Verify Date
 \begin{itemize}
 \item (Issue GH-69) Fix error in description of contents of matrix constructed from {\sf GrB\_Matrix\_diag}.
 \end{itemize}
 
 %--------------------------------------------------------------
 
-Changes in 2.0.0 (Released: 15 November 2021:
+Changes in 2.0.0 (Released: 15 November 2021):
 \begin{itemize}
 \item Reorganized Chapters 2 and 3: Chapter 2 contains prose regarding the basic concepts captured in the API; Chapter 3 presents all of the enumerations, literals, data types, and predefined objects required by the API.  Made short captions for the List of Tables.
 \item (Issue BB-49, BB-50) Updated and corrected language regarding multithreading and completion, and requirements regarding acquire-release memory orders.  Methods that used to force complete no longer do.

graph-api-c/context_methods.tex

@@ -106,7 +106,7 @@ \subsection{{\sf getVersion}: Get the version number of the standard.}
 \begin{itemize}[leftmargin=1.1in]
 	\item[{\sf version}] ({\sf OUT})  On successful return will hold the value
     of the major version number.
-	\item[{\sf version}] ({\sf OUT})  On successful return will hold the value
+	\item[{\sf subversion}] ({\sf OUT})  On successful return will hold the value
     of the subversion number.
 \end{itemize}
 

graph-api-c/free_methods.tex

@@ -38,7 +38,7 @@ \subsection{{\sf free}: Destroy an object and release its resources}
 so they are available for use by other GraphBLAS objects.
 
 The parameter passed into {\sf GrB\_free} is a handle referencing a
-GraphBLAS opaque object of a data type from table~\ref{Tab:ObjTypes}.
+GraphBLAS opaque object of a data type from Table~\ref{Tab:ObjTypes}.
 The object must have been created by an explicit call to a GraphBLAS
 constructor.  The behavior of a program that calls {\sf GrB\_free}
 on a pre-defined object is implementation defined.