From 318d8baaa696d0965de4420dbd864ac8188fdbb4 Mon Sep 17 00:00:00 2001 From: CarloLucibello Date: Sat, 30 Nov 2024 20:04:20 +0100 Subject: [PATCH] simplify documentation --- GraphNeuralNetworks/docs/make.jl | 16 ++-- GraphNeuralNetworks/docs/src/gsoc.md | 3 - GraphNeuralNetworks/docs/src/home.md | 87 --------------------- GraphNeuralNetworks/docs/src/index.md | 108 ++++++++++++++++++++------ docs/make-multi.jl | 6 +- 5 files changed, 92 insertions(+), 128 deletions(-) delete mode 100644 GraphNeuralNetworks/docs/src/gsoc.md delete mode 100644 GraphNeuralNetworks/docs/src/home.md diff --git a/GraphNeuralNetworks/docs/make.jl b/GraphNeuralNetworks/docs/make.jl index 7698a3abe..a9f9e1313 100644 --- a/GraphNeuralNetworks/docs/make.jl +++ b/GraphNeuralNetworks/docs/make.jl @@ -21,25 +21,19 @@ makedocs(; plugins = [interlinks], format = Documenter.HTML(; mathengine, prettyurls, assets = assets, size_threshold=nothing), sitename = "GraphNeuralNetworks.jl", - pages = ["Monorepo" => [ - "Home" => "index.md", - "Developer guide" => "dev.md", - "Google Summer of Code" => "gsoc.md", + pages = [ + "Home" => "index.md", + "Guides" => [ + "Models" => "models.md", ], - "GraphNeuralNetworks.jl" =>[ - "Home" => "home.md", - "Models" => "models.md",], - "API Reference" => [ - "Basic" => "api/basic.md", "Convolutional layers" => "api/conv.md", "Pooling layers" => "api/pool.md", "Temporal Convolutional layers" => "api/temporalconv.md", "Hetero Convolutional layers" => "api/heteroconv.md", - - ], + "Developer guide" => "dev.md", ], ) diff --git a/GraphNeuralNetworks/docs/src/gsoc.md b/GraphNeuralNetworks/docs/src/gsoc.md deleted file mode 100644 index a764f4dd7..000000000 --- a/GraphNeuralNetworks/docs/src/gsoc.md +++ /dev/null @@ -1,3 +0,0 @@ -# Graph Neural Networks - Summer of Code - -Potential candidates to Google Summer of Code's scholarships can find out about the available projects involving GraphNeuralNetworks.jl on the [dedicated page](https://julialang.org/jsoc/gsoc/gnn/) in the Julia Language website. diff --git a/GraphNeuralNetworks/docs/src/home.md b/GraphNeuralNetworks/docs/src/home.md deleted file mode 100644 index fa28621a7..000000000 --- a/GraphNeuralNetworks/docs/src/home.md +++ /dev/null @@ -1,87 +0,0 @@ -# GraphNeuralNetworks - -GraphNeuralNetworks.jl is a graph neural network package based on the deep learning framework [Flux.jl](https://github.com/FluxML/Flux.jl). - -It provides a set of stateful graph convolutional layers and utilities to build graph neural networks. - -Among its features: - -* Implements common graph convolutional layers. -* Supports computations on batched graphs. -* Easy to define custom layers. -* CUDA support. -* Integration with [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl). -* [Examples](https://github.com/JuliaGraphs/GraphNeuralNetworks.jl/tree/master/GraphNeuralNetworks/examples) of node, edge, and graph level machine learning tasks. -* Heterogeneous and temporal graphs. - - -## Package overview - -Let's give a brief overview of the package by solving a graph regression problem with synthetic data. - -Usage examples on real datasets can be found in the [examples](https://github.com/JuliaGraphs/GraphNeuralNetworks.jl/tree/master/GraphNeuralNetworks/examples) folder. - -### Data preparation - -We create a dataset consisting in multiple random graphs and associated data features. - -```julia -using GraphNeuralNetworks, Flux, CUDA, Statistics, MLUtils -using Flux: DataLoader - -all_graphs = GNNGraph[] - -for _ in 1:1000 - g = rand_graph(10, 40, - ndata=(; x = randn(Float32, 16,10)), # Input node features - gdata=(; y = randn(Float32))) # Regression target - push!(all_graphs, g) -end -``` - -### Model building - -We concisely define our model as a [`GraphNeuralNetworks.GNNChain`](@ref) containing two graph convolutional layers. If CUDA is available, our model will live on the gpu. - -```julia -device = CUDA.functional() ? Flux.gpu : Flux.cpu; - -model = GNNChain(GCNConv(16 => 64), - BatchNorm(64), # Apply batch normalization on node features (nodes dimension is batch dimension) - x -> relu.(x), - GCNConv(64 => 64, relu), - GlobalPool(mean), # Aggregate node-wise features into graph-wise features - Dense(64, 1)) |> device - -opt = Flux.setup(Adam(1f-4), model) -``` - -### Training - -Finally, we use a standard Flux training pipeline to fit our dataset. -We use Flux's `DataLoader` to iterate over mini-batches of graphs -that are glued together into a single `GNNGraph` using the `MLUtils.batch` method. This is what happens under the hood when creating a `DataLoader` with the -`collate=true` option. - -```julia -train_graphs, test_graphs = MLUtils.splitobs(all_graphs, at=0.8) - -train_loader = DataLoader(train_graphs, - batchsize=32, shuffle=true, collate=true) -test_loader = DataLoader(test_graphs, - batchsize=32, shuffle=false, collate=true) - -loss(model, g::GNNGraph) = mean((vec(model(g, g.x)) - g.y).^2) - -loss(model, loader) = mean(loss(model, g |> device) for g in loader) - -for epoch in 1:100 - for g in train_loader - g = g |> device - grad = gradient(model -> loss(model, g), model) - Flux.update!(opt, model, grad[1]) - end - - @info (; epoch, train_loss=loss(model, train_loader), test_loss=loss(model, test_loader)) -end -``` diff --git a/GraphNeuralNetworks/docs/src/index.md b/GraphNeuralNetworks/docs/src/index.md index 692347aea..d0500d3e1 100644 --- a/GraphNeuralNetworks/docs/src/index.md +++ b/GraphNeuralNetworks/docs/src/index.md @@ -1,43 +1,107 @@ -# GraphNeuralNetworks Monorepo +# GraphNeuralNetworks -This is the monorepository for the GraphNeuralNetworks project, bringing together all code into a unified structure to facilitate code sharing and reusability across different project components. It contains the following packages: +GraphNeuralNetworks.jl is a graph neural network package based on the deep learning framework [Flux.jl](https://github.com/FluxML/Flux.jl). -- `GraphNeuralNetwork.jl`: Package that contains stateful graph convolutional layers based on the machine learning framework [Flux.jl](https://fluxml.ai/Flux.jl/stable/). This is fronted package for Flux users. It depends on GNNlib.jl, GNNGraphs.jl, and Flux.jl packages. +It provides a set of stateful graph convolutional layers and utilities to build graph neural networks. -- `GNNLux.jl`: Package that contains stateless graph convolutional layers based on the machine learning framework [Lux.jl](https://lux.csail.mit.edu/stable/). This is fronted package for Lux users. It depends on GNNlib.jl, GNNGraphs.jl, and Lux.jl packages. +Among its features: -- `GNNlib.jl`: Package that contains the core graph neural network layers and utilities. It depends on GNNGraphs.jl and GNNlib.jl packages and serves for code base for GraphNeuralNetwork.jl and GNNLux.jl packages. - -- `GNNGraphs.jl`: Package that contains the graph data structures and helper functions for working with graph data. It depends on Graphs.jl package. - -Here is a schema of the dependencies between the packages: - -![Monorepo schema](assets/schema.png) - - -Among its general features: - -* Implements common graph convolutional layers both in stateful and stateless form. +* Implements common graph convolutional layers. * Supports computations on batched graphs. * Easy to define custom layers. * CUDA support. * Integration with [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl). * [Examples](https://github.com/JuliaGraphs/GraphNeuralNetworks.jl/tree/master/GraphNeuralNetworks/examples) of node, edge, and graph level machine learning tasks. -* Heterogeneous and temporal graphs. +* Heterogeneous and temporal graphs. + +The package is part of a larger ecosystem of packages that includes [GNNlib.jl](https://juliagraphs.org/GraphNeuralNetworks.jl/gnnlib), [GNNGraphs.jl](https://juliagraphs.org/GraphNeuralNetworks.jl/gnngraphs), and [GNNLux.jl](https://juliagraphs.org/GraphNeuralNetworks.jl/gnnlux). + +GraphNeuralNetworks.jl is the fronted package for Flux.jl users. [Lux.jl](https://lux.csail.mit.edu/stable/) users instead, can relyi on GNNLux.jl (still in development). ## Installation -GraphNeuralNetworks.jl, GNNlib.jl and GNNGraphs.jl are a registered Julia packages. You can easily install a package, for example GraphNeuralNetworks.jl, through the package manager : +GraphNeuralNetworks.jl is a registered Julia package. You can easily install it through the package manager : ```julia pkg> add GraphNeuralNetworks ``` -## Usage +## Package overview + +Let's give a brief overview of the package by solving a graph regression problem with synthetic data. + +Other usage examples can be found in the [examples](https://github.com/JuliaGraphs/GraphNeuralNetworks.jl/tree/master/GraphNeuralNetworks/examples) folder, in the [notebooks](https://github.com/JuliaGraphs/GraphNeuralNetworks.jl/tree/master/GraphNeuralNetworks/notebooks) folder, and in the [tutorials](https://juliagraphs.org/GraphNeuralNetworks.jl/tutorials/) section of the documentation. + +### Data preparation + +We create a dataset consisting in multiple random graphs and associated data features. + +```julia +using GraphNeuralNetworks, Flux, CUDA, Statistics, MLUtils +using Flux: DataLoader + +all_graphs = GNNGraph[] + +for _ in 1:1000 + g = rand_graph(10, 40, + ndata=(; x = randn(Float32, 16,10)), # Input node features + gdata=(; y = randn(Float32))) # Regression target + push!(all_graphs, g) +end +``` + +### Model building -Usage examples can be found in the [examples](https://github.com/JuliaGraphs/GraphNeuralNetworks.jl/tree/master/GraphNeuralNetworks/examples) and in the [notebooks](https://github.com/JuliaGraphs/GraphNeuralNetworks.jl/tree/master/GraphNeuralNetworks/notebooks) folder. Also, make sure to read the [documentation](https://juliagraphs.org/GraphNeuralNetworks.jl/graphneuralnetworks/) for a comprehensive introduction to the library and the [tutorials](https://juliagraphs.org/GraphNeuralNetworks.jl/tutorials/). +We concisely define our model as a [`GraphNeuralNetworks.GNNChain`](@ref) containing two graph convolutional layers. If CUDA is available, our model will live on the gpu. +```julia +device = CUDA.functional() ? Flux.gpu : Flux.cpu; + +model = GNNChain(GCNConv(16 => 64), + BatchNorm(64), # Apply batch normalization on node features (nodes dimension is batch dimension) + x -> relu.(x), + GCNConv(64 => 64, relu), + GlobalPool(mean), # Aggregate node-wise features into graph-wise features + Dense(64, 1)) |> device + +opt = Flux.setup(Adam(1f-4), model) +``` + +### Training + +Finally, we use a standard Flux training pipeline to fit our dataset. +We use Flux's `DataLoader` to iterate over mini-batches of graphs +that are glued together into a single `GNNGraph` using the `MLUtils.batch` method. This is what happens under the hood when creating a `DataLoader` with the +`collate=true` option. + +```julia +train_graphs, test_graphs = MLUtils.splitobs(all_graphs, at=0.8) + +train_loader = DataLoader(train_graphs, + batchsize=32, shuffle=true, collate=true) +test_loader = DataLoader(test_graphs, + batchsize=32, shuffle=false, collate=true) + +loss(model, g::GNNGraph) = mean((vec(model(g, g.x)) - g.y).^2) + +loss(model, loader) = mean(loss(model, g |> device) for g in loader) + +for epoch in 1:100 + for g in train_loader + g = g |> device + grad = gradient(model -> loss(model, g), model) + Flux.update!(opt, model, grad[1]) + end + + @info (; epoch, train_loss=loss(model, train_loader), test_loss=loss(model, test_loader)) +end +``` + +# Google Summer of Code + +Potential candidates to Google Summer of Code's scholarships can find out about the available projects involving GraphNeuralNetworks.jl on the [dedicated page](https://julialang.org/jsoc/gsoc/gnn/) in the Julia Language website. + ## Citing If you use GraphNeuralNetworks.jl in a scientific publication, we would appreciate the following reference: @@ -57,7 +121,3 @@ GraphNeuralNetworks.jl is largely inspired by [PyTorch Geometric](https://pytorc and [GeometricFlux.jl](https://fluxml.ai/GeometricFlux.jl/stable/). - - - - diff --git a/docs/make-multi.jl b/docs/make-multi.jl index 268a508d8..43a9ff626 100644 --- a/docs/make-multi.jl +++ b/docs/make-multi.jl @@ -15,17 +15,17 @@ docs = [ MultiDocumenter.MultiDocRef( upstream = joinpath(dirname(@__DIR__),"GraphNeuralNetworks", "docs", "build"), path = "graphneuralnetworks", - name = "GraphNeuralNetworks", + name = "GraphNeuralNetworks.jl", fix_canonical_url = false), MultiDocumenter.MultiDocRef( upstream = joinpath(dirname(@__DIR__), "GNNGraphs", "docs", "build"), path = "gnngraphs", - name = "GNNGraphs", + name = "GNNGraphs.jl", fix_canonical_url = false), MultiDocumenter.MultiDocRef( upstream = joinpath(dirname(@__DIR__), "GNNlib", "docs", "build"), path = "gnnlib", - name = "GNNlib", + name = "GNNlib.jl", fix_canonical_url = false), MultiDocumenter.MultiDocRef( upstream = joinpath(dirname(@__DIR__), "GNNLux", "docs", "build"),