scatter_nd#

ivy.scatter_nd(indices, updates, /, shape=None, *, reduction='sum', out=None)[source]#

Scatter updates into a new array according to indices.

Parameters:

indices (Union[Array, NativeArray]) – Indices for the new values to occupy.
updates (Union[Array, NativeArray]) – Values for the new array to hold.
shape (Optional[Union[Shape, NativeShape]]) – The shape of the result. Default is None, in which case tensor (default: None) argument must be provided.
reduction (str) – The reduction method for the scatter, one of ‘sum’, ‘min’, ‘max’ or ‘replace’ (default: 'sum')
out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type:

Array

Returns:

ret – New array of given shape, with the values scattered at the indices.

Examples

scatter values into an empty array, With ivy.Array input:

>>> indices = ivy.array([[4], [3], [1], [7]])
>>> updates = ivy.array([9, 10, 11, 12])
>>> shape = ivy.array([8])
>>> scatter = ivy.scatter_nd(indices, updates, shape)
>>> print(scatter)
ivy.array([ 0, 11,  0, 10,  9,  0,  0, 12])

With scatter into an empty array, With ivy.Container input:

>>> indices = ivy.Container(a=ivy.array([[4],[3],[6]]),
...                         b=ivy.array([[5],[1],[2]]))
>>> updates = ivy.Container(a=ivy.array([100, 200, 200]),
...                         b=ivy.array([20, 30, 40]))
>>> shape = ivy.Container(a=ivy.array([10]),
...                       b = ivy.array([10]))
>>> z = ivy.scatter_nd(indices, updates, shape=shape, reduction='replace')
>>> print(z)
{
    a: ivy.array([0, 0, 0, 200, 100, 0, 200, 0, 0, 0]),
    b: ivy.array([0, 30, 40, 0, 0, 20, 0, 0, 0, 0])
}

With ivy.Container and ivy.Array input:

>>> indices = ivy.array([[4],[3],[1]])
>>> updates = ivy.Container(a=ivy.array([10, 20, 30]),
...                         b=ivy.array([200, 300, 400]))
>>> z = ivy.Container(a=ivy.array([1, 2, 3, 4, 5]),
...                   b=ivy.array([10, 20, 30, 40, 50]))
>>> ivy.scatter_nd(indices, updates, reduction='replace', out=z)
>>> print(z)
{
    a: ivy.array([1, 30, 3, 20, 10]),
    b: ivy.array([10, 400, 30, 300, 200])
}

Array.scatter_nd(self, updates, /, shape=None, *, reduction='sum', out=None)#

Scatter updates into an array according to indices.

Parameters:

self (Array) – array of indices
updates (Union[Array, NativeArray]) – values to update input tensor with
shape (Optional[Array]) – The shape of the result. Default is None, in which case tensor (default: None) argument must be provided.
reduction (str) – The reduction method for the scatter, one of ‘sum’, ‘min’, ‘max’ (default: 'sum') or ‘replace’
out (Optional[Array]) – optional output array, for writing the result to. (default: None)

Return type:

Array

Returns:

ret – New array of given shape, with the values scattered at the indices.

Examples

With scatter values into an array

>>> arr = ivy.array([1,2,3,4,5,6,7,8, 9, 10])
>>> indices = ivy.array([[4], [3], [1], [7]])
>>> updates = ivy.array([9, 10, 11, 12])
>>> scatter = indices.scatter_nd(updates, reduction='replace', out=arr)
>>> print(scatter)
ivy.array([ 1, 11,  3, 10,  9,  6,  7, 12,  9, 10])

With scatter values into an empty array

>>> shape = ivy.array([2, 5])
>>> indices = ivy.array([[1,4], [0,3], [1,1], [0,2]])
>>> updates = ivy.array([25, 40, 21, 22])
>>> scatter = indices.scatter_nd(updates, shape=shape)
>>> print(scatter)
ivy.array([[ 0,  0, 22, 40,  0],
            [ 0, 21,  0,  0, 25]])

Container.scatter_nd(self, updates, /, shape=None, *, reduction='sum', key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)#

ivy.Container instance method variant of ivy.scatter_nd. This method simply wraps the function, and so the docstring for ivy.scatter_nd also applies to this method with minimal changes.

Parameters:

self (Container) – Index array or container.
updates (Union[Array, NativeArray, Container]) – values to update input tensor with
shape (Optional[Union[Array, NativeArray, Container]]) – The shape of the result. Default is None, in which case tensor argument (default: None) must be provided.
reduction (str) – The reduction method for the scatter, one of ‘sum’, ‘min’, ‘max’ (default: 'sum') or ‘replace’
key_chains (Optional[Union[List[str], Dict[str, str]]]) – The key-chains to apply or not apply the method to. Default is None. (default: None)
to_apply (bool) – If True, the method will be applied to key_chains, otherwise key_chains (default: True) will be skipped. Default is True.
prune_unapplied (bool) – Whether to prune key_chains for which the function was not applied. (default: False) Default is False.
map_sequences (bool) – Whether to also map method to sequences (lists, tuples). (default: False) Default is False.
out (Optional[Container]) – optional output container, for writing the result to. It must have a shape (default: None) that the inputs broadcast to.

Return type:

Container

Returns:

ret – New container of given shape, with the values updated at the indices.

Examples

scatter into an empty container

>>> indices = ivy.Container(a=ivy.array([[4],[3],[6]]),
...                         b=ivy.array([[5],[1],[2]]))
>>> updates = ivy.Container(a=ivy.array([100, 200, 200]),
...                         b=ivy.array([20, 30, 40]))
>>> shape = ivy.Container(a=ivy.array([10]),
...                       b=ivy.array([10]))
>>> z = indices.scatter_nd(updates, shape=shape)
>>> print(z)
{
    a: ivy.array([0, 0, 0, 200, 100, 0, 200, 0, 0, 0]),
    b: ivy.array([0, 30, 40, 0, 0, 20, 0, 0, 0, 0])
}

With scatter into a container.

>>> indices = ivy.Container(a=ivy.array([[5],[6],[7]]),
...                         b=ivy.array([[2],[3],[4]]))
>>> updates = ivy.Container(a=ivy.array([50, 60, 70]),
...                         b=ivy.array([20, 30, 40]))
>>> z = ivy.Container(a=ivy.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]),
...                   b=ivy.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]))
>>> indices.scatter_nd(updates,reduction='replace', out = z)
>>> print(z)
{
    a: ivy.array([1, 2, 3, 4, 5, 50, 60, 70, 9, 10]),
    b: ivy.array([1, 2, 20, 30, 40, 6, 7, 8, 9, 10])
}