pytorch_cluster

Pytorchクラスター

---

このパッケージは、Pytorchで使用するための高度に最適化されたグラフクラスターアルゴリズムの小さな拡張ライブラリで構成されています。パッケージは、次のクラスタリングアルゴリズムで構成されています。

• Dhillon et alのGraclus 。 ：固有ベクトルなしの加重グラフカット：マルチレベルアプローチ（Pami 2007）
• たとえば、SimonovskyおよびKomodakisからのVoxelグリッドプール：グラフ上の畳み込みニューラルネットワークの動的エッジコンディショナルフィルター（CVPR 2017）
• 例： Qi et al。 ：ポイントネット++：メトリック空間内のポイントセットでの深い階層機能学習（NIPS 2017）
• k-nnおよびradiusグラフの生成
• 最も近いポイントに基づくクラスタリング
• Grover and Leskovecなどのランダムウォークサンプリング：Node2Vec：ネットワークのスケーラブルな機能学習（KDD 2016）

含まれるすべての操作は、さまざまなデータ型で動作し、CPUとGPUの両方に実装されています。

インストール

アナコンダ

更新：すべての主要なOS/Pytorch/Cudaの組み合わせについて、Anaconda経由でpytorch-clusterをインストールできるようになりましたか？ pytorch >= 1.8.0インストールされていることを考えると、単に実行する

 conda install pytorch-cluster -c pyg

バイナリ

代わりに、すべての主要なOS/Pytorch/Cudaの組み合わせにピップホイールを提供しています。こちらをご覧ください。

Pytorch 2.5

Pytorch 2.5.0のバイナリをインストールするには、単に実行します

 pip install torch-cluster -f https://data.pyg.org/whl/torch-2.5.0+${CUDA}.html

Pytorchのインストールに応じて、 ${CUDA} cpu 、 cu118 、 cu121 、またはcu124のいずれかに置き換える必要があります。

	cpu	cu118	cu121	cu124
Linux	✅	✅	✅	✅
Windows	✅	✅	✅	✅
macos	✅

Pytorch 2.4

Pytorch 2.4.0のバイナリをインストールするには、単に実行します

 pip install torch-cluster -f https://data.pyg.org/whl/torch-2.4.0+${CUDA}.html

Pytorchのインストールに応じて、 ${CUDA} cpu 、 cu118 、 cu121 、またはcu124のいずれかに置き換える必要があります。

	cpu	cu118	cu121	cu124
Linux	✅	✅	✅	✅
Windows	✅	✅	✅	✅
macos	✅

注：古いバージョンのバイナリは、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、Pytthch 1.10.0にも提供されています。 1.12.0/1.12.1、Pytorch 1.13.0/1.13.1、Pytorch 2.0.0/2.0.1、Pytorch 2.1.0/2.1.1/2.1.2、Pytorch 2.2.0/2.2.1/2.2.2、およびPytorch 2.3.0/2.3.1（同じ手順）。古いバージョンの場合、ソースからの手動インストールを防ぐために、最新のサポートされているバージョン番号を明示的に指定するか、 pip install --no-indexを介してインストールする必要があります。ここで最新のサポートバージョン番号を調べることができます。

ソースから

少なくともPytorch 1.4.0がインストールされていることを確認し、 cuda/binとcuda/includeそれぞれ$PATHと$CPATHにあることを確認してください。

 $ python -c "import torch; print(torch.__version__)"
>>> 1.4.0

$ python -c "import torch; print(torch.__version__)"
>>> 1.1.0

$ echo $PATH
>>> /usr/local/cuda/bin:...

$ echo $CPATH
>>> /usr/local/cuda/include:...

その後、実行：

 pip install torch-cluster

NvidiaドライバーなしでDockerコンテナで走るとき、Pytorchは計算機能を評価する必要があり、故障する可能性があります。この場合、計算機能がTORCH_CUDA_ARCH_LISTを介して設定されていることを確認してください。

 export TORCH_CUDA_ARCH_LIST = "6.0 6.1 7.2+PTX 7.5+PTX"

関数

Graclus

マークされていない頂点を選択し、マークされていないネイバー（エッジ重量を最大化する）と一致する貪欲なクラスタリングアルゴリズム。 GPUアルゴリズムは、Fagginger AuerとBisselingから採用されています：貪欲なグラフマッチングのGPUアルゴリズム（LNCS 2012）

 import torch
from torch_cluster import graclus_cluster

row = torch . tensor ([ 0 , 1 , 1 , 2 ])
col = torch . tensor ([ 1 , 0 , 2 , 1 ])
weight = torch . tensor ([ 1. , 1. , 1. , 1. ])  # Optional edge weights.

cluster = graclus_cluster ( row , col , weight )

 print(cluster)
tensor([0, 0, 1])

Voxelgrid

クラスタリングアルゴリズムは、ポイントクラウド上にユーザー定義のサイズの通常のグリッドをオーバーレイし、ボクセル内のすべてのポイントをクラスターします。

 import torch
from torch_cluster import grid_cluster

pos = torch . tensor ([[ 0. , 0. ], [ 11. , 9. ], [ 2. , 8. ], [ 2. , 2. ], [ 8. , 3. ]])
size = torch . Tensor ([ 5 , 5 ])

cluster = grid_cluster ( pos , size )

 print(cluster)
tensor([0, 5, 3, 0, 1])

最も遠いポイントサンプリング

サンプリングアルゴリズムは、残りの点に関して最も遠い点を繰り返しサンプリングします。

 import torch
from torch_cluster import fps

x = torch . tensor ([[ - 1. , - 1. ], [ - 1. , 1. ], [ 1. , - 1. ], [ 1. , 1. ]])
batch = torch . tensor ([ 0 , 0 , 0 , 0 ])
index = fps ( x , batch , ratio = 0.5 , random_start = False )

 print(index)
tensor([0, 3])

knn-graph

グラフエッジを最も近いKポイントに計算します。

args：

• x （テンソル） ：形状[N, F]のノード機能マトリックス。
• K （int） ：隣人の数。
• Batch （Longtensor、オプション） ：Shape [N]のバッチベクトル、各ノードを特定の例に割り当てます。 batchをソートする必要があります。 （デフォルト： None ）
• ループ（ブール、オプション） ： True場合、グラフには自己ループが含まれます。 （デフォルト： False ）
• flow （string、optional） ：メッセージパッシングと組み合わせて使用する場合のフロー方向（ "source_to_target"または"target_to_source" ）。 （デフォルト： "source_to_target" ）
• COSINE （ブール、オプション） ： Trueの場合、ユークリッド距離の代わりにコサイン距離を使用して最近隣人を見つけます。 （デフォルト： False ）
• num_workers （int） ：計算に使用する労働者の数。 batchがNoneない場合、または入力がGPUにある場合に効果がありません。 （デフォルト： 1 ）

 import torch
from torch_cluster import knn_graph

x = torch . tensor ([[ - 1. , - 1. ], [ - 1. , 1. ], [ 1. , - 1. ], [ 1. , 1. ]])
batch = torch . tensor ([ 0 , 0 , 0 , 0 ])
edge_index = knn_graph ( x , k = 2 , batch = batch , loop = False )

 print(edge_index)
tensor([[1, 2, 0, 3, 0, 3, 1, 2],
        [0, 0, 1, 1, 2, 2, 3, 3]])

半径グラフ

特定の距離内ですべてのポイントにグラフエッジを計算します。

args：

• x （テンソル） ：形状[N, F]のノード機能マトリックス。
• R （フロート） ：半径。
• Batch （Longtensor、オプション） ：Shape [N]のバッチベクトル、各ノードを特定の例に割り当てます。 batchをソートする必要があります。 （デフォルト： None ）
• ループ（ブール、オプション） ： True場合、グラフには自己ループが含まれます。 （デフォルト： False ）
• max_num_neighbors （int、optional） ：各要素に対して戻る隣人の最大数。実際の隣人の数がmax_num_neighborsよりも大きい場合、返された隣人がランダムに選ばれます。 （デフォルト： 32 ）
• flow （string、optional） ：メッセージパッシングと組み合わせて使用する場合のフロー方向（ "source_to_target"または"target_to_source" ）。 （デフォルト： "source_to_target" ）
• num_workers （int） ：計算に使用する労働者の数。 batchがNoneない場合、または入力がGPUにある場合に効果がありません。 （デフォルト： 1 ）

 import torch
from torch_cluster import radius_graph

x = torch . tensor ([[ - 1. , - 1. ], [ - 1. , 1. ], [ 1. , - 1. ], [ 1. , 1. ]])
batch = torch . tensor ([ 0 , 0 , 0 , 0 ])
edge_index = radius_graph ( x , r = 2.5 , batch = batch , loop = False )

 print(edge_index)
tensor([[1, 2, 0, 3, 0, 3, 1, 2],
        [0, 0, 1, 1, 2, 2, 3, 3]])

最も近い

クラスターは、 yの特定のクエリポイントに最も近いxを一緒にポイントします。 batch_{x,y}ベクトルをソートする必要があります。

 import torch
from torch_cluster import nearest

x = torch . Tensor ([[ - 1 , - 1 ], [ - 1 , 1 ], [ 1 , - 1 ], [ 1 , 1 ]])
batch_x = torch . tensor ([ 0 , 0 , 0 , 0 ])
y = torch . Tensor ([[ - 1 , 0 ], [ 1 , 0 ]])
batch_y = torch . tensor ([ 0 , 0 ])
cluster = nearest ( x , y , batch_x , batch_y )

 print(cluster)
tensor([0, 0, 1, 1])

ランダムウォークサンプリング

サンプル(row, col)によって与えられたグラフのstartのすべてのノードインデックスから長さのwalk_lengthのランダムウォーク。

 import torch
from torch_cluster import random_walk

row = torch . tensor ([ 0 , 1 , 1 , 1 , 2 , 2 , 3 , 3 , 4 , 4 ])
col = torch . tensor ([ 1 , 0 , 2 , 3 , 1 , 4 , 1 , 4 , 2 , 3 ])
start = torch . tensor ([ 0 , 1 , 2 , 3 , 4 ])

walk = random_walk ( row , col , start , walk_length = 3 )

 print(walk)
tensor([[0, 1, 2, 4],
        [1, 3, 4, 2],
        [2, 4, 2, 1],
        [3, 4, 2, 4],
        [4, 3, 1, 0]])

実行中のテスト

 pytest

C ++ API

torch-cluster Pythonモデルに相当するC ++を含むC ++ APIも提供します。

 export Torch_DIR=`python -c 'import torch;print(torch.utils.cmake_prefix_path)'`
mkdir build
cd build
# Add -DWITH_CUDA=on support for the CUDA if needed
cmake ..
make
make install