docs and fix world age issue

Author: Wimmerer

docs/src/arrays.md

@@ -38,15 +38,20 @@ SuiteSparseGraphBLAS.GBVector(::AbstractVector{<:Integer}, ::AbstractVector)
 
 # Indexing
 
-Normal AbstractArray and SparseArray indexing should work here. Including indexing by scalars, vectors, and ranges.
+The usual AbstractArray and SparseArray indexing capabilities are available. Including indexing by scalars, vectors, and ranges.
 
 !!! danger "Indexing Structural Zeros"
-    When indexing a `SparseMatrixCSC` from `SparseArrays` a structural, or implicit, zero will be returned as `zero(T)` where `T` is the elemtn type of the matrix.
+    When indexing a `SparseMatrixCSC` from `SparseArrays` a structural, or implicit, zero will be returned as `zero(T)` where `T` is the element type of the matrix.
 
-    When indexing a GBArray a structural zero is instead returned as `nothing`. While this is a significant departure from the `SparseMatrixCSC` it more closely matches the GraphBLAS spec, and enables the consuming method to determine the value of implicit zeros. 
+    When indexing a GBArray structural zeros are instead returned as `nothing`. 
+    While this is a significant departure from the `SparseMatrixCSC` it more closely matches the GraphBLAS spec,
+    and enables the consuming method to determine the value of implicit zeros. 
 
     For instance with an element type of `Float64` you may want the zero to be `0.0`, `-∞` or `+∞` depending on your algorithm. In addition, for graph algorithms there may be a distinction between an implicit zero, indicating the lack of an edge between two vertices in an adjacency matrix, and an explicit zero where the edge exists but has a `0` weight.
 
+    Better compatibility with `SparseMatrixCSC` and the ability to specify the value of implicit zeros is provided
+    by `SuiteSparseGraphBLAS.SparseArrayCompat.SparseMatrixGB` array type.
+
 ```@repl mat
 A = GBMatrix([1,1,2,2,3,4,4,5,6,7,7,7], [2,4,5,7,6,1,3,6,3,3,4,5], [1:12...])
 SparseMatrixCSC(A)
@@ -65,6 +70,11 @@ The functionality illustrated above extends to `GBVector` as well.
 The lazy Julia `transpose` is available, and the adjoint operator `'` is also
 overloaded to be equivalent.
 
+!!! danger "Adjoint vs Transpose"
+    The adjoint operator `'` currently transposes matrices rather than performing the
+    conjugate transposition. In the future this will change to the complex conjugate
+    for complex types, but currently you must do `map(conj, A')` to achieve this.
+
 # Utilities
 
 ```@docs

docs/src/binaryops.md

@@ -5,11 +5,21 @@ However, the vast majority of binary operators are defined on a single domain.
 
 ## Built-Ins
 
-All built-in binary oeprators can be found in the `BinaryOps` submodule.
+All built-in binary operators can be found in the `BinaryOps` submodule.
 
-The documentation below uses `T` to refer to any of the valid primitive types listed in [Supported Types](@ref), `ℤ` to refer to integers (signed and unsigned), `F` to refer to floating point types, `ℝ` to refer to real numbers (non-complex numbers).
+```@eval
+using Pkg
+Pkg.activate("..")
+cd("..")
+using SuiteSparseGraphBLAS
+using Latexify
+head = ["UnaryOp", "Function Form", "Types"]
+v1 = filter((x) -> getproperty(BinaryOps, x) isa SuiteSparseGraphBLAS.AbstractBinaryOp, names(BinaryOps))
+ops = getproperty.(Ref(BinaryOps), v1)
+v2 = convert(Vector{Any}, SuiteSparseGraphBLAS.juliaop.(ops))
+v4 = SuiteSparseGraphBLAS.validtypes.(ops)
 
-```@autodocs
-Modules = [SuiteSparseGraphBLAS]
-Pages   = ["binaryops.jl"]
+v1 = "`" .* string.(v1) .* "`"
+v2 = "`" .* string.(v2) .* "`"
+Latexify.mdtable(hcat(v1,v2,v4); head, latex=false)
 ```

docs/src/index.md

@@ -20,10 +20,11 @@ Pkg.add("SuiteSparseGraphBLAS")
 
 The SuiteSparse:GraphBLAS binary is installed automatically as `SSGraphBLAS_jll`.
 
+Then in the REPL or script `using SuiteSparseGraphBLAS` will import the package.
 # Introduction
 
 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. 
+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 one of 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.
 
 Below is an example of the adjacency matrix of a directed graph, and finding the neighbors of a single vertex using basic matrix-vector multiplication on the arithemtic semiring.

docs/src/operations.md

@@ -26,6 +26,10 @@ where ``\bf M`` is a `GBArray` mask, ``\odot`` is a binary operator for accumula
 !!! 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.
 
+## Operation Documentation
+
+All non-mutating operations below support a mutating form by adding an output array as the first argument as well as the `!` function suffix. 
+
 ### `mul`
 ```@docs
 mul
@@ -45,37 +49,41 @@ LinearAlgebra.kron
 
 ## Common arguments
 
-The operations above have often accept most or all of the following arguments.
+The operations typically accept one of the following types in the `op` argument.
 
 ### `op` - `UnaryOp`, `BinaryOp`, `Monoid`, `Semiring`, or `SelectOp`:
 
-This is the most important argument for most of the GraphBLAS 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.
+This argument determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`. They typically have synonymous functions in Julia, so `conj` can be used in place of `UnaryOps.CONJ` for instance.
 
 !!! tip "Built-Ins"
     The built-in operators can be found in the submodules: `UnaryOps`, `BinaryOps`, `Monoids`, and `Semirings`.
 
+See the [Operators](@ref) section for more information.
+
 ### `desc` - `Descriptor`:
 
 The descriptor argument allows the user to modify the operation in some fashion. The most common options are:
 
-- `desc.[input1 | input2] == [DEFAULT | TRANSPOSE]` 
+- `desc.[transpose_input1 | transpose_input2] == [true | false]` 
 
-    Transposes the inputs and can be found in `[T0 | T1 | T0T1]`. 
     Typically you should use Julia's built-in transpose functionality.
 
-- `desc.mask == [DEFAULT | STRUCTURE | COMPLEMENT | STRUCT_COMP]` 
+- `desc.complement_mask == [true | false]` 
+
+    If `complement_mask` is set the presence/truth value of the mask is complemented.
 
-    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.structural_mask == [true | false]`
+    
+    If `structural_mask` is set the presence of a value in the mask determines the presence of values
+    in the output, rather than the actual value of the mask.
 
-- `desc.output == [DEFAULT | REPLACE]`
+- `desc.replace_output == [true | false]`
 
-    If `REPLACE` is set the operation will replace all values in the output matrix **after** the accumulation step. 
+    If this option 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`. 
 
 
-### `accum` - `BinaryOp`:
+### `accum` - `BinaryOp | Function`:
 
 The `accum` keyword argument provides a binary operation to accumulate results into the result array. 
 The accumulation step is performed **before** masking.
@@ -88,16 +96,10 @@ The mask may also be complemented. These options are controlled by the `desc` ar
 
 ## Order of Operations
 
-A GraphBLAS operation occurs in the following order (steps are skipped when possible):
+A GraphBLAS operation semantically occurs in the following order:
 
 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
-
-All non-mutating operations below support a mutating form by adding an output array as the first argument as well as the `!` function suffix. 
-
-
+If `replace_output` is set the option in step 3. is `nothing`, otherwise it is `C[i,j]`.

docs/src/operators.md

@@ -3,37 +3,35 @@
 There are five operator types in SuiteSparseGraphBLAS. Four are defined for all GraphBLAS implementations: `UnaryOp`, `BinaryOp`, `Monoid`, and `Semiring`. 
 One is an extension to the `v1.3` specification: `SelectOp`.
 
-!!! note "Operator vs Algebraic Object"
-    While we will refer to anything in the list above as an operator, semirings and monoids are technically not operators so much as algebraic objects.
-
 !!! danger "Note"
-    Operators are **not** callable objects like functions. They **do** behave like functions as arguments to higher-order functions (operations in the language of GraphBLAS). 
+    Operators are **not** callable objects like functions. They **do** behave like functions as arguments to higher-order functions (operations in the language of GraphBLAS). However `BinaryOp` and `UnaryOp` operators
+    typically have a synonymous julia function, which can be found using `juliaop(op)`.
 
 Typically operators are positional arguments in one of two places.
 For operations with a clear default operator they appear as the last positional argument:
 
-- [`emul(A, B, op::BinaryOp)`](@ref emul)
-- [`eadd(A, B, op::BinaryOp)`](@ref eadd)
-- [`kron(A, B, op::BinaryOp)`](@ref kron)
-- [`mul(A, B, op::Semiring)`](@ref mul)
+- [`emul(A, B, op::Union{BinaryOp, Function})`](@ref emul)
+- [`eadd(A, B, op::Union{BinaryOp, Function})`](@ref eadd)
+- [`kron(A, B, op::Union{BinaryOp, Function})`](@ref kron)
+- [`mul(A, B, op::Union{Semiring, Tuple{Function, Function}})`](@ref mul)
 
 For other operations without a clear default operator they appear as the first argument:
 
-- [`map(op::UnaryOp, A)`](@ref map) or [`map(op::Monoid, A, x)`](@ref map)
-- [`reduce(op::BinaryOp, A)`](@ref reduce)
-- [`select(op::SelectOp, A)`](@ref select)
+- [`map(op::Union{UnaryOp, Function}, A)`](@ref map)
+- [`reduce(op::Union{BinaryOp, Function}, A)`](@ref reduce)
+- [`select(op::Union{SelectOp, Function}, A)`](@ref select)
 
 ## UnaryOps, BinaryOps, Monoids, and Semirings
 
-Each operator is defined on a specific domain. For some this is the typical primitive datatypes like booleans, floats, and signed and unsigned integers of the typical sizes. A few also accept complex numbers, while most are restricted to some subset of these types.
+Each operator is defined on a specific domain. For some this is the usual primitive datatypes like booleans, floats, and signed and unsigned integers of the typical sizes.
 
-Each operator is represented as its own concrete type. 
+Each operator is represented as its own concrete type for dispatch purposes. 
 For instance `BinaryOps.PLUS <: AbstractBinaryOp <: AbstractOp`.
 Operators are effectively dictionaries containing the type-specific operators indexed by the `DataType` of their arguments. 
 
 ### Supported Types
 
-GraphBLAS supports the following types:
+SuiteSparseGraphBLAS.jl natively supports the following types:
 
 - Booleans
 - Integers with sizes 8, 16, 32, 64
@@ -46,11 +44,12 @@ The supported types can be found as in the example below:
 using SuiteSparseGraphBLAS
 ```
 ```@repl operators
+Semiring(max, +)
 Semirings.MAX_PLUS
 Semirings.MAX_PLUS[Float64]
 ```
 
-Either form may be passed to all operations, the function will take care of selecting the proper typed operator.
+All operations will accept the function/tuple form, the `DataType` form, or the `TypedSemiring` form.
 Unless you need to specifically cast the arguments to a specific type there is no need to specify the operator type.
 
 You can determine the available types for an operator and the input and output types of a type-specific operator with the functions below:

docs/src/selectops.md

@@ -9,7 +9,16 @@ Applying `select` with a `SelectOp` will always return a result with the same ty
 
 Built-in `SelectOp`s can be found in the `SelectOps` submodule.
 
-```@autodocs
-Modules = [SuiteSparseGraphBLAS]
-Pages   = ["selectops.jl"]
+```@docs
+SuiteSparseGraphBLAS.TRIL
+SuiteSparseGraphBLAS.TRIU
+SuiteSparseGraphBLAS.DIAG
+SuiteSparseGraphBLAS.OFFDIAG
+SuiteSparseGraphBLAS.NONZERO
+SuiteSparseGraphBLAS.NE
+SuiteSparseGraphBLAS.EQ
+SuiteSparseGraphBLAS.GT
+SuiteSparseGraphBLAS.GE
+SuiteSparseGraphBLAS.LT
+SuiteSparseGraphBLAS.LE
 ```

docs/src/sparsearrays.md

@@ -17,7 +17,19 @@ map(UnaryOps.ASIN, y)
 
 ## Built-Ins
 
-```@autodocs
-Modules = [SuiteSparseGraphBLAS]
-Pages   = ["unaryops.jl"]
+```@eval
+using Pkg
+Pkg.activate("..")
+cd("..")
+using SuiteSparseGraphBLAS
+using Latexify
+head = ["UnaryOp", "Function Form", "Types"]
+v1 = filter((x) -> getproperty(UnaryOps, x) isa SuiteSparseGraphBLAS.AbstractUnaryOp, names(UnaryOps))
+ops = getproperty.(Ref(UnaryOps), v1)
+v2 = convert(Vector{Any}, SuiteSparseGraphBLAS.juliaop.(ops))
+v4 = SuiteSparseGraphBLAS.validtypes.(ops)
+
+v1 = "`" .* string.(v1) .* "`"
+v2 = "`" .* string.(v2) .* "`"
+Latexify.mdtable(hcat(v1,v2,v4); head, latex=false)
 ```

docs/src/unaryops.md

@@ -92,7 +92,7 @@ end
     extract(A::GBMatOrTranspose, I, J; kwargs...)::GBMatrix
     extract(A::GBVector, I; kwargs...)::GBVector
 
-    Extract a submatrix or subvector from `A`
+Extract a submatrix or subvector from `A`
 
 # Arguments
 - `A::GBArray`: the array being indexed.

src/operations/extract.jl

@@ -91,7 +91,7 @@ Base.setindex!(o::AbstractBinaryOp, x, t1::DataType, t2::DataType) = setindex!(o
 Base.setindex!(o::AbstractBinaryOp, x, t::DataType) = setindex!(o, x, (t, t))
 
 function addtoop(op::AbstractUnaryOp, type)
-    f = juliaop(op)
+    f = Base.invokelatest(juliaop, op)
     resulttypes = Base.return_types(f, (type,))
     if length(resulttypes) != 1
         throw(ArgumentError("Inferred more than one result type for function $(string(f)) on type $type."))
@@ -100,8 +100,8 @@ function addtoop(op::AbstractUnaryOp, type)
 end
 
 function addtoop(op::AbstractBinaryOp, type1, type2)
-    f = juliaop(op)
-    resulttypes = Base.return_types(f, (type, type2))
+    f = Base.invokelatest(juliaop, op)
+    resulttypes = Base.return_types(f, (type1, type2))
     if length(resulttypes) != 1
         throw(ArgumentError("Inferred more than one result type for function $(string(f)) on type $type."))
     end
@@ -113,5 +113,5 @@ function Base.show(io::IO, ::MIME"text/plain", o::AbstractOp)
     print(io, o.name, ": ", validtypes(o))
 end
 
-function juliaop end
-juliaop(op::AbstractMonoid) = juliaop(op(op))
+juliaop(op) = nothing
+juliaop(op::AbstractMonoid) = juliaop(op(op))