[pypi-image]: https://badge.fury.io/py/torch-scatter.svg
[pypi-url]: https://pypi.python.org/pypi/torch-scatter
[testing-image]: https://github.com/rusty1s/pytorch_scatter/actions/workflows/testing.yml/badge.svg
[testing-url]: https://github.com/rusty1s/pytorch_scatter/actions/workflows/testing.yml
[linting-image]: https://github.com/rusty1s/pytorch_scatter/actions/workflows/linting.yml/badge.svg
[linting-url]: https://github.com/rusty1s/pytorch_scatter/actions/workflows/linting.yml
[docs-image]: https://readthedocs.org/projects/pytorch-scatter/badge/?version=latest
[docs-url]: https://pytorch-scatter.readthedocs.io/en/latest/?badge=latest
[coverage-image]: https://codecov.io/gh/rusty1s/pytorch_scatter/branch/master/graph/badge.svg
[coverage-url]: https://codecov.io/github/rusty1s/pytorch_scatter?branch=master
# PyTorch Scatter
[![PyPI Version][pypi-image]][pypi-url]
[![Testing Status][testing-image]][testing-url]
[![Linting Status][linting-image]][linting-url]
[![Docs Status][docs-image]][docs-url]
[![Code Coverage][coverage-image]][coverage-url]
<p align="center">
<img width="50%" src="https://raw.githubusercontent.com/rusty1s/pytorch_scatter/master/docs/source/_figures/add.svg?sanitize=true" />
</p>
--------------------------------------------------------------------------------
**[Documentation](https://pytorch-scatter.readthedocs.io)**
This package consists of a small extension library of highly optimized sparse update (scatter and segment) operations for the use in [PyTorch](http://pytorch.org/), which are missing in the main package.
Scatter and segment operations can be roughly described as reduce operations based on a given "group-index" tensor.
Segment operations require the "group-index" tensor to be sorted, whereas scatter operations are not subject to these requirements.
The package consists of the following operations with reduction types `"sum"|"mean"|"min"|"max"`:
* [**scatter**](https://pytorch-scatter.readthedocs.io/en/latest/functions/scatter.html) based on arbitrary indices
* [**segment_coo**](https://pytorch-scatter.readthedocs.io/en/latest/functions/segment_coo.html) based on sorted indices
* [**segment_csr**](https://pytorch-scatter.readthedocs.io/en/latest/functions/segment_csr.html) based on compressed indices via pointers
In addition, we provide the following **composite functions** which make use of `scatter_*` operations under the hood: `scatter_std`, `scatter_logsumexp`, `scatter_softmax` and `scatter_log_softmax`.
All included operations are broadcastable, work on varying data types, are implemented both for CPU and GPU with corresponding backward implementations, and are fully traceable.
## Installation
### Anaconda
**Update:** You can now install `pytorch-scatter` via [Anaconda](https://anaconda.org/pyg/pytorch-scatter) for all major OS/PyTorch/CUDA combinations 🤗
Given that you have [`pytorch >= 1.8.0` installed](https://pytorch.org/get-started/locally/), simply run
```
conda install pytorch-scatter -c pyg
```
### Binaries
We alternatively provide pip wheels for all major OS/PyTorch/CUDA combinations, see [here](https://data.pyg.org/whl).
#### PyTorch 2.1
To install the binaries for PyTorch 2.1.0, simply run
```
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.1.0+${CUDA}.html
```
where `${CUDA}` should be replaced by either `cpu`, `cu118`, or `cu121` depending on your PyTorch installation.
| | `cpu` | `cu118` | `cu121` |
|-------------|-------|---------|---------|
| **Linux** | ✅ | ✅ | ✅ |
| **Windows** | ✅ | ✅ | ✅ |
| **macOS** | ✅ | | |
#### PyTorch 2.0
To install the binaries for PyTorch 2.0.0, simply run
```
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.0.0+${CUDA}.html
```
where `${CUDA}` should be replaced by either `cpu`, `cu117`, or `cu118` depending on your PyTorch installation.
| | `cpu` | `cu117` | `cu118` |
|-------------|-------|---------|---------|
| **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 and PyTorch 1.13.0/1.13.1 (following the same procedure).
For 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.
You can look up the latest supported version number [here](https://data.pyg.org/whl).
### From source
Ensure 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.*:
```
$ python -c "import torch; print(torch.__version__)"
>>> 1.4.0
$ echo $PATH
>>> /usr/local/cuda/bin:...
$ echo $CPATH
>>> /usr/local/cuda/include:...
```
Then run:
```
pip install torch-scatter
```
When running in a docker container without NVIDIA driver, PyTorch needs to evaluate the compute capabilities and may fail.
In this case, ensure that the compute capabilities are set via `TORCH_CUDA_ARCH_LIST`, *e.g.*:
```
export TORCH_CUDA_ARCH_LIST = "6.0 6.1 7.2+PTX 7.5+PTX"
```
## Example
```py
import torch
from torch_scatter import scatter_max
src = torch.tensor([[2, 0, 1, 4, 3], [0, 2, 1, 3, 4]])
index = torch.tensor([[4, 5, 4, 2, 3], [0, 0, 2, 2, 1]])
out, argmax = scatter_max(src, index, dim=-1)
```
```
print(out)
tensor([[0, 0, 4, 3, 2, 0],
[2, 4, 3, 0, 0, 0]])
print(argmax)
tensor([[5, 5, 3, 4, 0, 1]
[1, 4, 3, 5, 5, 5]])
```
## Running tests
```
pytest
```
## C++ API
`torch-scatter` also offers a C++ API that contains C++ equivalent of python models.
For this, we need to add `TorchLib` to the `-DCMAKE_PREFIX_PATH` (*e.g.*, it may exists in `{CONDA}/lib/python{X.X}/site-packages/torch` if installed via `conda`):
```
mkdir build
cd build
# Add -DWITH_CUDA=on support for CUDA support
cmake -DCMAKE_PREFIX_PATH="..." ..
make
make install
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rusty1s/pytorch_scatter",
"name": "torch-scatter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "pytorch,scatter,segment,gather",
"author": "Matthias Fey",
"author_email": "matthias.fey@tu-dortmund.de",
"download_url": "https://files.pythonhosted.org/packages/f5/ab/2a44ecac0f891dd0d765fc59ac8d277c6283a31907626560e72685df2ed6/torch_scatter-2.1.2.tar.gz",
"platform": null,
"description": "[pypi-image]: https://badge.fury.io/py/torch-scatter.svg\n[pypi-url]: https://pypi.python.org/pypi/torch-scatter\n[testing-image]: https://github.com/rusty1s/pytorch_scatter/actions/workflows/testing.yml/badge.svg\n[testing-url]: https://github.com/rusty1s/pytorch_scatter/actions/workflows/testing.yml\n[linting-image]: https://github.com/rusty1s/pytorch_scatter/actions/workflows/linting.yml/badge.svg\n[linting-url]: https://github.com/rusty1s/pytorch_scatter/actions/workflows/linting.yml\n[docs-image]: https://readthedocs.org/projects/pytorch-scatter/badge/?version=latest\n[docs-url]: https://pytorch-scatter.readthedocs.io/en/latest/?badge=latest\n[coverage-image]: https://codecov.io/gh/rusty1s/pytorch_scatter/branch/master/graph/badge.svg\n[coverage-url]: https://codecov.io/github/rusty1s/pytorch_scatter?branch=master\n\n# PyTorch Scatter\n\n[![PyPI Version][pypi-image]][pypi-url]\n[![Testing Status][testing-image]][testing-url]\n[![Linting Status][linting-image]][linting-url]\n[![Docs Status][docs-image]][docs-url]\n[![Code Coverage][coverage-image]][coverage-url]\n\n<p align=\"center\">\n <img width=\"50%\" src=\"https://raw.githubusercontent.com/rusty1s/pytorch_scatter/master/docs/source/_figures/add.svg?sanitize=true\" />\n</p>\n\n--------------------------------------------------------------------------------\n\n**[Documentation](https://pytorch-scatter.readthedocs.io)**\n\nThis package consists of a small extension library of highly optimized sparse update (scatter and segment) operations for the use in [PyTorch](http://pytorch.org/), which are missing in the main package.\nScatter and segment operations can be roughly described as reduce operations based on a given \"group-index\" tensor.\nSegment operations require the \"group-index\" tensor to be sorted, whereas scatter operations are not subject to these requirements.\n\nThe package consists of the following operations with reduction types `\"sum\"|\"mean\"|\"min\"|\"max\"`:\n\n* [**scatter**](https://pytorch-scatter.readthedocs.io/en/latest/functions/scatter.html) based on arbitrary indices\n* [**segment_coo**](https://pytorch-scatter.readthedocs.io/en/latest/functions/segment_coo.html) based on sorted indices\n* [**segment_csr**](https://pytorch-scatter.readthedocs.io/en/latest/functions/segment_csr.html) based on compressed indices via pointers\n\nIn addition, we provide the following **composite functions** which make use of `scatter_*` operations under the hood: `scatter_std`, `scatter_logsumexp`, `scatter_softmax` and `scatter_log_softmax`.\n\nAll included operations are broadcastable, work on varying data types, are implemented both for CPU and GPU with corresponding backward implementations, and are fully traceable.\n\n## Installation\n\n### Anaconda\n\n**Update:** You can now install `pytorch-scatter` via [Anaconda](https://anaconda.org/pyg/pytorch-scatter) for all major OS/PyTorch/CUDA combinations \ud83e\udd17\nGiven that you have [`pytorch >= 1.8.0` installed](https://pytorch.org/get-started/locally/), simply run\n\n```\nconda install pytorch-scatter -c pyg\n```\n\n### Binaries\n\nWe alternatively provide pip wheels for all major OS/PyTorch/CUDA combinations, see [here](https://data.pyg.org/whl).\n\n#### PyTorch 2.1\n\nTo install the binaries for PyTorch 2.1.0, simply run\n\n```\npip install torch-scatter -f https://data.pyg.org/whl/torch-2.1.0+${CUDA}.html\n```\n\nwhere `${CUDA}` should be replaced by either `cpu`, `cu118`, or `cu121` depending on your PyTorch installation.\n\n| | `cpu` | `cu118` | `cu121` |\n|-------------|-------|---------|---------|\n| **Linux** | \u2705 | \u2705 | \u2705 |\n| **Windows** | \u2705 | \u2705 | \u2705 |\n| **macOS** | \u2705 | | |\n\n\n#### PyTorch 2.0\n\nTo install the binaries for PyTorch 2.0.0, simply run\n\n```\npip install torch-scatter -f https://data.pyg.org/whl/torch-2.0.0+${CUDA}.html\n```\n\nwhere `${CUDA}` should be replaced by either `cpu`, `cu117`, or `cu118` depending on your PyTorch installation.\n\n| | `cpu` | `cu117` | `cu118` |\n|-------------|-------|---------|---------|\n| **Linux** | \u2705 | \u2705 | \u2705 |\n| **Windows** | \u2705 | \u2705 | \u2705 |\n| **macOS** | \u2705 | | |\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 and PyTorch 1.13.0/1.13.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>>> 1.4.0\n\n$ echo $PATH\n>>> /usr/local/cuda/bin:...\n\n$ echo $CPATH\n>>> /usr/local/cuda/include:...\n```\n\nThen run:\n\n```\npip install torch-scatter\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## Example\n\n```py\nimport torch\nfrom torch_scatter import scatter_max\n\nsrc = torch.tensor([[2, 0, 1, 4, 3], [0, 2, 1, 3, 4]])\nindex = torch.tensor([[4, 5, 4, 2, 3], [0, 0, 2, 2, 1]])\n\nout, argmax = scatter_max(src, index, dim=-1)\n```\n\n```\nprint(out)\ntensor([[0, 0, 4, 3, 2, 0],\n [2, 4, 3, 0, 0, 0]])\n\nprint(argmax)\ntensor([[5, 5, 3, 4, 0, 1]\n [1, 4, 3, 5, 5, 5]])\n```\n\n## Running tests\n\n```\npytest\n```\n\n## C++ API\n\n`torch-scatter` also offers a C++ API that contains C++ equivalent of python models.\nFor this, we need to add `TorchLib` to the `-DCMAKE_PREFIX_PATH` (*e.g.*, it may exists in `{CONDA}/lib/python{X.X}/site-packages/torch` if installed via `conda`):\n\n```\nmkdir build\ncd build\n# Add -DWITH_CUDA=on support for CUDA support\ncmake -DCMAKE_PREFIX_PATH=\"...\" ..\nmake\nmake install\n```\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "PyTorch Extension Library of Optimized Scatter Operations",
"version": "2.1.2",
"project_urls": {
"Download": "https://github.com/rusty1s/pytorch_scatter/archive/2.1.2.tar.gz",
"Homepage": "https://github.com/rusty1s/pytorch_scatter"
},
"split_keywords": [
"pytorch",
"scatter",
"segment",
"gather"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f5ab2a44ecac0f891dd0d765fc59ac8d277c6283a31907626560e72685df2ed6",
"md5": "3af5b5accee424170070d9e20d3c4901",
"sha256": "69b3aa435f2424ac6a1bfb6ff702da6eb73b33ca0db38fb26989c74159258e47"
},
"downloads": -1,
"filename": "torch_scatter-2.1.2.tar.gz",
"has_sig": false,
"md5_digest": "3af5b5accee424170070d9e20d3c4901",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 108045,
"upload_time": "2023-10-06T08:49:07",
"upload_time_iso_8601": "2023-10-06T08:49:07.081822Z",
"url": "https://files.pythonhosted.org/packages/f5/ab/2a44ecac0f891dd0d765fc59ac8d277c6283a31907626560e72685df2ed6/torch_scatter-2.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-06 08:49:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rusty1s",
"github_project": "pytorch_scatter",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "torch-scatter"
}
JSON
