Skip to content

Commit

Permalink
Merge pull request #202 from DrTimothyAldenDavis/v742
Browse files Browse the repository at this point in the history 
GraphBLAS v7.4.2.beta2: NTHREADS and CHUNK in descriptor is deprecated
  • Loading branch information
@DrTimothyAldenDavis
DrTimothyAldenDavis authored Jan 17, 2023
2 parents 88c4796 + f5c17f3 commit e3d14bc
Show file tree
Hide file tree
Showing 7 changed files with 55 additions and 143 deletions.
43 changes: 10 additions & 33 deletions Config/GraphBLAS.h.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -425,16 +425,6 @@ GrB_Info GrB_getVersion // runtime access to C API version number
//
// GrB_INP1: the same as GrB_INP0 but for the second input
//
// GxB_NTHREADS: the maximum number of threads to use in the current method.
// If <= GxB_DEFAULT (which is zero), then the number of threads is
// determined automatically. This is the default value.
//
// GxB_CHUNK: an integer parameter that determines the number of threads to use
// for a small problem. If w is the work to be performed, and chunk is
// the value of this parameter, then the # of threads is limited to floor
// (w/chunk). The default chunk is currently 64K, but this may change in
// the future. If chunk is set to <= GxB_DEFAULT (that is, zero), the
// default is used.
//
// GxB_AxB_METHOD: this is a hint to SuiteSparse:GraphBLAS on which algorithm
// it should use to compute C=A*B, in GrB_mxm, GrB_mxv, and GrB_vxm.
Expand Down Expand Up @@ -499,12 +489,9 @@ typedef enum
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, // max number of threads to use.
// If <= GxB_DEFAULT, then GraphBLAS selects the number
// of threads automatically.

GxB_DESCRIPTOR_CHUNK = GxB_CHUNK, // chunk size for small problems.
// If <= GxB_DEFAULT, then the default is used.
// setting NTHREADS and CHUNK in the descriptor is deprecated
GxB_DESCRIPTOR_NTHREADS = GxB_NTHREADS, // DEPRECATED
GxB_DESCRIPTOR_CHUNK = GxB_CHUNK, // DEPRECATED

// GPU control (DRAFT: in progress, do not use)
GxB_DESCRIPTOR_GPU_CONTROL = GxB_GPU_CONTROL,
Expand Down Expand Up @@ -4089,7 +4076,7 @@ GrB_Info GxB_Matrix_diag // construct a diagonal matrix from a vector
GrB_Matrix C, // output matrix
const GrB_Vector v, // input vector
int64_t k,
const GrB_Descriptor desc // to specify # of threads
const GrB_Descriptor desc
) ;

// GxB_Vector_diag extracts a vector v from an input matrix A, which may be
Expand Down Expand Up @@ -4481,8 +4468,7 @@ GrB_Info GxB_Global_Option_get_FUNCTION // gets the current global option

// GxB_set and GxB_get are generic methods that and set or query the options in
// a GrB_Matrix, a GrB_Descriptor, or in the global options. They can be used
// with the following syntax. Note that GxB_NTHREADS can be used for both the
// global nthreads_max, and for the # of threads in the descriptor.
// with the following syntax.

// To set/get the global options:
//
Expand Down Expand Up @@ -4586,12 +4572,6 @@ GrB_Info GxB_Global_Option_get_FUNCTION // gets the current global option
// 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, nthreads) ;
// GxB_get (GrB_Descriptor d, GxB_NTHREADS, int *nthreads) ;
//
// GxB_set (GrB_Descriptor d, GxB_CHUNK, double chunk) ;
// GxB_get (GrB_Descriptor d, GxB_CHUNK, double *chunk) ;
//
// GxB_set (GrB_Descriptor d, GxB_SORT, int sort) ;
// GxB_get (GrB_Descriptor d, GxB_SORT, int *sort) ;
//
Expand Down Expand Up @@ -10964,7 +10944,6 @@ GrB_Info GxB_Matrix_serialize // serialize a GrB_Matrix to a blob
// input:
GrB_Matrix A, // matrix to serialize
const GrB_Descriptor desc // descriptor to select compression method
// and to control # of threads used
) ;

GrB_Info GrB_Matrix_serialize // serialize a GrB_Matrix to a blob
Expand All @@ -10986,7 +10965,6 @@ GrB_Info GxB_Vector_serialize // serialize a GrB_Vector to a blob
// input:
GrB_Vector u, // vector to serialize
const GrB_Descriptor desc // descriptor to select compression method
// and to control # of threads used
) ;

GrB_Info GrB_Matrix_serializeSize // estimate the size of a blob
Expand All @@ -10999,8 +10977,7 @@ GrB_Info GrB_Matrix_serializeSize // estimate the size of a blob
) ;

// The GrB* and GxB* deserialize methods are nearly identical. The GxB*
// deserialize methods simply add the descriptor, which allows for optional
// control of the # of threads used to deserialize the blob.
// deserialize methods simply add the descriptor.

GrB_Info GxB_Matrix_deserialize // deserialize blob into a GrB_Matrix
(
Expand All @@ -11013,7 +10990,7 @@ GrB_Info GxB_Matrix_deserialize // deserialize blob into a GrB_Matrix
// type of C.
const void *blob, // the blob
GrB_Index blob_size, // size of the blob
const GrB_Descriptor desc // to control # of threads used
const GrB_Descriptor desc
) ;

GrB_Info GrB_Matrix_deserialize // deserialize blob into a GrB_Matrix
Expand All @@ -11040,7 +11017,7 @@ GrB_Info GxB_Vector_deserialize // deserialize blob into a GrB_Vector
// type of w.
const void *blob, // the blob
GrB_Index blob_size, // size of the blob
const GrB_Descriptor desc // to control # of threads used
const GrB_Descriptor desc
) ;

// GxB_deserialize_type_name extracts the type_name of the GrB_Type of the
Expand Down Expand Up @@ -11131,7 +11108,7 @@ GrB_Info GxB_Matrix_reshape // reshape a GrB_Matrix in place
bool by_col, // true if reshape by column, false if by row
GrB_Index nrows_new, // new number of rows of C
GrB_Index ncols_new, // new number of columns of C
const GrB_Descriptor desc // to control # of threads used
const GrB_Descriptor desc
) ;

// GxB_Matrix_reshapeDup reshapes a matrix into another matrix.
Expand All @@ -11151,7 +11128,7 @@ GrB_Info GxB_Matrix_reshapeDup // reshape a GrB_Matrix into another GrB_Matrix
bool by_col, // true if reshape by column, false if by row
GrB_Index nrows_new, // number of rows of C
GrB_Index ncols_new, // number of columns of C
const GrB_Descriptor desc // to control # of threads used
const GrB_Descriptor desc
) ;

//==============================================================================
Expand Down
4 changes: 4 additions & 0 deletions Doc/ChangeLog
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
Version 7.4.2, Jan 17, 2023

* minor change to build system: for SuiteSparse v7.0.0
* deprecation notice: in GraphBLAS v8.0.0, the ability to set the
# of threads, and chunk size, in the descriptor will be removed.
It still appears in v7.x, but will be replaced by a Context object
in v8.0.0.

Version 7.4.1, Jan 9, 2023

Expand Down
Binary file modified Doc/GraphBLAS_UserGuide.pdf
View file
Binary file not shown.
87 changes: 21 additions & 66 deletions Doc/GraphBLAS_UserGuide.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5163,7 +5163,7 @@ \subsubsection{{\sf GxB\_Matrix\_reshape:} reshape a matrix}
bool by_col, // true if reshape by column, false if by row
GrB_Index nrows_new, // new number of rows of C
GrB_Index ncols_new, // new number of columns of C
const GrB_Descriptor desc // to control # of threads used
const GrB_Descriptor desc
) ;
\end{verbatim} } \end{mdframed}

Expand Down Expand Up @@ -5217,7 +5217,7 @@ \subsubsection{{\sf GxB\_Matrix\_reshapeDup:} reshape a matrix}
bool by_col, // true if reshape by column, false if by row
GrB_Index nrows_new, // number of rows of C
GrB_Index ncols_new, // number of columns of C
const GrB_Descriptor desc // to control # of threads used
const GrB_Descriptor desc
) ;
\end{verbatim} } \end{mdframed}

Expand Down Expand Up @@ -5601,7 +5601,6 @@ \subsubsection{{\sf GxB\_Vector\_serialize:} serialize a vector}
// input:
GrB_Vector u, // vector to serialize
const GrB_Descriptor desc // descriptor to select compression method
// and to control # of threads used
) ;
\end{verbatim}
} \end{mdframed}
Expand Down Expand Up @@ -5656,7 +5655,7 @@ \subsubsection{{\sf GxB\_Vector\_deserialize:} deserialize a vector}
GrB_Type type, // type of the vector w. See GxB_Matrix_deserialize.
const void *blob, // the blob
GrB_Index blob_size, // size of the blob
const GrB_Descriptor desc // to control # of threads used
const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}
Expand Down Expand Up @@ -5748,7 +5747,6 @@ \subsubsection{{\sf GxB\_Matrix\_serialize:} serialize a matrix}
// input:
GrB_Matrix A, // matrix to serialize
const GrB_Descriptor desc // descriptor to select compression method
// and to control # of threads used
) ;
\end{verbatim}
} \end{mdframed}
Expand Down Expand Up @@ -5817,7 +5815,7 @@ \subsubsection{{\sf GxB\_Matrix\_deserialize:} deserialize a matrix}
// type of C.
const void *blob, // the blob
GrB_Index blob_size, // size of the blob
const GrB_Descriptor desc // to control # of threads used
const GrB_Descriptor desc
) ;
\end{verbatim}
} \end{mdframed}
Expand Down Expand Up @@ -7598,16 +7596,14 @@ \subsection{GraphBLAS descriptors: {\sf GrB\_Descriptor}} %=====================
\begin{mdframed}[userdefinedwidth=6in]
{\footnotesize
\begin{verbatim}
#define GxB_NTHREADS 5 // for both GrB_Desc_field and GxB_Option_field
#define GxB_NTHREADS 5 // for GxB_Option_field
#define GxB_CHUNK 7
typedef enum
{
GrB_OUTP = 0, // descriptor for output of a method
GrB_MASK = 1, // descriptor for the mask input of a method
GrB_INP0 = 2, // descriptor for the first input of a method
GrB_INP1 = 3, // descriptor for the second input of a method
GxB_DESCRIPTOR_NTHREADS = GxB_NTHREADS, // number of threads to use
GxB_DESCRIPTOR_CHUNK = GxB_CHUNK, // chunk size for small problems
GxB_AxB_METHOD = 1000, // descriptor for selecting C=A*B algorithm
GxB_SORT = 35 // control sort in GrB_mxm
GxB_COMPRESSION = 36, // select compression for serialize
Expand Down Expand Up @@ -7775,17 +7771,12 @@ \subsection{GraphBLAS descriptors: {\sf GrB\_Descriptor}} %=====================

\end{itemize}

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

\item \verb'GxB_CHUNK' is a \verb'double' value that controls how many threads
a method uses for small problems. See Section~\ref{omp_parallelism} for
details.
\item \verb'GxB_CHUNK' is deprecated as used in the descriptor.
It will be removed from the descriptor entirely in v8.0.0.

\item \verb'GxB_SORT' provides a hint to \verb'GrB_mxm', \verb'GrB_mxv',
\verb'GrB_vxm', and \verb'GrB_reduce' (to vector). These methods can leave
Expand Down Expand Up @@ -7894,7 +7885,7 @@ \subsubsection{{\sf GrB\_Descriptor\_set:} set a parameter in a descriptor}
\verb'GrB_Descriptor_set' sets a descriptor field (\verb'GrB_OUTP',
\verb'GrB_MASK', \verb'GrB_INP0', \verb'GrB_INP1', or \verb'GxB_AxB_METHOD') to
a particular value. Use \verb'GxB_Dec_set' to set the value of
\verb'GxB_NTHREADS', \verb'GxB_CHUNK', and \verb'GxB_SORT'.
\verb'GxB_SORT'.
If an error occurs, \verb'GrB_error(&err,desc)' returns details about the error.

\vspace{0.2in}
Expand Down Expand Up @@ -8046,16 +8037,6 @@ \subsubsection{{\sf GrB\_DESC\_*:} built-in descriptors}
Attempts to modify them result in an error (\verb'GrB_INVALID_VALUE'); attempts
to free them are silently ignored.

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

\vspace{0.2in}
\noindent
{\footnotesize
Expand Down Expand Up @@ -8394,10 +8375,6 @@ \section{SuiteSparse:GraphBLAS Options} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\verb'GrB_MASK' & \verb'GrB_Desc_Value' & mask option \\
\verb'GrB_INP0' & \verb'GrB_Desc_Value' & transpose input 0 \\
\verb'GrB_INP1' & \verb'GrB_Desc_Value' & transpose input 1 \\
\verb'GxB_DESCRIPTOR_NTHREADS' & \verb'int' & number of threads to use \\
\verb'GxB_NTHREADS' & \verb'int' & number of threads to use \\
\verb'GxB_DESCRIPTOR_CHUNK' & \verb'double' & chunk size \\
\verb'GxB_CHUNK' & \verb'double' & chunk size \\
\verb'GxB_AxB_METHOD' & \verb'int' & method for matrix multiply \\
\verb'GxB_SORT' & \verb'int' & lazy vs aggressive sort \\
\verb'GxB_COMPRESSION' & \verb'int' & compression for serialization \\
Expand Down Expand Up @@ -8495,10 +8472,6 @@ \section{SuiteSparse:GraphBLAS Options} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\verb'GrB_MASK' & \verb'GrB_Desc_Value' & mask option \\
\verb'GrB_INP0' & \verb'GrB_Desc_Value' & transpose input 0 \\
\verb'GrB_INP1' & \verb'GrB_Desc_Value' & transpose input 1 \\
\verb'GxB_DESCRIPTOR_NTHREADS' & \verb'int' & number of threads to use \\
\verb'GxB_NTHREADS' & \verb'int' & number of threads to use \\
\verb'GxB_DESCRIPTOR_CHUNK' & \verb'double' & chunk size \\
\verb'GxB_CHUNK' & \verb'double' & chunk size \\
\verb'GxB_AxB_METHOD' & \verb'int' & method for matrix multiply \\
\verb'GxB_SORT' & \verb'int' & lazy vs aggressive sort \\
\verb'GxB_COMPRESSION' & \verb'int' & compression for serialization \\
Expand Down Expand Up @@ -8544,19 +8517,9 @@ \subsection{OpenMP parallelism}
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} }
\item Per operation: Setting the number of threads and the chunk
size in the descriptor is deprecated.
It will be removed entirely in v8.0.0 from the descriptor.

\end{itemize}

Expand All @@ -8568,15 +8531,9 @@ \subsection{OpenMP parallelism}
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.
threads, not eight.

GraphBLAS may be compiled without OpenMP, by setting \verb'-DNOPENMP=1'.
The library will be thread-safe, with one exception. \verb'GrB_wait' is
Expand Down Expand Up @@ -9145,8 +9102,8 @@ \subsection{{\sf GxB\_Desc\_set:} set a {\sf GrB\_Descriptor} value}

This usage is similar to \verb'GrB_Descriptor_set', just with a name that is
consistent with the other usages of this generic function. Unlike
\verb'GrB_Descriptor_set', the \verb'field' may also be \verb'GxB_NTHREADS',
\verb'GxB_CHUNK', \verb'GxB_SORT', \verb'GxB_COMPRESSION', or
\verb'GrB_Descriptor_set', the \verb'field' may also be
\verb'GxB_SORT', \verb'GxB_COMPRESSION', or
\verb'GxB_IMPORT'. Refer to Sections~\ref{descriptor_set}~and~\ref{desc_set}
for details. If an error occurs, \verb'GrB_error(&err,desc)' returns details
about the error.
Expand Down Expand Up @@ -9333,8 +9290,6 @@ \subsection{{\sf GxB\_Desc\_get:} retrieve a {\sf GrB\_Descriptor} value}
This usage is the same as \verb'GxB_Desc_get'. The \verb'field' parameter can
be \verb'GrB_OUTP', \verb'GrB_MASK', \verb'GrB_INP0', \verb'GrB_INP1',
\verb'GxB_AxB_METHOD',
\verb'GxB_NTHREADS',
\verb'GxB_CHUNK',
\verb'GxB_SORT',
\verb'GxB_COMPRESSION', or
\verb'GxB_IMPORT'.
Expand Down Expand Up @@ -9458,10 +9413,6 @@ \subsection{Summary of usage of {\sf GxB\_set} and {\sf GxB\_get}}
GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_SAXPY) ;
GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_DOT) ;
GxB_get (GrB_Descriptor d, GrB_AxB_METHOD, GrB_Desc_Value *v) ;
GxB_set (GrB_Descriptor d, GxB_NTHREADS, int nthreads) ;
GxB_get (GrB_Descriptor d, GxB_NTHREADS, int *nthreads) ;
GxB_set (GrB_Descriptor d, GxB_CHUNK, double chunk) ;
GxB_get (GrB_Descriptor d, GxB_CHUNK, double *chunk) ;
GxB_set (GrB_Descriptor d, GxB_SORT, sort) ;
GxB_get (GrB_Descriptor d, GxB_SORT, int *sort) ;
GxB_set (GrB_Descriptor d, GxB_COMPRESSION, GxB_FAST_IMPORT) ;
Expand Down Expand Up @@ -15542,6 +15493,10 @@ \section{Release Notes}

\begin{itemize}
\item minor change to build system: for SuiteSparse v7.0.0.
\item deprecation notice: in GraphBLAS v8.0.0, the ability to set the
number of threads, and chunk size, in the descriptor will be removed.
It still appears in v7.x, but will be replaced by a Context object
in v8.0.0.
\end{itemize}

\item Version 7.4.1 (Dec 29, 2022)
Expand Down
Loading

0 comments on commit e3d14bc

Please sign in to comment.