revise random number generator; move LAGraph_Random.c to src/utility

DrTimothyAldenDavis · DrTimothyAldenDavis · commit e7431130a188 · 2025-04-30T14:08:27.000-05:00
diff --git a/config/LAGraph.h.in b/config/LAGraph.h.in
@@ -2021,6 +2021,58 @@ int LAGraph_Vector_IsEqualOp
     char *msg
 ) ;
 
+//------------------------------------------------------------------------------
+// Random number generator
+//------------------------------------------------------------------------------
+
+// FIXME: rename these methods?  Rename the vector "Seed" to "State".
+
+/** LAGraph_Random_Seed creates a random vector.  On input, its values are
+ * ignored but its structure is used.  On output, all entries that were in
+ * the original structure are assigned random values, depending on the scalar
+ * seed value.  Each entry is considered its own pseudo-random number stream,
+ * with the overall seed value being revised for each entry in the vector,
+ * depending on their index in the vector.
+ *
+ * @param[out,out] Seed vector to initialize with random numbers.
+ * @param[in] seed      scalar seed value.
+ * @param[in,out] msg   any error messages.
+ *
+ * @retval GrB_SUCCESS if successful.
+ * @retval GrB_NULL_POINTER if Seed is NULL.
+ * @returns any GraphBLAS errors that may have been encountered.
+ */
+
+LAGRAPH_PUBLIC
+int LAGraph_Random_Seed     // construct a random seed vector
+(
+    // input/output:
+    GrB_Vector Seed,    // vector of random number seeds, normally GrB_UINT64
+    // input:
+    uint64_t seed,      // scalar input seed
+    char *msg
+) ;
+
+/** LAGraph_Random_Next takes as input a vector previously initialized by
+ * LAGraph_Random_Seed, and modifies all of them so that they take on their
+ * next value in its pseudo-random number stream.
+ *
+ * @param[out,out] Seed vector with random numbers to be advanced.
+ * @param[in,out] msg   any error messages.
+ *
+ * @retval GrB_SUCCESS if successful.
+ * @retval GrB_NULL_POINTER if Seed is NULL.
+ * @returns any GraphBLAS errors that may have been encountered.
+ */
+
+LAGRAPH_PUBLIC
+int LAGraph_Random_Next     // advance to next random vector
+(
+    // input/output:
+    GrB_Vector Seed,
+    char *msg
+) ;
+
 //==============================================================================
 // LAGraph Basic algorithms
 //==============================================================================
diff --git a/include/LAGraph.h b/include/LAGraph.h
@@ -2021,6 +2021,56 @@ int LAGraph_Vector_IsEqualOp
     char *msg
 ) ;
 
+//------------------------------------------------------------------------------
+// Random number generator
+//------------------------------------------------------------------------------
+
+// FIXME: rename these methods?
+
+/** LAGraph_Random_Seed creates a random vector.  On input, its values are
+ * ignored but its structure is used.  On output, all entries that were in
+ * the original structure are assigned random values, depending on the scalar
+ * seed value.  Each entry is considered its own pseudo-random number stream.
+ *
+ * @param[out,out] Seed vector to initialize with random numbers.
+ * @param[in] seed      scalar seed value.
+ * @param[in,out] msg   any error messages.
+ *
+ * @retval GrB_SUCCESS if successful.
+ * @retval GrB_NULL_POINTER if Seed is NULL.
+ * @returns any GraphBLAS errors that may have been encountered.
+ */
+
+LAGRAPH_PUBLIC
+int LAGraph_Random_Seed     // construct a random seed vector
+(
+    // input/output
+    GrB_Vector Seed,    // vector of random number seeds, normally GrB_UINT64
+    // input
+    uint64_t seed,      // scalar input seed
+    char *msg
+) ;
+
+/** LAGraph_Random_Next takes as input a vector previously initialized by
+ * LAGraph_Random_Seed, and modifies all of them so that they take on their
+ * next value in its pseudo-random number stream.
+ *
+ * @param[out,out] Seed vector with random numbers to be advanced.
+ * @param[in,out] msg   any error messages.
+ *
+ * @retval GrB_SUCCESS if successful.
+ * @retval GrB_NULL_POINTER if Seed is NULL.
+ * @returns any GraphBLAS errors that may have been encountered.
+ */
+
+LAGRAPH_PUBLIC
+int LAGraph_Random_Next     // advance to next random vector
+(
+    // input/output
+    GrB_Vector Seed,
+    char *msg
+) ;
+
 //==============================================================================
 // LAGraph Basic algorithms
 //==============================================================================
diff --git a/include/LAGraphX.h b/include/LAGraphX.h
@@ -57,12 +57,12 @@ extern "C"
 //------------------------------------------------------------------------------
 
 LAGRAPHX_PUBLIC
-int LAGraph_Random_Init
+int LAGraph_Random_Init // FIXME: remove this
 (
     char *msg
 ) ;
 LAGRAPHX_PUBLIC
-int LAGraph_Random_Finalize
+int LAGraph_Random_Finalize // FIXME: remove this
 (
     char *msg
 ) ;
@@ -72,24 +72,6 @@ int LAGraph_Random_Finalize
 LAGRAPHX_PUBLIC extern bool random_hack ;
 #endif
 
-LAGRAPHX_PUBLIC
-int LAGraph_Random_Seed     // construct a random seed vector
-(
-    // input/output
-    GrB_Vector Seed,    // vector of random number seeds, normally GrB_UINT64
-    // input
-    uint64_t seed,      // scalar input seed
-    char *msg
-) ;
-
-LAGRAPHX_PUBLIC
-int LAGraph_Random_Next     // advance to next random vector
-(
-    // input/output
-    GrB_Vector Seed,
-    char *msg
-) ;
-
 LAGRAPHX_PUBLIC
 GrB_Info LAGraph_Random_Matrix    // random matrix of any built-in type
 (
diff --git a/src/test/test_Random.c b/src/test/test_Random.c
diff --git a/src/utility/LAGr_Init.c b/src/utility/LAGr_Init.c
@@ -218,6 +218,8 @@ int LAGr_Init
     // create global objects
     //--------------------------------------------------------------------------
 
+    LG_Random_Init (msg) ;
+
     // LAGraph_plus_first_T: using the GrB_PLUS_MONOID_T monoid and the
     // GrB_FIRST_T multiplicative operator.  These semirings compute C=A*B
     // where only the structure of B is accessed.  In MATLAB, this can be
diff --git a/src/utility/LAGraph_Finalize.c b/src/utility/LAGraph_Finalize.c
@@ -30,6 +30,8 @@ int LAGraph_Finalize (char *msg)
     // free global objects
     //--------------------------------------------------------------------------
 
+    LG_TRY (LG_Random_Finalize (msg)) ;
+
     GRB_TRY (GrB_Semiring_free (&LAGraph_plus_first_int8  )) ;
     GRB_TRY (GrB_Semiring_free (&LAGraph_plus_first_int16 )) ;
     GRB_TRY (GrB_Semiring_free (&LAGraph_plus_first_int32 )) ;
@@ -82,3 +84,4 @@ int LAGraph_Finalize (char *msg)
     GRB_TRY (GrB_finalize ( )) ;
     return (GrB_SUCCESS) ;
 }
+
diff --git a/src/utility/LAGraph_Random.c b/src/utility/LAGraph_Random.c
@@ -17,12 +17,7 @@
 
 // A very simple thread-safe parallel pseudo-random nuumber generator.
 
-// FIXME: ready for src?
-
-// FIXME: add LAGraph_Random_Init to LAGraph_Init,
-// and added LAGraph_Random_Finalize to LAGraph_Finalize.
-
-// FIXME: is the new init function more complicated than it needs to be?
+// FIXME: ready for src
 
 #include "LG_internal.h"
 #include "LAGraphX.h"
@@ -91,9 +86,8 @@ void LG_rand_next_f2 (uint64_t *z, const uint64_t *x)
 
 // From these references, the recommendation is to create the initial state of
 // a random number generator with an entirely different random number
-// generator.  splitmix64 is recommended, but here we initialize the State(i)
-// with xorshift (i+1) to get a good start, add the scalar seed, and then
-// randomize the State with splitmix64.
+// generator.  splitmix64 is recommended, so we initialize the State(i) with
+// (i+seed) then randomize the State with splitmix64.
 
 // References:
 //
@@ -121,17 +115,12 @@ void LG_rand_next_f2 (uint64_t *z, const uint64_t *x)
 
 #endif
 
-// The init function computes z = splitmix64 (xorshift (i+1) + seed)
+// The init function computes z = splitmix64 (i + seed)
 void LG_rand_init_func (uint64_t *z, const void *x,
     GrB_Index i, GrB_Index j, const uint64_t *seed)
 {
-    // state = xorshift64 (i+1) + seed
-    uint64_t state = i + 1 ;
-    state ^= state << 13 ;
-    state ^= state >> 7 ;
-    state ^= state << 17 ;
-    state += (*seed) ;
-    // result = shiftmix64 (state)
+    uint64_t state = i + (*seed) ;
+    // result = splitmix64 (state)
     uint64_t result = (state += 0x9E3779B97f4A7C15) ;
     result = (result ^ (result >> 30)) * 0xBF58476D1CE4E5B9 ;
     result = (result ^ (result >> 27)) * 0x94D049BB133111EB ;
@@ -146,11 +135,7 @@ void LG_rand_init_func (uint64_t *z, const void *x,
 "void LG_rand_init_func (uint64_t *z, const void *x,            \n" \
 "    GrB_Index i, GrB_Index j, const uint64_t *seed)            \n" \
 "{                                                              \n" \
-"   uint64_t state = i + 1 ;                                    \n" \
-"   state ^= state << 13 ;                                      \n" \
-"   state ^= state >> 7 ;                                       \n" \
-"   state ^= state << 17 ;                                      \n" \
-"   state += (*seed) ;                                          \n" \
+"   uint64_t state = i + (*seed) ;                              \n" \
 "   uint64_t result = (state += 0x9E3779B97f4A7C15) ;           \n" \
 "   result = (result ^ (result >> 30)) * 0xBF58476D1CE4E5B9 ;   \n" \
 "   result = (result ^ (result >> 27)) * 0x94D049BB133111EB ;   \n" \
@@ -170,16 +155,21 @@ void LG_rand_init_func (uint64_t *z, const void *x,
     GrB_IndexUnaryOp_free (&LG_rand_init_op) ;              \
 }
 
-int LAGraph_Random_Init (char *msg)
+int LAGraph_Random_Init (char *msg) // FIXME: remove this method
+{
+    return (LG_Random_Init (msg)) ;
+}
+
+int LG_Random_Init (char *msg)
 {
     LG_CLEAR_MSG ;
+    LG_FREE_WORK ; // free the two ops in case LG_Random_Init is called twice
     LG_rand_next_op = NULL ;
     LG_rand_init_op = NULL ;
 
     #if LAGRAPH_SUITESPARSE
     {
         // give SuiteSparse:GraphBLAS the strings that define the functions
-        // using the xorshift generator from LAGraph v1.2
         GRB_TRY (GxB_UnaryOp_new (&LG_rand_next_op,
             (GxB_unary_function) LG_rand_next_f2,
             GrB_UINT64, GrB_UINT64,
@@ -192,7 +182,6 @@ int LAGraph_Random_Init (char *msg)
     #else
     {
         // vanilla GraphBLAS, no strings to define the new operators
-        // using the xorshift generator from LAGraph v1.2
         GRB_TRY (GrB_UnaryOp_new (&LG_rand_next_op,
             (GxB_unary_function) LG_rand_next_f2,
             GrB_UINT64, GrB_UINT64)) ;
@@ -209,13 +198,18 @@ int LAGraph_Random_Init (char *msg)
 // LAGraph_Random_Finalize:  free the random state operator
 //------------------------------------------------------------------------------
 
-int LAGraph_Random_Finalize (char *msg)
+int LG_Random_Finalize (char *msg)
 {
     LG_CLEAR_MSG ;
     LG_FREE_WORK ;
     return (GrB_SUCCESS) ;
 }
 
+int LAGraph_Random_Finalize (char *msg) // FIXME: remove this method
+{
+    return (LG_Random_Finalize (msg)) ;
+}
+
 //------------------------------------------------------------------------------
 // LAGraph_Random_Seed:  create a vector of random states
 //------------------------------------------------------------------------------
@@ -249,8 +243,7 @@ int LAGraph_Random_Seed // construct a random state vector
     LG_CLEAR_MSG ;
     LG_ASSERT (State != NULL, GrB_NULL_POINTER) ;
 
-    // LAGraph v1.2:
-    // State = splitmix64 (xorshift64 (i+1) + seed)
+    // State = splitmix64 (i + seed)
     GRB_TRY (GrB_apply (State, NULL, NULL, LG_rand_init_op, State, seed,
         NULL)) ;
 
diff --git a/src/utility/LG_internal.h b/src/utility/LG_internal.h
@@ -588,6 +588,9 @@ int LG_nself_edges
 // simple and portable random number generator (internal use only)
 //------------------------------------------------------------------------------
 
+// This is for testing and special-case use only, not for LAGraph
+// algorithms.
+
 #define LG_RANDOM15_MAX 32767
 #define LG_RANDOM60_MAX ((1ULL << 60) -1)
 
@@ -597,6 +600,13 @@ GrB_Index LG_Random15 (uint64_t *seed) ;
 // return a random uint64_t, in range 0 to LG_RANDOM60_MAX
 GrB_Index LG_Random60 (uint64_t *seed) ;
 
+//------------------------------------------------------------------------------
+// a better random number generator, for algorithmic usage
+//------------------------------------------------------------------------------
+
+int LG_Random_Init (char *msg) ;
+int LG_Random_Finalize (char *msg) ;
+
 //------------------------------------------------------------------------------
 // LG_KindName: return the name of a kind
 //------------------------------------------------------------------------------
