Add LAGraph_Matrix_Sum and LAGraph_Matrix_Binary_Sum utilities

[michelp]

Summary

Adds two experimental/utility/ functions that combine an array of GrB_Matrix objects into a single matrix, using a binary operator to resolve duplicate (i,j) entries. They compute the same result via two different techniques, so they can be compared:

• LAGraph_Matrix_Sum — concatenate-and-build: extract every matrix's tuples into one shared buffer, then a single GrB_Matrix_build.
• LAGraph_Matrix_Binary_Sum — pairwise binary reduction tree of GrB_eWiseAdd (per the GraphChallenge "Anonymized Network Sensing" paper, Fig. 3 "Binary Summation of Traffic Matrices").

With dup = GrB_PLUS_FP64 (for example) either computes the element-wise sum of all the matrices; other operators generalize it (max, times, etc.). All input matrices must have identical dimensions and the same built-in type; C is created with that type and dimensions. User-defined types return GrB_NOT_IMPLEMENTED.

LAGraph_Matrix_Sum (concatenate + build)

1. Compute the total nvals across all inputs and a per-matrix prefix-sum offset.
2. Allocate one tuple buffer (I, J, X) large enough for every entry.
3. Extract each matrix's tuples into its disjoint buffer region — parallelized across LG_nthreads_outer threads, since the regions never overlap.
4. GrB_Matrix_build with the provided dup operator to combine duplicate coordinates.

LAGraph_Matrix_Binary_Sum (pairwise binary reduction)

At each level the matrices are summed in disjoint adjacent pairs with GrB_eWiseAdd using dup; 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 run concurrently across LG_nthreads_outer threads. Working on the smaller intermediate matrices of the tree keeps the active data in faster memory: adding two matrices each with N entries yields a matrix with fewer than 2N entries, so the relative work shrinks as the matrices grow.

All intermediate matrices are tracked in a single pre-NULLed pool 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 (NULL dup returns GrB_NULL_POINTER).

Changes

• experimental/utility/LAGraph_Matrix_Sum.c — concatenate/build implementation.
• experimental/utility/LAGraph_Matrix_Binary_Sum.c — binary-reduction implementation.
• include/LAGraphX.h — public declarations (experimental LAGraphX API).
• experimental/test/test_Matrix_Sum.c, experimental/test/test_Matrix_Binary_Sum.c — tests.

Testing

ctest -R LAGraphX_Matrix_Sum and ctest -R LAGraphX_Matrix_Binary_Sum pass; clean builds with OpenMP on and off. The test binaries cover:

• correctness (vs GrB_eWiseAdd, single-matrix copy, empty-matrix inclusion)
• every built-in type branch
• odd counts exercising the binary-reduction carry path
• parallel reduction/extraction with multiple outer threads
• error handling (NULL args, nmatrices == 0, NULL array entry, dimension/type mismatch, UDT, and NULL dup for the binary variant)
• brutal malloc-failure variants exercising the cleanup paths

[michelp]

Original idea by Tim Davis.

[DrTimothyAldenDavis]

Can you change this to be a PR to the 1.3.x branch? That's the current development branch.

[DrTimothyAldenDavis]

Looks great!

Can you revise the PR to go to the v1.3.x branch instead of the stable branch? And can you put these in the experimental folder instead of src? Also put the header files in LAGraphX.h.

We have to talk in the LAGraph committee about what to add move from experimental to src, before anything can go into the src folder.

For the two utilities: would it be better to have a single method, LAGraph_Matrix_sum, which took in a parameter that told what method to use? That's something can can be discussed later, after these methods are merged into the experimental/utility folder.

[michelp]

The branch is now rebased on v1.3.x.

[DrTimothyAldenDavis]

Looks great to me. A future extension could add support for user-define types, assuming the dup operator is also user-defined. But that's not essential for now.

[DrTimothyAldenDavis]

Shall I merge it in?