Add LAGraph_Matrix_Sum utility

michelp · michelp · commit 43ee0acef248 · 2026-06-11T18:24:27.000-07:00
LAGraph_Matrix_Sum combines an array of GrB_Matrix objects into a single
matrix using a binary operator to resolve duplicate entries.  It computes
the total number of entries across all inputs, allocates one shared tuple
buffer (I, J, X), extracts the tuples of each input matrix into the buffer,
and calls GrB_Matrix_build with the dup operator to combine duplicate (i,j)
coordinates.  With dup = GrB_PLUS_FP64 (for example) this computes the
element-wise sum of all the matrices.

All input matrices must have identical dimensions and the same built-in
type; user-defined types return GrB_NOT_IMPLEMENTED.

Includes a test (src/test/test_Matrix_Sum.c) covering correctness, all
built-in type branches, error handling, and a brutal malloc-failure variant.
diff --git a/Config/LAGraph.h.in b/Config/LAGraph.h.in
@@ -1572,6 +1572,47 @@ int LAGraph_Matrix_Structure
     char *msg
 ) ;
 
+//------------------------------------------------------------------------------
+// LAGraph_Matrix_Sum: sum an array of matrices with a binary operator
+//------------------------------------------------------------------------------
+
+/** LAGraph_Matrix_Sum: combines an array of matrices into a single matrix C.
+ * The tuples of all input matrices are concatenated into a single buffer and
+ * passed to GrB_Matrix_build, using the binary operator dup to combine any
+ * duplicate (i,j) entries.  With dup = GrB_PLUS_FP64 (for example) this
+ * computes the element-wise sum of all the matrices.
+ *
+ * All input matrices must have identical dimensions and identical built-in
+ * type; C is created with that same type and dimensions.
+ *
+ * @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 duplicate (i,j) entries;
+ *                        if NULL, duplicates are handled per GrB_Matrix_build.
+ * @param[in,out] msg     any error messages.
+ *
+ * @retval GrB_SUCCESS if successful.
+ * @retval GrB_NULL_POINTER if C, Matrices, or any Matrices[k] 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_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 duplicate (i,j) entries
+    char *msg
+) ;
+
 //------------------------------------------------------------------------------
 // LAGraph_Vector_Structure: return the structure of a vector
 //------------------------------------------------------------------------------
diff --git a/include/LAGraph.h b/include/LAGraph.h
@@ -1572,6 +1572,47 @@ int LAGraph_Matrix_Structure
     char *msg
 ) ;
 
+//------------------------------------------------------------------------------
+// LAGraph_Matrix_Sum: sum an array of matrices with a binary operator
+//------------------------------------------------------------------------------
+
+/** LAGraph_Matrix_Sum: combines an array of matrices into a single matrix C.
+ * The tuples of all input matrices are concatenated into a single buffer and
+ * passed to GrB_Matrix_build, using the binary operator dup to combine any
+ * duplicate (i,j) entries.  With dup = GrB_PLUS_FP64 (for example) this
+ * computes the element-wise sum of all the matrices.
+ *
+ * All input matrices must have identical dimensions and identical built-in
+ * type; C is created with that same type and dimensions.
+ *
+ * @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 duplicate (i,j) entries;
+ *                        if NULL, duplicates are handled per GrB_Matrix_build.
+ * @param[in,out] msg     any error messages.
+ *
+ * @retval GrB_SUCCESS if successful.
+ * @retval GrB_NULL_POINTER if C, Matrices, or any Matrices[k] 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_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 duplicate (i,j) entries
+    char *msg
+) ;
+
 //------------------------------------------------------------------------------
 // LAGraph_Vector_Structure: return the structure of a vector
 //------------------------------------------------------------------------------
diff --git a/src/test/test_Matrix_Sum.c b/src/test/test_Matrix_Sum.c
@@ -0,0 +1,274 @@
+//------------------------------------------------------------------------------
+// LAGraph/src/test/test_Matrix_Sum.c:  test LAGraph_Matrix_Sum
+//------------------------------------------------------------------------------
+
+// LAGraph, (c) 2019-2025 by The LAGraph Contributors, All Rights Reserved.
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// For additional details (including references to third party source code and
+// other files) see the LICENSE file or contact permission@sei.cmu.edu. See
+// Contributors.txt for a full list of contributors. Created, in part, with
+// funding and support from the U.S. Government (see Acknowledgments.txt file).
+// DM22-0790
+
+// Contributed by Michel Pelletier.
+
+//------------------------------------------------------------------------------
+
+#include "LAGraph_test.h"
+#include "LG_internal.h"
+
+//------------------------------------------------------------------------------
+// global variables
+//------------------------------------------------------------------------------
+
+char msg [LAGRAPH_MSG_LEN] ;
+GrB_Matrix A = NULL, B = NULL, C = NULL, Expected = NULL ;
+
+//------------------------------------------------------------------------------
+// setup and teardown
+//------------------------------------------------------------------------------
+
+void setup (void)
+{
+    OK (LAGraph_Init (msg)) ;
+}
+
+void teardown (void)
+{
+    OK (LAGraph_Finalize (msg)) ;
+}
+
+//------------------------------------------------------------------------------
+// make_A, make_B: construct two 4x4 FP64 matrices with overlapping and
+// distinct (i,j) coordinates
+//------------------------------------------------------------------------------
+
+static void make_AB (void)
+{
+    // A has entries at (0,0), (1,1), (2,2), (0,3)
+    GrB_Index Ai [ ] = { 0, 1, 2, 0 } ;
+    GrB_Index Aj [ ] = { 0, 1, 2, 3 } ;
+    double    Ax [ ] = { 1, 2, 3, 4 } ;
+    OK (GrB_Matrix_new (&A, GrB_FP64, 4, 4)) ;
+    OK (GrB_Matrix_build_FP64 (A, Ai, Aj, Ax, 4, NULL)) ;
+
+    // B has entries at (0,0), (1,1), (3,3), (2,0)
+    //   shares (0,0) and (1,1) with A, distinct elsewhere
+    GrB_Index Bi [ ] = { 0, 1, 3, 2 } ;
+    GrB_Index Bj [ ] = { 0, 1, 3, 0 } ;
+    double    Bx [ ] = { 10, 20, 30, 40 } ;
+    OK (GrB_Matrix_new (&B, GrB_FP64, 4, 4)) ;
+    OK (GrB_Matrix_build_FP64 (B, Bi, Bj, Bx, 4, NULL)) ;
+}
+
+//------------------------------------------------------------------------------
+// test_Matrix_Sum: basic correctness
+//------------------------------------------------------------------------------
+
+void test_Matrix_Sum (void)
+{
+    setup ( ) ;
+
+    make_AB ( ) ;
+
+    // Expected = A + B (element-wise add, set union)
+    OK (GrB_Matrix_new (&Expected, GrB_FP64, 4, 4)) ;
+    OK (GrB_eWiseAdd (Expected, NULL, NULL, GrB_PLUS_FP64, A, B, NULL)) ;
+
+    // C = sum of {A, B} using GrB_PLUS_FP64 for duplicates
+    GrB_Matrix Mats [2] = { A, B } ;
+    OK (LAGraph_Matrix_Sum (&C, Mats, 2, GrB_PLUS_FP64, msg)) ;
+
+    bool ok ;
+    OK (LAGraph_Matrix_IsEqual (&ok, C, Expected, msg)) ;
+    TEST_CHECK (ok) ;
+    TEST_MSG ("sum of {A,B} did not equal A+B") ;
+    OK (GrB_free (&C)) ;
+
+    // single-matrix array: result must be a copy of A
+    GrB_Matrix One [1] = { A } ;
+    OK (LAGraph_Matrix_Sum (&C, One, 1, GrB_PLUS_FP64, msg)) ;
+    OK (LAGraph_Matrix_IsEqual (&ok, C, A, msg)) ;
+    TEST_CHECK (ok) ;
+    TEST_MSG ("sum of {A} did not equal A") ;
+    OK (GrB_free (&C)) ;
+
+    // an empty matrix in the array contributes nothing
+    GrB_Matrix Empty = NULL ;
+    OK (GrB_Matrix_new (&Empty, GrB_FP64, 4, 4)) ;
+    GrB_Matrix WithEmpty [3] = { A, Empty, B } ;
+    OK (LAGraph_Matrix_Sum (&C, WithEmpty, 3, GrB_PLUS_FP64, msg)) ;
+    OK (LAGraph_Matrix_IsEqual (&ok, C, Expected, msg)) ;
+    TEST_CHECK (ok) ;
+    TEST_MSG ("sum of {A,Empty,B} did not equal A+B") ;
+    OK (GrB_free (&Empty)) ;
+    OK (GrB_free (&C)) ;
+
+    OK (GrB_free (&A)) ;
+    OK (GrB_free (&B)) ;
+    OK (GrB_free (&Expected)) ;
+
+    teardown ( ) ;
+}
+
+//------------------------------------------------------------------------------
+// test_Matrix_Sum_types: exercise every built-in type branch
+//------------------------------------------------------------------------------
+
+void test_Matrix_Sum_types (void)
+{
+    setup ( ) ;
+
+    // (type, GrB_PLUS operator) pairs, one per built-in type branch
+    GrB_Type   types [ ] = { GrB_BOOL, GrB_INT8, GrB_INT16, GrB_INT32,
+        GrB_INT64, GrB_UINT8, GrB_UINT16, GrB_UINT32, GrB_UINT64,
+        GrB_FP32, GrB_FP64 } ;
+    GrB_BinaryOp ops [ ] = { GrB_LOR, GrB_PLUS_INT8, GrB_PLUS_INT16,
+        GrB_PLUS_INT32, GrB_PLUS_INT64, GrB_PLUS_UINT8, GrB_PLUS_UINT16,
+        GrB_PLUS_UINT32, GrB_PLUS_UINT64, GrB_PLUS_FP32, GrB_PLUS_FP64 } ;
+    int ntypes = sizeof (types) / sizeof (types [0]) ;
+
+    GrB_Index Ai [ ] = { 0, 1, 2 } ;
+    GrB_Index Aj [ ] = { 0, 1, 0 } ;
+    GrB_Index Bi [ ] = { 0, 1, 0 } ;
+    GrB_Index Bj [ ] = { 0, 1, 2 } ;
+
+    for (int t = 0 ; t < ntypes ; t++)
+    {
+        OK (GrB_Matrix_new (&A, types [t], 3, 3)) ;
+        OK (GrB_Matrix_new (&B, types [t], 3, 3)) ;
+        // build with INT32 values; GraphBLAS typecasts to the matrix type
+        int32_t Ax [ ] = { 1, 1, 1 } ;
+        int32_t Bx [ ] = { 1, 1, 1 } ;
+        OK (GrB_Matrix_build_INT32 (A, Ai, Aj, Ax, 3, NULL)) ;
+        OK (GrB_Matrix_build_INT32 (B, Bi, Bj, Bx, 3, NULL)) ;
+
+        OK (GrB_Matrix_new (&Expected, types [t], 3, 3)) ;
+        OK (GrB_eWiseAdd (Expected, NULL, NULL, ops [t], A, B, NULL)) ;
+
+        GrB_Matrix Mats [2] = { A, B } ;
+        OK (LAGraph_Matrix_Sum (&C, Mats, 2, ops [t], msg)) ;
+
+        bool ok ;
+        OK (LAGraph_Matrix_IsEqual (&ok, C, Expected, msg)) ;
+        TEST_CHECK (ok) ;
+        TEST_MSG ("type index %d failed", t) ;
+
+        OK (GrB_free (&A)) ;
+        OK (GrB_free (&B)) ;
+        OK (GrB_free (&C)) ;
+        OK (GrB_free (&Expected)) ;
+    }
+
+    teardown ( ) ;
+}
+
+//------------------------------------------------------------------------------
+// test_Matrix_Sum_brutal
+//------------------------------------------------------------------------------
+
+#if LG_BRUTAL_TESTS
+void test_Matrix_Sum_brutal (void)
+{
+    OK (LG_brutal_setup (msg)) ;
+
+    make_AB ( ) ;
+    OK (GrB_Matrix_new (&Expected, GrB_FP64, 4, 4)) ;
+    OK (GrB_eWiseAdd (Expected, NULL, NULL, GrB_PLUS_FP64, A, B, NULL)) ;
+
+    GrB_Matrix Mats [2] = { A, B } ;
+    LG_BRUTAL (LAGraph_Matrix_Sum (&C, Mats, 2, GrB_PLUS_FP64, msg)) ;
+
+    bool ok ;
+    OK (LAGraph_Matrix_IsEqual (&ok, C, Expected, msg)) ;
+    TEST_CHECK (ok) ;
+
+    OK (GrB_free (&A)) ;
+    OK (GrB_free (&B)) ;
+    OK (GrB_free (&C)) ;
+    OK (GrB_free (&Expected)) ;
+
+    OK (LG_brutal_teardown (msg)) ;
+}
+#endif
+
+//------------------------------------------------------------------------------
+// test_Matrix_Sum_failures: test error handling
+//------------------------------------------------------------------------------
+
+void test_Matrix_Sum_failures (void)
+{
+    setup ( ) ;
+
+    make_AB ( ) ;
+    GrB_Matrix Mats [2] = { A, B } ;
+    int result ;
+
+    // NULL output
+    result = LAGraph_Matrix_Sum (NULL, Mats, 2, GrB_PLUS_FP64, msg) ;
+    TEST_CHECK (result == GrB_NULL_POINTER) ;
+
+    // NULL Matrices array
+    C = NULL ;
+    result = LAGraph_Matrix_Sum (&C, NULL, 2, GrB_PLUS_FP64, msg) ;
+    TEST_CHECK (result == GrB_NULL_POINTER) ;
+    TEST_CHECK (C == NULL) ;
+
+    // nmatrices == 0
+    result = LAGraph_Matrix_Sum (&C, Mats, 0, GrB_PLUS_FP64, msg) ;
+    TEST_CHECK (result == GrB_INVALID_VALUE) ;
+
+    // NULL entry in the array
+    GrB_Matrix WithNull [2] = { A, NULL } ;
+    result = LAGraph_Matrix_Sum (&C, WithNull, 2, GrB_PLUS_FP64, msg) ;
+    TEST_CHECK (result == GrB_NULL_POINTER) ;
+
+    // dimension mismatch
+    GrB_Matrix D = NULL ;
+    OK (GrB_Matrix_new (&D, GrB_FP64, 5, 5)) ;
+    GrB_Matrix BadDim [2] = { A, D } ;
+    result = LAGraph_Matrix_Sum (&C, BadDim, 2, GrB_PLUS_FP64, msg) ;
+    TEST_CHECK (result == GrB_DIMENSION_MISMATCH) ;
+    OK (GrB_free (&D)) ;
+
+    // type mismatch
+    GrB_Matrix E = NULL ;
+    OK (GrB_Matrix_new (&E, GrB_INT32, 4, 4)) ;
+    GrB_Matrix BadType [2] = { A, E } ;
+    result = LAGraph_Matrix_Sum (&C, BadType, 2, GrB_PLUS_FP64, msg) ;
+    TEST_CHECK (result == GrB_DOMAIN_MISMATCH) ;
+    OK (GrB_free (&E)) ;
+
+    // user-defined type not supported
+    typedef struct { double x, y ; } udt_t ;
+    GrB_Type UDT = NULL ;
+    OK (GrB_Type_new (&UDT, sizeof (udt_t))) ;
+    GrB_Matrix U = NULL ;
+    OK (GrB_Matrix_new (&U, UDT, 4, 4)) ;
+    GrB_Matrix Udt [1] = { U } ;
+    result = LAGraph_Matrix_Sum (&C, Udt, 1, NULL, msg) ;
+    TEST_CHECK (result == GrB_NOT_IMPLEMENTED) ;
+    OK (GrB_free (&U)) ;
+    OK (GrB_free (&UDT)) ;
+
+    OK (GrB_free (&A)) ;
+    OK (GrB_free (&B)) ;
+
+    teardown ( ) ;
+}
+
+//------------------------------------------------------------------------------
+// TEST_LIST: the list of tasks for this entire test
+//------------------------------------------------------------------------------
+
+TEST_LIST =
+{
+    { "Matrix_Sum", test_Matrix_Sum },
+    { "Matrix_Sum_types", test_Matrix_Sum_types },
+    { "Matrix_Sum_failures", test_Matrix_Sum_failures },
+    #if LG_BRUTAL_TESTS
+    { "Matrix_Sum_brutal", test_Matrix_Sum_brutal },
+    #endif
+    { NULL, NULL }
+} ;
diff --git a/src/utility/LAGraph_Matrix_Sum.c b/src/utility/LAGraph_Matrix_Sum.c
