V1.2 documentation plus a few bug fixes

.github/workflows/build-arch-emu.yaml

@@ -1,6 +1,8 @@
 name: arch-emu
 
-# this is done on workflow_dispatch only since it takes a very long time
+# this is done on workflow_dispatch only since it takes a very long time.
+# It also uses the latest GraphBLAS dev2 branch, so be sure that branch
+# is operational before running this test.
 on:
   workflow_dispatch:
 
@@ -18,8 +20,7 @@ jobs:
     strategy:
       matrix:
         config:
-          # FIXME: switch to 10.1.0 when it is released:
-         - {grb_version: 10.0.5}
+         - {grb_version: dev2}
         # For available CPU architectures, see:
         # https://github.com/marketplace/actions/setup-alpine-linux-environment
         arch: [riscv64]
@@ -71,8 +72,6 @@ jobs:
           gcc -dumpmachine
           git clone https://github.com/DrTimothyAldenDavis/GraphBLAS.git
           cd GraphBLAS
-          # FIXME: switch to 10.1.0 when it is released:
-          # git checkout tags/v${{ matrix.config.grb_version }}
           git checkout dev2
           make compact
           sudo make install

.github/workflows/build.yml

@@ -18,9 +18,8 @@ jobs:
         config:
         # if there are multiple items in this list, only use should
         # deployit=true for just one of them.
-        # FIXME: use GraphBLAS v10.1.0 once it's released
          - {grb_version: 9.0.0, deployit: false}
-         - {grb_version: 10.0.5, deployit: true}
+         - {grb_version: 10.1.0, deployit: true}
 
     steps:
 
@@ -69,9 +68,8 @@ jobs:
     strategy:
       matrix:
         config:
-        # FIXME: use GraphBLAS v10.1.0 once it's released
          - {grb_version: 9.0.0}
-         - {grb_version: 10.0.5}
+         - {grb_version: 10.1.0}
 
     steps:
 

Config/LAGraph.h.in

@@ -248,7 +248,7 @@
  *
  * Error handling is simplified by the @sphinxref{LAGRAPH_TRY} / LAGRAPH_CATCH
  * mechanism described below.  For example, assuming the user application
- * #defines a single LAGRAPH_CATCH mechanism for all error handling, the
+ * defines a single LAGRAPH_CATCH mechanism for all error handling, the
  * above example would become:
  *
  *      GrB_Vector level, parent ;
@@ -286,7 +286,7 @@
  * The LAGRAPH_CATCH macro takes a single argument, which is the return value
  * from an LAGraph method.
  *
- * A typical example of a user function that calls LAGraph might #define
+ * A typical example of a user function that calls LAGraph might define
  * LAGRAPH_CATCH as follows.  Suppose workvector is a GrB_vector used for
  * computations internal to the mybfs function, and W is a (double *) space
  * created by malloc.
@@ -844,7 +844,7 @@ LAGRAPH_PUBLIC extern GrB_Semiring
 
 /** LAGraph_Version: determines the version of LAGraph.  The version number and
  * date can also be obtained via compile-time constants from LAGraph.h.
- * However, it is possible to compile a user application that #includes one
+ * However, it is possible to compile a user application that includes one
  * version of LAGraph.h and then links with another version of the LAGraph
  * library later on, so the version number and date may differ from the
  * compile-time constants.
@@ -2056,7 +2056,7 @@ int LAGraph_Vector_IsEqualOp
  * will affect the pseudo-random numbers generated and results are thus not
  * guaranteed in this case.
  *
- * @param[out,out] State vector to initialize with pseudo-random numbers.
+ * @param[in,out] State  vector to initialize with pseudo-random numbers.
  * @param[in] seed       scalar seed value.
  * @param[in,out] msg    any error messages.
  *
@@ -2085,7 +2085,7 @@ int LAGraph_Random_Seed // construct a random State vector
  * https://doi.org/10.18637/jss.v008.i14 and
  * https://en.wikipedia.org/wiki/Xorshift .
  *
- * @param[out,out] State vector with random numbers to be advanced.
+ * @param[in,out] State  vector with random numbers to be advanced.
  * @param[in,out] msg    any error messages.
  *
  * @retval GrB_SUCCESS if successful.

README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://github.com/GraphBLAS/LAGraph/workflows/LAGraph%20CI/badge.svg)](https://github.com/GraphBLAS/LAGraph/actions)
+[![Build Status](https://github.com/GraphBLAS/LAGraph/workflows/LAGraph%20CI%20with%20Builtin%20GraphBLAS/badge.svg)](https://github.com/GraphBLAS/LAGraph/actions)
 [![Documentation Status](https://readthedocs.org/projects/lagraph/badge/?version=latest)](https://lagraph.readthedocs.io/en/latest/?badge=latest)
 
 # LAGraph
@@ -10,7 +10,7 @@ See <https://github.com/GraphBLAS/LAGraph> for the source code for LAGraph,
 Documenation is at <https://lagraph.readthedocs.org>.
 Test coverage results are at <https://graphblas.org/LAGraph>.
 
-Currently, SuiteSparse:GraphBLAS v7.0.0 or later is required.  However, use the
+Currently, SuiteSparse:GraphBLAS v9.0.0 or later is required.  However, use the
 latest stable release of SuiteSparse:GraphBLAS for best results.
 See <https://github.com/DrTimothyAldenDavis/GraphBLAS>
 

experimental/algorithm/LAGr_SwapEdges.c

@@ -765,15 +765,20 @@ int LAGr_SwapEdges
         GRB_TRY (GxB_unload_Vector_into_Container(M, con, NULL)) ;
         GRB_TRY (GrB_free(&(con->b))) ;
         con->b = dup_swaps_v;
+        // n_keep = sum (dup_swaps_v), to count the # of 1's that now appear in
+        // dup_swaps_v, which will become nvals(M) after loading M from the
+        // container con.
+        GRB_TRY (GrB_reduce (&n_keep, NULL, GrB_PLUS_MONOID_UINT64,
+            dup_swaps_v, NULL)) ;
         con->nvals = n_keep;
         con->format = GxB_BITMAP;
         dup_swaps_v = NULL;
         GRB_TRY (GxB_load_Vector_from_Container(M, con, NULL)) ;
+        // GRB_TRY (GxB_print (M, 1)) ; // for debugging; must be OK here
         GRB_TRY (GrB_free(&con)) ;
         GRB_TRY (LAGraph_FastAssign_Semiring(
             E_vec, NULL, second_edge, edge_perm, M, ramp_v, 
             second_second_edge, NULL, msg)) ;
-
 
         n_keep /= 2;
 
@@ -810,6 +815,7 @@ int LAGr_SwapEdges
     LAGRAPH_TRY (LAGraph_New (
         G_new, &A_new, LAGraph_ADJACENCY_UNDIRECTED, msg)) ;
     LG_FREE_WORK ;
+    (*pSwaps) = num_swaps ;
     return (num_swaps >= totSwaps)? GrB_SUCCESS :  LAGRAPH_INSUFFICIENT_SWAPS ;
     #else
     // printf("LAGr_SwapEdges Needs GB v10\n") ;

experimental/algorithm/LAGraph_RichClubCoefficient.c

@@ -298,7 +298,7 @@ int LAGraph_RichClubCoefficient
 
         LG_ASSERT (max_deg == vpd_n && max_deg == epd_n, GrB_INVALID_VALUE) ;
         //run a cummulative sum (backwards) on vpd_arr
-        for(GrB_Index i = max_deg - 1; i > 0; --i)
+        for(int64_t i = max_deg - 1; i > 0; --i)
         {
             vpd_arr[i-1] += vpd_arr[i] ;
             epd_arr[i-1] += epd_arr[i] ;
@@ -358,7 +358,7 @@ int LAGraph_RichClubCoefficient
             vpd_index, vpd_arr, &max_deg, verts_per_deg
         )) ;
         //run a cummulative sum (backwards) on vpd_arr
-        for(GrB_Index i = max_deg - 1; i > 0; --i)
+        for(int64_t i = max_deg - 1; i > 0; --i)
         {
             vpd_arr[i-1] += vpd_arr[i] ;
             epd_arr[i-1] += epd_arr[i] ;

experimental/test/test_SwapEdges.c

@@ -123,6 +123,8 @@ void test_SwapEdges (void)
             //------------------------------------------------------------------
             // check results
             //------------------------------------------------------------------
+            // Check sufficient swaps were performed.
+            TEST_CHECK (pQ >= 100.0) ;
             //Make sure we got a symetric back out:
             OK (LAGraph_CheckGraph (G_new, msg)) ;
 
@@ -305,6 +307,8 @@ void test_SwapEdges_brutal (void)
         //------------------------------------------------------------------
         // check results
         //------------------------------------------------------------------
+        // Check sufficient swaps were performed.
+        TEST_CHECK (pQ >= 1.0) ;
         //Make sure we got a symetric back out:
         LG_BRUTAL_BURBLE (LAGraph_CheckGraph (G_new, msg)) ;
 

experimental/utility/LAGraph_FastAssign.c

@@ -161,8 +161,7 @@ int LAGraph_FastAssign_Semiring
     void *ramp_a = NULL, *i_a =NULL;
     int ramp_h = GrB_DEFAULT, trsp = GrB_DEFAULT, i_h = GrB_DEFAULT;
     uint64_t ramp_n = 0, ramp_size = 0, i_n = 0, i_size= 0;
-    GrB_Type x_type = NULL, i_type = NULL, ramp_type = NULL;
-    bool iso = false;
+    GrB_Type i_type = NULL, ramp_type = NULL;
     //----------------------------------------------------------------------
     // Check inputs
     //----------------------------------------------------------------------
@@ -191,10 +190,6 @@ int LAGraph_FastAssign_Semiring
         GRB_TRY (GrB_Vector_size(&nrows, c)) ;
     }
 
-    GRB_TRY (GrB_Vector_get_INT32(X_vec, (int32_t *) &iso, GxB_ISO)) ;
-
-    GRB_TRY (GxB_Vector_type(&x_type, X_vec));
-
     //----------------------------------------------------------------------
     // Load up containers
     //----------------------------------------------------------------------

include/LAGraph.h

@@ -248,7 +248,7 @@
  *
  * Error handling is simplified by the @sphinxref{LAGRAPH_TRY} / LAGRAPH_CATCH
  * mechanism described below.  For example, assuming the user application
- * #defines a single LAGRAPH_CATCH mechanism for all error handling, the
+ * defines a single LAGRAPH_CATCH mechanism for all error handling, the
  * above example would become:
  *
  *      GrB_Vector level, parent ;
@@ -286,7 +286,7 @@
  * The LAGRAPH_CATCH macro takes a single argument, which is the return value
  * from an LAGraph method.
  *
- * A typical example of a user function that calls LAGraph might #define
+ * A typical example of a user function that calls LAGraph might define
  * LAGRAPH_CATCH as follows.  Suppose workvector is a GrB_vector used for
  * computations internal to the mybfs function, and W is a (double *) space
  * created by malloc.
@@ -844,7 +844,7 @@ LAGRAPH_PUBLIC extern GrB_Semiring
 
 /** LAGraph_Version: determines the version of LAGraph.  The version number and
  * date can also be obtained via compile-time constants from LAGraph.h.
- * However, it is possible to compile a user application that #includes one
+ * However, it is possible to compile a user application that includes one
  * version of LAGraph.h and then links with another version of the LAGraph
  * library later on, so the version number and date may differ from the
  * compile-time constants.
@@ -2056,7 +2056,7 @@ int LAGraph_Vector_IsEqualOp
  * will affect the pseudo-random numbers generated and results are thus not
  * guaranteed in this case.
  *
- * @param[out,out] State vector to initialize with pseudo-random numbers.
+ * @param[in,out] State  vector to initialize with pseudo-random numbers.
  * @param[in] seed       scalar seed value.
  * @param[in,out] msg    any error messages.
  *
@@ -2085,7 +2085,7 @@ int LAGraph_Random_Seed // construct a random State vector
  * https://doi.org/10.18637/jss.v008.i14 and
  * https://en.wikipedia.org/wiki/Xorshift .
  *
- * @param[out,out] State vector with random numbers to be advanced.
+ * @param[in,out] State  vector with random numbers to be advanced.
  * @param[in,out] msg    any error messages.
  *
  * @retval GrB_SUCCESS if successful.

rtdocs/acknowledgements.rst

@@ -9,6 +9,6 @@ This work is funded in part by:
         development center.  [DM22-0790]
     2.  The United States Department of Defense under Contract No.
         FA8650-18-2-7835 and HR0011-18-3-0007
-    3.  NVIDIA, Intel, MIT Lincoln Laboratory, MathWorks, IBM, and Julia Computing.
+    3.  NVIDIA, Intel, MIT Lincoln Laboratory, MathWorks, IBM, Julia Computing, Redis, and FalkorDB.
     4.  The National Science Foundation (1514406, OAC-1740333, CCF-1629657).
     5.  The United States Department of Energy, Office of Science, ASCR Contract No. DE-AC02-05CH11231.

rtdocs/conf.py

@@ -45,7 +45,7 @@ def configureDoxyfile(input_dir, output_dir):
 # -- Project information -----------------------------------------------------
 
 project = 'LAGraph'
-copyright = '2019-2022, LAGraph Contributors'
+copyright = '2019-2025, LAGraph Contributors'
 author = 'Tim Davis, Tim Mattson, Scott McMillan, Jim Kitchen, Erik Welch'
 
 
@@ -85,4 +85,4 @@ def configureDoxyfile(input_dir, output_dir):
 # Breathe Configuration
 breathe_default_project = 'lagraph'
 
-master_doc = 'index'
+master_doc = 'index'

rtdocs/utils.rst

@@ -59,6 +59,13 @@ Printing
 
 .. doxygenenum:: LAGraph_PrintLevel
 
+Matrix/Vector Generation
+------------------------
+
+.. doxygenfunction:: LAGraph_Random_Seed
+
+.. doxygenfunction:: LAGraph_Random_Next
+
 Pre-defined semirings
 ---------------------