BB-28: Consider global get/set methods

[mcmillan03]

From Suitesparse:

Different usages of GxB_set and GxB_get are summarized below. Some of these should remain SuiteSparse specific, but the idea of a polymorphic GxB_set and GxB_get is a useful idea, as a clean way to extend GrB_Descriptor_set to a generic method.

To set/get the global options:

GxB_set (GxB_HYPER, double h) ;
GxB_set (GxB_HYPER, GxB_ALWAYS_HYPER) ;
GxB_set (GxB_HYPER, GxB_NEVER_HYPER) ;
GxB_get (GxB_HYPER, double *h) ;

GxB_set (GxB_FORMAT, GxB_BY_ROW) ;
GxB_set (GxB_FORMAT, GxB_BY_COL) ;
GxB_get (GxB_FORMAT, GxB_Format_Value *s) ; 

To get global options that can be queried but not modified:

GxB_get (GxB_MODE,          GrB_Mode *mode) ;
GxB_get (GxB_THREAD_SAFETY, GxB_Thread_Model *thread_safety) ;
GxB_get (GxB_THREADING,     GxB_Thread_Model *threading) ; 

To set/get a matrix option:

GxB_set (GrB_Matrix A, GxB_HYPER, double h) ;
GxB_set (GrB_Matrix A, GxB_HYPER, GxB_ALWAYS_HYPER) ;
GxB_set (GrB_Matrix A, GxB_HYPER, GxB_NEVER_HYPER) ;
GxB_get (GrB_Matrix A, GxB_HYPER, double *h) ;

GxB_set (GrB_Matrix A, GxB_FORMAT, GxB_BY_ROW) ;
GxB_set (GrB_Matrix A, GxB_FORMAT, GxB_BY_COL) ;
GxB_get (GrB_Matrix A, GxB_FORMAT, GxB_Format_Value *s) ;

To get the hypersparse status of a matrix:

GxB_get (GrB_Matrix A, GxB_IS_HYPER, bool *is_hyper) ; 

To set/get a descriptor field:

GxB_set (GrB_Descriptor d, GrB_OUTP, GxB_DEFAULT) ;
GxB_set (GrB_Descriptor d, GrB_OUTP, GrB_REPLACE) ;

GxB_set (GrB_Descriptor d, GrB_MASK, GxB_DEFAULT) ;
GxB_set (GrB_Descriptor d, GrB_MASK, GrB_SCMP) ;

GxB_set (GrB_Descriptor d, GrB_INP0, GxB_DEFAULT) ;
GxB_set (GrB_Descriptor d, GrB_INP0, GrB_TRAN) ;

GxB_set (GrB_Descriptor d, GrB_INP1, GxB_DEFAULT) ;
GxB_set (GrB_Descriptor d, GrB_INP1, GrB_TRAN);

GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_DEFAULT) ;
GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_GUSTAVSON) ;
GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_HEAP) ;
GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_DOT) ;

GxB_get (GrB_Descriptor d, GrB_Desc_Field f, GrB_Desc_Value *v) ;

[tgmattso]

I am sorry, but I don't understand what you are proposing. Is this really just a way to let an implementation of GraphBLAS put custom stuff into a descriptor?

[DrTimothyAldenDavis]

GxB_set / get is a polymorphic method. It can set/get global settings, matrix options, and descriptor settings.

For example, I can use GxB_set (A, GxB_FORMAT, GxB_BY_COL) to change the format of A so that it is held by row.
GxB_set (A, GxB_SPARSITY_CONTROL, GxB_SPARSE + GxB_BITMAP) tells me, as a hint: "Please let this matrix A be held in a compressed-sparse format (by row or col depending on GxB_FORMAT) or in a bitmap format, but not in a hypersparse or full format". That's just a hint; I can choose to ignore it.

GxB_get (GxB_MODE, &mode) returns the mode as GrB_BLOCKING or GrB_NONBLOCKING, as passed to GrB_init. YOu can't do GxB_set (GxB_MODE, mode) because it can only be set at GrB_init time.

GxB_set (GxB_NTHREADS, 4) tells me, "Tim, whenever you do anthing in parallel, in all of GraphBLAS, use no more than 4 threads in any one call to GraphBLAS". I can do the same to a descriptor, so I can do this on a call-by-call basis (but only for those GrB* and GxB* functions that take in a descriptor).

Most of these settings are Suitesparse specific, but it would be nice to have a way to give a library a uniform GrB way to add its own library-dependent settings to the global state, to a matrix/vector/scalar, or to a descriptor.

[manoj63]

I have argued this from the other side of the coin. We first standardize the metadata that we recommend the libraries to maintain. Then the above proposed "get" and "set" methods are used to manipulate that metadata.

I have suggested that such metadata be organized as JSON structures, but other approaches may be equally good.

The standardized metadata will be an "Ontology".