Nest

Collection of Ivy functions for nested objects.

ivy.all_nested_indices(nest, include_nests=False, _index=None, _base=True)[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.
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.

Return type

Union[Iterable, bool]

Returns

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

ivy.copy_nest(nest, include_derived=False, to_mutable=False)[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.

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 (Iterable) – The nested object to update.
index (Tuple) – A tuple of indices for the index at which to update.
fn (Callable) – The function to perform on the nest at the given index.

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.

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)[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.

Return type

bool

Returns

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

ivy.nested_indices_where(nest, fn, check_nests=False, to_ignore=None, _index=None, _base=True, stop_after_n_found=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)

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_indices_where(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_indices_where(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_indices_where(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)[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)

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 funciton.

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