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 keychains 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 keychains 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 keychains 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 keychains 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 keychains 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 keychains 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 subarrays 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 keychains 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 subarrays 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 keychains 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 keychains 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 subarrays filled with zeros.

at_key_chain
(key_chain, ignore_key_errors=False)[source]¶ Query container object at a specified keychain
 Returns
subcontainer or value at specified key chain

at_key_chains
(key_chains, ignore_none=True, ignore_key_errors=False)[source]¶ Query container object at specified keychains, either as list or nested dict.
 Returns
subcontainer 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 Keyerrors when trying to access the dict. Default is False.
 Returns
subcontainer containing only keychains 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 keychains 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 subarrays 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 pvalue for computing the pnorm container or number.
global_norm (bool, optional) – Whether to compute the norm across all the concattenated subarrays. Default is False.
key_chains (list or dict of strs, optional) – The keychains 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 subarrays 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 rightmost 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
¶

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 subcontainers 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 subdicts 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 keychains 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 keychains 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 keychains 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 keychains 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 subarray dimensions expanded along the axis.

expand_dims
(axis, key_chains=None, to_apply=True, prune_unapplied=False)[source]¶ Expand dims of all subarrays of container object.
 Parameters
axis (int) – Axis along which to expand dimensions of the subarrays.
key_chains (list or dict of strs, optional) – The keychains 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 subarray 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 keychains 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 subarray 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 jsonable 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 keychains 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 subarray 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 keychains 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 subarray 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 keychain
 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 leafwise, 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 keychains 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 keychains 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 subcontainer 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 keychains 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 subarray.

map_conts
(func, key_chains=None, to_apply=True, prune_unapplied=False, include_self=True, key_chain='')[source]¶ Apply function to all subcontains in the container.
 Parameters
func (python function) – Function to apply to each subcontainer
key_chains (list or dict of strs, optional) – The keychains 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 inplace) 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 subcontainer.

matrix_norm
(p=2, axis=None, keepdims=False, key_chains=None, to_apply=True, prune_unapplied=False)[source]¶ Compute matrix pnorm 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 keychains 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 subarray 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 keychains 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 subarrays 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 keychains 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 subarrays 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 keychains 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 keychain
 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 keychains
 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 substringcontainingkey from all key chains removed from the chain.

prune_keys
(query_keys, ignore_none=True)[source]¶ Recursively prune set of keys
 Returns
Container with keychains 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 substringcontainingkeys 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 subarrays 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 keychains 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 subarray 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 subarrays 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 keychains 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 subarray 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 subarrays 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 keychains 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 subarray 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 subarrays 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 keychains 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 subarray 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 subarrays 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 keychains 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 subarrays.

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 subarrays 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 keychains 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 subarray 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 subarrays 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 keychains 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 subarrays.

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 keychains 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 keychains 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 len2 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 keychain
 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 keychains
 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

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 subarrays, 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 keychains 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.

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 subcontainers, 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 1dimensional 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 keychains 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 subarrays.

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 keychains 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 keychains 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 keychains 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 subarray 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 keychains 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 subarrays converted to their ivy.Array instances.

to_jsonable
(return_dict=None)[source]¶ Return container with nonjsonable 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 keychains 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 subarrays 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 keychains 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.

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 pnorm 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 subarrays. Default is False.
key_chains (list or dict of strs, optional) – The keychains 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 subarray returned.
