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[tuple, list, Array, Shape, NativeShape]], default: None) – The shape of the result. Default is None, in which case tensor argument must be provided.

  • reduction (str, default: 'sum') – The reduction method for the scatter, one of ‘sum’, ‘min’, ‘max’ or ‘replace’

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

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

Examples

With ivy.Array input:

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

>>> indices = ivy.array([[0, 1], [1, 0], [1, 1], [1, 1]])
>>> updates = ivy.array([9, 11, 12, 10])
>>> shape = (2, 2)
>>> scatter = ivy.scatter_nd(indices, updates, shape, reduction="max")
>>> print(scatter)
ivy.array([[ 0,  9], [11, 12]])

>>> indices = ivy.array([[[0], [1]], [[2], [1]]])
>>> updates = ivy.array([[9, 12], [11, 10]])
>>> shape = [4]
>>> scatter = ivy.scatter_nd(indices, updates, shape, reduction="replace")
>>> print(scatter)
ivy.array([ 9, 10, 11,  0])

>>> indices = ivy.array([[[1, 1], [0, 0]], [[1, 1], [0, 0]]])
>>> updates = ivy.array([[-1, 12], [11, 10]])
>>> shape = ivy.Shape([2, 2])
>>> result = ivy.zeros([2, 2])
>>> scatter = ivy.scatter_nd(indices, updates, shape, reduction="min", out=result)
>>> print(result)
ivy.array([[ 0.,  0.], [ 0., -1.]])

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)
>>> 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)[source]#

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], default: None) – The shape of the result. Default is None, in which case tensor argument must be provided.

  • reduction (str, default: 'sum') – The reduction method for the scatter, one of ‘sum’, ‘min’, ‘max’ or ‘replace’

  • out (Optional[Array], default: None) – optional output array, for writing the result to.

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)[source]#

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]], default: None) – The shape of the result. Default is None, in which case tensor argument must be provided.

  • reduction (Union[str, Container], default: 'sum') – The reduction method for the scatter, one of ‘sum’, ‘min’, ‘max’ or ‘replace’

  • key_chains (Optional[Union[List[str], Dict[str, str], Container]], default: None) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (Union[bool, Container], default: True) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (Union[bool, Container], default: False) – Whether to prune key_chains for which the function was not applied. Default is False.

  • map_sequences (Union[bool, Container], default: False) – Whether to also map method to sequences (lists, tuples). Default is False.

  • out (Optional[Container], default: None) – optional output container, for writing the result to. It must have a shape 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])
}