---
title: "Scatter indexed updates on the GPU in C#"
url: https://recursiveai.org/onegpu/cookbook/scatter-updates-into-gpu-tensor/
description: "Use OneGpu ScatterND or ScatterElements in C# to write indexed updates to a GPU tensor, including adding multiple updates to the same target."
version: "1.0.0"
---

# Scatter indexed updates on the GPU in C#

**OneGpu** is a free, open-source GPU compute library for .NET from Recursive AI. MIT or Apache-2.0, no bundled native binaries.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneGpu.Kernels) · [GitHub](https://github.com/recursive-ai-oss/onegpu-csharp) · [Docs](https://recursiveai.org/onegpu/docs/) · [Download example (.zip)](https://recursiveai.org/onegpu/cookbook/scatter-updates-into-gpu-tensor/scatter-updates-into-gpu-tensor.zip)

Use `EncodeScatterNd` for coordinate tuples or `EncodeScatterElements` for indices along one axis. On Windows or Linux, use a Vulkan 1.3 driver and loader.

```shell
dotnet add package RecursiveAI.OneGpu.Backends
dotnet add package RecursiveAI.OneGpu.Kernels
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using RecursiveAI.OneGpu;
using RecursiveAI.OneGpu.Kernels;

using var gpu =
    GpuBackends.CreateDevice();
using var scatter = new ScatterKernels(gpu);
using var data = gpu.CreateBuffer<int>(
    [10, 20, 30]);
using var indices = gpu.CreateBuffer<int>(
    [1, -2, 2]);
using var updates = gpu.CreateBuffer<int>(
    [3, 7, 5]);
using var output = gpu.CreateBuffer<int>(3);
using var status = new GpuIndexStatus(gpu);
var cmd = gpu.BeginCommands();
scatter.EncodeScatterNd(cmd, data, 0, [3],
    indices, 0, [3, 1], updates, 0,
    output, 0, GpuScatterReduction.Add,
    status: status);
gpu.Submit(cmd);
await status.ThrowIfFailedAsync();
var values = new int[3];
await output.ReadAsync(values);
Console.WriteLine(string.Join(", ", values));
```

Unzip [the example](https://recursiveai.org/onegpu/cookbook/scatter-updates-into-gpu-tensor/scatter-updates-into-gpu-tensor.zip), then `dotnet run`.

Prints the updated tensor; both updates to index `1` are added:

```text
10, 30, 35
```

## The full program

The download compares the output with a CPU loop that starts from the original values and applies the increments in order.

```csharp
using RecursiveAI.OneGpu;
using RecursiveAI.OneGpu.Kernels;

using var gpu = GpuBackends.CreateDevice();
int[] sample = [10, 20, 30];
int[] targets = [1, -2, 2];
int[] increments = [3, 7, 5];
using var data = gpu.CreateBuffer<int>(sample);
using var indices = gpu.CreateBuffer<int>(targets);
using var updates = gpu.CreateBuffer<int>(increments);
using var output = gpu.CreateBuffer<int>(sample.Length);
using var scatter = new ScatterKernels(gpu);
using var status = new GpuIndexStatus(gpu);

var commands = gpu.BeginCommands();
scatter.EncodeScatterNd(commands, data, 0, [3],
    indices, 0, [3, 1], updates, 0, output, 0,
    GpuScatterReduction.Add, status: status);
gpu.Submit(commands);
await status.ThrowIfFailedAsync();
var values = new int[sample.Length];
await output.ReadAsync(values);

int[] expected = (int[])sample.Clone();
for (int i = 0; i < targets.Length; i++)
{
    int target = targets[i] < 0 ? targets[i] + sample.Length : targets[i];
    expected[target] += increments[i];
}
if (!values.SequenceEqual(expected))
    throw new InvalidOperationException("GPU and CPU scatter results differ.");
Console.WriteLine(string.Join(", ", values));
Console.WriteLine("Duplicate-target addition matched the CPU.");
Console.WriteLine($"{gpu.Backend}: {gpu.Adapter.Name}");
```

```text
10, 30, 35
Duplicate-target addition matched the CPU.
Vulkan: NVIDIA GeForce RTX 4070
```

An out-of-range index is skipped; with `GpuIndexStatus` attached as shown, `ThrowIfFailedAsync()` reports it after submission.

## Variations

**Replace instead of adding.** Replace the `EncodeScatterNd` call with this. In OneGpu, the last update wins when duplicate targets use `None`. This prints `10, 7, 5`.

```csharp
scatter.EncodeScatterNd(cmd, data, 0, [3],
    indices, 0, [3, 1], updates, 0,
    output, 0, GpuScatterReduction.None,
    status: status);
```

**Use ScatterElements for updates along one axis.** Replace the same call with the following. This time indices and updates both have shape `[3]`; there’s no tuple dimension. It prints `10, 30, 35`.

```csharp
scatter.EncodeScatterElements(
    cmd, data, 0, [3], axis: 0,
    indices, 0, [3], updates, 0,
    output, 0, GpuScatterReduction.Add,
    status: status);
```

## Related recipes

- [Gather embedding rows on the GPU](https://recursiveai.org/onegpu/cookbook/gather-embedding-rows-on-gpu/)
- [Read a GPU buffer back to the CPU in C#](https://recursiveai.org/onegpu/cookbook/read-back-a-gpu-buffer/)

## The short answer

Use `ScatterKernels.EncodeScatterNd` when you have coordinate tuples, or `EncodeScatterElements` when each index specifies a destination along one axis. Pass `GpuScatterReduction.Add` to add into the original values. In the example, `1` and `-2` refer to the same position in a length-three tensor, so that output starts at `20` and becomes `20 + 3 + 7 = 30`.

## What’s the difference between ScatterND and ScatterElements?

[ScatterND](https://onnx.ai/onnx/operators/onnx__ScatterND.html#scatternd-18) reads the last dimension of `indices` as the length of a coordinate tuple. A tuple can address one element or a whole slice. For a `[4, 2]` tensor, the tuple `[3]` addresses the fourth row, both elements of it. The tuple `[3, 1]` addresses only the second element of that row. In OneGpu, the tuple length `k` is at most six and can’t exceed the data rank. Give `updates` the shape of `indices` without its last dimension, followed by the data dimensions after the first `k`.

[ScatterElements](https://onnx.ai/onnx/operators/onnx__ScatterElements.html#scatterelements-18) uses single indices. It takes the coordinates of each update, replaces its coordinate along `axis` with the index value, and keeps all the other coordinates. `indices` and `updates` share a shape with the same rank as the data, and their dimensions off the selected axis can’t exceed the corresponding data dimensions. Both scatter forms produce the original data shape.

## What happens when scatter indices repeat?

In [OneGpu’s scatter contract](https://recursiveai.org/onegpu/docs/kernels/#gather-scatter-layout-and-int8), updates to the same destination combine in their original order. `Add` starts with the original value and adds each update; `Mul`, `Min`, and `Max` also start with the original value. `None` replaces instead and leaves the last value written. That replacement rule is specific to OneGpu; ONNX ScatterND with `reduction="none"` requires unique destinations.

Leave `indicesAreDistinct` at its default `false` unless you know that the destination elements or slices don’t repeat. OneGpu doesn’t check that promise, and repeated targets can produce an unspecified result if you pass `true`. Check after resolving negative indices: the raw integers `1` and `-2` look distinct, but they alias in the example.

## How is scatter different from gather?

Gather uses indices to pick what to **read** from a source, such as collecting rows from an embedding table. Repeating a gather index reads the same row twice into separate output positions. Scatter uses indices to pick where to **write**; repeating an index can send two updates to one destination. Use gather for lookup and scatter when the original tensor should keep its shape and only selected positions need to change.
