Use EncodeScatterNd for coordinate tuples or EncodeScatterElements for indices along one axis. On Windows or Linux, use a Vulkan 1.3 driver and loader.
dotnet add package RecursiveAI.OneGpu.Backends dotnet add package RecursiveAI.OneGpu.Kernels
Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
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, then dotnet run.
Prints the updated tensor; both updates to index 1 are added:
10, 30, 35The full program
The download compares the output with a CPU loop that starts from the original values and applies the increments in order.
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}");
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.
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.
scatter.EncodeScatterElements( cmd, data, 0, [3], axis: 0, indices, 0, [3], updates, 0, output, 0, GpuScatterReduction.Add, status: status);
Related recipes
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 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 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, 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.