Nest

Collection of Ivy functions for nested objects.

ivy.all_nested_indices(nest, include_nests=False, _index=None, _base=True, extra_nest_types=None)[source]

Returns indices of all the elements in nest

Parameters

nest (Iterable) – The nest to check the leaves of.
include_nests (bool) – Whether to also include indices of the nests themselves, not only leaves. (default: False) Default is False.
_index (Optional[List]) – The indices detected so far. None at the beginning. Used internally, do not set (default: None) manually.
_base (bool) – Whether the current function call is the first function call in the recursive (default: True) stack. Used internally, do not set manually.
extra_nest_types (Optional[Union[type, Tuple[type]]]) – Types to recursively check when deciding whether to go deeper into the (default: None) nest or not

Return type

Union[Iterable, bool]

Returns

ret – A set of indices of all elements in nest

ivy.copy_nest(nest, /, include_derived=False, to_mutable=False, extra_nest_types=None)[source]

Copies a nest deeply, but without copying leaves of the nest, only the nest lists, tuples and dicts are copied.

Parameters

nest (Union[Array, NativeArray, Iterable]) – The nest to copy.
include_derived (bool) – Whether to also recursive for classes derived from tuple, list and dict. (default: False) Default is False.
to_mutable (bool) – Whether to convert the nest to a mutable form, changing all tuples to lists. (default: False) Default is False.
extra_nest_types (Optional[Union[type, Tuple[type]]]) – Types to recursively check when deciding whether to go deeper into the (default: None) nest or not

Return type

Union[Array, NativeArray, Iterable]

Returns

ret – The copied nest.

Examples

With ivy.Array input:

>>> nest = ivy.array([[1.,2.,3.],[7.,8.,9.]])
>>> copied_nest = ivy.copy_nest(nest)
>>> print(copied_nest)
ivy.array([[1., 2., 3.],
        [7., 8., 9.]])

With Iterable input:

>>> nest = [[1, 2, 3, 4, 5], [23, 24, 25, 26, 27]]
>>> copied_nest = ivy.copy_nest(nest, include_derived = True)
>>> print(copied_nest)
[[1, 2, 3, 4, 5], [23, 24, 25, 26, 27]]

>>> nest = ([23, 25, 1337], [63, 98, 6])
>>> copied_nest = ivy.copy_nest(nest, to_mutable = True)
>>> print(copied_nest)
[[23, 25, 1337], [63, 98, 6]]

>>> nest = {'first': [23., 24., 25], 'second': [46., 48., 50]}
>>> copied_nest = ivy.copy_nest(nest)
>>> print(copied_nest)
{'first': [23.0, 24.0, 25], 'second': [46.0, 48.0, 50]}

ivy.index_nest(nest, index, /)[source]

Index a nested object, using a tuple of indices or keys in the case of dicts.

Parameters

nest (Union[List, Tuple, Dict, Array, NativeArray]) – The nested object to index.
index (Union[List[int], Tuple[int], Iterable[int]]) – A tuple of indices for indexing.

Return type

Any

Returns

ret – The result element through indexing the nested object.

Examples

With Tuple inputs:

>>> x = (1, 2)
>>> y = [0]
>>> z = ivy.index_nest(x, y)
>>> print(z)
1

With ivy.Array inputs:

>>> x = ivy.array([[1., 2.],
...                [3., 4.]])
>>> y = [1]
>>> z = ivy.index_nest(x, y)
>>> print(z)
ivy.array([3., 4.])

With Dict input:

>>> x = {'a': 0, 'b': [1, [2, 3]], 'c': (4, 5)}
>>> y = ('b', 1)
>>> z = ivy.index_nest(x, y)
>>> print(z)
[2, 3]

With List inputs:

>>> x = [['a', 'b', 'c'],
...      ['d', 'e', 'f'],
...      ['g', ['h', 'i']]]
>>> y = iter([2, 1, 0])
>>> z = ivy.index_nest(x, y)
>>> print(z)
h

ivy.insert_into_nest_at_index(nest, index, value, /)[source]

ivy.insert_into_nest_at_indices(nest, indices, values, /)[source]

Insert a value into the nested item at specified indices with specified values.

Parameters

nest (Iterable) – The nested object to insert into.
indices (Tuple) – A tuple of tuples of indices for the indices at which to insert values.
values – The new values for inserting.

ivy.map(fn, constant=None, unique=None, mean=False)[source]

Applies a function on each item of an iterable x.

Parameters

fn (Callable) – The function to map onto x.
constant (Optional[Dict[str, Any]]) – keyword arguments which remain constant between each function call. (default: None) Default is None.
unique (Optional[Dict[str, Iterable[Any]]]) – keyword arguments which are unique for each function call. Default is None. (default: None)
mean (bool) – Whether to compute the mean across the return values, and return this mean. (default: False) Default is False.

Return type

List

Returns

ret – x following the application of fn to each of its iterated items.

Examples

With int inputs:

>>> def special_square(x : float) -> float : return np.square(x)
>>> results = ivy.map(fn = special_square,
...                   constant = None,
...                   unique = {'x' : [1,2,3]},
...                   mean = False)
>>> print(results)
[1, 4, 9]

>>> results = ivy.map(fn = special_square,
...                   constant = None,
...                   unique = {'x':[0,1,2]},
...                   mean = True)
>>> print(results)
1.6666666666666667

>>> def special_pow(x:float,y:float) ->float : return np.power(x,y)
>>> results = ivy.map(fn = special_pow,
...                   constant = {'y':[0,1]},
...                   unique = {'x':[1,2,3]},
...                   mean = False)
>>> print(results)
[array([1,1]),
array([1,2]),
array([1,3])]

>>> results = ivy.map(fn = special_pow,
...                   constant = {'y':[0,1]},
...                   unique = {'x':[1,2,3]},
...                   mean = True)
>>> print(results)
[1. 2.]

With float inputs:

>>> def linear_model(w:float, x:float, b:float) -> float: return w*x + b
>>> results = ivy.map(fn = linear_model,
...                   constant = {'w':10., 'b':1.},
...                   unique = {'x':[0.,1.,2.]},
...                   mean = False)
>>> print(results)
[1.0, 11.0, 21.0]

With ivy.Array inputs:

>>> results = ivy.map(fn = linear_model,
...    constant = {'w':ivy.array([1.,0.,1.]), 'b':ivy.array([0.,10.,100.])},
...    unique = {'x':[ivy.array([0.,1.,0.]), ivy.array([1.,1.,1.])]},
...    mean = False)
>>> print(results)
[ivy.array([0., 10., 100.]),
ivy.array([1., 10., 101.])]

>>> results = ivy.map(fn = linear_model,
...    constant = {'w':ivy.array([1.,0.,1.]), 'b':ivy.array([0.,10.,100.])},
...    unique = {'x':[ivy.array([0.,1.,0.]), ivy.array([1.,1.,1.])]},
...    mean = True)
>>> print(results)
ivy.array([  0.5,  10. , 100. ])

ivy.map_nest_at_index(nest, index, fn, /)[source]

Map a function to the value of a nested item at a specified index.

Parameters

nest (Union[Array, NativeArray, Container, Dict, List]) – The nested object to update.
index (Sequence[Union[str, int]]) – A linear sequence of indices for the index at which to update.
fn (Callable[[Any], Any]) – The function to perform on the nested value at the given index.

Examples

With ivy.Array inputs:

>>> x = ivy.array([[1., 2.], [3., 4.]])
>>> y = (1, 1)
>>> z = lambda a: a + 1.
>>> ivy.map_nest_at_index(x, y, z)
>>> print(x)
ivy.array([[1., 2.], [3., 5.]])

>>> x = ivy.array([1., 2., 3., 4.])
>>> y = [1]
>>> z = lambda a: a + 3.
>>> ivy.map_nest_at_index(x, y, z)
>>> print(x)
ivy.array([1., 5., 3., 4.])

With Dict input:

>>> x = {1 : [1, [2, 3]], 2: (4, 5)}
>>> y = (1, 1)
>>> z = lambda _: 2
>>> ivy.map_nest_at_index(x, y, z)
>>> print(x)
{1: [1, 2], 2: (4, 5)}

With List inputs:

>>> x = [['a', 'b', 'c'],
...      ['d', 'e', 'f'],
...      ['g', ['h', 'i']]]
>>> y = (2, 1, 0)
>>> z = lambda a: a + 'H'
>>> ivy.map_nest_at_index(x, y, z)
>>> print(x)
[['a','b','c'],['d','e','f'],['g',['hH','i']]]

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([1., 2.]) , b=ivy.array([4., 5.]))
>>> y = ('b',)
>>> z = lambda _: ivy.array([3., 4.])
>>> ivy.map_nest_at_index(x, y, z)
>>> print(x)
{
    a: ivy.array([1., 2.]),
    b: ivy.array([3., 4.])
}

Return type: None

ivy.map_nest_at_indices(nest, indices, fn, /)[source]

Map a function to the values of a nested item at the specified indices.

Parameters

nest (Iterable) – The nested object to update.
indices (Tuple) – A tuple of tuples of indices for the indices at which to update.
fn (Callable) – The function to perform on the nest at the given index.

Examples

With List inputs:

>>> nest = [['a', 'c', 'e', 'd', 'u', 'k'], ['m', 'n', 'f', 'p', 'q', 't']]
>>> indices = [[0, 4], [1, 5]]
>>> function = lambda x : x + 'b'
>>> ivy.map_nest_at_indices(nest, indices, function)
>>> print(nest)
[['a', 'c', 'e', 'd', 'ub', 'k'], ['m', 'n', 'f', 'p', 'q', 'tb']]

With Tuple inputs:

>>> nest = ([-9, 8, -27],[9, -4, -5, 7])
>>> indices = ((0, 2),(1, 0),(1, 2))
>>> function = abs
>>> ivy.map_nest_at_indices(nest, indices, function)
>>> print(nest)
([-9, 8, 27], [9, -4, 5, 7])

With Dict input:

>>> nest = {'a': [8., 16., 22.], 'b': [10., 44., 81.], 'c': [9., 75., 37.]}
>>> indices = (('a', 2), ('b', 0), ('c', 1))
>>> function = lambda x : x + 1
>>> ivy.map_nest_at_indices(nest, indices, function)
>>> print(nest)
{'a': [8.0, 16.0, 23.0], 'b': [11.0, 44.0, 81.0], 'c': [9.0, 76.0, 37.0]}

With ivy.Array inputs:

>>> nest = ivy.array([[-9., 8., -17.],[11., -3., 5.]])
>>> indices = ((0, 1),(1, 1),(1, 2))
>>> function = lambda x : x ** 2
>>> ivy.map_nest_at_indices(nest, indices, function)
>>> print(nest)
ivy.array([[-9., 8., -17.], [11., -3., 5.]])

ivy.multi_index_nest(nest, indices, /)[source]

Repeatedly index a nested object, using a tuple of tuples of indices or keys in the case of dicts.

Parameters

nest (Iterable) – The nested object to slice.
indices (Tuple) – A tuple of tuples of indices to apply.

ivy.nested_any(nest, fn, check_nests=False, _base=True, extra_nest_types=None)[source]

Checks the leaf nodes of nest x via function fn, and returns True if any evaluate to True, else False.

Parameters

nest (Iterable) – The nest to check the leaves of.
fn (Callable) – The conditon function, returning True or False.
check_nests (bool) – Whether to also check the nests for the condition, not only nest leaves. (default: False) Default is False.
_base (bool) – Whether the current function call is the first function call in the recursive (default: True) stack. Used internally, do not set manually.
extra_nest_types (Optional[Union[type, Tuple[type]]]) – Types to recursively check when deciding whether to go deeper into the (default: None) nest or not

Return type

bool

Returns

ret – A boolean, whether the function evaluates to true for any leaf node.

ivy.nested_argwhere(nest, fn, check_nests=False, to_ignore=None, _index=None, _base=True, stop_after_n_found=None, extra_nest_types=None)[source]

Checks the leaf nodes of nested x via function fn, and returns all nest indices where the method evaluates as True.

Parameters

nest (Iterable) – The nest to check the leaves of.
fn (Callable) – The conditon function, returning True or False.
check_nests (bool) – Whether to also check the nests for the condition, not only nest leaves. (default: False) Default is False.
to_ignore (Optional[Union[type, Tuple[type]]]) – Types to ignore when deciding whether to go deeper into the nest or not (default: None)
_index (Optional[List]) – The indices detected so far. None at the beginning. Used internally, do not set (default: None) manually.
_base (bool) – Whether the current function call is the first function call in the recursive (default: True) stack. Used internally, do not set manually.
stop_after_n_found (Optional[int]) – to stop after some needed indices are found. (default: None)
extra_nest_types (Optional[Union[type, Tuple[type]]]) – Types to recursively check when deciding whether to go deeper into the (default: None) nest or not

Return type

Union[Iterable, bool]

Returns

ret – A set of indices for the nest where the function evaluated as True.

Examples

With List input:

>>> nest = [[[1, -2, 3], 19], [[9, -36, 80], -10.19]]
>>> fun = ivy.abs
>>> nested_indices = ivy.nested_argwhere(nest, fn=fun)
>>> print(nested_indices)
[
    [0, 0, 0], [0, 0, 1],
    [0, 0, 2], [0, 1],
    [1, 0, 0], [1, 0, 1],
    [1, 0, 2], [1, 1]
]

With Tuple input:

>>> nest = ([-5, 9, 2], [0.3, 4.])
>>> fun = ivy.abs
>>> nested_indices = ivy.nested_argwhere(nest, fn=fun, stop_after_n_found=4)
>>> print(nested_indices)
[[0, 0], [0, 1], [0, 2], [1, 0]]

With Dict input:

>>> nest={'a': [2., 0.6, -2.], 'b': [1., 4., 1.9], 'c': [9.4]}
>>> fun = ivy.abs
>>> nested_indices = ivy.nested_argwhere(nest, fn=fun)
>>> print(nested_indices)
[
    ['a', 0], ['a', 1],
    ['a', 2], ['b', 0],
    ['b', 1], ['b', 2],
    ['c', 0]
]

ivy.nested_map(x, /, fn, include_derived=None, to_mutable=False, max_depth=None, _depth=0, _tuple_check_fn=None, _list_check_fn=None, _dict_check_fn=None, extra_nest_types=None)[source]

Applies a function on x in a nested manner, whereby all dicts, lists and tuples are traversed to their lowest leaves before applying the method and returning x. If x is not nested, the method is applied to x directly.

Parameters

x (Union[Array, NativeArray, Iterable]) – The item to apply the mapped function to.
fn (Callable) – The function to map onto x.
include_derived (Optional[Union[Dict[type, bool], bool]]) – Whether to also recursive for classes derived from tuple, list and dict. (default: None) Default is False.
to_mutable (bool) – Whether to convert the nest to a mutable form, changing all tuples to lists. (default: False) Default is False.
max_depth (Optional[int]) – The maximum nested depth to reach. Default is 1. Increase this if the nest is (default: None) deeper.
_depth (int) – Placeholder for tracking the recursive depth, do not set this parameter. (default: 0)
_tuple_check_fn (Optional[Callable]) – Placeholder for the tuple check function, do not set this parameter. (default: None)
_list_check_fn (Optional[Callable]) – Placeholder for the list check function, do not set this parameter. (default: None)
_dict_check_fn (Optional[Callable]) – Placeholder for the dict check function, do not set this parameter. (default: None)
extra_nest_types (Optional[Union[type, Tuple[type]]]) – Types to recursively check when deciding whether to go deeper into the (default: None) nest or not

Return type

Union[Array, NativeArray, Iterable, Dict]

Returns

ret – x following the applicable of fn to it’s nested leaves, or x itself if x is not nested.

ivy.nested_multi_map(func, nests, key_chains=None, to_apply=True, prune_unapplied=False, key_chain='', config=None, to_ivy=True)[source]

Apply function to all array values from a collection of identically structured ivy arrays.

Parameters

func (Callable) – Function to apply to each nest entry.
nest – nests to map.
key_chains – The key-chains to apply or not apply the method to. Default is None.
to_apply – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.
prune_unapplied – Whether to prune key_chains for which the function was not applied, otherwise the leftmost nest value is used. Default is False.
key_chain – Chain of keys for this dict entry (Default value = ‘’)
config – The configuration for the nests. Default is the same as nest0.
to_ivy – convert the output to ivy_arrays. Default is True

Returns

nest containing the result of the function. The structure of the output is the
same as the input with the result of the function applied to each applicable
leaf and the value at that leaf in the first nest for a non-applicable leaf if
prune_unapplied is False else unapplied leaves are pruned.

ivy.prune_nest_at_index(nest, index, /)[source]

Prune a nested object at a specified index.

Parameters

nest (Iterable) – The nested object to prune.
index (Tuple) – A tuple of indices for the index at which to prune.

ivy.prune_nest_at_indices(nest, indices, /)[source]

Prune a nested object at specified indices.

Parameters

nest (Iterable) – The nested object to prune.
indices (Tuple) – A tuple of tuples of indices for the indices at which to prune.

ivy.set_nest_at_index(nest, index, value, /)[source]

Set the value of a nested item at a specified index.

Parameters

nest (Union[Array, NativeArray, Container, Dict, List]) – The nested object to update.
index (Sequence[Union[str, int]]) – A tuple of indices for the index at which to update.
value (Any) – The new value for updating.

Examples

With ivy.Array inputs:

>>> x = ivy.array([[1., 2.], [3., 4.]])
>>> y = (1, 1)
>>> z = 5.
>>> ivy.set_nest_at_index(x, y, z)
>>> print(x)
ivy.array([[1., 2.], [3., 5.]])

>>> x = ivy.array([1., 2., 3., 4.])
>>> y = [1]
>>> z = 5.
>>> ivy.set_nest_at_index(x, y, z)
>>> print(x)
ivy.array([1., 5., 3., 4.])

With Dict input:

>>> x = {1 : [1, [2, 3]], 2: (4, 5)}
>>> y = (1, 1)
>>> z = 2
>>> ivy.set_nest_at_index(x, y, z)
>>> print(x)
{1: [1, 2], 2: (4, 5)}

With List inputs:

>>> x = [['a', 'b', 'c'],
...      ['d', 'e', 'f'],
...      ['g', ['h', 'i']]]
>>> y = (2, 1, 0)
>>> z = 'H'
>>> ivy.set_nest_at_index(x, y, z)
>>> print(x)
[['a','b','c'],['d','e','f'],['g',['H','i']]]

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([1., 2.]) , b=ivy.array([4., 5.]))
>>> y = ('b',)
>>> z = ivy.array([3., 4.])
>>> ivy.set_nest_at_index(x, y, z)
>>> print(x)
{
    a: ivy.array([1., 2.]),
    b: ivy.array([3., 4.])
}

ivy.set_nest_at_indices(nest, indices, values, /)[source]

Set the value of a nested item at specified indices with specified values.

Parameters

nest (Union[List, Tuple, Dict, Array, NativeArray]) – The nested object to update.
indices (Union[List[int], Tuple[int], Iterable[int]]) – A tuple of tuples of indices for the indices at which to update.
values (Union[List[int], Tuple[int], Iterable[int]]) – The new values for updating.

Examples

With List inputs:

>>> nest = [[1, 2, 3, 4, 5, 6], ['a', 'b', 'c', 'd', 'e', 'f']]
>>> indices = [[0, 4], [1, 3]]
>>> values = [111, 'x']
>>> ivy.set_nest_at_indices(nest, indices, values)
>>> print(nest)
[[1, 2, 3, 4, 111, 6], ['a', 'b', 'c', 'x', 'e', 'f']]

With Tuple inputs:

>>> nest = [['abc', 'xyz', 'pqr'],[1, 4, 'a', 'b']]
>>> indices = ((0, 1),(1, 2))
>>> values = ('ivy', 'x')
>>> ivy.set_nest_at_indices(nest, indices, values)
>>> print(nest)
(['abc', 'ivy', 'pqr'], [1, 4, 'x', 'b'])

With Dict input:

>>> nest = {'a': [1., 2., 3.], 'b': [4., 5., 6.], 'c': [0.]}
>>> indices = (('a', 1), ('b', 2), ('c', 0))
>>> values = (11., 22., 33.)
>>> ivy.set_nest_at_indices(nest, indices, values)
>>> print(nest)
{'a': [1.0, 11.0, 3.0], 'b': [4.0, 5.0, 22.0], 'c': [33.0]}

With ivy.Array inputs:

>>> nest = ivy.array([[1., 2., 3.],[4., 5., 6.]])
>>> indices = ((0, 1),(1, 2))
>>> values = (11., 22.)
>>> ivy.set_nest_at_indices(nest, indices, values)
>>> print(nest)
ivy.array([[1., 11., 3.], [4., 5., 22.]])

Return type: Any

This should have hopefully given you an overview of the nest submodule,If you have any questions, please feel free to reach out on our discord in the nest channel or in the nest forum!