Interface as simple as possible

Project.toml

@@ -3,7 +3,14 @@ uuid = "ad2ac648-372e-45be-9d57-a550431b71c3"
 authors = ["JuliaGraphs contributors"]
 version = "0.1.0-DEV"
 
+[deps]
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+SimpleTraits = "699a6c99-e7fa-54fc-8d76-47d257e15c1d"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+
 [compat]
+DocStringExtensions = "0.9"
+SimpleTraits = "0.9"
 julia = "1.6"
 
 [extras]

docs/make.jl

@@ -12,7 +12,11 @@ makedocs(;
         canonical="https://juliagraphs.org/GraphsBase.jl",
         assets=String[],
     ),
-    pages=["Home" => "index.md"],
+    pages=[
+        "Home" => "index.md",
+        "Interface" => "interface.md",
+        "Implementations" => "implementations.md",
+    ],
 )
 
 deploydocs(;

docs/src/implementations.md

@@ -0,0 +1,13 @@
+# Concrete implementations
+
+## `SimpleGraphs`
+
+```@autodocs
+Modules = [GraphsBase.SimpleGraphs]
+```
+
+## `SimpleWeightedGraphs`
+
+```@autodocs
+Modules = [GraphsBase.SimpleWeightedGraphs]
+```

docs/src/index.md

@@ -6,10 +6,8 @@ CurrentModule = GraphsBase
 
 Documentation for [GraphsBase](https://github.com/JuliaGraphs/GraphsBase.jl).
 
-## API reference
-
-```@autodocs
-Modules = [GraphsBase]
+```@docs
+GraphsBase
 ```
 
 ## Index

docs/src/interface.md

@@ -0,0 +1,61 @@
+# Interface
+
+## Edge
+
+```@docs
+AbstractEdge
+src
+dst
+weight
+Base.reverse
+```
+
+## Graph (required)
+
+```@docs
+AbstractGraph
+is_directed
+vertices
+out_edges
+in_edges
+```
+
+## Graph (optional)
+
+```@docs
+nv
+ne
+has_vertex
+has_edge
+has_self_loops
+edges
+out_neighbors
+in_neighbors
+create_vertex_container
+create_edge_container
+```
+
+## Graph (modification)
+
+```@docs
+add_vertex!
+rm_vertex!
+add_edge!
+rm_edge!
+```
+
+## Element types
+
+```@docs
+Base.eltype
+edgetype
+weighttype
+```
+
+## Checks
+
+```@docs
+GraphsBase.check_comparable_interface
+GraphsBase.check_edge_interface
+GraphsBase.check_graph_interface
+```

src/GraphsBase.jl

@@ -5,4 +5,33 @@ The basic interface and graph types for the JuliaGraphs ecosystem.
 """
 module GraphsBase
 
+using DocStringExtensions
+using SimpleTraits
+using SparseArrays
+
+export AbstractEdge, check_edge_interface
+export eltype, weighttype
+export src, dst, weight
+
+export AbstractGraph, check_graph_interface
+export edgetype
+export is_directed
+export vertices
+export edges, out_edges, in_edges
+export nv, ne
+export has_vertex, has_edge, has_self_loops
+export out_neighbors, in_neighbors
+export create_vertex_container, create_edge_container
+export add_vertex!, rm_vertex!, add_edge!, rm_edge!
+
+include("interface/utils.jl")
+include("interface/abstractedge.jl")
+include("interface/abstractgraph.jl")
+include("interface/optional.jl")
+include("interface/modification.jl")
+
+include("SimpleGraphs/SimpleGraphs.jl")
+
+include("SimpleWeightedGraphs/SimpleWeightedGraphs.jl")
+
 end

src/SimpleGraphs/SimpleGraphs.jl

@@ -0,0 +1,14 @@
+module SimpleGraphs
+
+using DocStringExtensions
+using GraphsBase
+
+export SimpleEdge
+export SimpleGraph
+export SimpleDiGraph
+
+include("simpleedge.jl")
+include("simplegraph.jl")
+include("simpledigraph.jl")
+
+end

src/SimpleGraphs/simpledigraph.jl

@@ -0,0 +1,29 @@
+"""
+$(TYPEDEF)
+
+A type representing a directed graph with unweighted, non-multiple edges.
+
+# Fields
+
+$(TYPEDFIELDS)
+"""
+mutable struct SimpleDiGraph{T<:Integer} <: AbstractGraph{T,SimpleEdge{T}}
+    "Number of edges"
+    ne::Int
+    "Forward adjacency list such that `F[v]` contains the out-neighbors of vertex `v`"
+    fadjlist::Vector{Vector{T}}
+    "Backward adjacency list such that `B[u]` contains the in-neighbors of vertex `v`"
+    badjlist::Vector{Vector{T}}
+end
+
+GraphsBase.is_directed(::Type{<:SimpleDiGraph}) = true
+
+GraphsBase.vertices(g::SimpleDiGraph{T}) where {T} = one(T):T(length(g.fadjlist))
+
+function GraphsBase.out_edges(g::SimpleDiGraph{T}, u) where {T}
+    return (SimpleEdge{T}(u, v) for v in g.fadjlist[u])
+end
+
+function GraphsBase.in_edges(g::SimpleDiGraph{T}, v) where {T}
+    return (SimpleEdge{T}(u, v) for u in g.badjlist[v])
+end

src/SimpleGraphs/simpleedge.jl

@@ -0,0 +1,24 @@
+"""
+$(TYPEDEF)
+
+A type representing an unweighted directed edge.
+
+# Fields
+
+$(TYPEDFIELDS)
+"""
+struct SimpleEdge{T<:Integer} <: AbstractEdge{T,Int}
+    "Source of the edge"
+    src::T
+    "Destination of the edge"
+    dst::T
+end
+
+Base.Tuple(e::SimpleEdge) = (e.src, e.dst)
+Base.isless(e1::SimpleEdge, e2::SimpleEdge) = isless(Tuple(e1), Tuple(e2))
+Base.:(==)(e1::SimpleEdge, e2::SimpleEdge) = Tuple(e1) == Tuple(e2)
+
+GraphsBase.src(e::SimpleEdge) = e.src
+GraphsBase.dst(e::SimpleEdge) = e.dst
+GraphsBase.weight(e::SimpleEdge) = 1
+Base.reverse(e::SimpleEdge) = SimpleEdge(e.dst, e.src)

src/SimpleGraphs/simplegraph.jl

@@ -0,0 +1,25 @@
+"""
+$(TYPEDEF)
+
+A type representing an undirected graph with unweighted, non-multiple edges.
+
+# Fields
+
+$(TYPEDFIELDS)
+"""
+mutable struct SimpleGraph{T<:Integer} <: AbstractGraph{T,SimpleEdge{T}}
+    """Number of edges"""
+    ne::Int
+    "Adjacency list such that `L[v]` contains the neighbors of vertex `v`"
+    adjlist::Vector{Vector{T}}
+end
+
+GraphsBase.is_directed(::Type{<:SimpleGraph}) = false
+
+GraphsBase.vertices(g::SimpleGraph{T}) where {T} = one(T):T(length(g.adjlist))
+
+function GraphsBase.out_edges(g::SimpleGraph{T}, u) where {T}
+    return (SimpleEdge{T}(u, v) for v in g.adjlist[u])
+end
+
+GraphsBase.in_edges(g::SimpleGraph, v) = out_edges(g, v)

src/SimpleWeightedGraphs/SimpleWeightedGraphs.jl

@@ -0,0 +1,15 @@
+module SimpleWeightedGraphs
+
+using DocStringExtensions
+using SparseArrays
+using GraphsBase
+
+export SimpleWeightedEdge
+export SimpleWeightedGraph
+export SimpleWeightedDiGraph
+
+include("simpleweightededge.jl")
+include("simpleweightedgraph.jl")
+include("simpleweighteddigraph.jl")
+
+end

src/SimpleWeightedGraphs/simpleweighteddigraph.jl

@@ -0,0 +1,27 @@
+"""
+$(TYPEDEF)
+
+A type representing a directed graph with weighted, non-multiple edges.
+
+# Fields
+
+$(TYPEDFIELDS)
+"""
+struct SimpleWeightedDiGraph{T<:Integer,W} <: AbstractGraph{T,SimpleWeightedEdge{T,W}}
+    "Transposed weighted adjacency matrix: `weights[v, u]` contains the weight of edge `(u, v)`"
+    weights::SparseMatrixCSC{W,T}
+end
+
+GraphsBase.is_directed(::Type{<:SimpleWeightedDiGraph}) = true
+GraphsBase.vertices(g::SimpleWeightedDiGraph{T}) where {T} = one(T):T(size(g.weights, 1))
+
+function GraphsBase.out_edges(g::SimpleWeightedDiGraph{T}, u) where {T}
+    A = g.weights
+    return (SimpleWeightedEdge{T}(u, A.rowval[i], A.nzval[i]) for i in nzrange(A, u))
+end
+
+function GraphsBase.in_edges(g::SimpleWeightedDiGraph, v)
+    A = g.weights
+    a = A[v, :]
+    return (SimpleWeightedEdge{T}(u, v, a[u]) for u in a.nzind)
+end

src/SimpleWeightedGraphs/simpleweightededge.jl

@@ -0,0 +1,26 @@
+"""
+$(TYPEDEF)
+
+A type representing a weighted directed edge.
+
+# Fields
+
+$(TYPEDFIELDS)
+"""
+struct SimpleWeightedEdge{T<:Integer,W} <: AbstractEdge{T,W}
+    "Source of the edge"
+    src::T
+    "Destination of the edge"
+    dst::T
+    "Weight of the edge"
+    weight::W
+end
+
+Base.Tuple(e::SimpleWeightedEdge) = (e.src, e.dst, e.weight)
+Base.isless(e1::SimpleWeightedEdge, e2::SimpleWeightedEdge) = isless(Tuple(e1), Tuple(e2))
+Base.:(==)(e1::SimpleWeightedEdge, e2::SimpleWeightedEdge) = Tuple(e1) == Tuple(e2)
+
+GraphsBase.src(e::SimpleWeightedEdge) = e.src
+GraphsBase.dst(e::SimpleWeightedEdge) = e.dst
+GraphsBase.weight(e::SimpleWeightedEdge) = e.weight
+Base.reverse(e::SimpleWeightedEdge) = SimpleEdge(e.dst, e.src, e.weight)

src/SimpleWeightedGraphs/simpleweightedgraph.jl

@@ -0,0 +1,23 @@
+"""
+$(TYPEDEF)
+
+A type representing an undirected graph with weighted, non-multiple edges.
+
+# Fields
+
+$(TYPEDFIELDS)
+"""
+struct SimpleWeightedGraph{T<:Integer,W} <: AbstractGraph{T,SimpleWeightedEdge{T,W}}
+    "Symmetric weighted adjacency matrix: `weights[u, v]` and `weights[v, u]` both contain the weight of edge `{u, v}`"
+    weights::SparseMatrixCSC{W,T}
+end
+
+GraphsBase.is_directed(::Type{<:SimpleWeightedGraph}) = false
+GraphsBase.vertices(g::SimpleWeightedGraph{T}) where {T} = one(T):T(size(g.weights, 1))
+
+function GraphsBase.out_edges(g::SimpleWeightedGraph{T}, u) where {T}
+    A = g.weights
+    return (SimpleWeightedEdge{T}(u, A.rowval[i], A.nzval[i]) for i in nzrange(A, u))
+end
+
+GraphsBase.in_edges(g::SimpleWeightedGraph, v) = out_edges(g, v)