doc updates

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-## [master] - 2020-01-30
+## [master] - 2020-03-05
 
 ### Changed
 
@@ -9,7 +9,9 @@
 - Kernel map generation has tensor stride > 0 check
 - Fix `SparseTensor.set_tensor_stride`
 - Track whether the batch indices are set first when initializing coords, The initial batch indices will be used throughout the lifetime of a sparse tensor
-- Added warning on ModelNet40 training (Issue #86)
+- Add warning on ModelNet40 training (Issue #86)
+- Update the readme, definition
+- Fix an error on examples.convolution
 
 
 ## [0.4.1] - 2020-01-28

README.md

@@ -3,7 +3,7 @@
 
 # Minkowski Engine
 
-[![PyPI Version][pypi-image]][pypi-url]
+[![PyPI Version][pypi-image]][pypi-url][![Join the chat at https://gitter.im/MinkowskiEngineGitter/general](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/MinkowskiEngineGitter/general)
 
 The Minkowski Engine is an auto-differentiation library for sparse tensors. It supports all standard neural network layers such as convolution, pooling, unpooling, and broadcasting operations for sparse tensors. For more information, please visit [the documentation page](http://stanfordvl.github.io/MinkowskiEngine/overview.html).
 
@@ -19,10 +19,13 @@ The Minkowski Engine supports various functions that can be built on a sparse te
 | Completion            | <img src="https://stanfordvl.github.io/MinkowskiEngine/_images/completion_3d_net.png"> <br /> `python -m examples.completion`                                                   |
 
 
-## Building a Neural Network on a Sparse Tensor
+## Sparse Tensor Networks: Neural Networks for Spatially Sparse Tensors
 
-The Minkowski Engine provides APIs that allow users to build a neural network on a sparse tensor. Then, how dow we define convolution/pooling/transposed operations on a sparse tensor?
-Visually, a convolution on a sparse tensor is similar to that on a dense tensor. However, on a sparse tensor, we compute convolution outputs on a few specified points. For more information, please visit [convolution on a sparse tensor](https://stanfordvl.github.io/MinkowskiEngine/convolution_on_sparse.html).
+Compressing a neural network to speedup inference and minimize memory footprint has been studied widely. One of the popular techniques for model compression is pruning the weights in a convnet, is also known as a *sparse convolutional networks* [[Liu et al. CVPR'15]](https://www.cv-foundation.org/openaccess/content_cvpr_2015/papers/Liu_Sparse_Convolutional_Neural_2015_CVPR_paper.pdf). Such parameter-space sparsity used for model compression still operates on dense tensors and all intermediate activations are also dense tensors.
+
+However, in this work, we focus on *spatially* sparse data, in particular, spatially sparse high-dimensional inputs. We can also represent these data as sparse tensors, and are commonplace in high-dimensional problems such as 3D perception, registration, and statistical data. We define neural networks specialized for these inputs *sparse tensor networks*  and these sparse tensor networks processes and generates sparse tensors. To construct a sparse tensor network, we build all standard neural network layers such as MLPs, non-linearities, convolution, normalizations, pooling operations as the same way we define on a dense tensor and implemented in the Minkowski Engine.
+
+We visualized a sparse tensor network operation on a sparse tensor, convolution, below. The convolution layer on a sparse tensor works similarly to that on a dense tensor. However, on a sparse tensor, we compute convolution outputs on a few specified points which we can control in the [generalized convolution](https://stanfordvl.github.io/MinkowskiEngine/sparse_tensor_network.html). For more information, please visit [the documentation page on sparse tensor networks](https://stanfordvl.github.io/MinkowskiEngine/sparse_tensor_network.html) and [the terminology page](https://stanfordvl.github.io/MinkowskiEngine/terminology.html).
 
 | Dense Tensor                                                                    | Sparse Tensor                                                                     |
 |:-------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------:|
@@ -62,15 +65,15 @@ First, install pytorch following the [instruction](https://pytorch.org). Next, i
 
 ```
 sudo apt install libopenblas-dev
-pip3 install torch torchvision
+pip3 install torch
 pip3 install -U MinkowskiEngine
 ```
 
 ### Pip from the latest source
 
 ```
 sudo apt install libopenblas-dev
-pip3 install torch torchvision
+pip3 install torch
 pip3 install -U -I git+https://github.com/StanfordVL/MinkowskiEngine
 ```
 
@@ -221,6 +224,7 @@ If you use the Minkowski Engine, please cite:
 }
 ```
 
+## 
 ## Projects using Minkowski Engine
 
 - [4D Spatio-Temporal Segmentation](https://github.com/chrischoy/SpatioTemporalSegmentation)

docs/index.rst

@@ -11,7 +11,7 @@ Table of Contents
    :caption: Introduction
 
    overview
-   convolution_on_sparse
+   sparse_tensor_network
    quick_start
    terminology
 

docs/overview.md

@@ -3,7 +3,7 @@
 
 # Minkowski Engine
 
-[![PyPI Version][pypi-image]][pypi-url]
+[![PyPI Version][pypi-image]][pypi-url][![Join the chat at https://gitter.im/MinkowskiEngineGitter/general](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/MinkowskiEngineGitter/general)
 
 The Minkowski Engine is an auto-differentiation library for sparse tensors. It supports all standard neural network layers such as convolution, pooling, unpooling, and broadcasting operations for sparse tensors. For more information, please visit [the documentation page](http://stanfordvl.github.io/MinkowskiEngine/overview.html).
 
@@ -19,15 +19,17 @@ The Minkowski Engine supports various functions that can be built on a sparse te
 | Completion            | <img src="https://stanfordvl.github.io/MinkowskiEngine/_images/completion_3d_net.png"> <br /> `python -m examples.completion`                                                   |
 
 
-## Building a Neural Network on a Sparse Tensor
+## Sparse Tensor Networks: Neural Networks for Spatially Sparse Tensors
 
-The Minkowski Engine provides APIs that allow users to build a neural network on a sparse tensor. Then, how dow we define convolution/pooling/transposed operations on a sparse tensor?
-Visually, a convolution on a sparse tensor is similar to that on a dense tensor. However, on a sparse tensor, we compute convolution outputs on a few specified points. For more information, please visit [convolution on a sparse tensor](https://stanfordvl.github.io/MinkowskiEngine/convolution_on_sparse.html)
+Compressing a neural network to speedup inference and minimize memory footprint has been studied widely. One of the popular techniques for model compression is pruning the weights in a convnet, is also known as a *sparse convolutional networks* [[Liu et al. CVPR'15]](https://www.cv-foundation.org/openaccess/content_cvpr_2015/papers/Liu_Sparse_Convolutional_Neural_2015_CVPR_paper.pdf). Such parameter-space sparsity used for model compression still operates on dense tensors and all intermediate activations are also dense tensors.
 
-| Dense Tensor                  | Sparse Tensor                 |
-|:-----------------------------:|:-----------------------------:|
-| ![](./_images/conv_dense.gif) |![](./_images/conv_sparse.gif) |
+However, in this work, we focus on *spatially* sparse data, in particular, spatially sparse high-dimensional inputs. We can also represent these data as sparse tensors, and are commonplace in high-dimensional problems such as 3D perception, registration, and statistical data. We define neural networks specialized for these inputs *sparse tensor networks*  and these sparse tensor networks processes and generates sparse tensors. To construct a sparse tensor network, we build all standard neural network layers such as MLPs, non-linearities, convolution, normalizations, pooling operations as the same way we define on a dense tensor and implemented in the Minkowski Engine.
 
+We visualized a sparse tensor network operation on a sparse tensor, convolution, below. The convolution layer on a sparse tensor works similarly to that on a dense tensor. However, on a sparse tensor, we compute convolution outputs on a few specified points which we can control in the [generalized convolution](https://stanfordvl.github.io/MinkowskiEngine/sparse_tensor_network.html). For more information, please visit [the documentation page on sparse tensor networks](https://stanfordvl.github.io/MinkowskiEngine/sparse_tensor_network.html) and [the terminology page](https://stanfordvl.github.io/MinkowskiEngine/terminology.html).
+
+| Dense Tensor                                                                    | Sparse Tensor                                                                     |
+|:-------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------:|
+| <img src="https://stanfordvl.github.io/MinkowskiEngine/_images/conv_dense.gif"> | <img src="https://stanfordvl.github.io/MinkowskiEngine/_images/conv_sparse.gif" > |
 
 --------------------------------------------------------------------------------
 
@@ -62,16 +64,16 @@ The MinkowskiEngine is distributed via [PyPI MinkowskiEngine][pypi-url] which ca
 First, install pytorch following the [instruction](https://pytorch.org). Next, install `openblas`.
 
 ```
-sudo apt install openblas
-pip3 install torch torchvision
+sudo apt install libopenblas-dev
+pip3 install torch
 pip3 install -U MinkowskiEngine
 ```
 
 ### Pip from the latest source
 
 ```
-sudo apt install openblas
-pip3 install torch torchvision
+sudo apt install libopenblas-dev
+pip3 install torch
 pip3 install -U -I git+https://github.com/StanfordVL/MinkowskiEngine
 ```
 
@@ -87,8 +89,8 @@ First, follow [the anaconda documentation](https://docs.anaconda.com/anaconda/in
 ```
 conda create -n py3-mink python=3.7
 conda activate py3-mink
-conda install numpy openblas
-conda install pytorch torchvision -c pytorch
+conda install numpy mkl-include
+conda install pytorch -c pytorch
 ```
 
 #### 2. Compilation and installation
@@ -107,7 +109,7 @@ Like the anaconda installation, make sure that you install pytorch with the same
 
 ```
 # install system requirements
-sudo apt install python3-dev openblas
+sudo apt install python3-dev libopenblas-dev
 
 # Skip if you already have pip installed on your python3
 curl https://bootstrap.pypa.io/get-pip.py | python3

docs/convolution_on_sparse.rst → docs/sparse_tensor_network.rst

@@ -1,30 +1,37 @@
-Convolution on a Sparse Tensor
-==============================
+Sparse Tensor Networks
+======================
 
 Sparse Tensor
 -------------
 
 In traditional speech, text, or image data, features are extracted densely.
-Thus, the most common representations of these data are vectors, matrices, and
+Thus, the most common representations used for these data are vectors, matrices, and
 tensors. However, for 3-dimensional scans or even higher-dimensional spaces,
-such dense representations are inefficient due to the sparsity. Instead, we can
-only save the non-empty part of the space as its coordinates and the associated
-features. This representation is an N-dimensional extension of a sparse matrix;
-thus it is known as a sparse tensor.
+such dense representations are inefficient as effective information occupy only a small fraction of the space. Instead, we can
+only save information on the non-empty region of the space similar to how we save information on a sparse matrix.
+This representation is an N-dimensional extension of a sparse matrix; thus it is known as a sparse tensor.
 
-In Minkowski Engine, we adopt the same sparse tensor for the basic data
+In Minkowski Engine, we adopt the sparse tensor as the basic data
 representation and the class is provided as
 :attr:`MinkowskiEngine.SparseTensor`. Fore more information on sparse tensors
 please refer to the `terminology page <terminology.html>`_.
 
 
-Generalized Convolution on a Sparse Tensor
-------------------------------------------
+Sparse Tensor Network
+---------------------
+
+Compressing a neural network to speedup inference and minimize memory footprint has been studied widely. One of the popular techniques for model compression is pruning the weights in a convnet, is also known as a *sparse convolutional networks* `[1] <https://www.cv-foundation.org/openaccess/content_cvpr_2015/papers/Liu_Sparse_Convolutional_Neural_2015_CVPR_paper.pdf>`_. Such parameter-space sparsity used for model compression still operates on dense tensors and all intermediate activations are also dense tensors.
+
+However, in this work, we focus on *spatially* sparse data, in particular, spatially sparse high-dimensional inputs. We can also represent these data as sparse tensors, and are commonplace in high-dimensional problems such as 3D perception, registration, and statistical data. We define neural networks specialized for these inputs *sparse tensor networks*  and these sparse tensor networks processes and generates sparse tensors. To construct a sparse tensor network, we build all standard neural network layers such as MLPs, non-linearities, convolution, normalizations, pooling operations as the same way we define on a dense tensor and implemented in the Minkowski Engine.
+
+
+Generalized Convolution
+-----------------------
 
 The convolution is a fundamental operation in many fields. In image perception,
-the 2D convolution has achieved state-of-the-art performance in many tasks and
+convolutions have been the crux of achieving the state-of-the-art performance in many tasks and
 is proven to be the most crucial operation in AI, and computer vision research.
-In this work, we adopt the sparse convolution `[2]
+In this work, we adopt the convolution on a sparse tensor `[2]
 <https://arxiv.org/abs/1711.10275>`_ and propose the generalized convolution on a sparse
 tensor. The generalized convolution incorporates all discrete convolutions as special cases.
 We use the generalized convolution not only on the 3D
@@ -123,6 +130,6 @@ Also, when we use a hyper-cross shaped kernel `[3] <https://arxiv.org/abs/1904.0
 References
 ----------
 
-- `[1] An Investigation of Sparse Tensor Formats for Tensor Libraries, 2015 <http://groups.csail.mit.edu/commit/papers/2016/parker-thesis.pdf>`_
+- `[1] Sparse Convolutional Neural Networks, CVPR'15 <https://www.cv-foundation.org/openaccess/content_cvpr_2015/papers/Liu_Sparse_Convolutional_Neural_2015_CVPR_paper.pdf>`_
 - `[2] 3D Semantic Segmentation with Submanifold Sparse Convolutional Neural Networks, CVPR'18 <https://arxiv.org/abs/1711.10275>`_
 - `[3] 4D Spatio-Temporal ConvNets: Minkowski Convolutional Neural Networks, CVPR'19 <https://arxiv.org/abs/1904.08755>`_