pytorch_cluster

Cluster pytorch

---

Este pacote consiste em uma pequena biblioteca de extensão de algoritmos de cluster de gráficos altamente otimizados para o uso em Pytorch. O pacote consiste nos seguintes algoritmos de agrupamento:

• Graclus de Dhillon et al. : Cortes de gráficos pesados sem autovetores: uma abordagem multinível (Pami 2007)
• Voxel Grid Pooling de, por exemplo , Simonovsky e Komodakis: filtros dinâmicos condicionados à borda em redes neurais convolucionais em gráficos (CVPR 2017)
• Amostragem iterativa de ponto mais distante de, por exemplo , Qi et al. : PointNet ++: Aprendizagem de recursos hierárquicos profundos em conjuntos de pontos em um espaço métrico (NIPS 2017)
• Geração de gráficos K-NN e Radius
• Agrupamento com base nos pontos mais próximos
• Amostragem aleatória de caminhada de, por exemplo , Grover e Leskovec: Node2vec: aprendizado de recursos escaláveis para redes (KDD 2016)

Todas as operações incluídas funcionam em diferentes tipos de dados e são implementadas para CPU e GPU.

Instalação

Anaconda

ATUALIZAÇÃO: Agora você pode instalar pytorch-cluster via Anaconda para todas as principais combinações de OS/Pytorch/Cuda? Dado que você tem pytorch >= 1.8.0 instalado, basta executar

 conda install pytorch-cluster -c pyg

Binários

Alternativamente, fornecemos rodas PIP para todas as principais combinações de OS/Pytorch/Cuda, veja aqui.

Pytorch 2.5

Para instalar os binários para Pytorch 2.5.0, basta executar

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

onde ${CUDA} deve ser substituído por cpu , cu118 , cu121 ou cu124 dependendo da instalação do Pytorch.

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

Pytorch 2.4

Para instalar os binários para Pytorch 2.4.0, basta executar

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

onde ${CUDA} deve ser substituído por cpu , cu118 , cu121 ou cu124 dependendo da instalação do Pytorch.

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

Note: Binaries of older versions are also provided for 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, PyTorch 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 e pytorch 2.3.0/2.3.1 (seguindo o mesmo procedimento). Para versões mais antigas, você precisa especificar explicitamente o número mais recente da versão suportada ou instalação via pip install --no-index para impedir que uma instalação manual da fonte. Você pode procurar o número mais recente da versão suportada aqui.

Da fonte

Certifique -se de que pelo menos o Pytorch 1.4.0 esteja instalado e verifique se cuda/bin e cuda/include estão no seu $PATH e $CPATH , respectivamente, por exemplo :

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

Em seguida, corra:

 pip install torch-cluster

Ao executar em um contêiner do Docker sem motorista da NVIDIA, o Pytorch precisa avaliar os recursos de computação e pode falhar. Nesse caso, verifique se os recursos de computação são definidos via TORCH_CUDA_ARCH_LIST , por exemplo :

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

Funções

Graclus

Um algoritmo ganancioso de agrupamento de escolher um vértice não marcado e combiná -lo com um dos vizinhos não marcados (que maximiza seu peso de borda). O algoritmo GPU é adaptado de Fagginger Auer e Bisseling: um algoritmo GPU para correspondência de gráficos gananciosos (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

Um algoritmo de cluster, que se sobrepõe a uma grade regular de tamanho definido pelo usuário sobre uma nuvem de pontos e agrupa todos os pontos dentro de um 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])

FarThestPointSampling

Um algoritmo de amostragem, que amostra iterativamente o ponto mais distante em relação aos pontos restantes.

 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

Calcula as bordas do gráfico para os K pontos mais próximos.

Args:

• x (tensor) : Matriz do recurso de nó da forma [N, F] .
• K (int) : o número de vizinhos.
• Lote (Longtensor, Opcional) : Vector em lote da forma [N] , que atribui cada nó a um exemplo específico. batch precisa ser classificado. (Padrão: None )
• Loop (bool, opcional) : se True , o gráfico conterá loops auto. (Padrão: False )
• Flow (String, Opcional) : A direção do fluxo ao usar em combinação com a passagem da mensagem ( "source_to_target" ou "target_to_source" ). (padrão: "source_to_target" )
• Cosseno (booleano, opcional) : se True , usará a distância cosseno em vez da distância euclidiana para encontrar vizinhos mais próximos. (Padrão: False )
• Num_Workers (int) : Número de trabalhadores a serem usados para computação. Não tem efeito no caso de que batch não seja None , ou a entrada está na GPU. (Padrão: 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]])

Raio-graf

Calcula as bordas do gráfico para todos os pontos a uma determinada distância.

Args:

• x (tensor) : Matriz do recurso de nó da forma [N, F] .
• r (flutuação) : o raio.
• Lote (Longtensor, Opcional) : Vector em lote da forma [N] , que atribui cada nó a um exemplo específico. batch precisa ser classificado. (Padrão: None )
• Loop (bool, opcional) : se True , o gráfico conterá loops auto. (Padrão: False )
• max_num_neighbors (int, opcional) : o número máximo de vizinhos retornará para cada elemento. Se o número de vizinhos reais for maior que max_num_neighbors , os vizinhos retornados serão escolhidos aleatoriamente. (Padrão: 32 )
• Flow (String, Opcional) : A direção do fluxo ao usar em combinação com a passagem da mensagem ( "source_to_target" ou "target_to_source" ). (padrão: "source_to_target" )
• Num_Workers (int) : Número de trabalhadores a serem usados para computação. Não tem efeito no caso de que batch não seja None , ou a entrada está na GPU. (Padrão: 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]])

Mais próximo

Clusters apontam em X juntos, mais próximos de um determinado ponto de consulta em y . batch_{x,y} vetores precisam ser classificados.

 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 Sampling

Amostras Palinhas aleatórias de comprimento walk_length de todos os índices de nós no start do gráfico fornecido por (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]])

Testes de execução

 pytest

API C ++

torch-cluster também oferece uma API C ++ que contém C ++ equivalente aos modelos 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