reorg, docs changes

Author: Will Kimmerer

docs/src/arrays.md

@@ -1,4 +1,4 @@
-# GBArrays
+# Array Types
 
 There are two primary datastructures in in `SuiteSparseGraphBLAS.jl`: the `GBVector` and `GBMatrix`.
 
@@ -41,9 +41,11 @@ SuiteSparseGraphBLAS.GBVector(::AbstractVector{<:Integer}, ::AbstractVector)
 Normal AbstractArray and SparseArray indexing should work here. Including indexing by scalars, vectors, and ranges.
 
 !!! danger "Indexing Structural Zeros"
-    When you index a `SparseMatrixCSC` from `SparseArrays` and hit a structural zero (a value within the dimensions of the matrix but not stored) you can expect a `zero(T)`.
+    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 you index a GBArray you will get `nothing` when you hit a structural zero. This is because the zero in GraphBLAS depends not just on the domain of the elements but also on what you are __doing__ with them. For instance with an element type of `Float64` you could want the zero to be `0.0`, `-∞` or `+∞`.
+    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. 
+    
+    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.
 
 ```@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...])
@@ -57,15 +59,12 @@ A[:, 5]
 SparseMatrixCSC(A'[:,:]) #Transpose the first argument
 ```
 
-All of this same functionality exists for vectors in 1-dimension.
+The functionality illustrated above extends to `GBVector` as well.
 
 # Transpose
 The lazy Julia `transpose` is available, and the adjoint operator `'` is also
 overloaded to be equivalent.
 
-`x = A'` will create a `Transpose` wrapper.
-When an operation uses this argument it will cause the `desc` to set `INP<0|1> = T_<0|1>`. 
-
 # Utilities
 
 ```@docs

docs/src/operations.md

@@ -26,6 +26,23 @@ 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.
 
+### `mul`
+```@docs
+mul
+emul
+emul!
+eadd
+eadd!
+extract
+subassign!
+assign!
+Base.map
+select
+Base.reduce
+gbtranspose
+LinearAlgebra.kron
+```
+
 ## Common arguments
 
 The operations above have often accept most or all of the following arguments.
@@ -83,20 +100,4 @@ If `REPLACE` is set the option in step 3. is `nothing`, otherwise it is `C[i,j]`
 
 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
-```
 
-```@docs
-emul
-eadd
-extract
-subassign!
-assign!
-Base.map
-select
-Base.reduce
-gbtranspose
-LinearAlgebra.kron
-```

src/SuiteSparseGraphBLAS.jl

@@ -55,6 +55,8 @@ include("indexutils.jl")
 # Globals
 include("constants.jl")
 
+
+include("operations/extract.jl")
 include("scalar.jl")
 include("vector.jl")
 include("matrix.jl")

src/matrix.jl

@@ -230,142 +230,7 @@ SparseArrays.nonzeros(A::GBArray) = findnz(A)[end]
 
 # Indexing functions
 ####################
-"""
-    _outlength(A, I, J)
-    _outlength(u, I)
-Determine the size of the output for an operation like extract or range-based indexing.
-"""
-function _outlength(A, I, J)
-    if I == ALL
-        Ilen = size(A, 1)
-    else
-        Ilen = length(I)
-    end
-    if J == ALL
-        Jlen = size(A, 2)
-    else
-        Jlen = length(J)
-    end
-    return Ilen, Jlen
-end
-
-"""
-    extract!(C::GBMatrix, A::GBMatrix, I, J; kwargs...)::GBMatrix
-
-Extract a submatrix from `A` into `C`.
-
-# Arguments
-- `C::GBMatrix`: the submatrix extracted from `A`. It is a dimension mismatch if
-    `size(C) != (max(I), max(J))`.
-- `A::GBMatrix`: the array being indexed.
-- `I` and `J`: A colon, scalar, vector, or range indexing A.
-
-# Keywords
-- `mask::Union{Nothing, GBMatrix} = nothing`: mask where
-    `size(M) == (max(I), max(J))`.
-- `accum::Union{Nothing, AbstractBinaryOp} = nothing`: binary accumulator operation
-    where `C[i,j] = accum(C[i,j], T[i,j])` where T is the result of this function before accum is applied.
-- `desc::Descriptor = nothing`
-
-# Returns
-- `GBMatrix`: the modified matrix `C`, now containing the submatrix `A[I, J]`.
-
-# Throws
-- `GrB_DIMENSION_MISMATCH`: If `size(C) != (max(I), max(J))` or `size(C) != size(mask)`.
-"""
-function extract!(
-    C::GBMatrix, A::GBMatOrTranspose, I, J;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    I, ni = idx(I)
-    J, nj = idx(J)
-    I isa Number && (I = UInt64[I])
-    J isa Number && (J = UInt64[J])
-    mask === nothing && (mask = C_NULL)
-    desc = _handledescriptor(desc; in1 = A)
-    libgb.GrB_Matrix_extract(C, mask, getaccum(accum, eltype(C)), parent(A), I, ni, J, nj, desc)
-    return C
-end
-
-function extract!(
-    C::GBMatrix, A::GBMatOrTranspose, ::Colon, J;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract!(C, A, ALL, J; mask, accum, desc)
-end
-
-function extract!(
-    C::GBMatrix, A::GBMatOrTranspose, I, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract!(C, A, I, ALL; mask, accum, desc)
-end
-
-function extract!(
-    C::GBMatrix, A::GBMatOrTranspose, ::Colon, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract!(C, A, ALL, ALL; mask, accum, desc)
-end
-
-"""
-    extract(A::GBMatrix, I, J; kwargs...)::GBMatrix
-
-Extract a submatrix from `A`.
-
-# Arguments
-- `A::GBMatrix`: the array being indexed.
-- `I` and `J`: A colon, scalar, vector, or range indexing A.
-
-# Keywords
-- `mask::Union{Nothing, GBMatrix} = nothing`: mask where
-    `size(M) == (max(I), max(J))`.
-- `accum::Union{Nothing, AbstractBinaryOp} = nothing`: binary accumulator operation
-    where `C[i,j] = accum(C[i,j], T[i,j])` where T is the result of this function before accum is applied. `C` is, however, empty.
-- `desc::Descriptor = nothing`
-
-# Returns
-- `GBMatrix`: the submatrix `A[I, J]`.
-
-# Throws
-- `GrB_DIMENSION_MISMATCH`: If `(max(I), max(J)) != size(mask)`.
-"""
-function extract(
-    A::GBMatOrTranspose, I, J;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    Ilen, Jlen = _outlength(A, I, J)
-    C = similar(A, Ilen, Jlen)
-    return extract!(C, A, I, J; mask, accum, desc)
-end
 
-function extract(
-    A::GBMatOrTranspose, ::Colon, J;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, ALL, J; mask, accum, desc)
-end
-
-function extract(
-    A::GBMatOrTranspose, I, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, I, ALL; mask, accum, desc)
-end
-
-function extract(
-    A::GBMatOrTranspose, ::Colon, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, ALL, ALL; mask, accum, desc)
-end
-
-function Base.getindex(
-    A::GBMatOrTranspose, ::Colon, j;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, ALL, j; mask, accum, desc)
-end
 function Base.getindex(
     A::GBMatOrTranspose, i, ::Colon;
     mask = nothing, accum = nothing, desc = nothing
@@ -392,7 +257,7 @@ end
 """
     subassign!(C::GBMatrix, A::GBMatrix, I, J; kwargs...)::GBMatrix
 
-Assign a submatrix of `C` to `A`. Equivalent to [`assign!`](@ref) except that
+Assign a submatrix of `A` to `C`. Equivalent to [`assign!`](@ref) except that
 `size(mask) == size(A)`, whereas `size(mask) == size(C)` in `assign!`.
 
 # Arguments
@@ -403,9 +268,9 @@ Assign a submatrix of `C` to `A`. Equivalent to [`assign!`](@ref) except that
 # Keywords
 - `mask::Union{Nothing, GBMatrix} = nothing`: mask where
     `size(M) == size(A)`.
-- `accum::Union{Nothing, AbstractBinaryOp} = nothing`: binary accumulator operation
+- `accum::Union{Nothing, Function, AbstractBinaryOp} = nothing`: binary accumulator operation
     where `C[i,j] = accum(C[i,j], T[i,j])` where T is the result of this function before accum is applied.
-- `desc::Descriptor = nothing`
+- `desc::Union{Nothing, Descriptor} = nothing`
 
 # Returns
 - `GBMatrix`: The input matrix A.
@@ -439,7 +304,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 `A` to `C`. Equivalent to [`subassign!`](@ref) except that
 `size(mask) == size(C)`, whereas `size(mask) == size(A) in `subassign!`.
 
 # Arguments
@@ -450,9 +315,9 @@ Assign a submatrix of `C` to `A`. Equivalent to [`subassign!`](@ref) except that
 # Keywords
 - `mask::Union{Nothing, GBMatrix} = nothing`: mask where
     `size(M) == size(C)`.
-- `accum::Union{Nothing, AbstractBinaryOp} = nothing`: binary accumulator operation
+- `accum::Union{Nothing, Function, AbstractBinaryOp} = nothing`: binary accumulator operation
     where `C[i,j] = accum(C[i,j], T[i,j])` where T is the result of this function before accum is applied.
-- `desc::Descriptor = nothing`
+- `desc::Union{Nothing, Descriptor} = nothing`
 
 # Returns
 - `GBMatrix`: The input matrix A.