GP-GNN

Solving graph-defined problems with GNN.

We use Graph Neural Networks to solve problems defined on graph domains (from here, the name GP-GNN: graph problems GNN). In particular, we analyze the resolution of the graph Laplacian system and elliptic PDEs. The code is written in Python, and it's organized in the folder src as follows:

In src/graph there is the code used to random generate a graph given its properties,
In src/pde there is the implementation of Finite Element Method for graph-defined PDEs,
Lastly, in src/gnn there is the implementation of GNN used for our problems of interest.

Instead, in the examples directory there are the numerical experiments we have done to test our code.

The python module main.py is the main entry of the project, see how to run the project for the complete details.

How to install the project
How to run the project
Numerical experiments
Authors
License

How to install the project

Main dependencies

The main dependencies we used are:

FEniCS. It is a popular open-source computing platform for solving partial differential equations (PDEs) with the finite element method (FEM).
For what concerns the implementation of the Neural Network:
- PyTorch: Python package that provides tensor computation and deep neural networks built on a tape-based autograd system.
- PyTorch Geometric. It's a library built upon PyTorch to easily write and train Graph Neural Networks (GNNs) for a wide range of applications related to structured data.
Matplotlib: a comprehensive library for creating static, animated, and interactive visualizations in Python.

To easily install these dependencies, follow the instruction in the next section to create a conda environment.

Conda environment

We developed our code using Miniconda. Please verify that you have it properly installed on your system before proceeding. If it's not installed, follow this instructions.

The first step is to create the conda environment with FEniCS and Python version 3.11 (Of course, you can choose the name you prefer for the environment instead of GP-GNN)

conda create --name GP-GNN -c conda-forge fenics python=3.11

Then, you have to activate the environment just created

conda activate GP-GNN

Now, it's time to install the required packages. Let's start with PyTorch

conda install pytorch torchvision torchaudio cpuonly -c pytorch

Then, PyTorch Geometric

conda install pyg -c pyg

Now, install torch-summary package, used to plot the summary of a GNN

pip install torch-summary

Afterwards, you have to install Matplotlib

conda install -c conda-forge matplotlib

And finally, the tqdm package, used to create progress bars

conda install -c conda-forge tqdm

Optionally, you can install Jupyter to run the notebooks

pip install jupyter

Finally, you can clone this repository and run the project.

Troubleshooting

If the conda command returns conda: command not found, follow these steps in order:

Verify that conda is actually installed on your system.
If you have just installed it, close and reopen the terminal.
Verify that you have the conda environment variable. To fix it, run the command
```
export PATH="/home/username/miniconda3/bin:$PATH"
```
Where you have to replace /home/username/miniconda3 with your actual path. If you want to have the environmental variable when you launch your terminal automatically, use
```
conda init
```
which updates the .bashrc file.

How to run the project

First of all, remember to activate the conda environment:

conda activate GP-GNN

Then, you can run the main.py module as follows:

If you want to see the help, use
```
python main.py -h
```
If you want to simulate a numerical experiment, execute
```
python main.py -r {1,2,3,4,5}
```
where you have to choose the number of the simulation. You can also specify simulation options using -o followed by the option you want. For the complete list of the possible options and the explanation of what the simulations do, you can run
```
python main.py -l
```
A usage example to run the simulation is
```
python main.py -r 3 -o train=True -o data=True
```
where you run simulation number 3 (discrete Laplacian simulation) and you specify to create a new dataset and train again the neural network.

Warning: running some simulations may be very time-consuming, so we suggest running with the default options (i.e. do not specify any option). Even better, you can look at the Python notebook to see the results without losing computation time.

Numerical experiments

We did the following experiments (the number is the same as that you should use to run the simulation):

Graphs generation. Generate random graphs given certain properties. You can find the code, the Python notebook, and more information in the folder examples/graphs_generation.
FEM usage. Test the FEM implementation to solve three PDE problems defined on a star-shaped graph. You can find the code, the Python notebook, and more information in the folder examples/fem_usage.
Discrete Laplacian. Compute the discrete Laplacian given an input vector and a graph, using a GNN. You can find the code, the Python notebook, and more information in the folder examples/discrete_laplacian.
Graph Laplacian. Solve the graph Laplacian system using a GNN. You can find the code, the Python notebook, and more information in the folder examples/graph_laplacian.
PDE with GNN. Solve an elliptic PDE defined on a certain graph using a GNN. You can find the code, the Python notebook, and more information in the folder examples/pde_with_gnn.

Authors

Francesca Behrens (GitHub)
Paolo Botta (GitHub)

License

Our code is available under the MIT License.

ploki99/GP-GNN