Merge branch 'master' into new_features

Author: yuehhua

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.13.4]
+
+- support GraphSignals to 0.7
+
+## [0.13.3]
+
+- update doc for `FeaturedGraph`
+
+## [0.13.2]
+
+- fix doc
+
 ## [0.13.1]
 
 - `GraphParallel` support `positional_layer`

Project.toml

@@ -1,7 +1,7 @@
 name = "GeometricFlux"
 uuid = "7e08b658-56d3-11e9-2997-919d5b31e4ea"
 authors = ["Yueh-Hua Tu <[email protected]>"]
-version = "0.13.1"
+version = "0.13.4"
 
 [deps]
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
@@ -30,7 +30,7 @@ ChainRulesCore = "1"
 DataStructures = "0.18"
 FillArrays = "0.13"
 Flux = "0.12 - 0.13"
-GraphSignals = "0.6"
+GraphSignals = "0.7"
 Graphs = "1"
 MLDatasets = "0.7"
 NNlib = "0.8"

docs/src/assets/FeaturedGraph-support-DataLoader.svg

@@ -1,23 +1,37 @@
 # Batch Learning
 
-## Batch Learning for Variable Graph Strategy
+## Mini-batch Learning for [`FeaturedGraph`](@ref)
 
-Batch learning for variable graph strategy can be prepared as follows:
+```@raw html
+<figure>
+    <img src="../../assets/FeaturedGraph-support-DataLoader.svg" width="100%" alt="FeaturedGraph-support-DataLoader.svg" /><br>
+    <figcaption><em>FeaturedGraph supports DataLoader.</em></figcaption>
+</figure>
+```
+
+Batch learning for [`FeaturedGraph`](@ref) can be prepared as follows:
 
 ```julia
-train_data = [(FeaturedGraph(g, nf=train_X), train_y) for _ in 1:N]
-train_batch = Flux.batch(train_data)
+train_data = (FeaturedGraph(g, nf=train_X), train_y)
+train_batch = DataLoader(train_data, batchsize=batch_size, shuffle=true)
 ```
 
-It batches up [`FeaturedGraph`](@ref) objects into specified mini-batch. A batch is passed to a GNN model and trained/inferred one by one. It is hard for [`FeaturedGraph`](@ref) objects to train or infer in real batch for GPU.
+[`FeaturedGraph`](@ref) now supports `DataLoader` and one can specify mini-batch to it.
+A mini-batch is passed to a GNN model and trained/inferred in one [`FeaturedGraph`](@ref).
 
-## Batch Learning for Static Graph Strategy
+## Mini-batch Learning for array
+
+```@raw html
+<figure>
+    <img src="../../assets/cuda-minibatch.svg" width="100%" alt="cuda-minibatch.svg" /><br>
+    <figcaption><em>Mini-batch learning on CUDA.</em></figcaption>
+</figure>
+```
 
-A efficient batch learning should use static graph strategy. Batch learning for static graph strategy can be prepared as follows:
+Mini-batch learning for array can be prepared as follows:
 
 ```julia
-train_data = (repeat(train_X, outer=(1,1,N)), repeat(train_y, outer=(1,1,N)))
-train_loader = DataLoader(train_data, batchsize=batch_size, shuffle=true)
+train_loader = DataLoader((train_X, train_y), batchsize=batch_size, shuffle=true)
 ```
 
-An efficient batch learning should feed array to a GNN model. In the example, the mini-batch dimension is the third dimension for `train_X` array. The `train_X` array is split by `DataLoader` into mini-batches and feed a mini-batch to GNN model at a time. This strategy leverages the advantage of GPU training by accelerating training GNN model in a real batch learning.
+An array could be fed to a GNN model. In the example, the mini-batch dimension is the last dimension for `train_X` array. The `train_X` array is split by `DataLoader` into mini-batches and feed a mini-batch to GNN model at a time. This strategy leverages the advantage of GPU training by accelerating training GNN model in a real batch learning.

docs/src/assets/cuda-minibatch.svg

@@ -26,6 +26,13 @@ model = Chain(
 
 ## Branching Different Features Through Different Layers
 
+```@raw html
+<figure>
+    <img src="../assets/graphparallel.svg" width="70%" alt="graphparallel.svg" /><br>
+    <figcaption><em>GraphParallel wraps regular Flux layers for different kinds of features for integration to GNN layers.</em></figcaption>
+</figure>
+```
+
 A [`GraphParallel`](@ref) construct is designed for passing each feature through different layers from a [`FeaturedGraph`](@ref). An example is given as follow:
 
 ```julia

docs/src/assets/graphparallel.svg

@@ -55,6 +55,26 @@ Reference: [Morris2019](@cite)
 
 ---
 
+## SAmple and aggreGatE (GraphSAGE) Network
+
+```math
+\hat{\textbf{x}}_j = sample(\textbf{x}_j), \forall j \in \mathcal{N}(i) \\
+\textbf{m}_i = aggregate(\hat{\textbf{x}}_j) \\
+\textbf{x}_i' = \sigma (\Theta_1 \textbf{x}_i + \Theta_2 \textbf{m}_i)
+```
+
+```@docs
+SAGEConv
+MeanAggregator
+MeanPoolAggregator
+MaxPoolAggregator
+LSTMAggregator
+```
+
+Reference: [Hamilton2017](@cite) and [GraphSAGE website](http://snap.stanford.edu/graphsage/)
+
+---
+
 ## Graph Attentional Layer
 
 ```math
@@ -122,7 +142,7 @@ Reference: [Wang2019](@cite)
 ## Graph Isomorphism Network
 
 ```math
-\textbf{x}_i' = f_{\Theta}\left((1 + \varepsilon) \dot \textbf{x}_i + \sum_{j \in \mathcal{N}(i)} \textbf{x}_j \right)
+\textbf{x}_i' = f_{\Theta}\left((1 + \varepsilon) \cdot \textbf{x}_i + \sum_{j \in \mathcal{N}(i)} \textbf{x}_j \right)
 ```
 
 where ``f_{\Theta}`` denotes a neural network parametrized by ``\Theta``, *i.e.*, a MLP.
@@ -148,23 +168,3 @@ CGConv
 ```
 
 Reference: [Xie2018](@cite)
-
----
-
-## SAmple and aggreGatE (GraphSAGE) Network
-
-```math
-\hat{\textbf{x}}_j = sample(\textbf{x}_j), \forall j \in \mathcal{N}(i) \\
-\textbf{m}_i = aggregate(\hat{\textbf{x}}_j) \\
-\textbf{x}_i' = \sigma (\Theta_1 \textbf{x}_i + \Theta_2 \textbf{m}_i)
-```
-
-```@docs
-SAGEConv
-MeanAggregator
-MeanPoolAggregator
-MaxPoolAggregator
-LSTMAggregator
-```
-
-Reference: [Hamilton2017](@cite) and [GraphSAGE website](http://snap.stanford.edu/graphsage/)

docs/src/basics/batch.md

@@ -18,7 +18,7 @@ julia> in_dim, out_dim, pos_dim = 3, 5, 2
 (3, 5, 2)
 
 julia> egnn = EEquivGraphConv(in_dim=>out_dim, pos_dim, in_dim)
-EEquivGraphConv(ϕ_edge=Dense(10 => 5), ϕ_x=Dense(5 => 2), ϕ_h=Dense(8 => 5))
+EEquivGraphConv(ϕ_edge=Chain(Dense(10 => 2), Dense(2 => 2)), ϕ_x=Chain(Dense(2 => 2), Dense(2 => 1; bias=false)), ϕ_h=Chain(Dense(5 => 2), Dense(2 => 5)))
 ```
 
 See also [`WithGraph`](@ref) for training layer with static graph and [`EEquivGraphPE`](@ref) for positional encoding.

docs/src/cooperate.md

@@ -21,19 +21,17 @@
     @testset "without aggregation" begin
         function (l::NewGNLayer)(fg::AbstractFeaturedGraph)
             nf = node_feature(fg)
-            ef = edge_feature(fg)
             GraphSignals.check_num_nodes(fg, nf)
-            GraphSignals.check_num_edges(fg, ef)
-            return GeometricFlux.propagate(l, graph(fg), ef, nf, global_feature(fg), nothing, nothing, nothing)
+            return GeometricFlux.propagate(l, graph(fg), nothing, nf, nothing, nothing, nothing, nothing)
         end
 
         fg = FeaturedGraph(adj, nf=nf)
         l = NewGNLayer()
         ef_, nf_, gf_ = l(fg)
 
         @test nf_ == nf
-        @test size(ef_) == (0, 2E)
-        @test size(gf_) == (0,)
+        @test isnothing(ef_)
+        @test isnothing(gf_)
     end
 
     @testset "with neighbor aggregation" begin
@@ -42,16 +40,16 @@
             ef = edge_feature(fg)
             GraphSignals.check_num_nodes(fg, nf)
             GraphSignals.check_num_edges(fg, ef)
-            return GeometricFlux.propagate(l, graph(fg), ef, nf, global_feature(fg), +, nothing, nothing)
+            return GeometricFlux.propagate(l, graph(fg), ef, nf, nothing, +, nothing, nothing)
         end
 
         fg = FeaturedGraph(adj, nf=nf, ef=ef, gf=zeros(0))
         l = NewGNLayer()
         ef_, nf_, gf_ = l(fg)
 
         @test size(nf_) == (in_channel, V)
-        @test size(ef_) == (0, 2E)
-        @test size(gf_) == (0,)
+        @test size(ef_) == (in_channel, 2E)
+        @test isnothing(gf_)
     end
 
     GeometricFlux.update_edge(l::NewGNLayer, e, vi, vj, u) = similar(e, out_channel, size(e)[2:end]...)
@@ -61,7 +59,7 @@
             ef = edge_feature(fg)
             GraphSignals.check_num_nodes(fg, nf)
             GraphSignals.check_num_edges(fg, ef)
-            return GeometricFlux.propagate(l, graph(fg), ef, nf, global_feature(fg), +, nothing, nothing)
+            return GeometricFlux.propagate(l, graph(fg), ef, nf, nothing, +, nothing, nothing)
         end
 
         fg = FeaturedGraph(adj, nf=nf, ef=ef, gf=zeros(0))
@@ -70,17 +68,18 @@
 
         @test size(nf_) == (in_channel, V)
         @test size(ef_) == (out_channel, 2E)
-        @test size(gf_) == (0,)
+        @test isnothing(gf_)
     end
 
     GeometricFlux.update_vertex(l::NewGNLayer, ē, vi, u) = similar(vi, out_channel, size(vi)[2:end]...)
     @testset "update edge/vertex with all aggregation" begin
         function (l::NewGNLayer)(fg::AbstractFeaturedGraph)
             nf = node_feature(fg)
             ef = edge_feature(fg)
+            gf = global_feature(fg)
             GraphSignals.check_num_nodes(fg, nf)
             GraphSignals.check_num_edges(fg, ef)
-            return GeometricFlux.propagate(l, graph(fg), ef, nf, global_feature(fg), +, +, +)
+            return GeometricFlux.propagate(l, graph(fg), ef, nf, gf, +, +, +)
         end
 
         fg = FeaturedGraph(adj, nf=nf, ef=ef, gf=gf)

docs/src/manual/graph_conv.md

@@ -37,7 +37,7 @@
         @test GraphSignals.adjacency_matrix(fg_) == adj
         @test size(node_feature(fg_)) == (in_channel, num_V)
         @test size(edge_feature(fg_)) == (0, num_E)
-        @test size(global_feature(fg_)) == (0,)
+        @test !has_global_feature(fg_)
     end
 
     GeometricFlux.message(l::NewLayer, x_i, x_j::AbstractMatrix, e_ij) = l.weight * x_j
@@ -47,7 +47,7 @@
         @test GraphSignals.adjacency_matrix(fg_) == adj
         @test size(node_feature(fg_)) == (out_channel, num_V)
         @test size(edge_feature(fg_)) == (0, num_E)
-        @test size(global_feature(fg_)) == (0,)
+        @test !has_global_feature(fg_)
     end
 
     GeometricFlux.update(l::NewLayer, m::AbstractMatrix, x) = l.weight * x + m
@@ -57,6 +57,6 @@
         @test GraphSignals.adjacency_matrix(fg_) == adj
         @test size(node_feature(fg_)) == (out_channel, num_V)
         @test size(edge_feature(fg_)) == (0, num_E)
-        @test size(global_feature(fg_)) == (0,)
+        @test !has_global_feature(fg_)
     end
 end