{"id":13605421,"url":"https://github.com/DeepGraphLearning/GNN-QE","last_synced_at":"2025-04-12T05:33:00.817Z","repository":{"id":45911156,"uuid":"514941547","full_name":"DeepGraphLearning/GNN-QE","owner":"DeepGraphLearning","description":"Official implementation of Graph Neural Network Query Executor (ICML 2022)","archived":false,"fork":false,"pushed_at":"2023-09-05T13:10:14.000Z","size":2726,"stargazers_count":89,"open_issues_count":5,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-06T09:03:25.550Z","etag":null,"topics":["fuzzy-logic","graph-neural-networks","knowledge-graph","reasoning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeepGraphLearning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-17T19:52:39.000Z","updated_at":"2024-12-07T16:46:15.000Z","dependencies_parsed_at":"2024-11-07T10:34:32.520Z","dependency_job_id":"70617432-b11d-40ec-adc1-b6975ee4f1ff","html_url":"https://github.com/DeepGraphLearning/GNN-QE","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FGNN-QE","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FGNN-QE/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FGNN-QE/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepGraphLearning%2FGNN-QE/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeepGraphLearning","download_url":"https://codeload.github.com/DeepGraphLearning/GNN-QE/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248524246,"owners_count":21118609,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fuzzy-logic","graph-neural-networks","knowledge-graph","reasoning"],"created_at":"2024-08-01T19:00:58.532Z","updated_at":"2025-04-12T05:32:59.858Z","avatar_url":"https://github.com/DeepGraphLearning.png","language":"Python","readme":"# GNN-QE: Graph Neural Network Query Executor #\n\n![GNN-QE animation](asset/gnn-qe.gif)\n\nThis is the official code base of the paper\n\n[Neural-Symbolic Models for Logical Queries on Knowledge Graphs][paper]\n\n[Zhaocheng Zhu](https://kiddozhu.github.io),\n[Mikhail Galkin](https://migalkin.github.io),\n[Zuobai Zhang](https://oxer11.github.io),\n[Jian Tang](https://jian-tang.com)\n\n[paper]: https://proceedings.mlr.press/v162/zhu22c/zhu22c.pdf\n\n## Overview ##\n\nGNN-QE is a neural-symbolic model for answering multi-hop logical queries on\nknowledge graphs. Given a multi-hop logical query, GNN-QE first decomposes it into\n4 basic operations over fuzzy sets, and then executes the operations with graph\nneural networks and fuzzy logic operations.\n\nAdditionally, the intermediate variables in GNN-QE are interpretable, and one can\nvisualize them to better understand the multi-hop reasoning process.\n\n![GNN-QE visualization](asset/visualization.png)\n\n## Installation ##\n\nThe dependencies can be installed via either conda or pip. GNN-QE is compatible\nwith Python 3.7/3.8/3.9 and PyTorch \u003e= 1.8.0.\n\n### From Conda ###\n\n```bash\nconda install torchdrug pytorch cudatoolkit -c milagraph -c pytorch -c pyg\nconda install easydict pyyaml -c conda-forge\n```\n\n### From Pip ###\n\n```bash\npip install torchdrug torch\npip install easydict pyyaml\n```\n\n## Usage ##\n\nTo run GNN-QE, use the following command. Alternatively, you may specify\n`--gpus null` to run GNN-QE on a CPU. All the datasets will be automatically\ndownloaded in the code.\n\n```bash\npython script/run.py -c config/fb15k237.yaml --gpus [0]\n```\n\nWe provide the hyperparameters for each experiment in a separate configuration file.\nThe hyperparameters are designed for 32GB GPUs, but you may adjust the batch size\nto fit a smaller GPU memory. All the configuration files can be found in\n`config/*.yaml`. \n\nTo run GNN-QE with multiple GPUs or multiple machines, use the following commands\n\n```bash\npython -m torch.distributed.launch --nproc_per_node=4 script/run.py -c config/fb15k237.yaml --gpus [0,1,2,3]\n```\n\n```bash\npython -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]\n```\n\nOnce you have models trained on FB15k-237, you can visualize the intermediate\nvariables with the following line. The visualizations will be output in a new\nexperiment directory as `png` files. Please replace the checkpoint with your own\npath.\n\n```bash\npython script/visualize.py -c config/fb15k237_visualize.yaml --checkpoint /path/to/gnn-qe/experiment/model_epoch_10.pth\n```\n\n## Bring your own GNNs ##\n\nGenerally, GNN-QE is a GNN-agnostic framework for answering logical queries.\nYou may plug any GNN model into GNN-QE. To do so, just implement the convolution\nlayer in `gnnqe/layer.py` and the GNN model in `gnnqe/gnn.py`. The GNN model is\nexpected to have the following signature\n\n```python\ndef forward(self, graph, input, all_loss=None, metric=None):\n    ...\n    return {\n        \"node_feature\": node_feature,\n    }\n```\n\nwhere the arguments and the return value are\n- `graph` (data.Graph): the knowledge graph with `graph.query` being the query\n  embeddings of shape `(batch_size, input_dim)`. \n- `input` (Tensor): input tensor of shape `(|V|, batch_size, input_dim)` \n- `all_loss` (Tensor): a scalar tensor that accumulates losses during training\n- `metric` (Tensor): a dict that stores any scalar information for logging during\n  training\n- `node_feature` (Tensor): node feature of shape `(|V|, batch_size, output_dim)`\n\nFor how to implement GNN models in TorchDrug, please refer to these tutorials\n- [Graph Neural Network Layers](https://torchdrug.ai/docs/notes/layer.html)\n- [Customize Models \u0026 Tasks](https://torchdrug.ai/docs/notes/model.html)\n\n## Frequently Asked Questions ##\n\n1. **The code is stuck at the beginning of epoch 0.**\n\n   This is probably because the JIT cache is broken.\n   Try `rm -r ~/.cache/torch_extensions/*` and run the code again.\n\n## Citation ##\n\nIf you find this project useful in your research, please cite the following paper\n\n```bibtex\n@inproceedings{zhu2022neural,\n  title={Neural-Symbolic Models for Logical Queries on Knowledge Graphs},\n  author={Zhu, Zhaocheng and Galkin, Mikhail and Zhang, Zuobai and Tang, Jian},\n  booktitle={Proceedings of the 39th International Conference on Machine Learning},\n  pages={27454--27478},\n  volume={162},\n  year={2022},\n}\n```","funding_links":[],"categories":[":wrench: Implementations"],"sub_categories":["Dataset tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDeepGraphLearning%2FGNN-QE","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDeepGraphLearning%2FGNN-QE","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDeepGraphLearning%2FGNN-QE/lists"}