[pypi-image]: https://badge.fury.io/py/torch-spline-conv.svg
[pypi-url]: https://pypi.python.org/pypi/torch-spline-conv
[testing-image]: https://github.com/rusty1s/pytorch_spline_conv/actions/workflows/testing.yml/badge.svg
[testing-url]: https://github.com/rusty1s/pytorch_spline_conv/actions/workflows/testing.yml
[linting-image]: https://github.com/rusty1s/pytorch_spline_conv/actions/workflows/linting.yml/badge.svg
[linting-url]: https://github.com/rusty1s/pytorch_spline_conv/actions/workflows/linting.yml
[coverage-image]: https://codecov.io/gh/rusty1s/pytorch_spline_conv/branch/master/graph/badge.svg
[coverage-url]: https://codecov.io/github/rusty1s/pytorch_spline_conv?branch=master
# Spline-Based Convolution Operator of SplineCNN
[![PyPI Version][pypi-image]][pypi-url]
[![Testing Status][testing-image]][testing-url]
[![Linting Status][linting-image]][linting-url]
[![Code Coverage][coverage-image]][coverage-url]
--------------------------------------------------------------------------------
This is a PyTorch implementation of the spline-based convolution operator of SplineCNN, as described in our paper:
Matthias Fey, Jan Eric Lenssen, Frank Weichert, Heinrich Müller: [SplineCNN: Fast Geometric Deep Learning with Continuous B-Spline Kernels](https://arxiv.org/abs/1711.08920) (CVPR 2018)
The operator works on all floating point data types and is implemented both for CPU and GPU.
## Installation
### Anaconda
**Update:** You can now install `pytorch-spline-conv` via [Anaconda](https://anaconda.org/pyg/pytorch-spline-conv) for all major OS/PyTorch/CUDA combinations 🤗
Given that you have [`pytorch >= 1.8.0` installed](https://pytorch.org/get-started/locally/), simply run
```
conda install pytorch-spline-conv -c pyg
```
### Binaries
We alternatively provide pip wheels for all major OS/PyTorch/CUDA combinations, see [here](https://data.pyg.org/whl).
#### PyTorch 2.0
To install the binaries for PyTorch 2.0.0, simply run
```
pip install torch-spline-conv -f https://data.pyg.org/whl/torch-2.0.0+${CUDA}.html
```
where `${CUDA}` should be replaced by either `cpu`, `cu117`, or `cu118` depending on your PyTorch installation.
| | `cpu` | `cu117` | `cu118` |
|-------------|-------|---------|---------|
| **Linux** | ✅ | ✅ | ✅ |
| **Windows** | ✅ | ✅ | ✅ |
| **macOS** | ✅ | | |
#### PyTorch 1.13
To install the binaries for PyTorch 1.13.0, simply run
```
pip install torch-spline-conv -f https://data.pyg.org/whl/torch-1.13.0+${CUDA}.html
```
where `${CUDA}` should be replaced by either `cpu`, `cu116`, or `cu117` depending on your PyTorch installation.
| | `cpu` | `cu116` | `cu117` |
|-------------|-------|---------|---------|
| **Linux** | ✅ | ✅ | ✅ |
| **Windows** | ✅ | ✅ | ✅ |
| **macOS** | ✅ | | |
**Note:** Binaries of older versions are also provided for PyTorch 1.4.0, PyTorch 1.5.0, PyTorch 1.6.0, PyTorch 1.7.0/1.7.1, PyTorch 1.8.0/1.8.1, PyTorch 1.9.0, PyTorch 1.10.0/1.10.1/1.10.2, PyTorch 1.11.0 and PyTorch 1.12.0/1.12.1 (following the same procedure).
For older versions, you need to explicitly specify the latest supported version number or install via `pip install --no-index` in order to prevent a manual installation from source.
You can look up the latest supported version number [here](https://data.pyg.org/whl).
### From source
Ensure that at least PyTorch 1.4.0 is installed and verify that `cuda/bin` and `cuda/include` are in your `$PATH` and `$CPATH` respectively, *e.g.*:
```
$ python -c "import torch; print(torch.__version__)"
>>> 1.4.0
$ echo $PATH
>>> /usr/local/cuda/bin:...
$ echo $CPATH
>>> /usr/local/cuda/include:...
```
Then run:
```
pip install torch-spline-conv
```
When running in a docker container without NVIDIA driver, PyTorch needs to evaluate the compute capabilities and may fail.
In this case, ensure that the compute capabilities are set via `TORCH_CUDA_ARCH_LIST`, *e.g.*:
```
export TORCH_CUDA_ARCH_LIST = "6.0 6.1 7.2+PTX 7.5+PTX"
```
## Usage
```python
from torch_spline_conv import spline_conv
out = spline_conv(x,
edge_index,
pseudo,
weight,
kernel_size,
is_open_spline,
degree=1,
norm=True,
root_weight=None,
bias=None)
```
Applies the spline-based convolution operator
<p align="center">
<img width="50%" src="https://user-images.githubusercontent.com/6945922/38684093-36d9c52e-3e6f-11e8-9021-db054223c6b9.png" />
</p>
over several node features of an input graph.
The kernel function is defined over the weighted B-spline tensor product basis, as shown below for different B-spline degrees.
<p align="center">
<img width="45%" src="https://user-images.githubusercontent.com/6945922/38685443-3a2a0c68-3e72-11e8-8e13-9ce9ad8fe43e.png" />
<img width="45%" src="https://user-images.githubusercontent.com/6945922/38685459-42b2bcae-3e72-11e8-88cc-4b61e41dbd93.png" />
</p>
### Parameters
* **x** *(Tensor)* - Input node features of shape `(number_of_nodes x in_channels)`.
* **edge_index** *(LongTensor)* - Graph edges, given by source and target indices, of shape `(2 x number_of_edges)`.
* **pseudo** *(Tensor)* - Edge attributes, ie. pseudo coordinates, of shape `(number_of_edges x number_of_edge_attributes)` in the fixed interval [0, 1].
* **weight** *(Tensor)* - Trainable weight parameters of shape `(kernel_size x in_channels x out_channels)`.
* **kernel_size** *(LongTensor)* - Number of trainable weight parameters in each edge dimension.
* **is_open_spline** *(ByteTensor)* - Whether to use open or closed B-spline bases for each dimension.
* **degree** *(int, optional)* - B-spline basis degree. (default: `1`)
* **norm** *(bool, optional)*: Whether to normalize output by node degree. (default: `True`)
* **root_weight** *(Tensor, optional)* - Additional shared trainable parameters for each feature of the root node of shape `(in_channels x out_channels)`. (default: `None`)
* **bias** *(Tensor, optional)* - Optional bias of shape `(out_channels)`. (default: `None`)
### Returns
* **out** *(Tensor)* - Out node features of shape `(number_of_nodes x out_channels)`.
### Example
```python
import torch
from torch_spline_conv import spline_conv
x = torch.rand((4, 2), dtype=torch.float) # 4 nodes with 2 features each
edge_index = torch.tensor([[0, 1, 1, 2, 2, 3], [1, 0, 2, 1, 3, 2]]) # 6 edges
pseudo = torch.rand((6, 2), dtype=torch.float) # two-dimensional edge attributes
weight = torch.rand((25, 2, 4), dtype=torch.float) # 25 parameters for in_channels x out_channels
kernel_size = torch.tensor([5, 5]) # 5 parameters in each edge dimension
is_open_spline = torch.tensor([1, 1], dtype=torch.uint8) # only use open B-splines
degree = 1 # B-spline degree of 1
norm = True # Normalize output by node degree.
root_weight = torch.rand((2, 4), dtype=torch.float) # separately weight root nodes
bias = None # do not apply an additional bias
out = spline_conv(x, edge_index, pseudo, weight, kernel_size,
is_open_spline, degree, norm, root_weight, bias)
print(out.size())
torch.Size([4, 4]) # 4 nodes with 4 features each
```
## Cite
Please cite our paper if you use this code in your own work:
```
@inproceedings{Fey/etal/2018,
title={{SplineCNN}: Fast Geometric Deep Learning with Continuous {B}-Spline Kernels},
author={Fey, Matthias and Lenssen, Jan Eric and Weichert, Frank and M{\"u}ller, Heinrich},
booktitle={IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
year={2018},
}
```
## Running tests
```
pytest
```
## C++ API
`torch-spline-conv` also offers a C++ API that contains C++ equivalent of python models.
```
mkdir build
cd build
# Add -DWITH_CUDA=on support for the CUDA if needed
cmake ..
make
make install
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rusty1s/pytorch_spline_conv",
"name": "torch-spline-conv",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "pytorch,geometric-deep-learning,graph-neural-networks,spline-cnn",
"author": "Matthias Fey",
"author_email": "matthias.fey@tu-dortmund.de",
"download_url": "https://files.pythonhosted.org/packages/a0/50/5f80c47bf09b561ded0981b088ab0064424843696aa35b3b83afde421e56/torch_spline_conv-1.2.2.tar.gz",
"platform": null,
"description": "[pypi-image]: https://badge.fury.io/py/torch-spline-conv.svg\n[pypi-url]: https://pypi.python.org/pypi/torch-spline-conv\n[testing-image]: https://github.com/rusty1s/pytorch_spline_conv/actions/workflows/testing.yml/badge.svg\n[testing-url]: https://github.com/rusty1s/pytorch_spline_conv/actions/workflows/testing.yml\n[linting-image]: https://github.com/rusty1s/pytorch_spline_conv/actions/workflows/linting.yml/badge.svg\n[linting-url]: https://github.com/rusty1s/pytorch_spline_conv/actions/workflows/linting.yml\n[coverage-image]: https://codecov.io/gh/rusty1s/pytorch_spline_conv/branch/master/graph/badge.svg\n[coverage-url]: https://codecov.io/github/rusty1s/pytorch_spline_conv?branch=master\n\n# Spline-Based Convolution Operator of SplineCNN\n\n[![PyPI Version][pypi-image]][pypi-url]\n[![Testing Status][testing-image]][testing-url]\n[![Linting Status][linting-image]][linting-url]\n[![Code Coverage][coverage-image]][coverage-url]\n\n--------------------------------------------------------------------------------\n\nThis is a PyTorch implementation of the spline-based convolution operator of SplineCNN, as described in our paper:\n\nMatthias Fey, Jan Eric Lenssen, Frank Weichert, Heinrich M\u00fcller: [SplineCNN: Fast Geometric Deep Learning with Continuous B-Spline Kernels](https://arxiv.org/abs/1711.08920) (CVPR 2018)\n\nThe operator works on all floating point data types and is implemented both for CPU and GPU.\n\n## Installation\n\n### Anaconda\n\n**Update:** You can now install `pytorch-spline-conv` via [Anaconda](https://anaconda.org/pyg/pytorch-spline-conv) for all major OS/PyTorch/CUDA combinations \ud83e\udd17\nGiven that you have [`pytorch >= 1.8.0` installed](https://pytorch.org/get-started/locally/), simply run\n\n```\nconda install pytorch-spline-conv -c pyg\n```\n\n### Binaries\n\nWe alternatively provide pip wheels for all major OS/PyTorch/CUDA combinations, see [here](https://data.pyg.org/whl).\n\n#### PyTorch 2.0\n\nTo install the binaries for PyTorch 2.0.0, simply run\n\n```\npip install torch-spline-conv -f https://data.pyg.org/whl/torch-2.0.0+${CUDA}.html\n```\n\nwhere `${CUDA}` should be replaced by either `cpu`, `cu117`, or `cu118` depending on your PyTorch installation.\n\n| | `cpu` | `cu117` | `cu118` |\n|-------------|-------|---------|---------|\n| **Linux** | \u2705 | \u2705 | \u2705 |\n| **Windows** | \u2705 | \u2705 | \u2705 |\n| **macOS** | \u2705 | | |\n\n#### PyTorch 1.13\n\nTo install the binaries for PyTorch 1.13.0, simply run\n\n```\npip install torch-spline-conv -f https://data.pyg.org/whl/torch-1.13.0+${CUDA}.html\n```\n\nwhere `${CUDA}` should be replaced by either `cpu`, `cu116`, or `cu117` depending on your PyTorch installation.\n\n| | `cpu` | `cu116` | `cu117` |\n|-------------|-------|---------|---------|\n| **Linux** | \u2705 | \u2705 | \u2705 |\n| **Windows** | \u2705 | \u2705 | \u2705 |\n| **macOS** | \u2705 | | |\n\n**Note:** Binaries of older versions are also provided for PyTorch 1.4.0, PyTorch 1.5.0, PyTorch 1.6.0, PyTorch 1.7.0/1.7.1, PyTorch 1.8.0/1.8.1, PyTorch 1.9.0, PyTorch 1.10.0/1.10.1/1.10.2, PyTorch 1.11.0 and PyTorch 1.12.0/1.12.1 (following the same procedure).\nFor older versions, you need to explicitly specify the latest supported version number or install via `pip install --no-index` in order to prevent a manual installation from source.\nYou can look up the latest supported version number [here](https://data.pyg.org/whl).\n\n### From source\n\nEnsure that at least PyTorch 1.4.0 is installed and verify that `cuda/bin` and `cuda/include` are in your `$PATH` and `$CPATH` respectively, *e.g.*:\n\n```\n$ python -c \"import torch; print(torch.__version__)\"\n>>> 1.4.0\n\n$ echo $PATH\n>>> /usr/local/cuda/bin:...\n\n$ echo $CPATH\n>>> /usr/local/cuda/include:...\n```\n\nThen run:\n\n```\npip install torch-spline-conv\n```\n\nWhen running in a docker container without NVIDIA driver, PyTorch needs to evaluate the compute capabilities and may fail.\nIn this case, ensure that the compute capabilities are set via `TORCH_CUDA_ARCH_LIST`, *e.g.*:\n\n```\nexport TORCH_CUDA_ARCH_LIST = \"6.0 6.1 7.2+PTX 7.5+PTX\"\n```\n\n## Usage\n\n```python\nfrom torch_spline_conv import spline_conv\n\nout = spline_conv(x,\n edge_index,\n pseudo,\n weight,\n kernel_size,\n is_open_spline,\n degree=1,\n norm=True,\n root_weight=None,\n bias=None)\n```\n\nApplies the spline-based convolution operator\n<p align=\"center\">\n <img width=\"50%\" src=\"https://user-images.githubusercontent.com/6945922/38684093-36d9c52e-3e6f-11e8-9021-db054223c6b9.png\" />\n</p>\nover several node features of an input graph.\nThe kernel function is defined over the weighted B-spline tensor product basis, as shown below for different B-spline degrees.\n\n<p align=\"center\">\n <img width=\"45%\" src=\"https://user-images.githubusercontent.com/6945922/38685443-3a2a0c68-3e72-11e8-8e13-9ce9ad8fe43e.png\" />\n <img width=\"45%\" src=\"https://user-images.githubusercontent.com/6945922/38685459-42b2bcae-3e72-11e8-88cc-4b61e41dbd93.png\" />\n</p>\n\n### Parameters\n\n* **x** *(Tensor)* - Input node features of shape `(number_of_nodes x in_channels)`.\n* **edge_index** *(LongTensor)* - Graph edges, given by source and target indices, of shape `(2 x number_of_edges)`.\n* **pseudo** *(Tensor)* - Edge attributes, ie. pseudo coordinates, of shape `(number_of_edges x number_of_edge_attributes)` in the fixed interval [0, 1].\n* **weight** *(Tensor)* - Trainable weight parameters of shape `(kernel_size x in_channels x out_channels)`.\n* **kernel_size** *(LongTensor)* - Number of trainable weight parameters in each edge dimension.\n* **is_open_spline** *(ByteTensor)* - Whether to use open or closed B-spline bases for each dimension.\n* **degree** *(int, optional)* - B-spline basis degree. (default: `1`)\n* **norm** *(bool, optional)*: Whether to normalize output by node degree. (default: `True`)\n* **root_weight** *(Tensor, optional)* - Additional shared trainable parameters for each feature of the root node of shape `(in_channels x out_channels)`. (default: `None`)\n* **bias** *(Tensor, optional)* - Optional bias of shape `(out_channels)`. (default: `None`)\n\n### Returns\n\n* **out** *(Tensor)* - Out node features of shape `(number_of_nodes x out_channels)`.\n\n### Example\n\n```python\nimport torch\nfrom torch_spline_conv import spline_conv\n\nx = torch.rand((4, 2), dtype=torch.float) # 4 nodes with 2 features each\nedge_index = torch.tensor([[0, 1, 1, 2, 2, 3], [1, 0, 2, 1, 3, 2]]) # 6 edges\npseudo = torch.rand((6, 2), dtype=torch.float) # two-dimensional edge attributes\nweight = torch.rand((25, 2, 4), dtype=torch.float) # 25 parameters for in_channels x out_channels\nkernel_size = torch.tensor([5, 5]) # 5 parameters in each edge dimension\nis_open_spline = torch.tensor([1, 1], dtype=torch.uint8) # only use open B-splines\ndegree = 1 # B-spline degree of 1\nnorm = True # Normalize output by node degree.\nroot_weight = torch.rand((2, 4), dtype=torch.float) # separately weight root nodes\nbias = None # do not apply an additional bias\n\nout = spline_conv(x, edge_index, pseudo, weight, kernel_size,\n is_open_spline, degree, norm, root_weight, bias)\n\nprint(out.size())\ntorch.Size([4, 4]) # 4 nodes with 4 features each\n```\n\n## Cite\n\nPlease cite our paper if you use this code in your own work:\n\n```\n@inproceedings{Fey/etal/2018,\n title={{SplineCNN}: Fast Geometric Deep Learning with Continuous {B}-Spline Kernels},\n author={Fey, Matthias and Lenssen, Jan Eric and Weichert, Frank and M{\\\"u}ller, Heinrich},\n booktitle={IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},\n year={2018},\n}\n```\n\n## Running tests\n\n```\npytest\n```\n\n## C++ API\n\n`torch-spline-conv` also offers a C++ API that contains C++ equivalent of python models.\n\n```\nmkdir build\ncd build\n# Add -DWITH_CUDA=on support for the CUDA if needed\ncmake ..\nmake\nmake install\n```\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Implementation of the Spline-Based Convolution Operator of SplineCNN in PyTorch",
"version": "1.2.2",
"split_keywords": [
"pytorch",
"geometric-deep-learning",
"graph-neural-networks",
"spline-cnn"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a0505f80c47bf09b561ded0981b088ab0064424843696aa35b3b83afde421e56",
"md5": "ec7fbea1569802d7fc5f12f47f706507",
"sha256": "ed45a81da29f774665dbdd4709d7e534cdf16d2e7006dbd06957f35bd09661b2"
},
"downloads": -1,
"filename": "torch_spline_conv-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "ec7fbea1569802d7fc5f12f47f706507",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 25353,
"upload_time": "2023-03-16T14:33:40",
"upload_time_iso_8601": "2023-03-16T14:33:40.615909Z",
"url": "https://files.pythonhosted.org/packages/a0/50/5f80c47bf09b561ded0981b088ab0064424843696aa35b3b83afde421e56/torch_spline_conv-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-16 14:33:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "rusty1s",
"github_project": "pytorch_spline_conv",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "torch-spline-conv"
}
JSON
