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_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
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