add GraphBLASInterface as dependency & use 0-based indexing in higher-level interface (#7)

* add GraphBLAS interface as dependency

* update documentation

* use 0-based indexing 

* update Project.toml

* bug fixes

Author: abhinavmehndiratta

Project.toml

@@ -5,10 +5,11 @@ version = "0.1.0"
 
 [deps]
 BinaryProvider = "b99e7846-7c00-51b0-8f62-c81ae34c0232"
+GraphBLASInterface = "5f047416-9681-11e9-0804-033d9936201f"
 Libdl = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
-julia = "1"
 BinaryProvider = "0.5"
+julia = "1"

docs/make.jl

@@ -1,7 +1,7 @@
-using Documenter, SuiteSparseGraphBLAS
+using Documenter, GraphBLASInterface, SuiteSparseGraphBLAS
 
 makedocs(
-    modules     = [SuiteSparseGraphBLAS],
+    modules     = [GraphBLASInterface, SuiteSparseGraphBLAS],
     format      = Documenter.HTML(),
     sitename    = "SuiteSparseGraphBLAS",
     doctest     = false,

docs/src/desc_methods.md

@@ -1,9 +1,6 @@
 ## Descriptor methods
 
-```@autodocs
-Modules = [SuiteSparseGraphBLAS]
-Pages   = [
-    "Object_Methods/Descriptor_Methods.jl",
-]
-Private = false
+```@docs
+GrB_Descriptor_new
+GrB_Descriptor_set
 ```

src/Context_Methods.jl

@@ -1,59 +1,10 @@
-import Printf.@printf
+import GraphBLASInterface:
+        GrB_init, GrB_finalize
 
-"""
-    GrB_init(mode)
-
-`GrB_init` must called before any other GraphBLAS operation.
-`GrB_init` defines the mode that GraphBLAS will use: blocking or non-blocking.
-With blocking mode, all operations finish before returning to the user application.
-With non-blocking mode, operations can be left pending, and are computed only when needed.
-"""
 function GrB_init(mode::GrB_Mode)
     return GrB_Info(ccall(dlsym(graphblas_lib, "GrB_init"), Cint, (Cint, ), mode))
 end
 
-"""
-    GrB_wait()
-
-`GrB_wait` forces all pending operations to complete.
-Blocking mode is as if `GrB_wait` is called whenever a GraphBLAS method or operation returns to the user.
-"""
-function GrB_wait()
-    return GrB_Info(ccall(dlsym(graphblas_lib, "GrB_wait"), Cint, (), ))
-end
-
-"""
-    GrB_finalize()
-
-`GrB_finalize` must be called as the last GraphBLAS operation.
-`GrB_finalize` does not call `GrB_wait`; any pending computations are abandoned.
-"""
 function GrB_finalize()
     return GrB_Info(ccall(dlsym(graphblas_lib, "GrB_finalize"), Cint, (), ))
 end
-
-"""
-    GrB_error()
-
-Each GraphBLAS method and operation returns a `GrB_Info` error code.
-`GrB_error` returns additional information on the error.
-
-# Examples
-```jldoctest
-julia> using SuiteSparseGraphBLAS
-
-julia> GrB_init(GrB_NONBLOCKING)
-GrB_SUCCESS::GrB_Info = 0
-
-julia> GrB_init(GrB_NONBLOCKING)
-GrB_INVALID_VALUE::GrB_Info = 5
-
-julia> GrB_error()
-GraphBLAS error: GrB_INVALID_VALUE
-function: GrB_init (mode)
-GrB_init must not be called twice
-```
-"""
-function GrB_error()
-    @printf("%s", unsafe_string(ccall(dlsym(graphblas_lib, "GrB_error"), Cstring, (), )))
-end

src/Enums.jl

@@ -1,54 +1,6 @@
-@enum GrB_Info begin
-    GrB_SUCCESS = 0                 # all is well
-    GrB_NO_VALUE = 1                # A(ij) requested but not there
-    
-    # In non-blocking mode these errors are caught right away.
-
-    GrB_UNINITIALIZED_OBJECT = 2    # object has not been initialized
-    GrB_INVALID_OBJECT = 3          # object is corrupted
-    GrB_NULL_POINTER = 4            # input pointer is NULL
-    GrB_INVALID_VALUE = 5           # generic error code; some value is bad
-    GrB_INVALID_INDEX = 6           # a row or column index is out of bounds;
-                                    # used for indices passed as scalars not
-                                    # in a list.
-    GrB_DOMAIN_MISMATCH = 7         # object domains are not compatible
-    GrB_DIMENSION_MISMATCH = 8      # matrix dimensions do not match
-    GrB_OUTPUT_NOT_EMPTY = 9        # output matrix already has values in it
-
-    # In non-blocking mode these errors can be deferred.
-
-    GrB_OUT_OF_MEMORY = 10          # out of memory
-    GrB_INSUFFICIENT_SPACE = 11     # output array not large enough
-    GrB_INDEX_OUT_OF_BOUNDS = 12    # a row or column index is out of bounds
-    GrB_PANIC = 13                  # SuiteSparse:GraphBLAS only panics if a critical section fails
-end
-
-@enum GrB_Mode begin
-    GrB_NONBLOCKING = 0             # methods may return with pending computations
-    GrB_BLOCKING = 1                # no computations are ever left pending
-end
-
 @enum GxB_Print_Level begin
     GxB_SILENT = 0                  # nothing is printed just check the object
     GxB_SUMMARY = 1                 # print a terse summary
     GxB_SHORT = 2                   # short description about 30 entries of a matrix
     GxB_COMPLETE = 3                # print the entire contents of the object
 end
-
-@enum GrB_Desc_Field begin
-    GrB_OUTP = 0                    # descriptor for output of a method
-    GrB_MASK = 1                    # descriptor for the mask input of a method
-    GrB_INP0 = 2                    # descriptor for the first input of a method
-    GrB_INP1 = 3                    # descriptor for the second input of a method
-end
-
-@enum GrB_Desc_Value begin
-    # for all GrB_Descriptor fields:
-    GxB_DEFAULT = 0                 # default behavior of the method
-    # for GrB_OUTP only:
-    GrB_REPLACE = 1                 # clear the output before assigning new values to it
-    # for GrB_MASK only:
-    GrB_SCMP = 2                    # use the structural complement of the input
-    # for GrB_INP0 and GrB_INP1 only:
-    GrB_TRAN = 3                    # use the transpose of the input
-end

src/Interface/Interface.jl

@@ -1,14 +1,14 @@
 module Interface
 
-using SuiteSparseGraphBLAS
+using GraphBLASInterface, SuiteSparseGraphBLAS
 
 import Base:
     getindex, setindex!, empty!, copy, size, adjoint, ==
 
 import SuiteSparseGraphBLAS:
-    GrB_Info, GrB_Index, GrB_Matrix, GrB_Vector, GrB_Descriptor, GrB_Desc_Field, GrB_Desc_Value,
-    valid_types, get_GrB_Type, default_dup, equal_op
+    GrB_Info, GrB_Index, GrB_Matrix, GrB_Vector, GrB_Descriptor, GrB_Desc_Field, GrB_Desc_Value
 
+include("Utils.jl")
 include("./Object_Methods/Matrix_Methods.jl")
 include("./Object_Methods/Vector_Methods.jl")
 include("./Object_Methods/Descriptor_Methods.jl")

src/Interface/Object_Methods/Matrix_Methods.jl

@@ -3,36 +3,25 @@
 
 Create a GraphBLAS matrix of dimensions nrows x ncols such that A[I[k], J[k]] = X[k].
 dup is a GraphBLAS binary operator used to combine duplicates, it defaults to `FIRST`.
-If nrows and ncols are not specified, they are set to maximum(I) and maximum(J) respectively.
-nvals is set to length(I) is not specified.
-
-# Examples
-```jldoctest
-julia> using SuiteSparseGraphBLAS
-
-julia> A = GrB_Matrix([1, 1, 2, 3], [1, 1, 2, 3], UInt32[1, 10, 1, 1], dup = GrB_PLUS_UINT32)
-GrB_Matrix{UInt32}
-
-julia> A[1, 1]
-0x0000000b
-```
+If nrows and ncols are not specified, they are set to maximum(I)+1 and maximum(J)+1 (because of 0-based indexing)
+respectively. nvals is set to length(I) is not specified.
 """
 function GrB_Matrix(
         I::Vector{U},
         J::Vector{U},
         X::Vector{T};
-        nrows::U = maximum(I),
-        ncols::U = maximum(J),
+        nrows::U = maximum(I)+1,
+        ncols::U = maximum(J)+1,
         nvals::U = length(I),
-        dup::GrB_BinaryOp = default_dup(T)) where {T <: valid_types, U <: GrB_Index}
+        dup::GrB_BinaryOp = default_dup(T)) where {T, U <: GrB_Index}
 
     A = GrB_Matrix{T}()
     GrB_T = get_GrB_Type(T)
     res = GrB_Matrix_new(A, GrB_T, nrows, ncols)
     if res != GrB_SUCCESS
         error(res)
     end
-    res = GrB_Matrix_build(A, I.-1, J.-1, X, nvals, dup)
+    res = GrB_Matrix_build(A, I, J, X, nvals, dup)
     if res != GrB_SUCCESS
         error(res)
     end
@@ -58,7 +47,7 @@ julia> nnz(A)
 0
 ```
 """
-function GrB_Matrix(T::DataType, nrows::GrB_Index, ncols::GrB_Index)
+function GrB_Matrix(T, nrows::GrB_Index, ncols::GrB_Index)
     A = GrB_Matrix{T}()
     GrB_T = get_GrB_Type(T)
     res = GrB_Matrix_new(A, GrB_T, nrows, ncols)
@@ -163,7 +152,7 @@ function findnz(A::GrB_Matrix)
         error(res)
     end
     I, J, X = res
-    return I.+1, J.+1, X
+    return I, J, X
 end
 
 """
@@ -205,7 +194,7 @@ julia> using SuiteSparseGraphBLAS
 julia> GrB_init(GrB_NONBLOCKING)
 GrB_SUCCESS::GrB_Info = 0
 
-julia> A = GrB_Matrix([1, 2, 3], [1, 2, 3], [1, 1, 1])
+julia> A = GrB_Matrix([0, 1, 2], [0, 1, 2], [1, 1, 1])
 GrB_Matrix{Int64}
 
 julia> size(A)
@@ -272,7 +261,7 @@ julia> A[1, 1]
 ```
 """
 function getindex(A::GrB_Matrix, row_index::GrB_Index, col_index::GrB_Index)
-    res = GrB_Matrix_extractElement(A, row_index-1, col_index-1)
+    res = GrB_Matrix_extractElement(A, row_index, col_index)
     if typeof(res) == GrB_Info
         error(res)
     end
@@ -304,8 +293,8 @@ julia> A[1, 1]
 5
 ```
 """
-function setindex!(A::GrB_Matrix{T}, X::T, I::GrB_Index, J::GrB_Index) where {T <: valid_types}
-    res = GrB_Matrix_setElement(A, X, I-1, J-1)
+function setindex!(A::GrB_Matrix{T}, X::T, I::GrB_Index, J::GrB_Index) where T
+    res = GrB_Matrix_setElement(A, X, I, J)
     if res != GrB_SUCCESS
         error(res)
     end
@@ -364,7 +353,7 @@ julia> findnz(B)
 ([1, 2, 3], [1, 2, 3], [1, 1, 1])
 ```
 """
-function copy(A::GrB_Matrix{T}) where T <: valid_types
+function copy(A::GrB_Matrix{T}) where T
     C = GrB_Matrix{T}()
     res = GrB_Matrix_dup(C, A)
     if res != GrB_SUCCESS
@@ -392,7 +381,7 @@ julia> findnz(M')
 ([2, 3], [1, 1], [1, 1])
 ```
 """
-function adjoint(A::GrB_Matrix{T}) where T <: valid_types
+function adjoint(A::GrB_Matrix{T}) where T
     C = GrB_Matrix(T, size(A, 2), size(A, 1))
     res = GrB_transpose(C, GrB_NULL, GrB_NULL, A, GrB_NULL)
     if res != GrB_SUCCESS
@@ -406,7 +395,7 @@ end
 
 Return lower triangle of a GraphBLAS matrix.
 """
-function LowerTriangular(A::GrB_Matrix{T}) where T <: valid_types 
+function LowerTriangular(A::GrB_Matrix{T}) where T 
     nrows, ncols = size(A)
     if nrows != ncols
         error("Matrix is not square")
@@ -424,7 +413,7 @@ end
 
 Return upper triangle of a GraphBLAS matrix.
 """
-function UpperTriangular(A::GrB_Matrix{T}) where T <: valid_types 
+function UpperTriangular(A::GrB_Matrix{T}) where T 
     nrows, ncols = size(A)
     if nrows != ncols
         error("Matrix is not square")
@@ -442,7 +431,7 @@ end
 
 Return diagonal of a GraphBLAS matrix.
 """
-function Diagonal(A::GrB_Matrix{T}) where T <: valid_types 
+function Diagonal(A::GrB_Matrix{T}) where T 
     nrows, ncols = size(A)
     D = GrB_Matrix(T, nrows, ncols)
     res = GxB_select(D, GrB_NULL, GrB_NULL, GxB_DIAG, A, 0, GrB_NULL)