{"id":13610910,"url":"https://github.com/rusty1s/pytorch_cluster","last_synced_at":"2025-05-14T09:08:58.425Z","repository":{"id":38375899,"uuid":"117287184","full_name":"rusty1s/pytorch_cluster","owner":"rusty1s","description":"PyTorch Extension Library of Optimized Graph Cluster Algorithms","archived":false,"fork":false,"pushed_at":"2025-04-20T07:22:22.000Z","size":2731,"stargazers_count":865,"open_issues_count":32,"forks_count":155,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-05T14:45:37.012Z","etag":null,"topics":["cluster-algorithms","geometric-deep-learning","graph-neural-networks","pytorch"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rusty1s.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-12T20:56:06.000Z","updated_at":"2025-04-27T12:37:06.000Z","dependencies_parsed_at":"2023-02-12T21:00:54.494Z","dependency_job_id":"104bb8fb-70e7-401f-b89b-fa44f95dab9d","html_url":"https://github.com/rusty1s/pytorch_cluster","commit_stats":{"total_commits":574,"total_committers":36,"mean_commits":"15.944444444444445","dds":0.09581881533101044,"last_synced_commit":"d16c692840f01294e6b6184c39ef0383547d4d48"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rusty1s%2Fpytorch_cluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rusty1s%2Fpytorch_cluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rusty1s%2Fpytorch_cluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rusty1s%2Fpytorch_cluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rusty1s","download_url":"https://codeload.github.com/rusty1s/pytorch_cluster/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253672760,"owners_count":21945484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cluster-algorithms","geometric-deep-learning","graph-neural-networks","pytorch"],"created_at":"2024-08-01T19:01:49.312Z","updated_at":"2025-05-14T09:08:53.413Z","avatar_url":"https://github.com/rusty1s.png","language":"C++","funding_links":[],"categories":["图数据处理","Pytorch \u0026 related libraries","Pytorch \u0026 related libraries｜Pytorch \u0026 相关库"],"sub_categories":["Other libraries:","Other libraries｜其他库:"],"readme":"[pypi-image]: https://badge.fury.io/py/torch-cluster.svg\n[pypi-url]: https://pypi.python.org/pypi/torch-cluster\n[testing-image]: https://github.com/rusty1s/pytorch_cluster/actions/workflows/testing.yml/badge.svg\n[testing-url]: https://github.com/rusty1s/pytorch_cluster/actions/workflows/testing.yml\n[linting-image]: https://github.com/rusty1s/pytorch_cluster/actions/workflows/linting.yml/badge.svg\n[linting-url]: https://github.com/rusty1s/pytorch_cluster/actions/workflows/linting.yml\n[coverage-image]: https://codecov.io/gh/rusty1s/pytorch_cluster/branch/master/graph/badge.svg\n[coverage-url]: https://codecov.io/github/rusty1s/pytorch_cluster?branch=master\n\n# PyTorch Cluster\n\n[![PyPI Version][pypi-image]][pypi-url]\n[![Testing Status][testing-image]][testing-url]\n[![Linting Status][linting-image]][linting-url]\n[![Code Coverage][coverage-image]][coverage-url]\n\n--------------------------------------------------------------------------------\n\nThis package consists of a small extension library of highly optimized graph cluster algorithms for the use in [PyTorch](http://pytorch.org/).\nThe package consists of the following clustering algorithms:\n\n* **[Graclus](#graclus)** from Dhillon *et al.*: [Weighted Graph Cuts without Eigenvectors: A Multilevel Approach](http://www.cs.utexas.edu/users/inderjit/public_papers/multilevel_pami.pdf) (PAMI 2007)\n* **[Voxel Grid Pooling](#voxelgrid)** from, *e.g.*, Simonovsky and Komodakis: [Dynamic Edge-Conditioned Filters in Convolutional Neural Networks on Graphs](https://arxiv.org/abs/1704.02901) (CVPR 2017)\n* **[Iterative Farthest Point Sampling](#farthestpointsampling)** from, *e.g.* Qi *et al.*: [PointNet++: Deep Hierarchical Feature Learning on Point Sets in a Metric Space](https://arxiv.org/abs/1706.02413) (NIPS 2017)\n* **[k-NN](#knn-graph)** and **[Radius](#radius-graph)** graph generation\n* Clustering based on **[Nearest](#nearest)** points\n* **[Random Walk Sampling](#randomwalk-sampling)** from, *e.g.*, Grover and Leskovec: [node2vec: Scalable Feature Learning for Networks](https://arxiv.org/abs/1607.00653) (KDD 2016)\n\nAll included operations work on varying data types and are implemented both for CPU and GPU.\n\n## Installation\n\n### Binaries\n\nWe provide pip wheels for all major OS/PyTorch/CUDA combinations, see [here](https://data.pyg.org/whl).\n\n#### PyTorch 2.6\n\nTo install the binaries for PyTorch 2.6.0, simply run\n\n```\npip install torch-cluster -f https://data.pyg.org/whl/torch-2.6.0+${CUDA}.html\n```\n\nwhere `${CUDA}` should be replaced by either `cpu`, `cu118`, `cu124`, or `cu126` depending on your PyTorch installation.\n\n|             | `cpu` | `cu118` | `cu124` | `cu126` |\n|-------------|-------|---------|---------|---------|\n| **Linux**   | ✅    | ✅      | ✅      | ✅      |\n| **Windows** | ✅    | ✅      | ✅      | ✅      |\n| **macOS**   | ✅    |         |         |         |\n\n\n#### PyTorch 2.5\n\nTo install the binaries for PyTorch 2.5.0/2.5.1, simply run\n\n```\npip install torch-cluster -f https://data.pyg.org/whl/torch-2.5.0+${CUDA}.html\n```\n\nwhere `${CUDA}` should be replaced by either `cpu`, `cu118`, `cu121`, or `cu124` depending on your PyTorch installation.\n\n|             | `cpu` | `cu118` | `cu121` | `cu124` |\n|-------------|-------|---------|---------|---------|\n| **Linux**   | ✅    | ✅      | ✅      | ✅      |\n| **Windows** | ✅    | ✅      | ✅      | ✅      |\n| **macOS**   | ✅    |         |         |         |\n\n**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, PyTorch 2.3.0/2.3.1, and PyTorch 2.4.0/2.4.1 (following the same procedure).\nFor older versions, you need to explicitly specify the latest supported version number or install via `pip install --no-index` in order to prevent a manual installation from source.\nYou can look up the latest supported version number [here](https://data.pyg.org/whl).\n\n### From source\n\nEnsure that at least PyTorch 1.4.0 is installed and verify that `cuda/bin` and `cuda/include` are in your `$PATH` and `$CPATH` respectively, *e.g.*:\n\n```\n$ python -c \"import torch; print(torch.__version__)\"\n\u003e\u003e\u003e 1.4.0\n\n$ python -c \"import torch; print(torch.__version__)\"\n\u003e\u003e\u003e 1.1.0\n\n$ echo $PATH\n\u003e\u003e\u003e /usr/local/cuda/bin:...\n\n$ echo $CPATH\n\u003e\u003e\u003e /usr/local/cuda/include:...\n```\n\nThen run:\n\n```\npip install torch-cluster\n```\n\nWhen running in a docker container without NVIDIA driver, PyTorch needs to evaluate the compute capabilities and may fail.\nIn this case, ensure that the compute capabilities are set via `TORCH_CUDA_ARCH_LIST`, *e.g.*:\n\n```\nexport TORCH_CUDA_ARCH_LIST = \"6.0 6.1 7.2+PTX 7.5+PTX\"\n```\n\n## Functions\n\n### Graclus\n\nA greedy clustering algorithm of picking an unmarked vertex and matching it with one its unmarked neighbors (that maximizes its edge weight).\nThe GPU algorithm is adapted from Fagginger Auer and Bisseling: [A GPU Algorithm for Greedy Graph Matching](http://www.staff.science.uu.nl/~bisse101/Articles/match12.pdf) (LNCS 2012)\n\n```python\nimport torch\nfrom torch_cluster import graclus_cluster\n\nrow = torch.tensor([0, 1, 1, 2])\ncol = torch.tensor([1, 0, 2, 1])\nweight = torch.tensor([1., 1., 1., 1.])  # Optional edge weights.\n\ncluster = graclus_cluster(row, col, weight)\n```\n\n```\nprint(cluster)\ntensor([0, 0, 1])\n```\n\n### VoxelGrid\n\nA clustering algorithm, which overlays a regular grid of user-defined size over a point cloud and clusters all points within a voxel.\n\n```python\nimport torch\nfrom torch_cluster import grid_cluster\n\npos = torch.tensor([[0., 0.], [11., 9.], [2., 8.], [2., 2.], [8., 3.]])\nsize = torch.Tensor([5, 5])\n\ncluster = grid_cluster(pos, size)\n```\n\n```\nprint(cluster)\ntensor([0, 5, 3, 0, 1])\n```\n\n### FarthestPointSampling\n\nA sampling algorithm, which iteratively samples the most distant point with regard to the rest points.\n\n```python\nimport torch\nfrom torch_cluster import fps\n\nx = torch.tensor([[-1., -1.], [-1., 1.], [1., -1.], [1., 1.]])\nbatch = torch.tensor([0, 0, 0, 0])\nindex = fps(x, batch, ratio=0.5, random_start=False)\n```\n\n```\nprint(index)\ntensor([0, 3])\n```\n\n### kNN-Graph\n\nComputes graph edges to the nearest *k* points.\n\n**Args:**\n\n* **x** *(Tensor)*: Node feature matrix of shape `[N, F]`.\n* **k** *(int)*: The number of neighbors.\n* **batch** *(LongTensor, optional)*: Batch vector of shape `[N]`, which assigns each node to a specific example. `batch` needs to be sorted. (default: `None`)\n* **loop** *(bool, optional)*: If `True`, the graph will contain self-loops. (default: `False`)\n* **flow** *(string, optional)*: The flow direction when using in combination with message passing (`\"source_to_target\"` or `\"target_to_source\"`). (default: `\"source_to_target\"`)\n* **cosine** *(boolean, optional)*: If `True`, will use the Cosine distance instead of Euclidean distance to find nearest neighbors. (default: `False`)\n* **num_workers** *(int)*: Number of workers to use for computation. Has no effect in case `batch` is not `None`, or the input lies on the GPU. (default: `1`)\n\n```python\nimport torch\nfrom torch_cluster import knn_graph\n\nx = torch.tensor([[-1., -1.], [-1., 1.], [1., -1.], [1., 1.]])\nbatch = torch.tensor([0, 0, 0, 0])\nedge_index = knn_graph(x, k=2, batch=batch, loop=False)\n```\n\n```\nprint(edge_index)\ntensor([[1, 2, 0, 3, 0, 3, 1, 2],\n        [0, 0, 1, 1, 2, 2, 3, 3]])\n```\n\n### Radius-Graph\n\nComputes graph edges to all points within a given distance.\n\n**Args:**\n\n* **x** *(Tensor)*: Node feature matrix of shape `[N, F]`.\n* **r** *(float)*: The radius.\n* **batch** *(LongTensor, optional)*: Batch vector of shape `[N]`, which assigns each node to a specific example. `batch` needs to be sorted. (default: `None`)\n* **loop** *(bool, optional)*: If `True`, the graph will contain self-loops. (default: `False`)\n* **max_num_neighbors** *(int, optional)*: The maximum number of neighbors to return for each element. If the number of actual neighbors is greater than `max_num_neighbors`, returned neighbors are picked randomly. (default: `32`)\n* **flow** *(string, optional)*: The flow direction when using in combination with message passing (`\"source_to_target\"` or `\"target_to_source\"`). (default: `\"source_to_target\"`)\n* **num_workers** *(int)*: Number of workers to use for computation. Has no effect in case `batch` is not `None`, or the input lies on the GPU. (default: `1`)\n\n```python\nimport torch\nfrom torch_cluster import radius_graph\n\nx = torch.tensor([[-1., -1.], [-1., 1.], [1., -1.], [1., 1.]])\nbatch = torch.tensor([0, 0, 0, 0])\nedge_index = radius_graph(x, r=2.5, batch=batch, loop=False)\n```\n\n```\nprint(edge_index)\ntensor([[1, 2, 0, 3, 0, 3, 1, 2],\n        [0, 0, 1, 1, 2, 2, 3, 3]])\n```\n\n### Nearest\n\nClusters points in *x* together which are nearest to a given query point in *y*.\n`batch_{x,y}` vectors need to be sorted.\n\n```python\nimport torch\nfrom torch_cluster import nearest\n\nx = torch.Tensor([[-1, -1], [-1, 1], [1, -1], [1, 1]])\nbatch_x = torch.tensor([0, 0, 0, 0])\ny = torch.Tensor([[-1, 0], [1, 0]])\nbatch_y = torch.tensor([0, 0])\ncluster = nearest(x, y, batch_x, batch_y)\n```\n\n```\nprint(cluster)\ntensor([0, 0, 1, 1])\n```\n\n### RandomWalk-Sampling\n\nSamples random walks of length `walk_length` from all node indices in `start` in the graph given by `(row, col)`.\n\n```python\nimport torch\nfrom torch_cluster import random_walk\n\nrow = torch.tensor([0, 1, 1, 1, 2, 2, 3, 3, 4, 4])\ncol = torch.tensor([1, 0, 2, 3, 1, 4, 1, 4, 2, 3])\nstart = torch.tensor([0, 1, 2, 3, 4])\n\nwalk = random_walk(row, col, start, walk_length=3)\n```\n\n```\nprint(walk)\ntensor([[0, 1, 2, 4],\n        [1, 3, 4, 2],\n        [2, 4, 2, 1],\n        [3, 4, 2, 4],\n        [4, 3, 1, 0]])\n```\n\n## Running tests\n\n```\npytest\n```\n\n## C++ API\n\n`torch-cluster` also offers a C++ API that contains C++ equivalent of python models.\n\n```\nexport Torch_DIR=`python -c 'import torch;print(torch.utils.cmake_prefix_path)'`\nmkdir build\ncd build\n# Add -DWITH_CUDA=on support for the CUDA if needed\ncmake ..\nmake\nmake install\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frusty1s%2Fpytorch_cluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frusty1s%2Fpytorch_cluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frusty1s%2Fpytorch_cluster/lists"}