| Name | stgraph JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | |
| Summary | 🌟 Vertex Centric approach for building GNN/TGNNs |
| upload_time | 2023-11-18 16:11:11 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2023 STGraph Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
gnn
tgnn
gpu programming
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/bfGraph/STGraph/blob/main/assets/STGraph%20Banner%20%E2%80%93%20Dark.png?raw=true">
<source media="(prefers-color-scheme: light)" srcset="https://github.com/bfGraph/STGraph/blob/main/assets/STGraph%20Banner%20New.png?raw=true">
<img alt="STGraph Banner" src="https://github.com/bfGraph/STGraph/blob/main/assets/STGraph%20Banner%20New.png?raw=true">
</picture>
[](https://stgraph.readthedocs.io/en/latest/?badge=latest)
[](https://neurips.cc/virtual/2023/76335)
<div align="center">
<p align="center">
<a href="https://stgraph.readthedocs.io/en/latest/"><strong>Explore the docs »</strong></a>
<br />
<br />
<a href="https://github.com/bfGraph/STGraph/blob/main/INSTALLATION.md">Installation guide</a>
·
<a href="https://github.com/bfGraph/STGraph/issues">Report Bug</a>
·
<a href="https://github.com/bfGraph/STGraph/discussions">View Discussions</a>
.
<a href="https://openreview.net/forum?id=8PRRNv81qB">Paper</a>
</p>
</div>
# 🌟 STGraph
STGraph is a framework designed for deep-learning practitioners to write and train Graph Neural Networks (GNNs) and Temporal Graph Neural Networks (TGNNs). It is built on top of _Seastar_ and utilizes the vertex-centric approach to produce highly efficient fused GPU kernels for forward and backward passes. It achieves better usability, faster computation time and consumes less memory than state-of-the-art graph deep-learning systems like DGL, PyG and PyG-T.
_NOTE: If the contents of this repository are used for research work, kindly cite the paper linked above._
## Why STGraph
The primary goal of _Seastar_ is more natural GNN programming so that the users learning curve is flattened. Our key observation lies in recognizing that the equation governing a GCN layer, as shown above, takes the form of vertex-centric computation and can be implemented succinctly with only one line of code. Moreover, we can see a clear correspondence between the GNN formulas and the vertex-centric implementations. The benefit is two-fold: users can effortlessly implement GNN models, while simultaneously understanding these models by inspecting their direct implementations.
The _Seastar_ system outperforms state-of-the-art GNN frameworks but lacks support for TGNNs. STGraph bridges that gap and enables users to to develop TGNN models through a vertex-centric approach. STGraph has shown to be significantly faster and more memory efficient that state-of-the-art frameworks like PyG-T for training TGNN models.
## Getting Started
### Pre-requisites
Install the python packages by running the following. It is recommended that you create a virtual environment before installing the packages.
**Setup a new virtual environment**
```
conda create --name stgraph
conda activate stgraph
```
**Install the python packages**
```
pip install -r requirements.txt
```
STGraph requires CUDA Version `11.7` or above to run. Versions below that may or may not run, depending on any changes within CUDA.
### Installation
You can git clone STGraph into your workspace by running the following command
```
git clone https://github.com/bfGraph/STGraph.git
cd STGraph
```
## Running your first STGraph Program
In this is quick mini tutorial, we will show you how to train a simple GCN model on the Cora dataset. After installing STGraph and entering the STGraph directory, enter the following commands to reach the GCN `benchmarking` folder
```
cd benchmarking/gcn/stgraph
```
Run the `train.py`, with 100 epochs and specify the dataset name. For this example, we shall use Cora
```
python3 train.py --num_epochs 100 --dataset cora
```
You should get an output like this. The initial prints are truncated.
```
.
.
.
Epoch 00090 | Time(s) 0.0048 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00091 | Time(s) 0.0024 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00092 | Time(s) 0.0029 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00093 | Time(s) 0.0029 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00094 | Time(s) 0.0027 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00095 | Time(s) 0.0030 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00096 | Time(s) 0.0024 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00097 | Time(s) 0.0022 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00098 | Time(s) 0.0022 | train_acc 0.303791 | Used_Memory 32.975098 mb
Epoch 00099 | Time(s) 0.0036 | train_acc 0.303791 | Used_Memory 32.975098 mb
^^^0.032202^^^0.003098
```
If you don't get this output and have followed every single step in the setting up and installation section, please raise an issue we will look into it.
## How to build STGraph
This is for users who want to make changes to the STGraph codebase and get it build each time. Follow the steps mentioned to properly build STGraph.
### Compiling the CUDA code
The following steps need to be done if you made any changes to any CUDA files within the `stgraph/graph` directory for each graph representation.
STGraph supports training dynamic and static graphs. To handle all the graph representations logic, it is written as a PyBind11 module over a CUDA file. As of now the following CUDA code for different graph representations exists
1. `csr.cu`
2. `pcsr.cu`
3. `gpma.cu`
To compile the `[name].cu` file, run the following command
```
/usr/local/cuda-11.7/bin/nvcc $(python3 -m pybind11 --includes) -shared -rdc=true --compiler-options '-fPIC' -D__CDPRT_SUPPRESS_SYNC_DEPRECATION_WARNING -o [name].so [name].cu
```
This would generate the [name].so shared object file, that is used in the STGraph module.
### Building STGraph
Make sure to go back to the root directory and run the following to build and install STGraph
```
python3 -m build && pip uninstall stgraph -y && pip install dist/stgraph-1.0.0-py3-none-any.whl
```
## Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests, issues, etc to us.
## How to contribute to Documentation
We follow the PEP-8 format. [Black](https://pypi.org/project/black/) is used as the formatter and [pycodestyle](https://pypi.org/project/pycodestyle/) as the linter. The linter is is configure to work properly with black (set line length to 88)
Tutorial for Python Docstrings can be found [here](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)
```
sphinx-apidoc -o docs/developers_guide/developer_manual/package_reference/ python/stgraph/ -f
cd docs/
make clean
make html
```
## Authors
| Author | Bio |
| --------------------------------- | --------------------------------------------------------------------- |
| `Joel Mathew Cherian` | Computer Science Student at National Institute of Technology Calicut |
| `Nithin Puthalath Manoj` | Computer Science Student at National Institute of Technology Calicut |
| `Dr. Unnikrishnan Cheramangalath` | Assistant Professor in CSED at Indian Institue of Technology Palakkad |
| `Kevin Jude` | Ph.D. in CSED at Indian Institue of Technology Palakkad |
## Attributions
| Author(s) | Title | Link(s) |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `Wu, Yidi and Ma, Kaihao and Cai, Zhenkun and Jin, Tatiana and Li, Boyang and Zheng, Chenguang and Cheng, James and Yu, Fan` | `STGraph: vertex-centric programming for graph neural networks, 2021` | [paper](https://doi.org/10.1145/3447786.3456247), [code](https://zenodo.org/record/4988602) |
| `Wheatman, Brian and Xu, Helen` | `Packed Compressed Sparse Row: A Dynamic Graph Representation, 2018` | [paper](https://ieeexplore.ieee.org/abstract/document/8547566), [code](https://github.com/wheatman/Packed-Compressed-Sparse-Row) |
| `Sha, Mo and Li, Yuchen and He, Bingsheng and Tan, Kian-Lee` | `Accelerating Dynamic Graph Analytics on GPUs, 2017` | [paper](http://www.vldb.org/pvldb/vol11/p107-sha.pdf), [code](https://github.com/desert0616/gpma_demo) |
| `Benedek Rozemberczki, Paul Scherer, Yixuan He, George Panagopoulos, Alexander Riedel, Maria Astefanoaei, Oliver Kiss, Ferenc Beres, Guzmán López, Nicolas Collignon, Rik Sarkar` | `PyTorch Geometric Temporal: Spatiotemporal Signal Processing with Neural Machine Learning Models, 2021` | [paper](https://arxiv.org/pdf/2104.07788.pdf), [code](https://github.com/benedekrozemberczki/pytorch_geometric_temporal) |
Raw data
{
"_id": null,
"home_page": "",
"name": "stgraph",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "GNN,TGNN,GPU Programming",
"author": "",
"author_email": "Joel Mathew Cherian <joelmathewcherian@gmail.com>, Nithin Puthalath Manoj <nithinp.manoj@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/25/a5/bf23c0192b34e21e1bc9fc253d401d7246ec2a5005cd399c28b97862748d/stgraph-1.0.0.tar.gz",
"platform": null,
"description": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/bfGraph/STGraph/blob/main/assets/STGraph%20Banner%20%E2%80%93%20Dark.png?raw=true\">\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/bfGraph/STGraph/blob/main/assets/STGraph%20Banner%20New.png?raw=true\">\n <img alt=\"STGraph Banner\" src=\"https://github.com/bfGraph/STGraph/blob/main/assets/STGraph%20Banner%20New.png?raw=true\"> \n</picture>\n\n\n[](https://stgraph.readthedocs.io/en/latest/?badge=latest)\n[](https://neurips.cc/virtual/2023/76335)\n\n<div align=\"center\">\n <p align=\"center\">\n <a href=\"https://stgraph.readthedocs.io/en/latest/\"><strong>Explore the docs \u00bb</strong></a>\n <br />\n <br />\n <a href=\"https://github.com/bfGraph/STGraph/blob/main/INSTALLATION.md\">Installation guide</a>\n \u00b7\n <a href=\"https://github.com/bfGraph/STGraph/issues\">Report Bug</a>\n \u00b7\n <a href=\"https://github.com/bfGraph/STGraph/discussions\">View Discussions</a>\n .\n <a href=\"https://openreview.net/forum?id=8PRRNv81qB\">Paper</a>\n </p>\n</div>\n\n\n# \ud83c\udf1f STGraph\n\nSTGraph is a framework designed for deep-learning practitioners to write and train Graph Neural Networks (GNNs) and Temporal Graph Neural Networks (TGNNs). It is built on top of _Seastar_ and utilizes the vertex-centric approach to produce highly efficient fused GPU kernels for forward and backward passes. It achieves better usability, faster computation time and consumes less memory than state-of-the-art graph deep-learning systems like DGL, PyG and PyG-T.\n\n_NOTE: If the contents of this repository are used for research work, kindly cite the paper linked above._\n\n## Why STGraph\n\n\n\n\n\nThe primary goal of _Seastar_ is more natural GNN programming so that the users learning curve is flattened. Our key observation lies in recognizing that the equation governing a GCN layer, as shown above, takes the form of vertex-centric computation and can be implemented succinctly with only one line of code. Moreover, we can see a clear correspondence between the GNN formulas and the vertex-centric implementations. The benefit is two-fold: users can effortlessly implement GNN models, while simultaneously understanding these models by inspecting their direct implementations.\n\nThe _Seastar_ system outperforms state-of-the-art GNN frameworks but lacks support for TGNNs. STGraph bridges that gap and enables users to to develop TGNN models through a vertex-centric approach. STGraph has shown to be significantly faster and more memory efficient that state-of-the-art frameworks like PyG-T for training TGNN models.\n\n## Getting Started\n\n### Pre-requisites\n\nInstall the python packages by running the following. It is recommended that you create a virtual environment before installing the packages.\n\n**Setup a new virtual environment**\n```\nconda create --name stgraph\nconda activate stgraph\n```\n\n**Install the python packages**\n```\npip install -r requirements.txt\n```\n\nSTGraph requires CUDA Version `11.7` or above to run. Versions below that may or may not run, depending on any changes within CUDA.\n\n### Installation\n\nYou can git clone STGraph into your workspace by running the following command\n\n```\ngit clone https://github.com/bfGraph/STGraph.git\ncd STGraph\n```\n\n## Running your first STGraph Program\n\nIn this is quick mini tutorial, we will show you how to train a simple GCN model on the Cora dataset. After installing STGraph and entering the STGraph directory, enter the following commands to reach the GCN `benchmarking` folder\n\n```\ncd benchmarking/gcn/stgraph\n```\n\nRun the `train.py`, with 100 epochs and specify the dataset name. For this example, we shall use Cora\n\n```\npython3 train.py --num_epochs 100 --dataset cora\n```\n\nYou should get an output like this. The initial prints are truncated.\n\n```\n.\n.\n.\nEpoch 00090 | Time(s) 0.0048 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00091 | Time(s) 0.0024 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00092 | Time(s) 0.0029 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00093 | Time(s) 0.0029 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00094 | Time(s) 0.0027 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00095 | Time(s) 0.0030 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00096 | Time(s) 0.0024 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00097 | Time(s) 0.0022 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00098 | Time(s) 0.0022 | train_acc 0.303791 | Used_Memory 32.975098 mb\nEpoch 00099 | Time(s) 0.0036 | train_acc 0.303791 | Used_Memory 32.975098 mb\n\n^^^0.032202^^^0.003098\n```\n\nIf you don't get this output and have followed every single step in the setting up and installation section, please raise an issue we will look into it.\n\n## How to build STGraph\n\nThis is for users who want to make changes to the STGraph codebase and get it build each time. Follow the steps mentioned to properly build STGraph.\n\n### Compiling the CUDA code\n\nThe following steps need to be done if you made any changes to any CUDA files within the `stgraph/graph` directory for each graph representation.\n\nSTGraph supports training dynamic and static graphs. To handle all the graph representations logic, it is written as a PyBind11 module over a CUDA file. As of now the following CUDA code for different graph representations exists\n\n1. `csr.cu`\n2. `pcsr.cu`\n3. `gpma.cu`\n\nTo compile the `[name].cu` file, run the following command\n\n```\n/usr/local/cuda-11.7/bin/nvcc $(python3 -m pybind11 --includes) -shared -rdc=true --compiler-options '-fPIC' -D__CDPRT_SUPPRESS_SYNC_DEPRECATION_WARNING -o [name].so [name].cu\n```\nThis would generate the [name].so shared object file, that is used in the STGraph module. \n\n### Building STGraph\n\nMake sure to go back to the root directory and run the following to build and install STGraph\n\n```\n python3 -m build && pip uninstall stgraph -y && pip install dist/stgraph-1.0.0-py3-none-any.whl\n```\n\n## Contributing\n\nPlease read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests, issues, etc to us.\n\n## How to contribute to Documentation\n\nWe follow the PEP-8 format. [Black](https://pypi.org/project/black/) is used as the formatter and [pycodestyle](https://pypi.org/project/pycodestyle/) as the linter. The linter is is configure to work properly with black (set line length to 88)\n\nTutorial for Python Docstrings can be found [here](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)\n\n```\nsphinx-apidoc -o docs/developers_guide/developer_manual/package_reference/ python/stgraph/ -f\ncd docs/\nmake clean\nmake html\n```\n## Authors\n\n| Author | Bio |\n| --------------------------------- | --------------------------------------------------------------------- |\n| `Joel Mathew Cherian` | Computer Science Student at National Institute of Technology Calicut |\n| `Nithin Puthalath Manoj` | Computer Science Student at National Institute of Technology Calicut |\n| `Dr. Unnikrishnan Cheramangalath` | Assistant Professor in CSED at Indian Institue of Technology Palakkad |\n| `Kevin Jude` | Ph.D. in CSED at Indian Institue of Technology Palakkad |\n\n## Attributions\n\n| Author(s) | Title | Link(s) |\n| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |\n| `Wu, Yidi and Ma, Kaihao and Cai, Zhenkun and Jin, Tatiana and Li, Boyang and Zheng, Chenguang and Cheng, James and Yu, Fan` | `STGraph: vertex-centric programming for graph neural networks, 2021` | [paper](https://doi.org/10.1145/3447786.3456247), [code](https://zenodo.org/record/4988602) |\n| `Wheatman, Brian and Xu, Helen` | `Packed Compressed Sparse Row: A Dynamic Graph Representation, 2018` | [paper](https://ieeexplore.ieee.org/abstract/document/8547566), [code](https://github.com/wheatman/Packed-Compressed-Sparse-Row) |\n| `Sha, Mo and Li, Yuchen and He, Bingsheng and Tan, Kian-Lee` | `Accelerating Dynamic Graph Analytics on GPUs, 2017` | [paper](http://www.vldb.org/pvldb/vol11/p107-sha.pdf), [code](https://github.com/desert0616/gpma_demo) |\n| `Benedek Rozemberczki, Paul Scherer, Yixuan He, George Panagopoulos, Alexander Riedel, Maria Astefanoaei, Oliver Kiss, Ferenc Beres, Guzm\u00e1n L\u00f3pez, Nicolas Collignon, Rik Sarkar` | `PyTorch Geometric Temporal: Spatiotemporal Signal Processing with Neural Machine Learning Models, 2021` | [paper](https://arxiv.org/pdf/2104.07788.pdf), [code](https://github.com/benedekrozemberczki/pytorch_geometric_temporal) |\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 STGraph Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "\ud83c\udf1f Vertex Centric approach for building GNN/TGNNs",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/bfGraph/STGraph"
},
"split_keywords": [
"gnn",
"tgnn",
"gpu programming"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6150ee9270cf9a778f226c6f545f2bb100a8b1be9067bf8ad8e81c3501ecfa9",
"md5": "fbeb9c061e0b37390d1d29fd419cf8ce",
"sha256": "931a7c78d852fa47852eef8f2ba256c7eeabbdda7b56419a107e76cd544bc487"
},
"downloads": -1,
"filename": "stgraph-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fbeb9c061e0b37390d1d29fd419cf8ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 3611659,
"upload_time": "2023-11-18T16:11:07",
"upload_time_iso_8601": "2023-11-18T16:11:07.339064Z",
"url": "https://files.pythonhosted.org/packages/d6/15/0ee9270cf9a778f226c6f545f2bb100a8b1be9067bf8ad8e81c3501ecfa9/stgraph-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "25a5bf23c0192b34e21e1bc9fc253d401d7246ec2a5005cd399c28b97862748d",
"md5": "0d2e62fd7398ad80ee713a4a93cad663",
"sha256": "9f99c3c2c8309c722f4268eba0e6c78cf632a8d121b2194905d4f2f501c31c3d"
},
"downloads": -1,
"filename": "stgraph-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0d2e62fd7398ad80ee713a4a93cad663",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3549449,
"upload_time": "2023-11-18T16:11:11",
"upload_time_iso_8601": "2023-11-18T16:11:11.209719Z",
"url": "https://files.pythonhosted.org/packages/25/a5/bf23c0192b34e21e1bc9fc253d401d7246ec2a5005cd399c28b97862748d/stgraph-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-18 16:11:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bfGraph",
"github_project": "STGraph",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "stgraph"
}
