Add an Examples page to the docs

docs/make.jl

@@ -19,7 +19,8 @@ makedocs(
             "selectops.md"#,
             #"udfs.md"
         ],
-        "Utilities" => "utilities.md"
+        "Utilities" => "utilities.md",
+        "Examples" => "examples.md"
     ]
 )
 

docs/src/arrays.md

@@ -1,5 +1,10 @@
 # Array Types
 
+```@meta
+DocTestSetup = :(using SuiteSparseGraphBLAS, SparseArrays)
+DocTestFilters = [r"memory: \d+ bytes"]
+```
+
 There are two primary array types in SuiteSparseGraphBLAS.jl: [`GBVector`](@ref) and [`GBMatrix`](@ref), as well as a few specialized versions of those array types. The full type hierarchy is:
 
 ```
@@ -33,17 +38,38 @@ Users should rarely need to directly interact with the underlying storage format
 ### Construction
 
 There are several methods to construct GBArrays. Shown here are empty construction, conversion from a dense matrix and a sparse matrix, and coordinate form with uniform or *iso* coefficients. 
-```@setup mat
-using SuiteSparseGraphBLAS
-using SparseArrays
-```
-```@repl mat
-x = GBMatrix{Bool}(20_000_000, 50_000)
-x = GBMatrix([[1,2] [3,4]])
-x = GBMatrix(sprand(100, 100, 0.5); fill = 0.0)
-x = GBMatrix(
-    rand(1:50_000, 5000), rand(1:500_000, 5000), 1, 500_000, 500_000
-)
+```jldoctest mat
+julia> x = GBMatrix{Bool}(20_000_000, 50_000)
+20000000x50000 GraphBLAS bool matrix, hypersparse by row, ints: 32/32/32
+  no entries, memory: 256 bytes
+
+julia> x = GBMatrix([[1,2] [3,4]])
+2x2 GraphBLAS int64_t matrix, full by col
+  4 entries, memory: 272 bytes
+
+    (1,1)   1
+    (2,1)   2
+    (1,2)   3
+    (2,2)   4
+
+julia> x = GBMatrix(sparse([1, 2, 3], [3, 1, 2], [1.0, 2.0, 3.0]); fill = 0.0)
+3x3 GraphBLAS double matrix, bitmap by col
+  3 entries, memory: 321 bytes
+
+    (2,1)    2
+    (3,2)    3
+    (1,3)    1
+
+julia> x = GBMatrix(
+           [1, 20_000, 400_000], [7, 30_000, 500_000], 1, 500_000, 500_000
+       )
+500000x500000 GraphBLAS int64_t matrix, hypersparse by row, ints: 32/32/32
+  3 entries, memory: 288 bytes
+  iso value:   1
+
+    (1,7)   1
+    (20000,30000)   1
+    (400000,500000)   1
 ```
 
 ```@docs
@@ -56,10 +82,26 @@ A `GBVector` is the one-dimensional equivalent of the `GBMatrix`, and internally
 
 ### Construction 
 
-```@repl mat
-v = GBVector{ComplexF32}(100)
-v = GBMatrix(rand(ComplexF64, 3); fill = nothing)
-v = GBVector(sprand(Bool, 100_000_000, 0.001))
+```jldoctest mat
+julia> v = GBVector{ComplexF32}(100)
+100x1 GraphBLAS float complex matrix, sparse by col, ints: 32/32/32
+  no entries, memory: 248 bytes
+
+julia> v = GBMatrix(ComplexF64[1, 2im, 3 + 4im]; fill = nothing)
+3x1 GraphBLAS double complex matrix, full by col
+  3 entries, memory: 288 bytes
+
+    (1,1)    1 + 0i
+    (2,1)    0 + 2i
+    (3,1)    3 + 4i
+
+julia> v = GBVector(sparsevec([1, 50_000_000, 100_000_000], true, 100_000_000))
+100000000x1 GraphBLAS bool matrix, sparse by col, ints: 64/64/64
+  3 entries, memory: 283 bytes
+
+    (1,1)   1
+    (50000000,1)   1
+    (100000000,1)   1
 ```
 
 ```@docs
@@ -81,15 +123,87 @@ The usual AbstractArray and SparseArray indexing capabilities are available. Inc
 
     However, many functions outside of GraphBLAS will throw an error if they receive `nothing` from an indexing operation. To accomodate these functions the user may set the fill value for an `AbstractGBArray` on construction and with [`setfill`](@ref) and [`setfill!`](@ref).
 
-```@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)
-A[4]
-A[1,2]
-A[[1,3,5,7], :]
-A[1:2:7, :]
-A[:,:]
-A[:, 5]
+```jldoctest mat
+julia> 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...])
+7x7 GraphBLAS int64_t matrix, bitmap by row
+  12 entries, memory: 681 bytes
+
+    (1,2)   1
+    (1,4)   2
+    (2,5)   3
+    (2,7)   4
+    (3,6)   5
+    (4,1)   6
+    (4,3)   7
+    (5,6)   8
+    (6,3)   9
+    (7,3)   10
+    (7,4)   11
+    (7,5)   12
+
+julia> SparseMatrixCSC(A)
+7×7 SparseMatrixCSC{Int64, Int64} with 12 stored entries:
+ ⋅  1   ⋅   2   ⋅  ⋅  ⋅
+ ⋅  ⋅   ⋅   ⋅   3  ⋅  4
+ ⋅  ⋅   ⋅   ⋅   ⋅  5  ⋅
+ 6  ⋅   7   ⋅   ⋅  ⋅  ⋅
+ ⋅  ⋅   ⋅   ⋅   ⋅  8  ⋅
+ ⋅  ⋅   9   ⋅   ⋅  ⋅  ⋅
+ ⋅  ⋅  10  11  12  ⋅  ⋅
+
+julia> A[4]
+6
+
+julia> A[1,2]
+1
+
+julia> A[[1,3,5,7], :]
+4x7 GraphBLAS int64_t matrix, bitmap by row
+  7 entries, memory: 492 bytes
+
+    (1,2)   1
+    (1,4)   2
+    (2,6)   5
+    (3,6)   8
+    (4,3)   10
+    (4,4)   11
+    (4,5)   12
+
+julia> A[1:2:7, :]
+4x7 GraphBLAS int64_t matrix, bitmap by row
+  7 entries, memory: 492 bytes
+
+    (1,2)   1
+    (1,4)   2
+    (2,6)   5
+    (3,6)   8
+    (4,3)   10
+    (4,4)   11
+    (4,5)   12
+
+julia> A[:,:]
+7x7 GraphBLAS int64_t matrix, bitmap by row
+  12 entries, memory: 681 bytes
+
+    (1,2)   1
+    (1,4)   2
+    (2,5)   3
+    (2,7)   4
+    (3,6)   5
+    (4,1)   6
+    (4,3)   7
+    (5,6)   8
+    (6,3)   9
+    (7,3)   10
+    (7,4)   11
+    (7,5)   12
+
+julia> A[:, 5]
+7x1 GraphBLAS int64_t matrix, bitmap by col
+  2 entries, memory: 304 bytes
+
+    (2,1)   3
+    (7,1)   12
 ```
 
 The functionality illustrated above extends to `GBVector` as well.

docs/src/binaryops.md

@@ -1,35 +1,94 @@
 # Binary Operators
 
+```@meta
+DocTestSetup = :(using SuiteSparseGraphBLAS)
+DocTestFilters = [r"memory: \d+ bytes", r"Ptr{.*}\(0x[0-9a-f]+\)"]
+```
+
 Binary operators are defined on three domains $D_1 \times D_2 \rightarrow D_3$.
 However, the vast majority of binary operators are defined on a single domain.
 
 `BinaryOp`s are in almost every GraphBLAS operation. They are the primary `op` argument for [`emul`](@ref), [`eadd`](@ref), and [`apply`](@ref). `BinaryOp`s which are also monoids may be used in [`reduce`](@ref). And every GraphBLAS operation which takes an `accum` keyword argument accepts a `BinaryOp`.
 
 In almost all cases you should pass Julia functions, which will be mapped to built-in operators, or used to create a new user-defined operator.
 
-```@repl
-using SuiteSparseGraphBLAS
+```jldoctest
+julia> x = GBMatrix([[1,2] [3,4]])
+2x2 GraphBLAS int64_t matrix, full by col
+  4 entries, memory: 272 bytes
+
+    (1,1)   1
+    (2,1)   2
+    (1,2)   3
+    (2,2)   4
+
+julia> x .+ x
+2x2 GraphBLAS int64_t matrix, full by row
+  4 entries, memory: 272 bytes
+
+    (1,1)   2
+    (1,2)   6
+    (2,1)   4
+    (2,2)   8
+
+julia> eadd(x, x, +)
+2x2 GraphBLAS int64_t matrix, full by row
+  4 entries, memory: 272 bytes
+
+    (1,1)   2
+    (1,2)   6
+    (2,1)   4
+    (2,2)   8
+
+julia> x .^ x
+2x2 GraphBLAS int64_t matrix, full by row
+  4 entries, memory: 272 bytes
+
+    (1,1)   1
+    (1,2)   27
+    (2,1)   4
+    (2,2)   256
+
+julia> emul(x, x, ^)
+2x2 GraphBLAS int64_t matrix, full by row
+  4 entries, memory: 272 bytes
+
+    (1,1)   1
+    (1,2)   27
+    (2,1)   4
+    (2,2)   256
 
-x = GBMatrix([[1,2] [3,4]])
+julia> x2 = Float64.(x)
+2x2 GraphBLAS double matrix, full by col
+  4 entries, memory: 272 bytes
 
-x .+ x
-eadd(x, x, +)
+    (1,1)    1
+    (2,1)    2
+    (1,2)    3
+    (2,2)    4
 
-x .^ x
-emul(x, x, ^)
+julia> eadd!(x2, x, x, +; accum=/)
+2x2 GraphBLAS double matrix, full by col
+  4 entries, memory: 272 bytes
 
-x2 = Float64.(x)
-eadd!(x2, x, x, +; accum=/)
+    (1,1)    0.5
+    (2,1)    0.5
+    (1,2)    0.5
+    (2,2)    0.5
 ```
 
 Internally functions are lowered like this:
 
-```@repl
-using SuiteSparseGraphBLAS
+```jldoctest
+julia> typedop = binaryop(+, Int64, Int64)
+SuiteSparseGraphBLAS.TypedBinaryOperator{typeof(+), Int64, Int64, Int64}(true, true, "GrB_PLUS_INT64", Ptr{SuiteSparseGraphBLAS.LibGraphBLAS.GB_BinaryOp_opaque}(0x0000736051461e20), +, nothing)
 
-typedop = binaryop(+, Int64, Int64)
+julia> eadd(GBVector([1,2]), GBVector([3,4]), typedop)
+2x1 GraphBLAS int64_t matrix, full by col
+  2 entries, memory: 256 bytes
 
-eadd(GBVector([1,2]), GBVector([3,4]), typedop)
+    (1,1)   4
+    (2,1)   6
 ```
 
 ## Built-Ins

docs/src/examples.md

@@ -0,0 +1,71 @@
+# Examples
+
+```@meta
+DocTestSetup = quote
+    using SuiteSparseGraphBLAS
+    for f in ("Cohen", "Sandia", "BFSParents", "BellmanFord")
+        include(joinpath(pkgdir(SuiteSparseGraphBLAS), "examples", "$f.jl"))
+    end
+end
+DocTestFilters = [r"memory: \d+ bytes"]
+```
+
+The [`examples`](https://github.com/JuliaSparse/SuiteSparseGraphBLAS.jl/tree/v11/examples) directory of the repository contains graph algorithms written with SuiteSparseGraphBLAS.jl.
+They are not part of the package API: `include` a file to use the functions it defines.
+Each file links to a paper or reference describing the algorithm, and all of them are tested in `test/examples.jl`.
+
+Unless noted otherwise `A` is the adjacency matrix of an undirected graph with `n` vertices.
+
+| Algorithm | File | Function | Notes |
+|:----------|:-----|:---------|:------|
+| Triangle counting (Cohen) | `Cohen.jl` | `cohen(A)` | |
+| Triangle counting (Sandia) | `Sandia.jl` | `sandia(A)` | |
+| Triangle counting (CMU) | `CMU.jl` | `cmu(A, n)` | |
+| Triangles per vertex | `NodeWiseTriangleCount.jl` | `nodewise_tc(A)` | |
+| k-truss | `KTruss.jl` | `ktruss(A, k)` | Returns the truss with edge supports as values. |
+| BFS parents | `BFSParents.jl` | `bfs_parents(A, s, n)` | The parent of the source is `0`. |
+| Multi-source BFS parents | `BFSParentsMultiSource.jl` | `ms_bfsp(A, S, n, s)` | Row `i` of the `s × n` matrix `S` marks source `i`. |
+| Multi-source BFS levels | `BFSLevelsMultiSource.jl` | `ms_bfsl(A, S, n, s)` | `A` and `S` are `Bool`. Sources are level `1`, unreachable vertices `0`. |
+| Bellman-Ford | `BellmanFord.jl` | `bellmanford(A, s, n)` | `A[i,j]` is the weight of edge `i → j`, with explicit zeros on the diagonal. |
+| Floyd-Warshall | `FloydWarshall.jl` | `floydwarshall(A, n)` | Same input as Bellman-Ford. |
+| Prim's minimum spanning tree | `BasicPrim.jl`, `AdvancedPrim.jl` | `b_prim(A, n, zeros(n))`, `a_prim(A, n, zeros(n))` | `A` is dense, with `Inf` where there is no edge and zeros on the diagonal. |
+| Community detection by label propagation | `CDLP.jl` | `cdlp(A, n, t)` | Runs `t` iterations. Every vertex must have a neighbour. |
+
+The graph below has edges `1-2`, `1-3`, `2-3`, `2-4`, `3-4` and `4-5`, and two triangles, `{1,2,3}` and `{2,3,4}`.
+
+```jldoctest examples
+julia> src = [1, 1, 2, 2, 3, 4]; dst = [2, 3, 3, 4, 4, 5];
+
+julia> A = GBMatrix([src; dst], [dst; src], 1, 5, 5);
+
+julia> cohen(A), sandia(A)
+(2, 2)
+
+julia> bfs_parents(A, 1, 5)
+5x1 GraphBLAS int64_t matrix, bitmap by col
+  5 entries, memory: 288 bytes
+
+    (1,1)   0
+    (2,1)   1
+    (3,1)   1
+    (4,1)   2
+    (5,1)   4
+```
+
+With edge weights, and the explicit zero diagonal that Bellman-Ford expects:
+
+```jldoctest examples
+julia> w = [1.0, 4.0, 2.0, 7.0, 3.0, 1.0];
+
+julia> W = GBMatrix([src; dst; 1:5], [dst; src; 1:5], [w; w; zeros(5)]);
+
+julia> bellmanford(W, 1, 5)
+5x1 GraphBLAS double matrix, full by col
+  5 entries, memory: 280 bytes
+
+    (1,1)    0
+    (2,1)    1
+    (3,1)    3
+    (4,1)    6
+    (5,1)    7
+```