Add LAGraph_Matrix_Binary_Sum utility

Adds LAGraph_Matrix_Binary_Sum, which combines an array of matrices into
a single matrix with the same interface and result as LAGraph_Matrix_Sum
but a different technique: a pairwise binary reduction tree built from
GrB_eWiseAdd (per the GraphChallenge "Anonymized Network Sensing" paper,
"Binary Summation of Traffic Matrices"), rather than one large
extract/build.

At each level the matrices are summed in disjoint adjacent pairs using
the dup operator; an unpaired (odd) trailing matrix is carried up to the
next level unchanged, until a single matrix remains. The independent
pair-sums within a level are parallelized across LG_nthreads_outer
threads. Working on the smaller intermediate matrices of the tree keeps
the active data in faster memory.

All intermediate matrices are tracked in a single pre-NULLed Pool array
with deterministic per-pair slots, so cleanup is a simple sweep that is
correct on any failure path. Unlike LAGraph_Matrix_Sum, dup must be
non-NULL since GrB_eWiseAdd requires a binary operator.

Includes tests for correctness, odd counts (carry path), all built-in
types, parallel reduction with multiple outer threads, error handling,
and a brutal malloc-failure variant.

Author: michelp

Config/LAGraph.h.in

@@ -1613,6 +1613,57 @@ int LAGraph_Matrix_Sum
     char *msg
 ) ;
 
+//------------------------------------------------------------------------------
+// LAGraph_Matrix_Binary_Sum: sum an array of matrices by binary reduction
+//------------------------------------------------------------------------------
+
+/** LAGraph_Matrix_Binary_Sum: combines an array of matrices into a single
+ * matrix C, computing the same result as LAGraph_Matrix_Sum but with a
+ * different technique: a pairwise binary reduction tree built from
+ * GrB_eWiseAdd (as in the GraphChallenge "Anonymized Network Sensing" paper,
+ * "Binary Summation of Traffic Matrices").  At each level the matrices are
+ * summed in disjoint adjacent pairs using the binary operator dup; an unpaired
+ * (odd) trailing matrix is carried up to the next level unchanged, until a
+ * single matrix remains.  The dup operator has the same set-union semantics as
+ * the dup of GrB_Matrix_build (applied where both inputs have an entry, lone
+ * entries pass through), so the result equals that of LAGraph_Matrix_Sum.
+ * With dup = GrB_PLUS_FP64 (for example) this computes the element-wise sum of
+ * all the matrices.  The independent pair-sums within a level are parallelized
+ * across LG_nthreads_outer threads.
+ *
+ * All input matrices must have identical dimensions and identical built-in
+ * type; C is created with that same type and dimensions.  Unlike
+ * LAGraph_Matrix_Sum, dup must be non-NULL, since GrB_eWiseAdd requires a
+ * binary operator.
+ *
+ * @param[out] C          the resulting matrix.
+ * @param[in]  Matrices   array of nmatrices input matrices.
+ * @param[in]  nmatrices  number of matrices in Matrices (must be >= 1).
+ * @param[in]  dup        binary operator to combine (i,j) entries; must be
+ *                        non-NULL.
+ * @param[in,out] msg     any error messages.
+ *
+ * @retval GrB_SUCCESS if successful.
+ * @retval GrB_NULL_POINTER if C, Matrices, any Matrices[k], or dup is NULL.
+ * @retval GrB_INVALID_VALUE if nmatrices is zero.
+ * @retval GrB_DIMENSION_MISMATCH if the inputs do not all share dimensions.
+ * @retval GrB_DOMAIN_MISMATCH if the inputs do not all share a type.
+ * @retval GrB_NOT_IMPLEMENTED if the matrix type is user-defined.
+ * @returns any GraphBLAS errors that may have been encountered.
+ */
+
+LAGRAPH_PUBLIC
+int LAGraph_Matrix_Binary_Sum
+(
+    // output:
+    GrB_Matrix *C,          // result = combination of all input matrices
+    // input:
+    GrB_Matrix *Matrices,   // array of nmatrices input matrices
+    GrB_Index nmatrices,    // number of matrices in the array (must be >= 1)
+    GrB_BinaryOp dup,       // operator to combine (i,j) entries (must be != NULL)
+    char *msg
+) ;
+
 //------------------------------------------------------------------------------
 // LAGraph_Vector_Structure: return the structure of a vector
 //------------------------------------------------------------------------------

include/LAGraph.h

@@ -1613,6 +1613,57 @@ int LAGraph_Matrix_Sum
     char *msg
 ) ;
 
+//------------------------------------------------------------------------------
+// LAGraph_Matrix_Binary_Sum: sum an array of matrices by binary reduction
+//------------------------------------------------------------------------------
+
+/** LAGraph_Matrix_Binary_Sum: combines an array of matrices into a single
+ * matrix C, computing the same result as LAGraph_Matrix_Sum but with a
+ * different technique: a pairwise binary reduction tree built from
+ * GrB_eWiseAdd (as in the GraphChallenge "Anonymized Network Sensing" paper,
+ * "Binary Summation of Traffic Matrices").  At each level the matrices are
+ * summed in disjoint adjacent pairs using the binary operator dup; an unpaired
+ * (odd) trailing matrix is carried up to the next level unchanged, until a
+ * single matrix remains.  The dup operator has the same set-union semantics as
+ * the dup of GrB_Matrix_build (applied where both inputs have an entry, lone
+ * entries pass through), so the result equals that of LAGraph_Matrix_Sum.
+ * With dup = GrB_PLUS_FP64 (for example) this computes the element-wise sum of
+ * all the matrices.  The independent pair-sums within a level are parallelized
+ * across LG_nthreads_outer threads.
+ *
+ * All input matrices must have identical dimensions and identical built-in
+ * type; C is created with that same type and dimensions.  Unlike
+ * LAGraph_Matrix_Sum, dup must be non-NULL, since GrB_eWiseAdd requires a
+ * binary operator.
+ *
+ * @param[out] C          the resulting matrix.
+ * @param[in]  Matrices   array of nmatrices input matrices.
+ * @param[in]  nmatrices  number of matrices in Matrices (must be >= 1).
+ * @param[in]  dup        binary operator to combine (i,j) entries; must be
+ *                        non-NULL.
+ * @param[in,out] msg     any error messages.
+ *
+ * @retval GrB_SUCCESS if successful.
+ * @retval GrB_NULL_POINTER if C, Matrices, any Matrices[k], or dup is NULL.
+ * @retval GrB_INVALID_VALUE if nmatrices is zero.
+ * @retval GrB_DIMENSION_MISMATCH if the inputs do not all share dimensions.
+ * @retval GrB_DOMAIN_MISMATCH if the inputs do not all share a type.
+ * @retval GrB_NOT_IMPLEMENTED if the matrix type is user-defined.
+ * @returns any GraphBLAS errors that may have been encountered.
+ */
+
+LAGRAPH_PUBLIC
+int LAGraph_Matrix_Binary_Sum
+(
+    // output:
+    GrB_Matrix *C,          // result = combination of all input matrices
+    // input:
+    GrB_Matrix *Matrices,   // array of nmatrices input matrices
+    GrB_Index nmatrices,    // number of matrices in the array (must be >= 1)
+    GrB_BinaryOp dup,       // operator to combine (i,j) entries (must be != NULL)
+    char *msg
+) ;
+
 //------------------------------------------------------------------------------
 // LAGraph_Vector_Structure: return the structure of a vector
 //------------------------------------------------------------------------------