BB-26: build()/extractTuples() that allow NULL arrays

[mcmillan03]

Allow the user arrays to be NULL. Not an error.

If NULL for extractTuples(), that array is not populated (perhaps the user just needs the values and not the integer row/col indices, or perhaps the user needs the pattern and not the values, etc).

On build(), if the values array is NULL, then it is implicitly all equal to 1.

[tgmattso]

I do not understand the last line ... if the values array is NULL then it is implicitly all equal to one.

[DrTimothyAldenDavis]

What I mean is this: GrB_Matrix_build currently has the signature:

GrB_Matrix_build (C, I, J, X, nvals, dup).

What I want do is build an iso-valued matrix, where all entries are equal to 1. Since this issue, I have created a GxB_Matrix_build_Scalar with the signature:

GxB_Matrix_build_Scalar (C, I, J, GrB_Scalar S, nvals)

so that I can be told "all of the (i,j,x) tuples, of which there nvals of them, have the same numerical value, as (i,j,s) for the Scalar s, and duplicates are to be ignored". This is very useful, since matrices with all entries present in their sparsity pattern having the same value is very common (like a GrB_PATTERN matrix but far better because GrB_PATTERN has lots of problems in how it should be defined).

I also want to do the following, to build an n-by-1 matrix with J implicitly all zero:

GrB_Matrix_new (&C, type, n, 1) ; GrB_Matrix_build (C, I, NULL, X, nvals, dup).

Since C is n-by-1, the entire J array is filled with all zeros. That's useless. So let J be NULL, which means "J is an array of all zeros". This feature is required by Julia.

[DrTimothyAldenDavis]

This is to save memory and improve performance. If the C is n-by-1, the J array is [0,0,0, .... 0,0], of size nvals, which is useless to create and takes up a lot of memory.

[DrTimothyAldenDavis]

For extractTuples, say the user just wants the values and not the indices. THen pass in I and J as NULL, and X as non-NULL.

Or they might want just the pattern, not the values, so pass in I and J as non-NULL, and X as NULL. No reason to export something the user doesn't need.

[DrTimothyAldenDavis]

I have a new pair of methods, GxB_Matrix_build_Scalar and a vector variant:

GrB_Info GxB_Matrix_build_Scalar    // build a matrix from (I,J,scalar) tuples
(
    GrB_Matrix C,                   // matrix to build
    const GrB_Index *I,             // array of row indices of tuples
    const GrB_Index *J,             // array of column indices of tuples
    GrB_Scalar scalar,              // value for all tuples
    GrB_Index nvals                 // number of tuples
) ;

This is just like GrB_Matrix_build_TYPE, except that the values array does not appear. Instead, a single GrB_Scalar is used to specify the value of all entries in the resulting matrix. Duplicates are ignored (this is not an error). There is no dup operator.

This method is very important. Many, perhaps most, graphs that arise in practice are unweighted. It is wasteful (time and memory) to require that the user specify all the edge weights in a values array of size nvals, if all the edge weights are the same (say, all equal to 1, or any other value as determined by the GrB_Scalar).

A method like this will allow GraphBLAS to easily handle "pattern-only" matrices but without all the nasty breaking of GraphBLAS that issue #25 would cause. With the ONEB binary operator, and this build method, and with a library that can detect and exploit other cases where all the entries in the matrix happen to have the same value (as I do in SuiteSparse), issue #25 is not needed.

[jim22k]

Let's split this into 2 different issues