Container

class ivy.Container(dict_in=None, queues=None, queue_load_sizes=None, container_combine_method='list_join', queue_timeout=None, print_limit=10, print_indent=4, print_line_spacing=0, ivyh=None, keyword_color_dict=None, rebuild_child_containers=False, types_to_iteratively_nest=None, **kwargs)[source]

Bases: dict

__init__(dict_in=None, queues=None, queue_load_sizes=None, container_combine_method='list_join', queue_timeout=None, print_limit=10, print_indent=4, print_line_spacing=0, ivyh=None, keyword_color_dict=None, rebuild_child_containers=False, types_to_iteratively_nest=None, **kwargs)[source]

Initialize container object from input dict representation.

Parameters
  • dict_in (dict, optional) – the dictionary the container should wrap around. Default is None.

  • queues (sequence of multiprocessing queues, optional) – Sequence of multiprocessing queues, each of which returns containers. This enables the current container to be passed around asynchronously while waiting for data. Default is None.

  • queue_load_sizes (sequence of ints, optional) – Size of leading dimension of the containers returned by each queue. Default is None.

  • container_combine_method (str, optional) – The method to use for combining containers arriving from different queues. Default is ivy.Container.list_join

  • queue_timeout (float, optional) – The timeout when waiting for containers to arrive from the queues. Default is global.

  • print_limit (int, optional) – The total array size limit when printing the container. Default is 10.

  • print_indent (int, optional) – The number of whitespaces to use for indenting when printing the container. Default is 4.

  • print_line_spacing (int, optional) – The number of extra newlines to use between keys when printing the container. Default is 0.

  • ivyh (handle to ivy module, optional) – Handle to ivy module to use for the calculations. Default is None, which results in the global ivy.

  • keyword_color_dict (dict, optional) – A dict mapping keywords to their termcolor color codes for printing the container.

  • rebuild_child_containers (bool, optional) – Whether to rebuild container found in dict_in with these constructor params. Default is False, in which case the original container are kept as are.

  • types_to_iteratively_nest (seq of iterable types) – The data types to nest iteratively in the dict structure, each type must be iterable. Default is None.

  • kwargs (keyword arguments.) – keyword arguments for dict creation. Default is None.

all_false(assert_is_bool=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Determine whether all the entries in the container boolean evaluate to False.

Parameters
  • assert_is_bool (bool, optional) – Whether or not to assert each entry is of type Boolean.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Boolean, whether all entries are boolean False.

all_true(assert_is_bool=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Determine whether all the entries in the container boolean evaluate to True.

Parameters
  • assert_is_bool (bool, optional) – Whether or not to assert each entry is of type Boolean.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Boolean, whether all entries are boolean True.

arrays_as_lists(key_chains=None, to_apply=True, prune_unapplied=False)[source]

Converts all nested arrays to lists, a useful intermediate step for conversion to other framework array types.

Parameters
  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

container with each array converted to a list.

as_arrays(key_chains=None, to_apply=True, prune_unapplied=False)[source]

Converts all nested variables to arrays, which do not support gradient computation.

Parameters
  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

container with each variable converted to an array.

as_bools(assert_is_bool=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Return boolean evaluation for all nested items in the container.

Parameters
  • assert_is_bool (bool, optional) – Whether or not to assert the entry is of type Boolean.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all entries boolean evaluated.

as_ones(key_chains=None, to_apply=True, prune_unapplied=False)[source]

Return arrays of ones for all nested arrays in the container.

Parameters
  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-arrays filled with ones.

as_random_uniform(low=0.0, high=1.0, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Return arrays of random uniform values for all nested arrays in the container.

Parameters
  • low (float) – Lower boundary of the output interval. All values generated will be greater than or equal to low. The default value is 0.

  • high (float) – Upper boundary of the output interval. All values generated will be less than high. The default value is 1.0.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-arrays filled with random uniform values.

as_variables(key_chains=None, to_apply=True, prune_unapplied=False)[source]

Converts all nested arrays to variables, which support gradient computation.

Parameters
  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

container with each array converted to a variable.

as_zeros(key_chains=None, to_apply=True, prune_unapplied=False)[source]

Return arrays of zeros for all nested arrays in the container.

Parameters
  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-arrays filled with zeros.

at_key_chain(key_chain, ignore_key_errors=False)[source]

Query container object at a specified key-chain

Returns

sub-container or value at specified key chain

at_key_chains(key_chains, ignore_none=True, ignore_key_errors=False)[source]

Query container object at specified key-chains, either as list or nested dict.

Returns

sub-container containing only the specified key chains

at_keys(queries, ignore_none=True, containing=False, ignore_key_errors=False)[source]

Query container object at specified keys, either as list or nested dict.

Parameters
  • queries (sequence of strs or single str) – The keys to query.

  • ignore_none (bool, optional) – Whether to ignore None input. Default is True.

  • containing (bool, optional) – Whether to include keys which only contain the query substrings. Default is False.

  • ignore_key_errors (bool, optional) – Whether to ignore Key-errors when trying to access the dict. Default is False.

Returns

sub-container containing only key-chains containing the specified keys.

clip(clip_min, clip_max, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes the elementwise clipped values between this container and clip_min and clip_max containers or numbers.

Parameters
  • clip_min (Ivy container or number) – The minimum container or number to clip against.

  • clip_max (Ivy container or number) – The maximum container or number to clip against.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-arrays having the clipped values returned.

clip_vector_norm(max_norm, p, global_norm=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes the elementwise clipped values between this container and clip_min and clip_max containers or numbers.

Parameters
  • max_norm (Ivy container or number) – The max norm container or number to clip against.

  • p (Ivy container or number) – The p-value for computing the p-norm container or number.

  • global_norm (bool, optional) – Whether to compute the norm across all the concattenated sub-arrays. Default is False.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-arrays having the clipped norms returned.

static combine(*containers, config=None)[source]

Combine keys and values in a sequence of containers, with priority given to the right-most container in the case of duplicates.

Parameters
  • containers (sequence of Container objects) – containers to compare

  • config (dict, optional) – The configuration for the containers. Default is the same as container_rightmost.

Returns

Combined containers

static concat(containers, dim, config=None)[source]

Concatenate containers together along the specified dimension.

Parameters
  • containers (sequence of Container objects) – containers to concatenate

  • dim (int) – dimension along which to concatenate

  • config (dict, optional) – The configuration for the containers. Default is the same as container0.

Returns

Concatenated containers

property config
copy()[source]

Create a copy of this container.

Returns

A copy of the container

deep_copy()[source]

Create a deep copy (copying all internal tensors) of this container.

Returns

A deep copy of the container

dev_clone(dev_strs)[source]

Clone the current container across multiple devices.

Parameters

dev_strs (sequence of str) – The devices on which to clone the container.

Returns

a set of cloned containers across the specified devices.

dev_dist(dev_strs: Union[Iterable[str], Dict[str, int]], axis=0)[source]

Distribute the current container across multiple devices.

Parameters
  • dev_strs (sequence of strs or dict of split sizes) – The devices along which to distribute the container.

  • axis (int, optional) – The axis along which to split the arrays at the container leaves. Default is 0.

Returns

a set of distributed sub-containers across the specified devices.

property dev_str

The device to which the arrays in the container belong, with None returned if the devices are not consistent

static diff(*containers, mode='all', diff_keys='diff', detect_key_diffs=True, config=None)[source]

Compare keys and values in a sequence of containers, returning the single shared values where they are the same, and new nested sub-dicts with all values where they are different.

Parameters
  • containers (sequence of Container objects) – containers to compare

  • mode (str, optional) – The mode of the diff operation, returning either all keys and values, only those that are consist across the containers, or only the differences. Default is all.

  • diff_keys (str or list of strs, optional) – The key/keys to add to the returned container when differences are found. Default is “diff”.

  • detect_key_diffs (bool, optional) – Whether to treat different keys as detected differences. If not, the keys among the input containers are simply combined without flagging differences. Default is True.

  • config (dict, optional) – The configuration for the containers. Default is the same as container0.

Returns

Compared containers

dtype()[source]

Return container, with all entries replaced with their data types.

Returns

New datatype container

einops_rearrange(pattern, key_chains=None, to_apply=True, prune_unapplied=False, **axes_lengths)[source]

Perform einops rearrange operation on each sub array in the container.

Parameters
  • pattern (str) – Rearrangement pattern.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

  • axes_lengths (keyword parameter args) – Any additional specifications for dimensions.

Returns

ivy.Container with each array having einops.rearrange applied.

einops_reduce(pattern, reduction, key_chains=None, to_apply=True, prune_unapplied=False, **axes_lengths)[source]

Perform einops reduce operation on each sub array in the container.

Parameters
  • pattern (str) – Reduction pattern.

  • reduction (str or callable) – One of available reductions (‘min’, ‘max’, ‘sum’, ‘mean’, ‘prod’), or callable.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

  • axes_lengths (keyword parameter args) – Any additional specifications for dimensions.

Returns

ivy.Container with each array having einops.reduce applied.

einops_repeat(pattern, key_chains=None, to_apply=True, prune_unapplied=False, **axes_lengths)[source]

Perform einops repeat operation on each sub array in the container.

Parameters
  • pattern (str) – Rearrangement pattern.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

  • axes_lengths (keyword parameter args) – Any additional specifications for dimensions.

Returns

ivy.Container with each array having einops.repeat applied.

einsum(equation, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Sums the product of the elements of the input operands along dimensions specified using a notation based on the Einstein summation convention, for each array in the container.

Parameters
  • equation (str) – A str describing the contraction, in the same format as numpy.einsum.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions expanded along the axis.

expand_dims(axis, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Expand dims of all sub-arrays of container object.

Parameters
  • axis (int) – Axis along which to expand dimensions of the sub-arrays.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions expanded along the axis.

flip(axis=None, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Reverses the order of elements in for each array in the container, along the given axis. The shape of the array is preserved, but the elements are reordered.

Parameters
  • axis (None or int or sequence of ints, optional) – Axis or axes along which to flip over. The default, axis=None, will flip over all axes.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions expanded along the axis.

static from_disk_as_hdf5(h5_obj_or_filepath, slice_obj=slice(None, None, None), ivyh=None)[source]

Load container object from disk, as an h5py file, at the specified hdf5 filepath.

Parameters
  • h5_obj_or_filepath (str or h5 obj) – Filepath where the container object is saved to disk, or h5 object.

  • slice_obj (slice or sequence of slices) – slice object to slice all h5 elements.

  • ivyh (handle to ivy module, optional) – Handle to ivy module to use for the calculations. Default is None, which results in the global ivy.

Returns

Container loaded from disk

static from_disk_as_json(json_filepath, ivyh=None)[source]

Load container object from disk at the specified json filepath. If some objects were not json-able during saving, then they will be loaded as strings.

Parameters
  • json_filepath (str) – Filepath where the container object is saved to disk.

  • ivyh (handle to ivy module, optional) – Handle to ivy module to use for the calculations. Default is None, which results in the global ivy.

Returns

Container loaded from disk

static from_disk_as_pickled(pickle_filepath, ivyh=None)[source]

Load container object from disk at the specified pickle filepath.

Parameters
  • pickle_filepath (str) – Filepath where the container object is saved to disk.

  • ivyh (handle to ivy module, optional) – Handle to ivy module to use for the calculations. Default is None, which results in the global ivy.

Returns

Container loaded from disk

from_flat_list(flat_list)[source]

Return new container object with the same hierarchy, but with values replaced from flat list.

Parameters

flat_list (sequence of arrays) – flat list of values to populate container with.

Returns

Container.

gather(indices, axis=- 1, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Gather slices from all container params at axis according to indices.

Parameters
  • indices (array) – Index array.

  • axis (int, optional) – The axis from which to gather from. Default is -1.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions gathered along the axis.

gather_nd(indices, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Gather slices from all container params into a arrays with shape specified by indices.

Parameters
  • indices (array) – Index array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions gathered.

static h5_file_size(h5_obj_or_filepath)[source]

Get file size of h5 file contents.

Parameters

h5_obj_or_filepath (str or h5 obj) – Filepath where the container object is saved to disk, or h5 object.

Returns

Size of h5 file contents, and batch size.

has_key(query_key)[source]

Determine whether container object has specified key somewhere in the nested structure

Returns

Boolean

has_key_chain(key_chain)[source]

Determine whether container object has specified key-chain

Returns

Boolean

has_nans(include_infs=True, leafwise=False)[source]

Determine whether arrays in the container contain any nans, as well as infs or -infs if specified.

Parameters
  • include_infs (bool, optional) – Whether to include infs and -infs in the check. Default is True.

  • leafwise (bool, optional) – Whether to apply the check leaf-wise, and return a container of booleans. Default is False, in which case the check is applied across the entire container, returning a single boolean.

Returns

Whether the container has any nans, applied either leafwise or across the entire container.

static identical_structure(containers, check_types=True, key_chains=None, to_apply=True, key_chain='')[source]

Returns a single boolean as to whether the input containers have identical key-chains and data types.

Parameters
  • containers (sequence of Container objects) – containers to map.

  • check_types (bool, optional) – Whether to also check whether the datatypes of the leaf nodes are the same. Default is True.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • key_chain (str) – Chain of keys for this dict entry

Returns

Boolean

if_exists(key)[source]

Returns the sub-container at the following key if it exists, otherwise None.

property ivy
static list_join(containers, config=None)[source]

Join containers of lists together along the specified dimension.

Parameters
  • containers (sequence of Container objects) – containers to list join

  • config (dict, optional) – The configuration for the containers. Default is the same as container0.

Returns

List joined containers, with each entry being a list of arrays

static list_stack(containers, dim, config=None)[source]

List stack containers together along the specified dimension.

Parameters
  • containers (sequence of Container objects) – containers to list stack

  • dim (int) – dimension along which to list stack

  • config (dict, optional) – The configuration for the containers. Default is the same as container0.

Returns

Stacked containers, with each entry being a list of arrays

map(func, key_chains=None, to_apply=True, prune_unapplied=False, key_chain='')[source]

Apply function to all array values of container

Parameters
  • func (python function) – Function to apply to each container entry

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

  • key_chain (str) – Chain of keys for this dict entry

Returns

New container following the function mapped to each sub-array.

map_conts(func, key_chains=None, to_apply=True, prune_unapplied=False, include_self=True, key_chain='')[source]

Apply function to all sub-contains in the container.

Parameters
  • func (python function) – Function to apply to each sub-container

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

  • include_self (bool, optional) – Whether to also apply the (possiby in-place) function to this container. Default is True.

  • key_chain (str) – Chain of keys for this dict entry

Returns

New container following the function mapped to each sub-container.

matrix_norm(p=2, axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Compute matrix p-norm for each array in the container.

Parameters
  • p (int or str, optional) – Order of the norm. Default is 2.

  • axis (int or sequence of ints, optional) – If axis is an integer, it specifies the axis of x along which to compute the matrix norms. Default is None, in which case the flattened array is considered.

  • keepdims (bool, optional) – If this is set to True, the axes which are normed over are left in the result as dimensions with size one. With this option the result will broadcast correctly against the original x. Default is False.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with the matrix norms for each sub-array returned.

maximum(other, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes the elementwise maximum between this container and another container or number.

Parameters
  • other (Ivy container or number) – The other container or number to compute the maximum against.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-arrays having the maximum values computed.

minimum(other, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes the elementwise minimum between this container and another container or number.

Parameters
  • other (Ivy container or number) – The other container or number to compute the minimum against.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-arrays having the minimum values computed.

static multi_map(func, containers, key_chains=None, to_apply=True, prune_unapplied=False, key_chain='', config=None)[source]

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

Parameters
  • func (python function) – Function to apply to each container entry.

  • containers (sequence of Container objects) – containers to map.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied, otherwise the leftmost container value is used. Default is False.

  • key_chain (str) – Chain of keys for this dict entry

  • config (dict, optional) – The configuration for the containers. Default is the same as container0.

Returns

Contaienr

overwrite_at_key_chain(key_chain, val, inplace=False)[source]

Overwrite value of container object at a specified key-chain

Returns

new container with updated value at key chain, provided it existed before.

overwrite_at_key_chains(target_dict, return_dict=None, inplace=False)[source]

Overwrite values of container object at specified key-chains

Returns

new container with updated values at the key chains, provided they existed before.

prune_empty(keep_Nones=False, base=True)[source]

Recursively prunes empty keys from the container dict structure. Returns None if the entire container is empty.

Returns

Container with empty keys pruned.

prune_key_chain(key_chain)[source]

Recursively prune chain of keys, specified as ‘key1/key2/key3/…’

Returns

Container with keys in key chain pruned.

prune_key_chains(key_chains, ignore_none=True)[source]

Recursively prune set of key chains

Returns

Container with keys in the set of key chains pruned.

prune_key_from_key_chains(absolute=None, containing=None)[source]

Recursively prune absolute key or key containing a certain substring from all key chains.

Parameters
  • absolute (str, optional) – The absolute key to detect in the key chains.

  • containing (str, optional) – A substring to check each key for, when deciding which keys to prune.

Returns

Container with specified key or substring-containing-key from all key chains removed from the chain.

prune_keys(query_keys, ignore_none=True)[source]

Recursively prune set of keys

Returns

Container with key-chains containing the specified keys pruned.

prune_keys_from_key_chains(absolute=None, containing=None)[source]

Recursively prune absolute keys or keys containing certain substrings from all key chains.

Parameters
  • absolute (sequence of strs, optional) – The absolute key to detect in the key chains.

  • containing (sequence of strs, optional) – A substring to check each key for, when deciding which keys to prune.

Returns

Container with specified keys or substring-containing-keys from all key chains removed from the chain.

static reduce(containers, reduction, config=None)[source]

Reduce containers.

Parameters
  • containers (sequence of Container objects) – containers to reduce

  • reduction (callable with single list input x) – the reduction function

  • config (dict, optional) – The configuration for the containers. Default is the same as container0.

Returns

reduced containers

reduce_max(axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes max of array elements along a given axis for all sub-arrays of container object.

Parameters
  • axis (int or sequence of ints) – Axis or axes along which a max is performed. The default, axis=None, will max all of the elements of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a max is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before.

  • keepdims (bool, optional) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions expanded along the axis.

reduce_mean(axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes mean of array elements along a given axis for all sub-arrays of container object.

Parameters
  • axis (int or sequence of ints) – Axis or axes along which a mean is performed. The default, axis=None, will mean all of the elements of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a mean is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before.

  • keepdims (bool, optional) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions expanded along the axis.

reduce_min(axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes min of array elements along a given axis for all sub-arrays of container object.

Parameters
  • axis (int or sequence of ints) – Axis or axes along which a min is performed. The default, axis=None, will min all of the elements of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a min is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before.

  • keepdims (bool, optional) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions expanded along the axis.

reduce_prod(axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes product of array elements along a given axis for all sub-arrays of container object.

Parameters
  • axis (int or sequence of ints) – Axis or axes along which a product is performed. The default, axis=None, will multiply all of the elements of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a multiplication is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before.

  • keepdims (bool, optional) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions expanded along the axis.

reduce_std(axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes standard deviation of array elements along a given axis for all sub-arrays of container object.

Parameters
  • axis (int or sequence of ints) – Axis or axes along which a var is performed. The default, axis=None, will var all of the elements of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a var is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before.

  • keepdims (bool, optional) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with the standard deviation computed for all sub-arrays.

reduce_sum(axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes sum of array elements along a given axis for all sub-arrays of container object.

Parameters
  • axis (int or sequence of ints) – Axis or axes along which a sum is performed. The default, axis=None, will sum all of the elements of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a sum is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before.

  • keepdims (bool, optional) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-array dimensions expanded along the axis.

reduce_var(axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Computes variance of array elements along a given axis for all sub-arrays of container object.

Parameters
  • axis (int or sequence of ints) – Axis or axes along which a var is performed. The default, axis=None, will var all of the elements of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a var is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before.

  • keepdims (bool, optional) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with the variance computed for all sub-arrays.

remove_print_limit()[source]
repeat(repeats, axis=None, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Repeat values along a given dimension for each array in the container.

Parameters
  • repeats (int or sequence of ints.) – Number of repetitions for each element. repeats is broadcast to fit the shape of the given axis.

  • axis (int, optional) – The axis along which to repeat values. By default, use the flattened input array, and return a flat output array.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

container with each array being repeated along the specified dimension.

reshape(pre_shape=None, shape_slice=None, post_shape=None, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Reshapes each array x in the container, to a new shape given by pre_shape + x.shape[shape_slice] + post_shape. If shape_slice or post_shape are not specified, then the term is ignored.

Parameters
  • pre_shape (int or sequence of ints, optional) – The first elements in the new array shape.

  • shape_slice (int or sequence of ints, optional) – The slice of the original shape to use in the new shape. Default is None.

  • post_shape (sequence of ints, optional) – The final elements in the new array shape. Default is None.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

ivy.Container with each array reshaped as specified.

reshape_like(target_dict, leading_shape=None, return_cont=None)[source]

Set shapes of container entries to shapes specified by new container with the same key structure

Returns

new container with values of updated shapes

restructure_keys(key_chain_mapping)[source]

Restructure the keys of the container.

Parameters

key_chain_mapping (sequence of len-2 sequences) – Sequence of lists/tuples of key chain mapping to apply, with original and new key chains being the left and right terms respectively.

Returns

New contaienr with the key chains updated.

set_at_key_chain(key_chain, val, inplace=False)[source]

Set value of container object at a specified key-chain

Returns

new container with updated value at key chain

set_at_key_chains(target_dict, return_dict=None, inplace=False)[source]

Set values of container object at specified key-chains

Returns

new container with updated values at the key chains

set_at_keys(target_dict)[source]

Set values of container object at specified keys

Returns

new container with updated value at each key

set_framework(ivyh)[source]

Update the framework to use for the container.

property shape

The shape of the arrays in the container, with None placed in indices which are not consistent across arrays

property shapes

The shapes of each array in the container, with None placed in leaf entries without a shape attribute.

shuffle(seed_value=None, key_chains=None, to_apply=True, prune_unapplied=False, key_chain='')[source]

Shuffle entries in all sub-arrays, such that they are still aligned along axis 0.

Parameters
  • seed_value (int) – random seed to use for array shuffling

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

  • key_chain (str) – Chain of keys for this dict entry

static shuffle_h5_file(h5_obj_or_filepath, seed_value=0)[source]

Shuffle entries in all datasets of h5 file, such that they are still aligned along axis 0.

Parameters
  • h5_obj_or_filepath (str or h5 obj) – Filepath where the container object is saved to disk, or h5 object.

  • seed_value (int) – random seed to use for array shuffling

slice_via_key(slice_key)[source]

Get slice of container, based on key.

Parameters

slice_key (str) – key to slice container at.

Returns

Container object sliced at desired key.

sort_by_key()[source]
split(num_or_size_splits=None, axis=0, with_remainder=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Splits a container into multiple sub-containers, by splitting their constituent arrays.

Parameters
  • num_or_size_splits (int, optional) – Number of equal arrays to divide the array into along the given axis if an integer. The size of each split element if a sequence of integers. Default is to divide into as many 1-dimensional arrays as the axis dimension.

  • axis (int, optional) – The axis along which to split, default is 0.

  • with_remainder (bool, optional) – If the tensor does not split evenly, then store the last remainder entry. Default is False.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

A list of sub-arrays.

static stack(containers, dim, config=None)[source]

Stack containers together along the specified dimension.

Parameters
  • containers (sequence of Container objects) – containers to stack

  • dim (int) – dimension along which to stack

  • config (dict, optional) – The configuration for the containers. Default is the same as container0.

Returns

Stacked containers

stop_gradients(preserve_type=True, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Stop gradients of all array entries in the container.

Parameters
  • preserve_type – Whether to preserve the input type (ivy.Variable or ivy.Array), otherwise an array is always returned. Default is True.

  • preserve_type – bool, optional

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

container with each array having their gradients stopped.

swapaxes(axis0, axis1, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Interchange two axes for each array in the container.

Parameters
  • axis0 (int) – First axis to be swapped.

  • axis1 (int) – Second axis to be swapped.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

ivy.Container with each chosen array having the axes swapped.

to_dev(dev_str, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Move the container arrays to the desired device, specified by device string.

Parameters
  • dev_str (str, optional) – device to move the array to ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Keep same device if None.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

The container, but with each sub-array now placed on the target device.

to_dict()[source]

Return nested pure dict representation of container object.

Returns

Container as nested dict.

to_disk_as_hdf5(h5_obj_or_filepath, starting_index=0, mode='a', max_batch_size=None)[source]

Save container object to disk, as an h5py file, at the specified filepath.

Parameters
  • h5_obj_or_filepath (str or h5 object) – Filepath for where to save the container to disk, or h5 object.

  • starting_index (int) – Batch index for which to start writing to file, if it already exists

  • mode (str) – H5 read/write mode for writing to disk, [‘r’, ‘r+’, ‘w’, ‘w-‘, ‘a’], default is ‘a’.

  • max_batch_size (int) – Maximum batch size for the container on disk, this is useful if later appending to file.

to_disk_as_json(json_filepath)[source]

Save container object to disk, as an json file, at the specified filepath.

Parameters

json_filepath (str) – Filepath for where to save the container to disk.

to_disk_as_pickled(pickle_filepath)[source]

Save container object to disk, as an pickled file, at the specified filepath.

Parameters

pickle_filepath (str) – Filepath for where to save the container to disk.

to_flat_list()[source]

Return flat list representation of container object.

Returns

Container as flat list.

to_iterator(key_chain='', leaf_keys_only=False)[source]

Return iterator for traversing through the nested elements of container object.

Returns

Iterator for the container elements.

to_iterator_keys(key_chain='', leaf_keys_only=False)[source]

Return iterator for traversing through the nested keys of container object.

Returns

Iterator for the container elements.

to_iterator_values()[source]

Return iterator for traversing through the nested values of container object.

Returns

Iterator for the container values.

to_ivy(nested=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Return ivy arrays for all nested native framework arrays in the container.

Parameters
  • nested (bool, optional) – Whether to apply the conversion on arguments in a nested manner. If so, all dicts, lists and tuples will be traversed to their lowest leaves in search of ivy.Array and ivy.Variable instances. Default is False.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all native sub-arrays converted to their ivy.Array instances.

to_jsonable(return_dict=None)[source]

Return container with non-jsonable elements converted to string representations, which are jsonable.

to_list()[source]

Return nested list representation of container object.

Returns

Container as nested list.

to_multi_dev(dev_strs, axis=0)[source]

Return a single MultiDevContainer, which shares the same structure as the current container, but replaces arrays at the leaves with DistributedArray instances.

Parameters
  • dev_strs (sequence of str) – The devices along which to distribute each array in the container.

  • axis (int, optional) – The axis along which to split the arrays at the container leaves. Default is 0.

Returns

a MultiDevContainer instance, with all leafs arrays replaced by DistributedArray instances.

to_native(nested=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Return native framework arrays for all nested arrays in the container.

Parameters
  • nested (bool, optional) – Whether to apply the conversion on arguments in a nested manner. If so, all dicts, lists and tuples will be traversed to their lowest leaves in search of ivy.Array and ivy.Variable instances. Default is False.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with all sub-arrays converted to their native format.

to_numpy(key_chains=None, to_apply=True, prune_unapplied=False)[source]

Converts all nested ivy arrays to numpy arrays.

Parameters
  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

container with each ivy array converted to a numpy array.

to_raw()[source]

Return nested raw representation of container object. This includes restoring lists and tuples passed in the constructor to their original form.

Returns

Container data in it’s raw form.

try_kc(key)[source]

Tries the following key or key chain, returning self if not present.

static unify(containers, dev_str, mode, axis=0)[source]

Unify a list of containers, on arbitrary devices, to a single container on the specified device.

Parameters
  • containers (sequence of Container objects) – containers to unify

  • dev_str (str) – The device to unify the containers to.

  • mode (str) – The mode by which to unify, must be one of [ concat | mean | sum ]

  • axis (int, optional) – The axis along which to concattenate the container, if concat mode is set. Default is 0.

Returns

Unified container

unstack(axis, keepdims=False, dim_size=None)[source]

Unstack containers along specified dimension.

Parameters
  • axis (int) – Dimensions along which to unstack.

  • keepdims (bool, optional) – Whether to keep dimension 1 in the unstack dimensions. Default is False.

  • dim_size (int, optional) – Size of the dimension to unstack. Determined from inputs by default.

Returns

List of containers, unstacked along the specified dimension.

vector_norm(p=2, axis=None, keepdims=False, global_norm=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]

Compute vector p-norm for each array in the container.

Parameters
  • p (int or str or container, optional) – Order of the norm. Default is 2.

  • axis (int or sequence of ints, optional) – If axis is an integer, it specifies the axis of x along which to compute the vector norms. Default is None, in which case the flattened array is considered.

  • keepdims (bool, optional) – If this is set to True, the axes which are normed over are left in the result as dimensions with size one. With this option the result will broadcast correctly against the original x. Default is False.

  • global_norm (bool, optional) – Whether to compute the norm across all the concattenated sub-arrays. Default is False.

  • key_chains (list or dict of strs, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

Returns

Container object with the vector norms for each sub-array returned.

with_entries_as_lists()[source]

Return container object, with each array entry in the container cast to a list

with_print_indent(print_indent)[source]
with_print_limit(print_limit)[source]
with_print_line_spacing(print_line_spacing)[source]

Supported Frameworks:

empty jax_logo empty tf_logo empty pytorch_logo empty mxnet_logo empty numpy_logo empty