Add GraphBLAS operations, iterators, and option accessors to functional API

Operations (matrix.py / vector.py):
- mxm, mxv, vxm, transpose, kronecker
- eWiseAdd, eWiseMult, eWiseUnion
- apply, apply_first, apply_second, select
- reduce (to vector and scalar), vector reduce
- assign, assign_scalar, extract, col_extract, row/col_assign
- build and extractTuples for all 13 element types
- concat, diag (matrix), diag (vector)
- dup, clear, wait, print, fprint

Scalar operations (scalar.py):
- dup, clear, wait, print, fprint

Iterator module (new file iterator.py):
- iterator_new / iterator_free
- matrix entry, row, column, and vector iterator attach/seek/next
- Row/column index getters, kount, getp/getpmax
- Type-specific value getters for all 13 types
- Column iterators require GxB_BY_COL matrix format

Global and per-object option accessors (__init__.py, matrix.py, vector.py):
- global_option_get/set for INT32, FP64, CHAR
- matrix_option_get/set for INT32, FP64
- vector_option_get/set for INT32, FP64

All 1046 doctests pass. 9 pytest tests pass.

Author: michelp

suitesparse_graphblas/__init__.py

@@ -108,6 +108,86 @@ def libget(name):
         raise
 
 
+# ---------------------------------------------------------------------------
+# Global option get/set
+# ---------------------------------------------------------------------------
+
+
+def global_option_get_int32(field):
+    """Get a global option as an int32.
+
+    >>> global_option_get_int32(lib.GxB_BURBLE) in (0, 1)
+    True
+
+    """
+    val = ffi.new("int32_t*")
+    info = lib.GxB_Global_Option_get_INT32(field, val)
+    if info != lib.GrB_SUCCESS:
+        raise _error_code_lookup.get(info, RuntimeError)(
+            f"GxB_Global_Option_get_INT32 failed with info={info}"
+        )
+    return val[0]
+
+
+def global_option_set_int32(field, value):
+    """Set a global option from an int32.
+
+    >>> global_option_set_int32(lib.GxB_BURBLE, 0)
+
+    """
+    info = lib.GxB_Global_Option_set_INT32(field, ffi.cast("int32_t", value))
+    if info != lib.GrB_SUCCESS:
+        raise _error_code_lookup.get(info, RuntimeError)(
+            f"GxB_Global_Option_set_INT32 failed with info={info}"
+        )
+
+
+def global_option_get_fp64(field):
+    """Get a global option as a float64.
+
+    >>> isinstance(global_option_get_fp64(lib.GxB_HYPER_SWITCH), float)
+    True
+
+    """
+    val = ffi.new("double*")
+    info = lib.GxB_Global_Option_get_FP64(field, val)
+    if info != lib.GrB_SUCCESS:
+        raise _error_code_lookup.get(info, RuntimeError)(
+            f"GxB_Global_Option_get_FP64 failed with info={info}"
+        )
+    return val[0]
+
+
+def global_option_set_fp64(field, value):
+    """Set a global option from a float64.
+
+    >>> default = global_option_get_fp64(lib.GxB_HYPER_SWITCH)
+    >>> global_option_set_fp64(lib.GxB_HYPER_SWITCH, default)
+
+    """
+    info = lib.GxB_Global_Option_set_FP64(field, ffi.cast("double", value))
+    if info != lib.GrB_SUCCESS:
+        raise _error_code_lookup.get(info, RuntimeError)(
+            f"GxB_Global_Option_set_FP64 failed with info={info}"
+        )
+
+
+def global_option_get_char(field):
+    """Get a global option as a string.
+
+    >>> 'SuiteSparse:GraphBLAS' in global_option_get_char(lib.GxB_LIBRARY_NAME)
+    True
+
+    """
+    val = ffi.new("char**")
+    info = lib.GxB_Global_Option_get_CHAR(field, val)
+    if info != lib.GrB_SUCCESS:
+        raise _error_code_lookup.get(info, RuntimeError)(
+            f"GxB_Global_Option_get_CHAR failed with info={info}"
+        )
+    return ffi.string(val[0]).decode()
+
+
 bool_types = frozenset((lib.GrB_BOOL,))
 
 signed_integer_types = frozenset(