Mostly docs

Author: Wimmerer

Project.toml

@@ -12,7 +12,6 @@ ContextVariablesX = "6add18c4-b38d-439d-96f6-d6bc489c04c5"
 Libdl = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
-MatrixDepot = "b51810bb-c9f3-55da-ae3c-350fc1fbce05"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SSGraphBLAS_jll = "7ed9a814-9cab-54e9-8e9e-d9e95b4d61b1"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"

docs/make.jl

@@ -3,11 +3,17 @@ using SuiteSparseGraphBLAS
 
 makedocs(
     modules = [SuiteSparseGraphBLAS],
-    sitename="SuiteSparse:GraphBLAS",
+    sitename="SuiteSparseGraphBLAS.jl",
     pages = [
         "Introduction" => "index.md",
         "Arrays" => "arrays.md",
-        "Operations" => "operations.md"
+        "Operations" => "operations.md",
+        "Operators" => [
+            "unaryops.md",
+            "binaryops.md",
+            "monoids.md",
+            "semirings.md"
+        ]
     ]
 )
 

docs/src/index.md

@@ -9,11 +9,10 @@ While the core library is mostly complete, and all GraphBLAS functionality is pr
 
 1. ChainRules.jl integration for AD.
 2. Complete SparseArrays and ArrayInterface interfaces.
-3. Import and Export in all formats including bitmap and csr. Currently only dense and csc are supported.
-4. Printing v2.
-5. User-defined types and functions.
-6. Alternative syntax for GraphBLAS ops (currently must use `BinaryOps.PLUS` instead of `+`).
-7. Complex builtins.
+3. Printing v2.
+4. User-defined types and functions.
+5. Alternative syntax for GraphBLAS ops (currently must use `BinaryOps.PLUS` instead of `+`).
+6. Complex builtins.
 
 Once these are completed there will be a v1.0 release, with the goal being JuliaCon 2021.
 
@@ -47,7 +46,7 @@ The SuiteSparse:GraphBLAS binary is installed automatically as `SSGraphBLAS_jll`
 
 # Introduction
 
-GraphBLAS harnesses the well-understood duality between graphs and matrices. 
+GraphBLAS harnesses the well-understood duality between graphs and matrices.
 Specifically a graph can be represented by its [adjacency matrix](https://en.wikipedia.org/wiki/Adjacency_matrix), [incidence matrix](https://en.wikipedia.org/wiki/Incidence_matrix), or the many variations on those formats. 
 With this matrix representation in hand we have a method to operate on the graph using linear algebra operations on the matrix.
 
@@ -104,8 +103,8 @@ v = GBVector([4], [10])
 ```
 ## GraphBLAS Operations
 
-A complete list of supported operations can be found in [Operations](@ref).
-GraphBLAS operations are, where possible, wrapped in existing Julia functions. The equivalent Julia functions are:
+The complete documentation of supported operations can be found in [Operations](@ref).
+GraphBLAS operations are, where possible, methods of existing Julia functions  listed in the third column.
 
 | GraphBLAS           | Operation                                                        | Julia                                   |
 |:--------------------|:----------------------------------------:                        |----------:                              |
@@ -126,25 +125,15 @@ GraphBLAS operations are, where possible, wrapped in existing Julia functions. T
 
 where ``\bf M`` is a `GBArray` mask, ``\odot`` is a binary operator for accumulating into ``\bf C``, and ``\otimes`` and ``\oplus`` are a binary operation and commutative monoid respectively. 
 
-!!! note "assign vs subassign"
-
-    `subassign` is equivalent to `assign` except that the mask in `subassign` has the dimensions of ``\bf C(I,J)`` vs the dimensions of ``C`` for `assign`, and elements outside of the mask will never be modified by `subassign`.
-
 ### Common arguments
 
-The operations above have a typical set of common arguments. These are:
+The operations above have often accept most or all of the following arguments.
 
-#### `op` - `UnaryOp`, `BinaryOp`, `Monoid`, or `Semiring`:
+#### `op` - `UnaryOp`, `BinaryOp`, `Monoid`, `Semiring`, or `SelectOp`:
 
-This is the key argument to most of these operations, which determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`.
+This is the most important argument for most of these operations. It determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`.
 Most operations are restricted to one type of operator.
 
-!!! warning "Keyword vs Positional"
-    For some operations like `mul` and `emul` this is a keyword argument which defaults to the typical arithmetic operators.
-    For others like `map` this is the first argument, since there is no sensible default choice.
-
-
-
 !!! tip "Built-Ins"
     The built-in operators can be found in the submodules: `UnaryOps`, `BinaryOps`, `Monoids`, and `Semirings`.
 
@@ -157,12 +146,12 @@ The descriptor argument allows the user to modify the operation in some fashion.
     Transposes the inputs and can be found in `Descriptors.[T0 | T1 | T0T1]`. 
     Typically you should use Julia's built-in transpose functionality.
 
-- `desc.mask == [DEFAULT | STRUCTURE | COMPLEMENT | STRUCTURE + COMPLEMENT]` 
+- `desc.mask == [DEFAULT | STRUCTURE | COMPLEMENT | STRUCT_COMP]` 
 
     If `STRUCTURE` is set the operation will use the presence of a value rather than the value itself to determine whether the index is masked. 
     If `COMPLEMENT` is set the presence/truth value is complemented (ie. if **no** value is present or the value is **false** that index is masked).
 
-- `desc.output` == [DEFAULT | REPLACE]
+- `desc.output == [DEFAULT | REPLACE]`
 
     If `REPLACE` is set the operation will replace all values in the output matrix **after** the accumulation step. 
     If an index is found in the output matrix, but not in the results of the operation it will be set to `nothing`. 
@@ -177,18 +166,7 @@ The accumulation step is performed **before** masking.
 
 The `mask` keyword argument determines whether each index from the result of an operation appears in the output. 
 The mask may be structural, where the presence of a value indicates the mask is `true`, or valued where the value of the mask indicates its truth value. 
-The mask may also be complemented.
-
-
-### Order of Operations
-
-A GraphBLAS operation occurs in the following order (steps are skipped when possible):
-
-1. Calculate `T = <operation>(args...)`
-2. Elementwise accumulate `Z[i,j] = accum(C[i,j], T[i,j])`
-3. Optionally masked assignment `C[i,j] = mask[i,j] ? Z[i,j] : [nothing | C[i,j]]`
-
-If `REPLACE` is set the option in step 3. is `nothing`, otherwise it is `C[i,j]`.
+The mask may also be complemented. These options are controlled by the `desc` argument.
 
 ## GraphBLAS Operators
 
@@ -214,7 +192,25 @@ BOR       COPYSIGN   FIRSTJ     ISEQ       LAND       MAX        POW        SECO
 
 ## Example
 
+Here is an example of several different methods of triangle counting with GraphBLAS.
+The methods are drawn from the LAGraph [repo](https://github.com/GraphBLAS/LAGraph).
 
+Input `A` must be a square, symmetric matrix with any element type.
+We'll test it using the matrix from the GBArray section above, which has two triangles in its undirected form.
 
 ```julia
+function cohen(A)
+  U = select(SelectOps.TRIU, A)
+  L = select(SelectOps.TRIL, A)
+  return reduce(Monoids.PLUS_MONOID[Int64], mul(L, U, Semirings.PLUS_PAIR; mask=A)) ÷ 2
+end
+
+function sandia(A)
+  L = select(SelectOps.TRIL, A)
+  return reduce(Monoids.PLUS_MONOID[Int64], mul(L, L, Semirings.PLUS_PAIR; mask=L))
+end
+
+M = eadd(A, A', BinaryOps.PLUS) #Make undirected/symmetric
+cohen(A) # 2
+sandia(A) # 2
 ```

docs/src/operations.md

@@ -1 +1,54 @@
-# Operations
+# Operations
+
+GraphBLAS operations cover most of the typical linear algebra operations on arrays in Julia.
+
+## Correspondence of GraphBLAS C functions and Julia functions
+
+| GraphBLAS           | Operation                                                        | Julia                                   |
+|:--------------------|:----------------------------------------:                        |----------:                              |
+|`mxm`, `mxv`, `vxm`  |``\bf C \langle M \rangle = C \odot AB``                          |`mul[!]`                                 |
+|`eWiseMult`          |``\bf C \langle M \rangle = C \odot (A \otimes B)``               |`emul[!]`                                |
+|`eWiseAdd`           |``\bf C \langle M \rangle = C \odot (A \oplus  B)``               |`eadd[!]`                                |
+|`extract`            |``\bf C \langle M \rangle = C \odot A(I,J)``                      |`extract[!]`, `getindex`                 |
+|`subassign`          |``\bf C (I,J) \langle M \rangle = C(I,J) \odot A``                |`subassign[!]`, `setindex!`              |
+|`assign`             |``\bf C \langle M \rangle (I,J) = C(I,J) \odot A``                |`assign[!]`                              |
+|`apply`              |``{\bf C \langle M \rangle = C \odot} f{\bf (A)}``                |`map[!]`                                 |
+|                     |``{\bf C \langle M \rangle = C \odot} f({\bf A},y)``              |                                         |
+|                     |``{\bf C \langle M \rangle = C \odot} f(x,{\bf A})``              |                                         |
+|`select`             |``{\bf C \langle M \rangle = C \odot} f({\bf A},k)``              |`select[!]`                              |
+|`reduce`             |``{\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]`` |`reduce[!]`                              |
+|                     |``s = s \odot [{\oplus}_{ij}  {\bf A}(i,j)]``                     |                                         |
+|`transpose`          |``\bf C \langle M \rangle = C \odot A^{\sf T}``                   |`gbtranspose[!]`, lazy: `transpose`, `'` |
+|`kronecker`          |``\bf C \langle M \rangle = C \odot \text{kron}(A, B)``           |`kron[!]`                                |
+
+where ``\bf M`` is a `GBArray` mask, ``\odot`` is a binary operator for accumulating into ``\bf C``, and ``\otimes`` and ``\oplus`` are a binary operation and commutative monoid respectively. 
+
+!!! note "assign vs subassign"
+    `subassign` is equivalent to `assign` except that the mask in `subassign` has the dimensions of ``\bf C(I,J)`` vs the dimensions of ``C`` for `assign`, and elements outside of the mask will never be modified by `subassign`. See the [GraphBLAS User Guide](https://github.com/DrTimothyAldenDavis/GraphBLAS/blob/stable/Doc/GraphBLAS_UserGuide.pdf) for more details.
+
+## Order of Operations
+
+A GraphBLAS operation occurs in the following order (steps are skipped when possible):
+
+1. Calculate `T = <operation>(args...)`
+2. Elementwise accumulate `Z[i,j] = accum(C[i,j], T[i,j])`
+3. Optionally masked assignment `C[i,j] = mask[i,j] ? Z[i,j] : [nothing | C[i,j]]`
+
+If `REPLACE` is set the option in step 3. is `nothing`, otherwise it is `C[i,j]`.
+
+## Operation Documentation
+
+```@docs
+mul
+emul
+eadd
+extract
+extract!
+subassign!
+assign!
+map
+select
+reduce
+gbtranspose
+kron
+```

docs/src/operators.md

@@ -0,0 +1 @@
+# Operators

docs/src/unaryops.md

@@ -0,0 +1,6 @@
+# Unary Operators
+
+```@autodocs
+Modules = [SuiteSparseGraphBLAS]
+Pages   = ["unaryops.jl"]
+```

src/SuiteSparseGraphBLAS.jl

@@ -63,6 +63,7 @@ const OperatorUnion = Union{
     GrBOp
 }
 
+#Context variables for the `with` function
 @contextvar ctxop::OperatorUnion
 @contextvar ctxmask::Union{GBArray, Ptr} = C_NULL
 @contextvar ctxaccum::Union{BinaryUnion, Ptr} = C_NULL
@@ -93,17 +94,18 @@ include("options.jl")
 include("misc.jl")
 export libgb
 export UnaryOps, BinaryOps, Monoids, Semirings, SelectOps, Descriptors #Submodules
+export Descriptor #Types
 export xtype, ytype, ztype
 export GBScalar, GBVector, GBMatrix #arrays
 export clear!, extract, extract!, subassign!, assign! #array functions
 
 #operations
 export mul, select, select!, eadd, eadd!, emul, emul!, map, map!, gbtranspose, gbtranspose!
 # Reexports.
-export diag, Diagonal, mul!, kron, kron!, transpose
+export diag, Diagonal, mul!, kron, kron!, transpose, reduce
 export nnz, sprand, findnz
 
-#with function
+#context/with
 export with
 
 function __init__()
@@ -121,7 +123,4 @@ function __init__()
     end
 end
 
-#We need to do this after __init__
-
-
 end #end of module

src/descriptors.jl

@@ -95,7 +95,7 @@ end
 #This is probably not ideal. Perhaps kwargs = nothing by default is better
 Base.:+(d1::Descriptor, ::Nothing) = d1
 Base.:+(::Nothing, d2::Descriptor) = d2
-
+Base.:+(f1::libgb.GrB_Desc_Value, f2::libgb.GrB_Desc_Value) = libgb.GrB_Desc_Value(UInt32(f1) + UInt32(f2))
 function Base.propertynames(d::Descriptor)
     return (
     :output,
@@ -117,6 +117,7 @@ GxB_DEFAULT,
 GrB_REPLACE,
 GrB_COMP,
 GrB_STRUCTURE,
+GrB_STRUCT_COMP,
 GrB_TRAN,
 GxB_GPU_ALWAYS,
 GxB_GPU_NEVER,
@@ -131,6 +132,7 @@ const DEFAULT = GxB_DEFAULT
 const REPLACE = GrB_REPLACE
 const COMPLEMENT = GrB_COMP
 const STRUCTURE = GrB_STRUCTURE
+const STRUCT_COMP = GrB_STRUCT_COMP
 const TRANSPOSE = GrB_TRAN
 const GUSTAVSON = GxB_AxB_GUSTAVSON
 const DOT = GxB_AxB_DOT

src/lib/LibGraphBLAS.jl

@@ -97,6 +97,7 @@ end
     GrB_COMP = 2
     # GrB_SCMP = 2
     GrB_STRUCTURE = 4
+    GrB_STRUCT_COMP = 6
     GrB_TRAN = 3
     GxB_GPU_ALWAYS = 2001
     GxB_GPU_NEVER = 2002

src/matrix.jl

@@ -305,7 +305,7 @@ end
 """
     assign!(C::GBMatrix, A::GBMatrix, I, J; kwargs...)::GBMatrix
 
-Assign a submatrix of `C` to `A`. Equivalent to [`subassign`](@ref) except that
+Assign a submatrix of `C` to `A`. Equivalent to [`subassign!`](@ref) except that
 `size(mask) == size(C)`, whereas `size(mask) == size(A) in `subassign!`.
 
 # Arguments
@@ -392,3 +392,18 @@ function Base.setindex(
 )
     throw("Not implemented")
 end
+
+#Printing fixes:
+function Base.isstored(A::GBArray, i::Integer, j::Integer)
+    @boundscheck checkbounds(A, i, j)
+    if A[i, j] === nothing
+        return false
+    else
+        return true
+    end
+end
+
+#Help wanted: This isn't really centered for a lot of eltypes.
+function Base.replace_in_print_matrix(A::GBArray, i::Integer, j::Integer, s::AbstractString)
+    Base.isstored(A, i, j) ? s : Base.replace_with_centered_mark(s)
+end