README.md 7.87 KB
Newer Older
yan.yan's avatar
yan.yan committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!--
 Copyright 2021 Yan Yan
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
     http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
[pypi-ver-cpu]: https://img.shields.io/pypi/v/spconv
[pypi-ver-114]: https://img.shields.io/pypi/v/spconv-cu114
[pypi-ver-111]: https://img.shields.io/pypi/v/spconv-cu111
[pypi-ver-113]: https://img.shields.io/pypi/v/spconv-cu113
[pypi-ver-102]: https://img.shields.io/pypi/v/spconv-cu102

[pypi-url-111]: https://pypi.org/project/spconv-cu111/
[pypi-download-111]: https://img.shields.io/pypi/dm/spconv-cu111
[pypi-url-113]: https://pypi.org/project/spconv-cu113/
[pypi-download-113]: https://img.shields.io/pypi/dm/spconv-cu113
[pypi-url-102]: https://pypi.org/project/spconv-cu102/
[pypi-download-102]: https://img.shields.io/pypi/dm/spconv-cu102
[pypi-url-114]: https://pypi.org/project/spconv-cu114/
[pypi-download-114]: https://img.shields.io/pypi/dm/spconv-cu114
[pypi-url-cpu]: https://pypi.org/project/spconv/
[pypi-download-cpu]: https://img.shields.io/pypi/dm/spconv
yan.yan's avatar
yan.yan committed
32

yan.yan's avatar
v2.1  
yan.yan committed
33
# SpConv: Spatially Sparse Convolution Library
34
35
36
37
38
39
40
41
42
[![Build Status](https://github.com/traveller59/spconv/workflows/build/badge.svg)](https://github.com/traveller59/spconv/actions?query=workflow%3Abuild) 

|                | PyPi Version  | Downloads  |
| -------------- |:---------------------:| ---------------------:| 
| CPU (Linux Only) | [![PyPI Version][pypi-ver-cpu]][pypi-url-cpu] | [![pypi monthly download][pypi-download-cpu]][pypi-url-cpu] | 
| CUDA 10.2 | [![PyPI Version][pypi-ver-102]][pypi-url-102] | [![pypi monthly download][pypi-download-102]][pypi-url-102] | 
| CUDA 11.1 | [![PyPI Version][pypi-ver-111]][pypi-url-111] | [![pypi monthly download][pypi-download-111]][pypi-url-111]| 
| CUDA 11.3 (Linux Only) | [![PyPI Version][pypi-ver-113]][pypi-url-113] |[![pypi monthly download][pypi-download-113]][pypi-url-113]| 
| CUDA 11.4 | [![PyPI Version][pypi-ver-114]][pypi-url-114] | [![pypi monthly download][pypi-download-114]][pypi-url-114]| 
traveller59's avatar
traveller59 committed
43

tusimple's avatar
tusimple committed
44

45
```spconv``` is a project that provide heavily-optimized sparse convolution implementation with tensor core support. check [benchmark](docs/BENCHMARK.md) to see how fast spconv 2.x runs.
46

yan.yan's avatar
v2.1  
yan.yan committed
47
[Spconv 1.x code](https://github.com/traveller59/spconv/tree/v1.2.1). We won't provide any support for spconv 1.x since it's deprecated. use spconv 2.x if possible. <!--remove this message in spconv 2.2-->
FindDefinition's avatar
FindDefinition committed
48

49
50
**WARNING** spconv < 2.1.4 users need to upgrade your version to 2.1.4, it fix a serious bug in SparseInverseConvXd.

yan.yan's avatar
v2.1  
yan.yan committed
51
## Breaking changes in Spconv 2.x
FindDefinition's avatar
FindDefinition committed
52

yan.yan's avatar
v2.1  
yan.yan committed
53
Spconv 1.x users **NEED READ [THIS](docs/SPCONV_2_BREAKING_CHANGEs.md)** before using spconv 2.x.
FindDefinition's avatar
FindDefinition committed
54

yan.yan's avatar
v2.1  
yan.yan committed
55
## Spconv 2.1 vs Spconv 1.x
traveller59's avatar
traveller59 committed
56

yan.yan's avatar
yan.yan committed
57
* spconv now can be installed by **pip**. see install section in readme for more details. Users don't need to build manually anymore!
yan.yan's avatar
v2.1  
yan.yan committed
58
59
60
61
* Microsoft Windows support (only windows 10 has been tested).
* fp32 (not tf32) training/inference speed is increased (+50~80%)
* fp16 training/inference speed is greatly increased when your layer support tensor core (channel size must be multiple of 8).
* int8 op is ready, but we still need some time to figure out how to run int8 in pytorch.
yan.yan's avatar
yan.yan committed
62
63
* doesn't depend on pytorch binary. 
* since spconv 2.x doesn't depend on pytorch binary (never in future), it's impossible to support torch.jit/libtorch inference.
traveller59's avatar
traveller59 committed
64

65
## Spconv 2.x Development and Roadmap
66

67
See [dev plan](docs/SPCONV_DEVELOP_PLAN.md). A complete guide of spconv development will be released soon.
68

yan.yan's avatar
yan.yan committed
69

yan.yan's avatar
v2.1  
yan.yan committed
70

yan.yan's avatar
yan.yan committed
71
72
73
74
## Usage

Firstly you need to use ```import spconv.pytorch as spconv``` in spconv 2.x.

yan.yan's avatar
v2.1  
yan.yan committed
75
Then see [this](docs/USAGE.md).
yan.yan's avatar
yan.yan committed
76

yan.yan's avatar
v2.1  
yan.yan committed
77
Don't forget to check [performance guide](docs/PERFORMANCE_GUIDE.md).
traveller59's avatar
traveller59 committed
78

yan.yan's avatar
yan.yan committed
79
## Install
traveller59's avatar
traveller59 committed
80

yan.yan's avatar
yan.yan committed
81
You need to install python >= 3.7 first to use spconv 2.x.
traveller59's avatar
traveller59 committed
82

yan.yan's avatar
yan.yan committed
83
You need to install CUDA toolkit first before using prebuilt binaries or build from source.
traveller59's avatar
traveller59 committed
84

yan.yan's avatar
yan.yan committed
85
You need at least CUDA 10.2 to build and run spconv 2.x. We won't offer any support for CUDA < 10.2.
traveller59's avatar
traveller59 committed
86

yan.yan's avatar
yan.yan committed
87
### Prebuilt
traveller59's avatar
traveller59 committed
88

yan.yan's avatar
v2.1  
yan.yan committed
89
We offer python 3.7-3.10 and cuda 10.2/11.1/11.3/11.4 prebuilt binaries for linux (manylinux) and windows 10/11.
traveller59's avatar
traveller59 committed
90

yan.yan's avatar
v2.1  
yan.yan committed
91
We will provide prebuilts for CUDA versions supported by latest pytorch release. For example, pytorch 1.10 provide cuda 10.2 and 11.3 prebuilts, so we provide them too.
traveller59's avatar
traveller59 committed
92

yan.yan's avatar
yan.yan committed
93
For Linux users, you need to install pip >= 20.3 first to install prebuilt.
traveller59's avatar
traveller59 committed
94

yan.yan's avatar
v2.1  
yan.yan committed
95
96
97
98
99
100
CUDA 11.1 will be removed in spconv 2.2 because pytorch 1.10 don't provide prebuilts for it.

```pip install spconv``` for CPU only (**Linux Only**). you should only use this for debug usage, the performance isn't optimized due to manylinux limit (no omp support).

```pip install spconv-cu102``` for CUDA 10.2

yan.yan's avatar
yan.yan committed
101
```pip install spconv-cu111``` for CUDA 11.1
traveller59's avatar
traveller59 committed
102

yan.yan's avatar
yan.yan committed
103
```pip install spconv-cu113``` for CUDA 11.3 (**Linux Only**)
yan.yan's avatar
v2.1  
yan.yan committed
104

yan.yan's avatar
yan.yan committed
105
```pip install spconv-cu114``` for CUDA 11.4
traveller59's avatar
traveller59 committed
106

yan.yan's avatar
v2.1  
yan.yan committed
107
108
**NOTE** It's safe to have different **minor** cuda version between system and conda (pytorch) **in Linux**. for example, you can use spconv-cu114 with anaconda version of pytorch cuda 11.1 in a OS with CUDA 11.2 installed.

yan.yan's avatar
yan.yan committed
109
**NOTE** In Linux, you can install spconv-cuxxx without install CUDA to system! only suitable NVIDIA driver is required. for CUDA 11, we need driver >= 450.82.
yan.yan's avatar
v2.1  
yan.yan committed
110
111
112
113
114
115
116

### Build from source for development (JIT, recommend)

The c++ code will be built automatically when you change c++ code in project.

For NVIDIA Embedded Platforms, you need to specify cuda arch before build: ```export CUMM_CUDA_ARCH_LIST="7.2"``` for xavier.

117
118
You need to remove ```cumm``` in ```requires``` section in pyproject.toml after install editable ```cumm``` and before install spconv due to pyproject limit (can't find editable installed ```cumm```).

yan.yan's avatar
v2.1  
yan.yan committed
119
#### Linux
120

yan.yan's avatar
v2.1  
yan.yan committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
0. uninstall spconv and cumm installed by pip
1. install build-essential, install CUDA
2. ```git clone https://github.com/FindDefinition/cumm```, ```cd ./cumm```, ```pip install -e .```
3. ```git clone https://github.com/traveller59/spconv```, ```cd ./spconv```, ```pip install -e .```
4. in python, ```import spconv``` and wait for build finish.

#### Windows
0. uninstall spconv and cumm installed by pip
1. install visual studio 2019 or newer. make sure C++ development component is installed. install CUDA
2. set [powershell script execution policy](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.1)
3. start a new powershell, run ```tools/msvc_setup.ps1```
4. ```git clone https://github.com/FindDefinition/cumm```, ```cd ./cumm```, ```pip install -e .```
5. ```git clone https://github.com/traveller59/spconv```, ```cd ./spconv```, ```pip install -e .```
6. in python, ```import spconv``` and wait for build finish.
yan.yan's avatar
yan.yan committed
135

yan.yan's avatar
v2.1  
yan.yan committed
136
### Build wheel from source (not recommend, this is done in CI.)
traveller59's avatar
traveller59 committed
137

yan.yan's avatar
yan.yan committed
138
You need to rebuild ```cumm``` first if you are build along a CUDA version that not provided in prebuilts.
traveller59's avatar
traveller59 committed
139

yan.yan's avatar
yan.yan committed
140
#### Linux
traveller59's avatar
traveller59 committed
141

yan.yan's avatar
yan.yan committed
142
143
1. install build-essential, install CUDA
2. run ```export SPCONV_DISABLE_JIT="1"```
yan.yan's avatar
v2.1  
yan.yan committed
144
145
3. run ```pip install pccm cumm wheel```
4. run ```python setup.py bdist_wheel```+```pip install dists/xxx.whl```
traveller59's avatar
traveller59 committed
146

yan.yan's avatar
v2.1  
yan.yan committed
147
#### Windows
traveller59's avatar
traveller59 committed
148

yan.yan's avatar
v2.1  
yan.yan committed
149
1. install visual studio 2019 or newer. make sure C++ development component is installed. install CUDA
yan.yan's avatar
yan.yan committed
150
151
152
2. set [powershell script execution policy](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.1)
3. start a new powershell, run ```tools/msvc_setup.ps1```
4. run ```$Env:SPCONV_DISABLE_JIT = "1"```
yan.yan's avatar
v2.1  
yan.yan committed
153
154
5. run ```pip install pccm cumm wheel```
6. run ```python setup.py bdist_wheel```+```pip install dists/xxx.whl```
traveller59's avatar
traveller59 committed
155

156

yan.yan's avatar
yan.yan committed
157

yan.yan's avatar
yan.yan committed
158
## Note
traveller59's avatar
traveller59 committed
159

yan.yan's avatar
yan.yan committed
160
The work is done when the author is an employee at [Tusimple](https://www.tusimple.com/).
traveller59's avatar
traveller59 committed
161

yan.yan's avatar
yan.yan committed
162
## LICENSE
traveller59's avatar
traveller59 committed
163

FindDefinition's avatar
FindDefinition committed
164
Apache 2.0