pytorch_cluster

Cluster de pytorch

---

Ce package se compose d'une petite bibliothèque d'extension d'algorithmes de cluster de graphes hautement optimisés pour l'utilisation dans Pytorch. Le package se compose des algorithmes de clustering suivants:

• Graclus de Dhillon et al. : Coupes de graphiques pondérés sans vecteurs propres: une approche à plusieurs niveaux (Pami 2007)
• Voxel Grid Envocant de, par exemple , Simonovsky et Komodakis: Filtres dynamiques conditionnés par le bord dans les réseaux de neurones convolutionnels sur les graphiques (CVPR 2017)
• Échantillonnage itératif le plus éloigné de, par exemple Qi et al. : PointNet ++: Apprentissage des fonctionnalités hiérarchiques profondes sur les ensembles de points dans un espace métrique (NIPS 2017)
• Génération de graphiques K-NN et Radius
• Clustering basé sur les points les plus proches
• Échantillonnage de marche aléatoire de, par exemple , Grover et Leskovec: Node2Vec: Apprentissage des fonctionnalités évolutives pour les réseaux (KDD 2016)

Toutes les opérations incluses fonctionnent sur différents types de données et sont implémentées à la fois pour CPU et GPU.

Installation

Anaconda

MISE À JOUR: Vous pouvez maintenant installer pytorch-cluster via Anaconda pour toutes les principales combinaisons OS / Pytorch / Cuda? Étant donné que vous avez installé pytorch >= 1.8.0 , exécutez simplement

 conda install pytorch-cluster -c pyg

Binaires

Nous fournissons également des roues PIP pour toutes les principales combinaisons OS / Pytorch / Cuda, voir ici.

Pytorch 2.5

Pour installer les binaires pour Pytorch 2.5.0, exécutez simplement

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

où ${CUDA} doit être remplacé par cpu , cu118 , cu121 ou cu124 en fonction de votre installation Pytorch.

	cpu	cu118	cu121	cu124
Linux	✅	✅	✅	✅
Fenêtre	✅	✅	✅	✅
macos	✅

Pytorch 2.4

Pour installer les binaires pour Pytorch 2.4.0, exécutez simplement

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

où ${CUDA} doit être remplacé par cpu , cu118 , cu121 ou cu124 en fonction de votre installation Pytorch.

	cpu	cu118	cu121	cu124
Linux	✅	✅	✅	✅
Fenêtre	✅	✅	✅	✅
macos	✅

Remarque: Des binaires des versions plus anciennes sont également fournies pour 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, pytorch 1.11.0, pyTTOR 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, et Pytorch 2.3.0 / 2.3.1 (suivant la même procédure). Pour les anciennes versions, vous devez spécifier explicitement le dernier numéro de version pris en charge ou installer via pip install --no-index afin d'empêcher une installation manuelle de Source. Vous pouvez rechercher le dernier numéro de version pris en charge ici.

De la source

Assurez-vous qu'au moins Pytorch 1.4.0 est installé et vérifiez que cuda/bin et cuda/include sont respectivement dans votre $PATH et $CPATH , par exemple :

 $ 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:...

Puis courez:

 pip install torch-cluster

Lors de l'exécution dans un conteneur Docker sans pilote nvidia, Pytorch doit évaluer les capacités de calcul et peut échouer. Dans ce cas, assurez-vous que les capacités de calcul sont définies via TORCH_CUDA_ARCH_LIST , par exemple :

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

Fonctions

Graclus

Un algorithme de clustering gourmand de choisir un sommet non marqué et de le faire correspondre à l'un de ses voisins non marqués (qui maximise son poids de bord). L'algorithme GPU est adapté de Fagginger Auer et Bisseling: un algorithme GPU pour la correspondance de graphiques gourmands (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

Un algorithme de clustering, qui superpose une grille régulière de taille définie par l'utilisateur sur un nuage de points et clusters tous les points dans un voxel.

 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])

Échantillonnage le plus éloigné

Un algorithme d'échantillonnage, qui échantillonne de manière itérative le point le plus éloigné en ce qui concerne les points de repos.

 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

Calcule les bords du graphique aux points K les plus proches.

Args:

• x (tenseur) : matrice de caractéristiques de nœud de forme [N, F] .
• K (int) : le nombre de voisins.
• Batch (longtensor, facultatif) : vecteur de lot de forme [N] , qui attribue chaque nœud à un exemple spécifique. batch doit être trié. (par défaut: None )
• LOOP (BOOL, FACTIONNELLE) : Si True , le graphique contiendra des boucles d'auto-boucles. (par défaut: False )
• Flow (String, Facultatif) : La direction de flux lors de l'utilisation en combinaison avec le message passant ( "source_to_target" ou "target_to_source" ). (par défaut: "source_to_target" )
• Cosin (booléen, facultatif) : si True , utilisera la distance du cosinus au lieu de la distance euclidienne pour trouver des voisins les plus proches. (par défaut: False )
• num_workers (int) : nombre de travailleurs à utiliser pour le calcul. N'a aucun effet dans le cas où batch n'est pas None , ou l'entrée se trouve sur le GPU. (par défaut: 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]])

Rayon-graphique

Calcule les bords du graphique à tous les points à une distance donnée.

Args:

• x (tenseur) : matrice de caractéristiques de nœud de forme [N, F] .
• r (float) : le rayon.
• Batch (longtensor, facultatif) : vecteur de lot de forme [N] , qui attribue chaque nœud à un exemple spécifique. batch doit être trié. (par défaut: None )
• LOOP (BOOL, FACTIONNELLE) : Si True , le graphique contiendra des boucles d'auto-boucles. (par défaut: False )
• MAX_NUM_NEIGHBORS (int, facultatif) : le nombre maximum de voisins à retourner pour chaque élément. Si le nombre de voisins réels est supérieur à max_num_neighbors , les voisins retournés sont choisis au hasard. (par défaut: 32 )
• Flow (String, Facultatif) : La direction de flux lors de l'utilisation en combinaison avec le message passant ( "source_to_target" ou "target_to_source" ). (par défaut: "source_to_target" )
• num_workers (int) : nombre de travailleurs à utiliser pour le calcul. N'a aucun effet dans le cas où batch n'est pas None , ou l'entrée se trouve sur le GPU. (par défaut: 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]])

Le plus proche

Les clusters pointent en x ensemble qui sont les plus proches d'un point de requête donné en y . batch_{x,y} Les vecteurs doivent être triés.

 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])

Randomwalk-échantillonnage

Échantillons Salks aléatoires de longueur walk_length de tous les indices de nœud dans start dans le graphique donné par (row, col) .

 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]])

Tests en cours d'exécution

 pytest

API C ++

torch-cluster propose également une API C ++ qui contient l'équivalent C ++ des modèles Python.

 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