MinkowskiEngine 0.5 : 概要 (README) (翻訳/解説)
翻訳 : (株)クラスキャット セールスインフォメーション
作成日時 : 03/20/2021 (0.5.2)

* 本ページは、MinkowskiEngine 0.5 の以下のページを翻訳した上で適宜、補足説明したものです：

• README.md

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

MinkowskiEngine 0.5 : 概要 (README)

Minkowski エンジンはスパース tensor のための自動微分ライブラリです。それはスパース tensor のための畳込み、プーリング、unpooling とブロードキャスティング演算のような総ての標準的なニューラルネットワーク層をサポートします。より多くの情報については、ドキュメント・ページ を訪ねてください。

News

• 2020-12-24 v0.5 is now available! The new version provides CUDA accelerations for all coordinate management functions.

サンプル・ネットワーク

Minkowski エンジンはスパース tensor 上で構築できる様々な関数をサポートします。ここで幾つかのポピュラーなネットワーク・アーキテクチャとアプリケーションをリストします。サンプルを実行するには、パッケージをインストールしてパッケージ・ルートディレクトリのコマンドを実行してください。

サンプル	ネットワークとコマンド
セマンティック セグメンテーション	python -m examples.indoor
分類	python -m examples.classification_modelnet40
再構築	python -m examples.reconstruction
Completion (完成)	python -m examples.completion
検出

スパース Tensor ネットワーク: 空間的にスパースな Tensor のためのニューラルネットワーク

推論をスピードアップしてメモリ使用量を最小化するためにニューラルネットワークを圧縮することは広く研究されてきました。モデル圧縮のためのポピュラーなテクニックの一つは convnet の重みを刈り取る (= prune) ことで、スパース畳込みネットワーク としても知られています。モデル圧縮のために使用されるそのようなパラメータ空間スパース性 (= sparsity) はデンス tensor 上で動作するネットワークを圧縮します、これらのネットワークの総ての中間的な活性はまたデンス tensor です。

けれども、このワークでは、空間的にスパースなデータ にフォーカスします、特に、空間的にスパースな高次元入力です。これらのデータをスパース tensor として表すこともできて、そしてこれらのスパース tensor は 3D 知覚、レジストレーションと統計データのような高次元問題では普通のことです。これらの入力のために特化されたニューラルネットワークを スパース tensor ネットワーク として定義してそしてこれらの スパース tensor ネットワークはスパース tensor を処理して出力として生成します。スパース tensor ネットワークを構築するために、MLP、非-線形性、畳込み、正規化、プーリング演算のような総ての標準的なニューラルネットワーク層をそれらをデンス tensor 上で定義するのと同じ方法で構築して Minkowski エンジンの中で実装しました。

スパース tensor 上のスパース tensor ネットワーク演算、畳込みを下で可視化しました。スパース tensor 上の畳込み層はデンス tensor 上のそれと同様に動作します。けれども、スパース tensor 上では、畳込み出力を (一般化された畳込み で制御できる) 幾つかの指定されたポイント上で計算します。より多くの情報については、スパース tensor ネットワーク上のドキュメントページ と 用語ページ を訪ねてください。

デンス Tensor	スパース Tensor

特徴

• 無制限高次元スパース tensor サポート
• 総ての標準的なニューラルネットワーク層 (畳込み、プーリング、ブロードキャスト等)
• 動的計算グラフ
• カスタム・カーネル shape
• マルチ GPU 訓練
• マルチスレッド・カーネルマップ
• マルチスレッド・コンパイル
• 高度に最適化された GPU カーネル

要件

• Ubuntu >= 14.04
• CUDA >= 11.1 or 11.0 > CUDA >= 10.1.243, No CUDA 11.0
• 1.8 > pytorch >= 1.7 Pytorch 1.8 is unstable
• python >= 3.6
• GCC >= 7

インストール

Minkowski エンジンは pip で、anacoda で、あるいはシステム上で直接的にインストールできます。パッケージをインストールする問題を経験する場合、インストール wiki ページ を確認してください。If you cannot find a relevant problem, please report the issue on the github issue page.

• PIP インストール
• Conda インストール
• Python インストール

Pip

MinkowskiEngine は PyPI MinkowskiEngine を通して配布されています、これは単純に pip でインストールできます。最初に、手順 に従って pytorch をインストールしてください。次に、openblas をインストールします。

sudo apt install build-essential python3-dev libopenblas-dev
pip install torch
pip install -U MinkowskiEngine --install-option="--blas=openblas" -v --no-deps

# For pip installation from the latest source
# pip install -U git+https://github.com/NVIDIA/MinkowskiEngine --no-deps

If you want to specify arguments for the setup script, please refer to the following command.

# Uncomment some options if things don't work
# export CXX=c++; # set this if you want to use a different C++ compiler
# export CUDA_HOME=/usr/local/cuda-11.1; # or select the correct cuda version on your system.
pip install -U git+https://github.com/NVIDIA/MinkowskiEngine -v --no-deps \
#                           \ # uncomment the following line if you want to force cuda installation
#                           --install-option="--force_cuda" \
#                           \ # uncomment the following line if you want to force no cuda installation. force_cuda supercedes cpu_only
#                           --install-option="--cpu_only" \
#                           \ # uncomment the following line to override to openblas, atlas, mkl, blas
#                           --install-option="--blas=openblas" \

クイックスタート

Minkowski エンジンを使用するには、最初にエンジンをインポートする必要があります。それから、ネットワークを定義する必要があるでしょう。貴方が持つデータが量子化されていない場合、(空間) データをスパース tensor にボクセル化 or 量子化する必要があるでしょう。幸い、Minkowski エンジンは量子化関数 (MinkowskiEngine.utils.sparse_quantize) を提供します。

ネットワークを作成する

import torch.nn as nn
import MinkowskiEngine as ME

class ExampleNetwork(ME.MinkowskiNetwork):

    def __init__(self, in_feat, out_feat, D):
        super(ExampleNetwork, self).__init__(D)
        self.conv1 = nn.Sequential(
            ME.MinkowskiConvolution(
                in_channels=in_feat,
                out_channels=64,
                kernel_size=3,
                stride=2,
                dilation=1,
                has_bias=False,
                dimension=D),
            ME.MinkowskiBatchNorm(64),
            ME.MinkowskiReLU())
        self.conv2 = nn.Sequential(
            ME.MinkowskiConvolution(
                in_channels=64,
                out_channels=128,
                kernel_size=3,
                stride=2,
                dimension=D),
            ME.MinkowskiBatchNorm(128),
            ME.MinkowskiReLU())
        self.pooling = ME.MinkowskiGlobalPooling()
        self.linear = ME.MinkowskiLinear(128, out_feat)

    def forward(self, x):
        out = self.conv1(x)
        out = self.conv2(out)
        out = self.pooling(out)
        return self.linear(out)

カスタムネットワークを使用する forward と backward

    # loss and network
    criterion = nn.CrossEntropyLoss()
    net = ExampleNetwork(in_feat=3, out_feat=5, D=2)
    print(net)

    # a data loader must return a tuple of coords, features, and labels.
    coords, feat, label = data_loader()
    input = ME.SparseTensor(feat, coords=coords)
    # Forward
    output = net(input)

    # Loss
    loss = criterion(output.F, label)

以上