README.md 4.46 KB
Newer Older
rusty1s's avatar
rusty1s committed
1
2
3
4
5
6
7
[pypi-image]: https://badge.fury.io/py/torch-spline-conv.svg
[pypi-url]: https://pypi.python.org/pypi/torch-spline-conv
[build-image]: https://travis-ci.org/rusty1s/pytorch_spline_conv.svg?branch=master
[build-url]: https://travis-ci.org/rusty1s/pytorch_spline_conv
[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

rusty1s's avatar
typos  
rusty1s committed
8
# Spline-Based Convolution Operator of SplineCNN
rusty1s's avatar
rusty1s committed
9
10
11
12
13
14

[![PyPI Version][pypi-image]][pypi-url]
[![Build Status][build-image]][build-url]
[![Code Coverage][coverage-image]][coverage-url]

--------------------------------------------------------------------------------
rusty1s's avatar
rusty1s committed
15

rusty1s's avatar
bugfix  
rusty1s committed
16
17
18
19
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)

rusty1s's avatar
typos  
rusty1s committed
20
The operator works on all floating point data types and is implemented both for CPU and GPU.
rusty1s's avatar
bugfix  
rusty1s committed
21
22
23

## Installation

rusty1s's avatar
typos  
rusty1s committed
24
If cuda is available, check that `nvcc` is accessible from your terminal, e.g. by typing `nvcc --version`.
rusty1s's avatar
bugfix  
rusty1s committed
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
If not, add cuda (`/usr/local/cuda/bin`) to your `$PATH`.
Then run:

```
pip install cffi torch-spline-conv
```

## Usage

```python
from torch_spline_conv import spline_conv

output = spline_conv(src, edge_index, pseudo, weight, kernel_size,
                     is_open_spline, degree=1, root_weight=None, bias=None)
```

rusty1s's avatar
typo  
rusty1s committed
41
Applies the spline-based convolution operator
rusty1s's avatar
rusty1s committed
42
<p align="center">
Matthias Fey's avatar
Matthias Fey committed
43
  <img width="50%" src="https://user-images.githubusercontent.com/6945922/38684093-36d9c52e-3e6f-11e8-9021-db054223c6b9.png" />
rusty1s's avatar
rusty1s committed
44
</p>
rusty1s's avatar
bugfix  
rusty1s committed
45
over several node features of an input graph.
rusty1s's avatar
typos  
rusty1s committed
46
The kernel function g is defined over the weighted B-spline tensor product basis, as shown below for different B-spline degrees.
rusty1s's avatar
bugfix  
rusty1s committed
47

Matthias Fey's avatar
Matthias Fey committed
48
49
50
51
52
<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>

rusty1s's avatar
bugfix  
rusty1s committed
53
54
55
### Parameters

* **src** *(Tensor or Variable)* - Input node features of shape `(number_of_nodes x in_channels)`
rusty1s's avatar
typos  
rusty1s committed
56
57
* **edge_index** *(LongTensor)* - Graph edges, given by source and target indices, of shape `(2 x number_of_edges)`
* **pseudo** *(Tensor or Variable)* - Edge attributes, ie. pseudo coordinates, of shape `(number_of_edges x number_of_edge_attributes)` in the fixed interval [0, 1]
rusty1s's avatar
bugfix  
rusty1s committed
58
59
60
61
62
63
64
65
66
67
68
69
70
* **weight** *(Tensor or Variable)* - 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)* - B-spline basis degree (default: `1`)
* **root_weight** *(Tensor or Variable)* - Additional shared trainable parameters for each feature of the root node of shape `(in_channels x out_channels)` (default: `None`)
* **bias** *(Tensor or Variable)* - Optional bias of shape (out_channels) (default: `None`)

### Example

```python
import torch
from torch_spline_conv import spline_conv

rusty1s's avatar
typo  
rusty1s committed
71
src = torch.Tensor(4, 2)  # 4 nodes with 2 features each
rusty1s's avatar
bugfix  
rusty1s committed
72
edge_index = torch.LongTensor([[0, 1, 1, 2, 2, 3], [1, 0, 2, 1, 3, 2]])  # 6 edges
rusty1s's avatar
typos  
rusty1s committed
73
pseudo = torch.Tensor(6, 2)  # two-dimensional edge attributes
rusty1s's avatar
typo  
rusty1s committed
74
weight = torch.Tensor(25, 2, 4)  # 25 trainable parameters for in_channels x out_channels
rusty1s's avatar
bugfix  
rusty1s committed
75
kernel_size = torch.LongTensor([5, 5])  # 5 trainable parameters in each edge dimension
rusty1s's avatar
typos  
rusty1s committed
76
77
is_open_spline = torch.ByteTensor([1, 1])  # only use open B-splines
degree = 1  # B-spline degree of 1
rusty1s's avatar
typo  
rusty1s committed
78
root_weight = torch.Tensor(2, 4)  # Weight root nodes separately
rusty1s's avatar
typos  
rusty1s committed
79
bias = None  # No additional bias
rusty1s's avatar
bugfix  
rusty1s committed
80
81

output = spline_conv(src, edge_index, pseudo, weight, kernel_size,
rusty1s's avatar
typos  
rusty1s committed
82
                     is_open_spline, degree, root_weight, bias)
rusty1s's avatar
bugfix  
rusty1s committed
83
84

print(output.size())
rusty1s's avatar
typo  
rusty1s committed
85
torch.Size([4, 4])  # 4 nodes with 4 features each
rusty1s's avatar
bugfix  
rusty1s committed
86
87
```

rusty1s's avatar
rusty1s committed
88
89
90
91
92
93
94
95
96
97
98
99
## 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},
}
```
rusty1s's avatar
typos  
rusty1s committed
100
101
102
103
104
105

## Running tests

```
python setup.py test
```