https://github.com/DeepGraphLearning/GNN-QE

Official implementation of Graph Neural Network Query Executor (ICML 2022)
https://github.com/DeepGraphLearning/GNN-QE

fuzzy-logic graph-neural-networks knowledge-graph reasoning

Last synced: 1 day ago
JSON representation

Official implementation of Graph Neural Network Query Executor (ICML 2022)

• Host: GitHub
• URL: https://github.com/DeepGraphLearning/GNN-QE
• Owner: DeepGraphLearning
• License: mit
• Created: 2022-07-17T19:52:39.000Z (over 2 years ago)
• Default Branch: master
• Last Pushed: 2023-09-05T13:10:14.000Z (about 1 year ago)
• Last Synced: 2024-08-02T19:37:21.792Z (3 months ago)
• Topics: fuzzy-logic, graph-neural-networks, knowledge-graph, reasoning
• Language: Python
• Homepage:
• Size: 2.6 MB
• Stars: 89
• Watchers: 5
• Forks: 12
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-logical-query - GNN-QE - QE (:wrench: Implementations / Dataset tools)

README

        
# GNN-QE: Graph Neural Network Query Executor #

![GNN-QE animation](asset/gnn-qe.gif)

This is the official code base of the paper

[Neural-Symbolic Models for Logical Queries on Knowledge Graphs][paper]

[Zhaocheng Zhu](https://kiddozhu.github.io),

[Mikhail Galkin](https://migalkin.github.io),

[Zuobai Zhang](https://oxer11.github.io),

[Jian Tang](https://jian-tang.com)

[paper]: https://proceedings.mlr.press/v162/zhu22c/zhu22c.pdf

## Overview ##

GNN-QE is a neural-symbolic model for answering multi-hop logical queries on

knowledge graphs. Given a multi-hop logical query, GNN-QE first decomposes it into

4 basic operations over fuzzy sets, and then executes the operations with graph

neural networks and fuzzy logic operations.

Additionally, the intermediate variables in GNN-QE are interpretable, and one can

visualize them to better understand the multi-hop reasoning process.

![GNN-QE visualization](asset/visualization.png)

## Installation ##

The dependencies can be installed via either conda or pip. GNN-QE is compatible

with Python 3.7/3.8/3.9 and PyTorch >= 1.8.0.

### From Conda ###

```bash

conda install torchdrug pytorch cudatoolkit -c milagraph -c pytorch -c pyg

conda install easydict pyyaml -c conda-forge

```

### From Pip ###

```bash

pip install torchdrug torch

pip install easydict pyyaml

```

## Usage ##

To run GNN-QE, use the following command. Alternatively, you may specify

`--gpus null` to run GNN-QE on a CPU. All the datasets will be automatically

downloaded in the code.

```bash

python script/run.py -c config/fb15k237.yaml --gpus [0]

```

We provide the hyperparameters for each experiment in a separate configuration file.

The hyperparameters are designed for 32GB GPUs, but you may adjust the batch size

to fit a smaller GPU memory. All the configuration files can be found in

`config/*.yaml`. 

To run GNN-QE with multiple GPUs or multiple machines, use the following commands

```bash

python -m torch.distributed.launch --nproc_per_node=4 script/run.py -c config/fb15k237.yaml --gpus [0,1,2,3]

```

```bash

python -m torch.distributed.launch --nnodes=4 --nproc_per_node=4 script/run.py -c config/fb15k237.yaml --gpus [0,1,2,3,0,1,2,3,0,1,2,3,0,1,2,3]

```

Once you have models trained on FB15k-237, you can visualize the intermediate

variables with the following line. The visualizations will be output in a new

experiment directory as `png` files. Please replace the checkpoint with your own

path.

```bash

python script/visualize.py -c config/fb15k237_visualize.yaml --checkpoint /path/to/gnn-qe/experiment/model_epoch_10.pth

```

## Bring your own GNNs ##

Generally, GNN-QE is a GNN-agnostic framework for answering logical queries.

You may plug any GNN model into GNN-QE. To do so, just implement the convolution

layer in `gnnqe/layer.py` and the GNN model in `gnnqe/gnn.py`. The GNN model is

expected to have the following signature

```python

def forward(self, graph, input, all_loss=None, metric=None):

    ...

    return {

        "node_feature": node_feature,

    }

```

where the arguments and the return value are

- `graph` (data.Graph): the knowledge graph with `graph.query` being the query

  embeddings of shape `(batch_size, input_dim)`. 

- `input` (Tensor): input tensor of shape `(|V|, batch_size, input_dim)` 

- `all_loss` (Tensor): a scalar tensor that accumulates losses during training

- `metric` (Tensor): a dict that stores any scalar information for logging during

  training

- `node_feature` (Tensor): node feature of shape `(|V|, batch_size, output_dim)`

For how to implement GNN models in TorchDrug, please refer to these tutorials

- [Graph Neural Network Layers](https://torchdrug.ai/docs/notes/layer.html)

- [Customize Models & Tasks](https://torchdrug.ai/docs/notes/model.html)

## Frequently Asked Questions ##

1. **The code is stuck at the beginning of epoch 0.**

   This is probably because the JIT cache is broken.

   Try `rm -r ~/.cache/torch_extensions/*` and run the code again.

## Citation ##

If you find this project useful in your research, please cite the following paper

```bibtex

@inproceedings{zhu2022neural,

  title={Neural-Symbolic Models for Logical Queries on Knowledge Graphs},

  author={Zhu, Zhaocheng and Galkin, Mikhail and Zhang, Zuobai and Tang, Jian},

  booktitle={Proceedings of the 39th International Conference on Machine Learning},

  pages={27454--27478},

  volume={162},

  year={2022},

}

```