### Install PyTorch Scatter from Source

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Install PyTorch Scatter after ensuring PyTorch is installed and environment variables are set.

```bash
pip install torch-scatter
```

--------------------------------

### Install PyTorch Scatter Binaries

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Install pre-built binaries for PyTorch 2.9. Replace `${CUDA}` with your specific CUDA version (e.g., `cpu`, `cu126`).

```bash
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.9.0+${CUDA}.html
```

--------------------------------

### Get PyTorch Scatter Version and Device Info

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Use this snippet to print the installed PyTorch Scatter package version, check for CUDA support by retrieving the CUDA version, and determine the active device (GPU or CPU). Ensure PyTorch and PyTorch Scatter are installed.

```python
import torch_scatter
import torch

# Package version
print(torch_scatter.__version__)

# CUDA support
cuda_version = torch.ops.torch_scatter.cuda_version()
print(f"CUDA version: {cuda_version}")

# Device detection
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
```

--------------------------------

### PyTorch Scatter scatter_max Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Demonstrates the usage of the `scatter_max` function from `torch_scatter` with sample tensors for source and index.

```python
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)
```

--------------------------------

### Install PyTorch Scatter for PyTorch 2.10

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Installs PyTorch Scatter binaries for PyTorch 2.10. Replace ${CUDA} with your specific CUDA version (cpu, cu126, cu128, or cu130).

```bash
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.10.0+${CUDA}.html
```

--------------------------------

### Example Usage of Testing Utilities

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Demonstrates how to use the testing utilities like dtypes, devices, and the tensor helper function to create test tensors for different data types and devices.

```python
from torch_scatter.testing import dtypes, devices, tensor

for dtype in dtypes:
    for device in devices:
        src = tensor([1, 2, 3], dtype, device)
        index = tensor([0, 1, 0], torch.long, device)
```

--------------------------------

### Attention Mechanism Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Illustrates using scatter_softmax and scatter_sum for implementing attention mechanisms, often seen in sequence models.

```python
from torch_scatter import scatter_softmax, scatter_sum

attention_weights = scatter_softmax(attention_scores, query_idx)
output = scatter_sum(weighted_values, query_idx, dim_size=num_queries)
```

--------------------------------

### Install PyTorch Scatter for PyTorch 2.11

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Installs PyTorch Scatter binaries for PyTorch 2.11. Replace ${CUDA} with your specific CUDA version (cpu, cu126, cu128, or cu130).

```bash
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.11.0+${CUDA}.html
```

--------------------------------

### Broadcasting Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/types.md

Demonstrates how index tensors are automatically broadcast to match source tensor dimensions. The index tensor is expanded to align with non-scatter dimensions of the source tensor.

```python
src = torch.randn(10, 6, 64)      # 3D tensor
index = torch.tensor([0, 1, 0, 1, 2, 1])  # 1D tensor

# Index is broadcast to match src along non-scatter dimensions
scatter_sum(src, index, dim=1)
# Broadcasting rule applied: index becomes shape (6,) → broadcasts with (10, 6, 64)
```

--------------------------------

### Install PyTorch Scatter for PyTorch 2.12

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Installs PyTorch Scatter binaries for PyTorch 2.12. Replace ${CUDA} with your specific CUDA version (cpu, cu126, cu130, or cu132).

```bash
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.12.0+${CUDA}.html
```

--------------------------------

### Get PyTorch Scatter Package Version

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Use this snippet to print the installed version of the torch_scatter package. Ensure torch_scatter is installed.

```python
import torch_scatter
print(torch_scatter.__version__)  # e.g., '2.1.2'
```

--------------------------------

### Basic scatter_add example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/scatter-operations.md

Shows the basic usage of scatter_add, which is an alias for scatter_sum. Values are summed into the output tensor based on the index.

```python
import torch
from torch_scatter import scatter_add

src = torch.tensor([1.0, 3.0, 2.0, 4.0])
index = torch.tensor([0, 1, 0, 1])
out = scatter_add(src, index)
# Result: [3.0, 7.0]
```

--------------------------------

### Device Compatibility Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/types.md

Shows how PyTorch Scatter operations support CPU and CUDA tensors, requiring consistency across src, index, and out tensors. The resulting tensor will reside on the same device as the input tensors.

```python
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
src = torch.randn(100, device=device)
index = torch.randint(0, 10, (100,), dtype=torch.long, device=device)
out = scatter_sum(src, index)  # Result is on same device
```

--------------------------------

### Basic 1D scatter_sum example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/scatter-operations.md

Demonstrates the basic usage of scatter_sum for a 1D tensor. Values from src are summed into out based on the provided index.

```python
import torch
from torch_scatter import scatter_sum

# Basic 1D example
src = torch.tensor([1.0, 3.0, 2.0, 4.0, 5.0, 6.0])
index = torch.tensor([0, 1, 0, 1, 1, 3])
out = scatter_sum(src, index, dim=-1)
# Result: [3.0, 12.0, 0.0, 6.0]
```

--------------------------------

### 2D Example of scatter_log_softmax

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/composite-operations.md

Demonstrates the usage of scatter_log_softmax with a 2D tensor and verifies its output size. It also includes an assertion to confirm that exponentiating the log-softmax values yields the softmax values, ensuring numerical correctness.

```python
src = torch.randn(10, 50)
index = torch.randint(0, 5, (50,))
out = scatter_log_softmax(src, index, dim=1)
print(out.size())  # torch.Size([10, 50])

# Verify log-softmax: exp(log_softmax) should be softmax
log_softmax_vals = scatter_log_softmax(src, index)
softmax_vals = scatter_softmax(src, index)
assert torch.allclose(log_softmax_vals.exp(), softmax_vals, atol=1e-6)
```

--------------------------------

### Min/Max Return Tuple Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Illustrates that scatter_min and scatter_max return a tuple of (values, indices).

```python
values, indices = scatter_min(src, index)
# values: minimum values per group
# indices: source indices where minimum was found
```

--------------------------------

### Pooling in Neural Networks Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Demonstrates using scatter_max for pooling operations, such as max pooling within specific regions in a neural network.

```python
from torch_scatter import scatter_max

# Max pooling per region
pooled_features, indices = scatter_max(features, region_indices)
```

--------------------------------

### Time Series Downsampling Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Shows how scatter_mean can be used to downsample time series data by grouping values into time buckets.

```python
from torch_scatter import scatter_mean

# Group by time bucket
means = scatter_mean(values, time_buckets)
```

--------------------------------

### Verify PyTorch Version

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Check if PyTorch version 1.4.0 or higher is installed before building from source.

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

--------------------------------

### Single Tensor Return Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Demonstrates a typical usage of scatter_sum returning a single tensor.

```python
out = scatter_sum(src, index)  # Returns Tensor
```

--------------------------------

### 2D scatter_sum example with explicit dimension

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/scatter-operations.md

Shows how to use scatter_sum on a 2D tensor by specifying the scatter dimension (dim=0). Values are summed along the rows.

```python
# 2D example with explicit dimension
src = torch.tensor([[1.0, 2.0], [5.0, 6.0], [3.0, 4.0]])
index = torch.tensor([0, 1, 0])
out = scatter_sum(src, index, dim=0)
# Result: [[4.0, 6.0], [5.0, 6.0]]
```

--------------------------------

### segment_sum_coo 2D Example with Broadcasting

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/segment-coo-operations.md

Demonstrates segment sum with broadcasting on a 2D source tensor. The index tensor is reshaped to enable broadcasting across specified dimensions, affecting the output tensor's size.

```python
import torch
from torch_scatter import segment_sum_coo

# 2D example with broadcasting
src = torch.randn(10, 6, 64)
index = torch.tensor([0, 0, 1, 1, 1, 2])
index = index.view(1, -1)  # Broadcasting in first and last dim
out = segment_sum_coo(src, index)
print(out.size())  # torch.Size([10, 3, 64])
```

--------------------------------

### Graph Node Aggregation Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

A common pattern for aggregating features from neighboring nodes to a central node in graph neural networks.

```python
from torch_scatter import scatter_sum

# Aggregate messages from source to destination nodes
messages = src_features[edge_src]
aggregated = scatter_sum(messages, edge_dst, dim_size=num_nodes)
```

--------------------------------

### Gradient Computation with Scatter Mean

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Demonstrates that all torch_scatter operations support automatic differentiation. The example shows a forward pass with scatter_mean, followed by loss calculation and a backward pass to compute gradients for the source tensor.

```python
import torch
from torch_scatter import scatter_mean

# Source tensor requires gradients
src = torch.randn(100, 64, requires_grad=True)
index = torch.randint(0, 10, (100,))

# Forward pass
out = scatter_mean(src, index)

# Loss
loss = out.sum()

# Backward pass
loss.backward()

print(src.grad.shape)  # (100, 64) - gradient computed automatically
```

--------------------------------

### Check CUDA Compatibility

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Verify CUDA compatibility by checking the CUDA version reported by torch_scatter. This helps ensure compatibility between your PyTorch installation, CUDA toolkit, and the torch_scatter library.

```python
from torch_scatter import torch_scatter
cuda_version = torch.ops.torch_scatter.cuda_version()
# Returns: -1 (CPU), 10000+ (CUDA version), or HIP version
```

--------------------------------

### segment_sum_coo 1D Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/segment-coo-operations.md

Performs a segment sum operation on a 1D source tensor using sorted indices. The result shows the sum of values within each defined segment.

```python
import torch
from torch_scatter import segment_sum_coo

# 1D example with sorted indices
src = torch.tensor([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
index = torch.tensor([0, 0, 1, 1, 1, 3])
out = segment_sum_coo(src, index)
# Result: [3.0, 12.0, 0.0, 6.0]
# Segment 0: src[0] + src[1] = 1 + 2 = 3
# Segment 1: src[2] + src[3] + src[4] = 3 + 4 + 5 = 12
# Segment 2: (empty) = 0
# Segment 3: src[5] = 6
```

--------------------------------

### Check Environment Variables for Source Build

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Verify that CUDA bin and include paths are set in the environment variables `$PATH` and `$CPATH` respectively.

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

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

--------------------------------

### Selecting Reduction Operation (reduce)

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Illustrates how to select the reduction operation (e.g., 'sum', 'mean') for generic scatter and segment functions using the 'reduce' parameter.

```python
scatter(src, index, reduce="sum")    # Sum reduction
scatter(src, index, reduce="mean")   # Mean reduction
```

--------------------------------

### Sorting Indices for Speedup

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Demonstrates converting scatter operations to segment_coo for potential speedup by sorting indices first.

```python
sorted_index, sort_idx = torch.sort(index)
sorted_src = src[sort_idx]
out = segment_sum_coo(sorted_src, sorted_index)
```

--------------------------------

### All-in-one PyTorch Scatter Import

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Import the entire torch_scatter library for convenient access to all its functions. This is useful for quick access but may lead to namespace pollution in larger projects.

```python
import torch_scatter
result = torch_scatter.scatter_sum(src, index)
```

--------------------------------

### segment_add_coo Example

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/segment-coo-operations.md

Performs a segment addition operation, which is an alias for segment_sum_coo. It sums values from the source tensor into segments defined by sorted indices.

```python
import torch
from torch_scatter import segment_add_coo

src = torch.tensor([1.0, 3.0, 2.0, 4.0, 5.0])
index = torch.tensor([0, 1, 0, 1, 1])
out = segment_add_coo(src, index)
# Result: [3.0, 12.0]
```

--------------------------------

### Testing Utilities Import

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Imports various testing utilities from torch_scatter.testing, including reductions, data types, gradient data types, devices, and a helper function for creating tensors.

```python
from torch_scatter.testing import (
    reductions,   # List: ['sum', 'add', 'mean', 'min', 'max']
    dtypes,       # List of torch dtypes for testing
    grad_dtypes,  # List of torch dtypes for gradient testing
    devices,      # List of torch devices available
    tensor,       # Helper function to create test tensors
)
```

--------------------------------

### Generic Scatter Operation with Different Reductions

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/scatter-operations.md

Demonstrates the usage of the scatter function with various reduction types (sum, mean, max). Ensure the torch_scatter library is imported.

```python
import torch
from torch_scatter import scatter

src = torch.randn(10, 6, 64)
index = torch.tensor([0, 1, 0, 1, 2, 1])

# Different reduction types
out_sum = scatter(src, index, dim=1, reduce="sum")
out_mean = scatter(src, index, dim=1, reduce="mean")
out_max = scatter(src, index, dim=1, reduce="max")

print(out_sum.size())   # torch.Size([10, 3, 64])
print(out_mean.size())  # torch.Size([10, 3, 64])
print(out_max.size())   # torch.Size([10, 3, 64])
```

--------------------------------

### Public Composite Operations Import

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Import composite operations such as standard deviation, log-sum-exp, softmax, and log-softmax from the composite submodule.

```python
from torch_scatter import (
    scatter_std,           # torch_scatter.composite.std:scatter_std
    scatter_logsumexp,     # torch_scatter.composite.logsumexp:scatter_logsumexp
    scatter_softmax,       # torch_scatter.composite.softmax:scatter_softmax
    scatter_log_softmax   # torch_scatter.composite.softmax:scatter_log_softmax
)
```

--------------------------------

### Handling Dimension Mismatch Errors

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Highlights a common pitfall: dimension mismatch between the source tensor and the index tensor. The example shows that an `IndexError` will occur if the index length is not broadcastable with the source dimension.

```python
import torch
from torch_scatter import scatter_sum

src = torch.randn(100, 64)
index = torch.tensor([0, 1, 0, 1])  # Wrong length!

# This will error: index must be broadcastable
# scatter_sum(src, index, dim=0)  # IndexError
```

--------------------------------

### Batch Operations with Scatter Sum

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Demonstrates efficient batch processing using scatter_sum with broadcasting. A single call can process multiple batches simultaneously, which is faster than iterating through each batch individually.

```python
import torch
from torch_scatter import scatter_sum

# Process multiple batches at once with broadcasting
batch_size = 32
sequence_len = 100
feature_dim = 64

src = torch.randn(batch_size, sequence_len, feature_dim)
index = torch.randint(0, 10, (sequence_len,))

# Single call processes all batches
out = scatter_sum(src, index, dim=1)
print(out.shape)  # (32, 10, 64)

# Equivalent to but faster than:
# for i in range(batch_size):
#     out[i] = scatter_sum(src[i], index)
```

--------------------------------

### Import All Public Functions

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Provides a comprehensive import statement to bring all public functions from the torch_scatter library into the current scope.

```python
# Import all public functions
from torch_scatter import (
    scatter_sum, scatter_add, scatter_mul, scatter_mean, scatter_min, scatter_max, scatter,
    segment_sum_csr, segment_add_csr, segment_mean_csr, segment_min_csr, segment_max_csr, segment_csr, gather_csr,
    segment_sum_coo, segment_add_coo, segment_mean_coo, segment_min_coo, segment_max_coo, segment_coo, gather_coo,
    scatter_std, scatter_logsumexp, scatter_softmax, scatter_log_softmax
)
```

--------------------------------

### Broadcasting Index to Multi-Dimensional Source

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Demonstrates how index tensors are automatically broadcast to match source tensor dimensions when the index tensor has fewer dimensions than the source. Useful for applying the same scattering pattern across multiple batches or dimensions.

```python
import torch
from torch_scatter import scatter_sum

# Source: shape (10, 6, 64) - 10 batches, 6 items per batch, 64 features
src = torch.randn(10, 6, 64)

# Index: shape (6,) - specifies group for each item in a batch
index = torch.tensor([0, 1, 0, 1, 2, 1])

# Scatter along dimension 1
out = scatter_sum(src, index, dim=1)
# Result shape: (10, 3, 64)
# Each of the 10 batches is independently reduced by the same index pattern

# Explicit broadcasting: add batch dimension to index
index_2d = index.unsqueeze(0)  # Shape (1, 6)
out = scatter_sum(src, index_2d, dim=1)
# Same result with explicit dimension
```

--------------------------------

### Segment Sum with CSR Index Pointers (1D)

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/segment-csr-operations.md

Calculates the sum of values within segments defined by CSR index pointers for a 1D source tensor. Ensure indptr is sorted, starts at 0, and ends at src.size(dim).

```python
import torch
from torch_scatter import segment_sum_csr

# 1D example with CSR index pointers
src = torch.tensor([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
indptr = torch.tensor([0, 2, 5, 5, 6])  # Segments: [0:2], [2:5], [5:5], [5:6]
out = segment_sum_csr(src, indptr)
# Result: [3.0, 12.0, 0.0, 6.0]
# Segment 0: src[0:2] = 1 + 2 = 3
# Segment 1: src[2:5] = 3 + 4 + 5 = 12
# Segment 2: src[5:5] = (empty) = 0
# Segment 3: src[5:6] = 6
```

--------------------------------

### Build PyTorch Scatter C++ API

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Compile the C++ API for PyTorch Scatter. Ensure `TorchLib` is added to `CMAKE_PREFIX_PATH` and consider enabling CUDA support with `-DWITH_CUDA=on`.

```bash
mkdir build
cd build
# Add -DWITH_CUDA=on support for CUDA support
cmake -DCMAKE_PREFIX_PATH="..." ..
make
make install
```

--------------------------------

### Index Pointer Tensor for Segment CSR Operations

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/types.md

This tensor, in CSR format, defines segment boundaries for segment_csr operations. It must be of dtype torch.long with strictly ascending values, starting at 0 and ending at the size of the segment dimension.

```python
# For segment_csr operations
indptr: torch.Tensor  # dtype=torch.long, ascending values
```

```python
# 1D indptr tensor
indptr = torch.tensor([0, 2, 5, 6])  # 4 segments
# Segment 0: indices 0-1 (inclusive 0, exclusive 2)
# Segment 1: indices 2-4
# Segment 2: indices 5-5 (empty)
# Segment 3: indices 5-5 (exclusive, may be empty)
```

```python
# 2D indptr tensor (for broadcasting)
indptr = torch.tensor([[0, 2, 5, 6]])  # Shape (1, 4)
```

--------------------------------

### Sum values at each index (Unordered)

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Use `scatter_sum` for summing values based on arbitrary, unordered indices. Ensure `torch_scatter` is imported.

```python
from torch_scatter import scatter_sum
out = scatter_sum(src, index)
```

--------------------------------

### Run PyTorch Scatter Tests

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

Execute the test suite for PyTorch Scatter using pytest.

```bash
pytest
```

--------------------------------

### Set Compute Capabilities for Docker

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/README.md

When running in a Docker container without an NVIDIA driver, set compute capabilities via `TORCH_CUDA_ARCH_LIST` to prevent potential PyTorch evaluation failures.

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

--------------------------------

### Metadata Imports

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Import metadata like the package version and a reference to the module itself.

```python
from torch_scatter import (
    __version__,           # Package version (e.g., '2.1.2')
    torch_scatter         # Reference to the module itself
)
```

--------------------------------

### Public Scatter Operations Import

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Import common scatter operations directly from the torch_scatter package. These include sum, add, multiply, mean, min, max, and a generic scatter function.

```python
from torch_scatter import (
    scatter_sum,           # torch_scatter.scatter:scatter_sum
    scatter_add,           # torch_scatter.scatter:scatter_add
    scatter_mul,           # torch_scatter.scatter:scatter_mul
    scatter_mean,          # torch_scatter.scatter:scatter_mean
    scatter_min,           # torch_scatter.scatter:scatter_min
    scatter_max,           # torch_scatter.scatter:scatter_max
    scatter               # torch_scatter.scatter:scatter (generic)
)
```

--------------------------------

### Pre-allocating Output Tensor

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Shows the performance benefit of pre-allocating the output tensor using the 'out' parameter.

```python
out = torch.zeros(output_size, device=src.device, dtype=src.dtype)
scatter_sum(src, index, out=out)
```

--------------------------------

### Specifying Reduction Dimension (dim)

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Shows how to specify the dimension for reduction using the 'dim' parameter, including negative indexing.

```python
scatter_sum(src, index, dim=0)   # Reduce first dimension
scatter_sum(src, index, dim=-1)  # Reduce last dimension
```

--------------------------------

### Time Series Grouping and Aggregation

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Demonstrates how to group and aggregate time series data using scatter_mean and scatter_std. This is useful for downsampling time series data by aggregating values within specific time steps.

```python
import torch
from torch_scatter import scatter_mean, scatter_std

# Time series data
timestamps = torch.tensor([0, 0, 1, 1, 1, 2, 2])
values = torch.tensor([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0])

# Aggregate by time step
mean_per_step = scatter_mean(values, timestamps)  # [1.5, 4.0, 6.5]
std_per_step = scatter_std(values, timestamps)    # [std per step]

# Useful for downsampling time series
```

--------------------------------

### Setting Output Tensor Size (dim_size)

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/quick-reference.md

Demonstrates using 'dim_size' to explicitly set the output tensor's size along the reduction dimension, useful for sparse operations.

```python
out = scatter_sum(src, index)  # Output size = index.max() + 1
out = scatter_sum(src, index, dim_size=1000)  # Output size = 1000
```

--------------------------------

### Metadata Exports

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Metadata and module references that can be imported directly from the torch_scatter package.

```APIDOC
## __version__

### Description
Provides the current version of the torch_scatter package.

### Usage
```python
import torch_scatter

version = torch_scatter.__version__
print(version) # e.g., '2.1.2'
```

### Response
- `str` - The package version string.
```

```APIDOC
## torch_scatter

### Description
A reference to the torch_scatter module itself.

### Usage
```python
import torch_scatter

# Use this to access module-level attributes or functions if needed
print(torch_scatter)
```

### Response
- `module` - The torch_scatter module object.
```

--------------------------------

### Dynamic Extension Loading

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

The main module dynamically loads compiled C++ extensions at import time. The CUDA version is checked after loading.

```python
# Dynamically loads one of these, whichever is available:
# - _scatter_cuda     (CUDA version if compiled with CUDA)
# - _scatter_cpu      (CPU version)
# - _segment_csr_cuda / _segment_csr_cpu
# - _segment_coo_cuda / _segment_coo_cpu
# - _version_cuda / _version_cpu

torch.ops.torch_scatter.cuda_version()  # Available after loading
```

--------------------------------

### Gradient Flow in Graph Operations with Scatter Sum

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Illustrates how gradients flow back to the original node features in graph operations using scatter_sum. It confirms that gradients are computed for the node_features tensor after a backward pass.

```python
import torch
from torch_scatter import scatter_sum

node_features = torch.randn(50, 32, requires_grad=True)
edge_src = torch.tensor([0, 1, 2, 3, 4])
edge_dst = torch.tensor([5, 6, 7, 8, 9])

edge_messages = node_features[edge_src] * 0.5
aggregated = scatter_sum(edge_messages, edge_dst, dim=0, dim_size=50)

loss = aggregated.sum()
loss.backward()

# Gradients flow back to original node_features
print(node_features.grad is not None)  # True
```

--------------------------------

### Public Segment COO Operations Import

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Import segment operations using the Coordinate (COO) format. This includes sum, add, mean, min, max, a generic segment function, and gather.

```python
from torch_scatter import (
    segment_sum_coo,       # torch_scatter.segment_coo:segment_sum_coo
    segment_add_coo,       # torch_scatter.segment_coo:segment_add_coo
    segment_mean_coo,      # torch_scatter.segment_coo:segment_mean_coo
    segment_min_coo,       # torch_scatter.segment_coo:segment_min_coo
    segment_max_coo,       # torch_scatter.segment_coo:segment_max_coo
    segment_coo,           # torch_scatter.segment_coo:segment_coo (generic)
    gather_coo            # torch_scatter.segment_coo:gather_coo
)
```

--------------------------------

### Find Minimum Value and Index per Segment (segment_min_coo)

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/segment-coo-operations.md

Finds the minimum value and its index within each segment defined by sorted indices. Useful for identifying the smallest element and its position in each group.

```python
import torch
from torch_scatter import segment_min_coo

src = torch.tensor([5.0, 2.0, 3.0, 4.0, 1.0, 6.0])
index = torch.tensor([0, 0, 1, 1, 1, 3])
out_val, out_idx = segment_min_coo(src, index)
# out_val: [2.0, 1.0, inf, 6.0]
# out_idx: [1, 4, 6, 5]
```

--------------------------------

### Selective PyTorch Scatter Imports

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

Import specific functions from the torch_scatter library to keep your namespace clean and improve code readability. This is recommended for most use cases.

```python
from torch_scatter import scatter_sum, scatter_mean, scatter_std
from torch_scatter import segment_csr, segment_coo
```

--------------------------------

### Attention-Based Aggregation in GNNs

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Shows how to implement attention mechanisms in GNNs using scatter_softmax for normalization and scatter_sum for weighted aggregation. This allows nodes to weigh incoming messages based on learned attention scores.

```python
import torch
from torch_scatter import scatter_softmax, scatter_sum

num_nodes = 100
num_edges = 500
node_features = torch.randn(num_nodes, 64)

edge_src = torch.randint(0, num_nodes, (num_edges,))
edge_dst = torch.randint(0, num_nodes, (num_edges,))

# Compute attention scores for each edge
attention_logits = torch.randn(num_edges)  # logits for each edge

# Softmax attention normalized per destination node
attention_weights = scatter_softmax(attention_logits, edge_dst, dim=0)

# Weighted aggregation using attention
edge_messages = node_features[edge_src] * attention_weights.unsqueeze(-1)
attended_features = scatter_sum(edge_messages, edge_dst, dim=0, dim_size=num_nodes)
```

--------------------------------

### Trace Scatter Operations with Hooks

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Use PyTorch hooks to trace scatter operations, printing input and output shapes. This is useful for inspecting data flow and debugging.

```python
import torch
from torch_scatter import scatter_sum

def trace_scatter(module, input, output):
    print(f"Scatter input shape: {input[0].shape}")
    print(f"Index shape: {input[1].shape}")
    print(f"Output shape: {output.shape}")

src = torch.randn(100)
index = torch.randint(0, 10, (100,))
result = scatter_sum(src, index)
# Note: This example shows the concept but doesn't attach the hook to scatter_sum directly as it's a functional API.
```

--------------------------------

### Memory-Efficient Operations with Out Parameter

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Shows how to use the 'out' parameter for memory efficiency by pre-allocating the output tensor. This avoids repeated memory allocations when performing multiple scatter operations in a loop.

```python
import torch
from torch_scatter import scatter_sum

src = torch.randn(10000, 64)
index = torch.randint(0, 100, (10000,))

# Pre-allocate output once
out = torch.zeros(100, 64, dtype=src.dtype, device=src.device)

# Reuse in loop for multiple operations
for _ in range(1000):
    out.zero_()  # Reset to zeros
    scatter_sum(src, index, dim=0, out=out)
    # Use out...
```

--------------------------------

### Node Aggregation for Graph Neural Networks

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Demonstrates a common Graph Neural Network (GNN) pattern for aggregating features from source nodes to destination nodes using scatter_sum. This is typically used to pass messages along edges.

```python
import torch
from torch_scatter import scatter_sum

# Graph: nodes have features, edges connect them
num_nodes = 100
num_edges = 500
node_features = torch.randn(num_nodes, 64)

# Edge indices: source -> destination
edge_src = torch.randint(0, num_nodes, (num_edges,))
edge_dst = torch.randint(0, num_nodes, (num_edges,))

# Aggregate source node features to destination nodes
# This is a common GNN pattern: message = f(src_features)
edge_messages = node_features[edge_src]  # Get source features for each edge
aggregated = scatter_sum(edge_messages, edge_dst, dim=0, dim_size=num_nodes)
# aggregated[i] = sum of messages received at node i

# Node update: new_features = old_features + aggregated_messages
updated_features = node_features + aggregated
```

--------------------------------

### Public Composite Operations

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/module-structure.md

These composite operations, including standard deviation, log-sum-exp, and softmax, can be imported directly from the torch_scatter package.

```APIDOC
## scatter_std

### Description
Computes the standard deviation of elements in `src` along `dim` based on `index`.

### Method
`scatter_std(src, index, dim=-1, out=None, dim_size=None)`

### Parameters
- `src` (Tensor) - Input tensor.
- `index` (Tensor) - Indices to scatter elements to.
- `dim` (int, optional) - Dimension along which to scatter. Defaults to -1.
- `out` (Tensor, optional) - Output tensor to store results.
- `dim_size` (int, optional) - Size of the dimension to scatter into.

### Response
- `Tensor` - Tensor with scattered standard deviation values.
```

```APIDOC
## scatter_logsumexp

### Description
Computes the log-sum-exp of elements in `src` along `dim` based on `index`.

### Method
`scatter_logsumexp(src, index, dim=-1, out=None, dim_size=None)`

### Parameters
- `src` (Tensor) - Input tensor.
- `index` (Tensor) - Indices to scatter elements to.
- `dim` (int, optional) - Dimension along which to scatter. Defaults to -1.
- `out` (Tensor, optional) - Output tensor to store results.
- `dim_size` (int, optional) - Size of the dimension to scatter into.

### Response
- `Tensor` - Tensor with scattered log-sum-exp values.
```

```APIDOC
## scatter_softmax

### Description
Computes the softmax of elements in `src` along `dim` based on `index`.

### Method
`scatter_softmax(src, index, dim=-1, out=None, dim_size=None)`

### Parameters
- `src` (Tensor) - Input tensor.
- `index` (Tensor) - Indices to scatter elements to.
- `dim` (int, optional) - Dimension along which to scatter. Defaults to -1.
- `out` (Tensor, optional) - Output tensor to store results.
- `dim_size` (int, optional) - Size of the dimension to scatter into.

### Response
- `Tensor` - Tensor with scattered softmax values.
```

```APIDOC
## scatter_log_softmax

### Description
Computes the log-softmax of elements in `src` along `dim` based on `index`.

### Method
`scatter_log_softmax(src, index, dim=-1, out=None, dim_size=None)`

### Parameters
- `src` (Tensor) - Input tensor.
- `index` (Tensor) - Indices to scatter elements to.
- `dim` (int, optional) - Dimension along which to scatter. Defaults to -1.
- `out` (Tensor, optional) - Output tensor to store results.
- `dim_size` (int, optional) - Size of the dimension to scatter into.

### Response
- `Tensor` - Tensor with scattered log-softmax values.
```

--------------------------------

### Two-Stage Reduction with Scatter Max and Scatter Sum

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/advanced-usage.md

Combines scatter_max and scatter_sum to perform a two-stage reduction. First, it finds the maximum value per group, and then it sums these maximum values.

```python
import torch
from torch_scatter import scatter_max, scatter_sum

src = torch.randn(1000)
index = torch.randint(0, 50, (1000,))

# Stage 1: Find maximum value per group
max_vals, max_indices = scatter_max(src, index)

# Stage 2: Sum only the maximum values
# Create a new index mapping max values back
new_index = torch.arange(len(max_vals))
final = scatter_sum(max_vals, new_index)
```

--------------------------------

### scatter_logsumexp

Source: https://github.com/rusty1s/pytorch_scatter/blob/master/_autodocs/composite-operations.md

Computes the log-sum-exp reduction, which is numerically stable logarithm of sum of exponentials. Uses the log-sum-exp trick for numerical stability.

```APIDOC
## scatter_logsumexp

### Description
Computes log(Σ(exp(x))) in a numerically stable way using the log-sum-exp trick. This operation is particularly useful in probabilistic models and attention mechanisms to avoid numerical overflow/underflow.

### Signature
```python
def scatter_logsumexp(
    src: torch.Tensor,
    index: torch.Tensor,
    dim: int = -1,
    out: Optional[torch.Tensor] = None,
    dim_size: Optional[int] = None,
    eps: float = 1e-12
) -> torch.Tensor
```

### Parameters
#### Path Parameters
- **src** (torch.Tensor) - Required - The source tensor (must be floating-point). Values to compute log-sum-exp.
- **index** (torch.Tensor) - Required - The indices tensor specifying which group each value belongs to.
- **dim** (int) - Optional - The dimension along which to compute log-sum-exp. Defaults to -1.
- **out** (Optional[torch.Tensor]) - Optional - Optional pre-allocated output tensor.
- **dim_size** (Optional[int]) - Optional - Size of output tensor at the scatter dimension.
- **eps** (float) - Optional - Small epsilon for numerical stability to prevent log(0). Defaults to 1e-12.

### Return Type
torch.Tensor — The output tensor with log-sum-exp values per group.

### Example Usage
```python
import torch
from torch_scatter import scatter_logsumexp

# Compute log-sum-exp for each group
src = torch.randn(100)
index = torch.randint(0, 5, (100,))
out = scatter_logsumexp(src, index)
# Result: log(Σ(exp(x))) per group

# With custom epsilon
out = scatter_logsumexp(src, index, eps=1e-8)

# 2D example
src = torch.randn(10, 50)
index = torch.randint(0, 5, (50,))
out = scatter_logsumexp(src, index, dim=1)
print(out.size())  # torch.Size([10, 5])

# This is useful in softmax computation
```
```