Merge pull request #156 from DrTimothyAldenDavis/master

Master

Author: DrTimothyAldenDavis

CMakeLists.txt

@@ -26,7 +26,7 @@ endif ( )
 set ( CMAKE_MACOSX_RPATH TRUE )
 
 # version of SuiteSparse:GraphBLAS
-set ( GraphBLAS_DATE "Aug 6, 2022" )
+set ( GraphBLAS_DATE "Aug 8, 2022" )
 set ( GraphBLAS_VERSION_MAJOR 7 )
 set ( GraphBLAS_VERSION_MINOR 2 )
 set ( GraphBLAS_VERSION_SUB   0 )
@@ -279,7 +279,7 @@ if ( "${CMAKE_C_COMPILER_ID}" STREQUAL "GNU" )
     # integer operations wrap
     set ( CMAKE_C_FLAGS  "${CMAKE_C_FLAGS} -fwrapv " )
     # check all warnings (uncomment for development only)
-#   set ( CMAKE_C_FLAGS  "${CMAKE_C_FLAGS} -Wall -Wextra -Wpedantic -Werror " )
+#   set ( CMAKE_C_FLAGS  "${CMAKE_C_FLAGS} -Wall -Wextra -Wpedantic " )
     if ( CMAKE_C_COMPILER_VERSION VERSION_LESS 4.9 )
         message ( FATAL_ERROR "gcc version must be at least 4.9" )
     endif ( )

Config/GraphBLAS.h.in

@@ -471,7 +471,7 @@ GrB_Info GrB_getVersion         // runtime access to C API version number
 //      done, and this setting has no effect.
 //
 // GxB_COMPRESSION: compression method for GxB_Matrix_serialize and
-//      GxB_Vector_serialize.  The default is LZ4.
+//      GxB_Vector_serialize.  The default is ZSTD (level 1).
 //
 // GxB_IMPORT:  GxB_FAST_IMPORT (faster, for trusted input data) or
 //      GxB_SECURE_IMPORT (slower, for untrusted input data), for the
@@ -11372,46 +11372,29 @@ GrB_Info GrB_Matrix_exportHint  // suggest the best export format
 
 // Currently implemented: no compression, LZ4, LZ4HC, and ZSTD
 #define GxB_COMPRESSION_NONE -1     // no compression
-#define GxB_COMPRESSION_DEFAULT 0   // LZ4
+#define GxB_COMPRESSION_DEFAULT 0   // ZSTD (level 1)
 #define GxB_COMPRESSION_LZ4   1000  // LZ4
 #define GxB_COMPRESSION_LZ4HC 2000  // LZ4HC, with default level 9
-#define GxB_COMPRESSION_ZSTD  3000  // ZSTD, with default level 6
+#define GxB_COMPRESSION_ZSTD  3000  // ZSTD, with default level 1
 
-// possible future methods that could be added:
-// #define GxB_COMPRESSION_LZO   4000  // LZO, with default level 2
-// #define GxB_COMPRESSION_BZIP2 5000  // BZIP2, with default level 9
-// #define GxB_COMPRESSION_LZSS  6000  // LZSS
-// #define GxB_COMPRESSION_ZLIB  7000  // ZLIB, with default level 6
-// ...
-
-// using the Intel IPP versions, if available (not yet supported);
-#define GxB_COMPRESSION_INTEL   1000000
+#define GxB_COMPRESSION_INTEL   1000000 // not yet supported
 
 // Most of the above methods have a level parameter that controls the tradeoff
 // between run time and the amount of compression obtained.  Higher levels
 // result in a more compact result, at the cost of higher run time:
 
 //  LZ4     no level setting
 //  LZ4HC   1: fast, 9: default, 9: max
-//  ZSTD:   1: fast, 3: default, 19: max
-
-//  these methos are not yet supported but may be added in the future:
-//  ZLIB    1: fast, 6: default, 9: max
-//  LZO     1: fast (X1ST), 2: default (XST)
-//  BZIP2   1: fast, 9: default, 9: max
-//  LZSS    no level setting
+//  ZSTD:   1: fast, 1: default, 19: max
 
 // For all methods, a level of zero results in the default level setting.
 // These settings can be added, so to use LZ4HC at level 5, use method =
 // GxB_COMPRESSION_LZ4HC + 5.
 
 // If the level setting is out of range, the default is used for that method.
 // If the method is negative, no compression is performed.  If the method is
-// positive but unrecognized, the default is used (GxB_COMPRESSION_LZ4, with no
-// level setting, and the non-Intel version).
-
-// If a method is not implemented, LZ4 is used instead, and the level setting
-// is ignored.
+// positive but unrecognized, the default is used (GxB_COMPRESSION_ZSTD,
+// level 1).
 
 GB_PUBLIC
 GrB_Info GxB_Matrix_serialize       // serialize a GrB_Matrix to a blob
@@ -11590,6 +11573,7 @@ GrB_Info GxB_Matrix_sort
 // The format of the input matrix (by row or by column) is unchanged; this
 // format need not match the by_col input parameter.
 
+GB_PUBLIC
 GrB_Info GxB_Matrix_reshape     // reshape a GrB_Matrix in place
 (
     // input/output:
@@ -11609,6 +11593,7 @@ GrB_Info GxB_Matrix_reshape     // reshape a GrB_Matrix in place
 // determines the format of the output matrix C, which need not match the
 // by_col input parameter.
 
+GB_PUBLIC
 GrB_Info GxB_Matrix_reshapeDup // reshape a GrB_Matrix into another GrB_Matrix
 (
     // output:

Doc/ChangeLog

@@ -1,9 +1,10 @@
-Version 7.2.0, Aug 6, 2022
+Version 7.2.0, Aug 8, 2022
 
     * added ZSTD as a compression option for serialize/deserialize:
         Version 1.5.3 by Yann Collet, https://github.com/facebook/zstd.git
         Copyright (c) 2016-present, Facebook, Inc. All rights reserved.
         Included in SuiteSparse:GraphBLAS via its BSD-3-clause license.
+        The default method is now ZSTD, level 1.
     * added GxB_Matrix_reshape and GxB_Matrix_reshapeDup
     * MATLAB interface: faster C(:)=A, C=A(:), and reshape.
         Better error messages.

Doc/GraphBLAS_UserGuide.pdf

@@ -5452,9 +5452,10 @@ \subsection{Serialize/deserialize methods}
 allocated by the user application, and it must be large enough to hold the
 matrix or vector.
 
-By default, LZ4 compression is used for serialization, but other options can be
-selected via the descriptor: \verb'GxB_set (desc, GxB_COMPRESSION, method)',
-where \verb'method' is an integer selected from the following options:
+By default, ZSTD (level 1) compression is used for serialization, but other
+options can be selected via the descriptor:
+\verb'GxB_set (desc, GxB_COMPRESSION, method)', where \verb'method' is an
+integer selected from the following options:
 
 \vspace{0.2in}
 {\footnotesize
@@ -5463,10 +5464,10 @@ \subsection{Serialize/deserialize methods}
 method                           &  description \\
 \hline
 \verb'GxB_COMPRESSION_NONE'      &  no compression \\
-\verb'GxB_COMPRESSION_DEFAULT'   &  LZ4 \\
+\verb'GxB_COMPRESSION_DEFAULT'   &  ZSTD, with default level 1 \\
 \verb'GxB_COMPRESSION_LZ4'       &  LZ4 \\
 \verb'GxB_COMPRESSION_LZ4HC'     &  LZ4HC, with default level 9 \\
-\verb'GxB_COMPRESSION_ZSTD'      &  ZSTD, with default level 3 \\
+\verb'GxB_COMPRESSION_ZSTD'      &  ZSTD, with default level 1 \\
 \hline
 \end{tabular} }
 \vspace{0.2in}
@@ -5480,7 +5481,7 @@ \subsection{Serialize/deserialize methods}
     \begin{verbatim}
     GxB_set (desc, GxB_COMPRESSION, GxB_COMPRESSION_LZ4HC + 6) ; \end{verbatim}}
 
-The ZSTD method can be specified as level 1 to 19, with 3 being the default.
+The ZSTD method can be specified as level 1 to 19, with 1 being the default.
 To compress with ZSTD at level 6, use:
 
     {\footnotesize
@@ -5580,7 +5581,7 @@ \subsection{Serialize/deserialize methods}
 % On output, it is reduced to the numbed of bytes actually used to serialize
 % the vector.  After calling \verb'GrB_Vector_serialize', the blob may be
 % \verb'realloc''d to this revised size if desired (this is optional).
-% LZ4 compression is used to construct a compact blob.
+% ZSTD (level 1) compression is used to construct a compact blob.
 
 %-------------------------------------------------------------------------------
 \subsubsection{{\sf GxB\_Vector\_serialize:}      serialize a vector}
@@ -5605,10 +5606,9 @@ \subsubsection{{\sf GxB\_Vector\_serialize:}      serialize a vector}
 
 \verb'GxB_Vector_serialize' serializes a vector into a single array of bytes
 (the blob), which is \verb'malloc''ed and filled with the serialized vector.
-By default, LZ4 compression is used, but other options can be selected
-via the descriptor.
-Serializing a vector is identical to serializing a matrix;
-see Section \ref{matrix_serialize_GxB} for more information.
+By default, ZSTD (level 1) compression is used, but other options can be
+selected via the descriptor.  Serializing a vector is identical to serializing
+a matrix; see Section \ref{matrix_serialize_GxB} for more information.
 
 \newpage
 %-------------------------------------------------------------------------------
@@ -5728,7 +5728,7 @@ \subsubsection{{\sf GrB\_Matrix\_serialize:}      serialize a matrix}
 On output, it is reduced to the numbed of bytes actually used to serialize
 the matrix.  After calling \verb'GrB_Matrix_serialize', the blob may be
 \verb'realloc''d to this revised size if desired (this is optional).
-LZ4 compression is used to construct a compact blob.
+ZSTD (level 1) compression is used to construct a compact blob.
 
 %-------------------------------------------------------------------------------
 \subsubsection{{\sf GxB\_Matrix\_serialize:}      serialize a matrix}
@@ -5753,7 +5753,7 @@ \subsubsection{{\sf GxB\_Matrix\_serialize:}      serialize a matrix}
 
 \verb'GxB_Matrix_serialize' is identical to \verb'GrB_Matrix_serialize', except
 that it does not require a pre-allocated blob.  Instead, it allocates the blob
-internally, and fills it with the serialized matrix.  By default, LZ4
+internally, and fills it with the serialized matrix.  By default, ZSTD (level 1)
 compression is used, but other options can be selected via the descriptor.
 
 The blob is allocated with the \verb'malloc' function passed to
@@ -7676,8 +7676,8 @@ \subsection{GraphBLAS descriptors: {\sf GrB\_Descriptor}} %=====================
     value will inform the matrix multiplication to sort its result, instead.
 
 \item \verb'GxB_COMPRESSION' selects the compression method for serialization.
-    The default is LZ4.  See Section~\ref{serialize_deserialize} for other
-    options.
+    The default is ZSTD (level 1).  See Section~\ref{serialize_deserialize} for
+    other options.
 
 \item \verb'GxB_IMPORT' informs the \verb'GxB' pack methods
     that they can trust their input data, or not.  The default is to trust
@@ -15331,14 +15331,15 @@ \section{Release Notes}
 
 \begin{itemize}
 
-\item Version 7.2.0 (Aug 6, 2022)
+\item Version 7.2.0 (Aug 8, 2022)
 
     \begin{packed_itemize}
     \item added ZSTD as a compression option for serialize/deserialize:
         Version 1.5.3 by Yann Collet,
         \url{https://github.com/facebook/zstd.git}.
         Copyright (c) 2016-present, Facebook, Inc. All rights reserved.
         Included in SuiteSparse:GraphBLAS via its BSD-3-clause license.
+        The default method is now ZSTD, level 1.
     \item \verb'GxB_Matrix_reshape*' added.
     \item MATLAB interface: \verb'reshape', \verb'C(:)=A', \verb'C=A(:)' are
         faster.  Better error messages.

Doc/GraphBLAS_UserGuide.tex

@@ -1,5 +1,5 @@
 % version of SuiteSparse:GraphBLAS
 \date{VERSION
 7.2.0,
-Aug 6, 2022}
+Aug 8, 2022}
 

Doc/GraphBLAS_version.tex

@@ -49,16 +49,17 @@ void mexFunction
         {
             method = GxB_COMPRESSION_NONE ;
         }
-        else if (MATCH (method_name, "default") || MATCH (method_name, "lz4"))
+        else if (MATCH (method_name, "lz4"))
         { 
             method = GxB_COMPRESSION_LZ4 ;
         }
         else if (MATCH (method_name, "lz4hc"))
         { 
             method = GxB_COMPRESSION_LZ4HC ;
         }
-        else if (MATCH (method_name, "zstd"))
+        else if (MATCH (method_name, "default") || MATCH (method_name, "zstd"))
         {
+            // the default is ZSTD, with level 1
             method = GxB_COMPRESSION_ZSTD ;
         }
         else if (MATCH (method_name, "debug"))

GraphBLAS/@GrB/private/mexfunctions/gbserialize.c

@@ -12,23 +12,23 @@
 % more compact blob at the cost of higher run time.  Levels outside
 % the allowable range are changed to the default level.
 %
-%   'lz4'    LZ4, with no level setting.  This is the default if the
-%            method is not specified.  Very fast with good compression.
-%            For large problems, lz4 can be faster than no compression,
-%            and it cuts the size of the blob by about 3x on average.
+%   'zstd'  ZSTD.  The level can be 1 to 19 with 1 the default.
+%           This is the default method if no method is specified.
 %
-%   'none'   no compression.
+%   'lz4'   LZ4, with no level setting. Fast with decent compression.
+%           For large problems, lz4 can be faster than no compression,
+%           and it cuts the size of the blob by about 3x on average.
 %
-%   'lz4hc'  LZ4HC, much slower than LZ4 but results in a more compact blob.
-%            The level can be 1 to 9 with 9 the default.  LZ4HC level 1
-%            provides excellent compression compared with LZ4, and higher
-%            levels of LZ4HC only slightly improve compression quality.
+%   'none'  no compression.
 %
-%   'zstd'   ZSTD.  The level can be 1 to 19 with 3 the default.
+%   'lz4hc' LZ4HC, much slower than LZ4 but results in a more compact blob.
+%           The level can be 1 to 9 with 9 the default.  LZ4HC level 1
+%           provides excellent compression compared with LZ4, and higher
+%           levels of LZ4HC only slightly improve compression quality.
 %
 % Example:
 %   G = GrB (magic (5))
-%   blob = GrB.serialize (G) ;      % compressed via LZ4
+%   blob = GrB.serialize (G) ;      % compressed via ZSTD, level 1
 %   f = fopen ('G.bin', 'wb') ;
 %   fwrite (f, blob) ;
 %   fclose (f)

GraphBLAS/@GrB/serialize.m

@@ -31,7 +31,7 @@ set ( CMAKE_MACOSX_RPATH TRUE )
 # version must match ../CMakeLists.txt:
 
 # version of SuiteSparse:GraphBLAS
-set ( GraphBLAS_DATE "Aug 6, 2022" )
+set ( GraphBLAS_DATE "Aug 8, 2022" )
 set ( GraphBLAS_VERSION_MAJOR 7 )
 set ( GraphBLAS_VERSION_MINOR 2 )
 set ( GraphBLAS_VERSION_SUB   0 )