Add LAGraph_Matrix_Sum and LAGraph_Matrix_Binary_Sum utilities

[michelp]

Summary

Adds two src/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

• src/utility/LAGraph_Matrix_Sum.c — concatenate/build implementation.
• src/utility/LAGraph_Matrix_Binary_Sum.c — binary-reduction implementation.
• Config/LAGraph.h.in — public declarations (include/LAGraph.h is generated from this template).
• src/test/test_Matrix_Sum.c, src/test/test_Matrix_Binary_Sum.c — tests.

Testing

ctest -R Matrix_Sum and ctest -R 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.