0Vh d UdZddlmZddlZddlZddlZddlZddlmZm Z m Z ddl m Z m Z mZmZmZmZddlmZddlmZddlmZmZmZmZe r(ddlZddlmZmZmZdd lm Z dd lm!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(gd Z)ejTZ*d e+d < dZ,de+d< dZ-de+d< dmddd dndZ. dmddd dodZ/ dmddd dpdZ0dqdZ1 dmddd drdZ2 dmddd dsdZ3 dmddd dtdZ4 dmddd dudZ5 dmddd dvdZ6 dmddd dwdZ7 dmddd dxdZ8dddd  dyd!Z9dddd  dzd"Z:dddd  dyd#Z;dddd  dzd$Z d{ d|d'Z?e dmddd d}d(Z@e dmddd d~d)Z@ dmdddd* d~d+Z@ dm dd,ZAddddd- dd.ZBddddd- dd/ZCddddd- dd0ZD dmddd dd1ZE dmddd dd2ZF dmddd dd3ZG dmddd dd4ZHdddd  dd5ZIdddd  dd6ZJdddd  dd7ZKdddd  dd8ZLGd9d:ZMeMZNd;e+d<<[Medddd  dd=ZOeeNfdddd  dd>ZOeNfdddd  dd?ZO ddddd  dd@ZPedddddA ddBZQeeNdddddC ddDZQeNdddddC ddEZQedddddF ddGZReeNdddddC ddHZReNdddddC ddIZRdddd  ddJZSdddd  ddKZTGdLdMeeeZUGdNdOeUeZV dmddd ddPZWddQZXddRZYddSZZddTZ[ddUZ\ddVZ]ddWZ^ d ddXZ_ddYddZZ`dd[Zadd\ZbddY dd]ZcddY dd^Zdddd dd_Zeddd dd`Zf dddd ddaZg dddd ddbZh dddd ddcZiddd dddZj dddd ddeZk dddd ddfZl dddd ddgZmddd ddhZnddd ddiZoepeqee hZrdje+dk< dmddd ddlZsy)z#OpTree: Optimized PyTree Utilities.) annotationsN) OrderedDict defaultdictdeque) TYPE_CHECKINGAnyCallableClassVarGenericoverload)PyTreeAccessor) NamedTupleTis_namedtuple_instanceis_structseq_instance) CollectionIterableMapping) PyTreeEntry)MetaDataPyTree PyTreeKind PyTreeSpecSStructSequenceU UnflattenFunc)AMAX_RECURSION_DEPTH NONE_IS_NODE NONE_IS_LEAF tree_flattentree_flatten_with_pathtree_flatten_with_accessortree_unflatten tree_iter tree_leavestree_structure tree_pathstree_accessors tree_is_leaf all_leavestree_map tree_map_tree_map_with_pathtree_map_with_path_tree_map_with_accessortree_map_with_accessor_tree_replace_nonestree_partitiontree_transposetree_transpose_maptree_transpose_map_with_path tree_transpose_map_with_accessortree_broadcast_prefixbroadcast_prefixtree_broadcast_commonbroadcast_commontree_broadcast_maptree_broadcast_map_with_path tree_broadcast_map_with_accessor tree_reducetree_sumtree_maxtree_mintree_alltree_anytree_flatten_one_leveltreespec_pathstreespec_accessorstreespec_entriestreespec_entrytreespec_childrentreespec_childtreespec_one_leveltreespec_transformtreespec_is_leaftreespec_is_strict_leaftreespec_is_one_leveltreespec_is_prefixtreespec_is_suffix treespec_leaf treespec_nonetreespec_tuple treespec_list treespec_dicttreespec_namedtupletreespec_ordereddicttreespec_defaultdicttreespec_dequetreespec_structseqtreespec_from_collection prefix_errorsintrFboolrTr  none_is_leaf namespacec2tj||||S)aS Flatten a pytree. See also :func:`tree_flatten_with_path` and :func:`tree_unflatten`. The flattening order (i.e., the order of elements in the output list) is deterministic, corresponding to a left-to-right depth-first tree traversal. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> tree_flatten(tree) # doctest: +IGNORE_WHITESPACE ( [1, 2, 3, 4, 5], PyTreeSpec({'a': *, 'b': (*, [*, *]), 'c': None, 'd': *}) ) >>> tree_flatten(tree, none_is_leaf=True) # doctest: +IGNORE_WHITESPACE ( [1, 2, 3, 4, None, 5], PyTreeSpec({'a': *, 'b': (*, [*, *]), 'c': *, 'd': *}, NoneIsLeaf) ) >>> tree_flatten(1) ([1], PyTreeSpec(*)) >>> tree_flatten(None) ([], PyTreeSpec(None)) >>> tree_flatten(None, none_is_leaf=True) ([None], PyTreeSpec(*, NoneIsLeaf)) For unordered dictionaries, :class:`dict` and :class:`collections.defaultdict`, the order is dependent on the **sorted** keys in the dictionary. Please use :class:`collections.OrderedDict` if you want to keep the keys in the insertion order. >>> from collections import OrderedDict >>> tree = OrderedDict([('b', (2, [3, 4])), ('a', 1), ('c', None), ('d', 5)]) >>> tree_flatten(tree) # doctest: +IGNORE_WHITESPACE ( [2, 3, 4, 1, 5], PyTreeSpec(OrderedDict({'b': (*, [*, *]), 'a': *, 'c': None, 'd': *})) ) >>> tree_flatten(tree, none_is_leaf=True) # doctest: +IGNORE_WHITESPACE ( [2, 3, 4, 1, None, 5], PyTreeSpec(OrderedDict({'b': (*, [*, *]), 'a': *, 'c': *, 'd': *}), NoneIsLeaf) ) Args: tree (pytree): A pytree to flatten. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A pair ``(leaves, treespec)`` where the first element is a list of leaf values and the second element is a treespec representing the structure of the pytree. _Cflattentreeis_leafrcrds :/home/dcms/DCMS/lib/python3.12/site-packages/optree/ops.pyr!r!sD ::dG\9 ==c2tj||||S)aW Flatten a pytree and additionally record the paths. See also :func:`tree_flatten`, :func:`tree_paths`, and :func:`treespec_paths`. The flattening order (i.e., the order of elements in the output list) is deterministic, corresponding to a left-to-right depth-first tree traversal. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> tree_flatten_with_path(tree) # doctest: +IGNORE_WHITESPACE ( [('a',), ('b', 0), ('b', 1, 0), ('b', 1, 1), ('d',)], [1, 2, 3, 4, 5], PyTreeSpec({'a': *, 'b': (*, [*, *]), 'c': None, 'd': *}) ) >>> tree_flatten_with_path(tree, none_is_leaf=True) # doctest: +IGNORE_WHITESPACE ( [('a',), ('b', 0), ('b', 1, 0), ('b', 1, 1), ('c',), ('d',)], [1, 2, 3, 4, None, 5], PyTreeSpec({'a': *, 'b': (*, [*, *]), 'c': *, 'd': *}, NoneIsLeaf) ) >>> tree_flatten_with_path(1) ([()], [1], PyTreeSpec(*)) >>> tree_flatten_with_path(None) ([], [], PyTreeSpec(None)) >>> tree_flatten_with_path(None, none_is_leaf=True) ([()], [None], PyTreeSpec(*, NoneIsLeaf)) For unordered dictionaries, :class:`dict` and :class:`collections.defaultdict`, the order is dependent on the **sorted** keys in the dictionary. Please use :class:`collections.OrderedDict` if you want to keep the keys in the insertion order. >>> from collections import OrderedDict >>> tree = OrderedDict([('b', (2, [3, 4])), ('a', 1), ('c', None), ('d', 5)]) >>> tree_flatten_with_path(tree) # doctest: +IGNORE_WHITESPACE ( [('b', 0), ('b', 1, 0), ('b', 1, 1), ('a',), ('d',)], [2, 3, 4, 1, 5], PyTreeSpec(OrderedDict({'b': (*, [*, *]), 'a': *, 'c': None, 'd': *})) ) >>> tree_flatten_with_path(tree, none_is_leaf=True) # doctest: +IGNORE_WHITESPACE ( [('b', 0), ('b', 1, 0), ('b', 1, 1), ('a',), ('c',), ('d',)], [2, 3, 4, 1, None, 5], PyTreeSpec(OrderedDict({'b': (*, [*, *]), 'a': *, 'c': *, 'd': *}), NoneIsLeaf) ) Args: tree (pytree): A pytree to flatten. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A triple ``(paths, leaves, treespec)``. The first element is a list of the paths to the leaf values, while each path is a tuple of the index or keys. The second element is a list of leaf values and the last element is a treespec representing the structure of the pytree. rgflatten_with_pathris rlr"r"sN   g|Y GGrmc^tj||||\}}|j||fS)asFlatten a pytree and additionally record the accessors. See also :func:`tree_flatten`, :func:`tree_accessors`, and :func:`treespec_accessors`. The flattening order (i.e., the order of elements in the output list) is deterministic, corresponding to a left-to-right depth-first tree traversal. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> tree_flatten_with_accessor(tree) # doctest: +IGNORE_WHITESPACE ( [ PyTreeAccessor(*['a'], (MappingEntry(key='a', type=),)), PyTreeAccessor(*['b'][0], (MappingEntry(key='b', type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][0], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][1], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=1, type=))), PyTreeAccessor(*['d'], (MappingEntry(key='d', type=),)) ], [1, 2, 3, 4, 5], PyTreeSpec({'a': *, 'b': (*, [*, *]), 'c': None, 'd': *}) ) >>> tree_flatten_with_accessor(tree, none_is_leaf=True) # doctest: +IGNORE_WHITESPACE ( [ PyTreeAccessor(*['a'], (MappingEntry(key='a', type=),)), PyTreeAccessor(*['b'][0], (MappingEntry(key='b', type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][0], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][1], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=1, type=))), PyTreeAccessor(*['c'], (MappingEntry(key='c', type=),)), PyTreeAccessor(*['d'], (MappingEntry(key='d', type=),)) ], [1, 2, 3, 4, None, 5], PyTreeSpec({'a': *, 'b': (*, [*, *]), 'c': *, 'd': *}, NoneIsLeaf) ) >>> tree_flatten_with_accessor(1) ([PyTreeAccessor(*, ())], [1], PyTreeSpec(*)) >>> tree_flatten_with_accessor(None) ([], [], PyTreeSpec(None)) >>> tree_flatten_with_accessor(None, none_is_leaf=True) ([PyTreeAccessor(*, ())], [None], PyTreeSpec(*, NoneIsLeaf)) For unordered dictionaries, :class:`dict` and :class:`collections.defaultdict`, the order is dependent on the **sorted** keys in the dictionary. Please use :class:`collections.OrderedDict` if you want to keep the keys in the insertion order. >>> from collections import OrderedDict >>> tree = OrderedDict([('b', (2, [3, 4])), ('a', 1), ('c', None), ('d', 5)]) >>> tree_flatten_with_accessor(tree) # doctest: +IGNORE_WHITESPACE ( [ PyTreeAccessor(*['b'][0], (MappingEntry(key='b', type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][0], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][1], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=1, type=))), PyTreeAccessor(*['a'], (MappingEntry(key='a', type=),)), PyTreeAccessor(*['d'], (MappingEntry(key='d', type=),)) ], [2, 3, 4, 1, 5], PyTreeSpec(OrderedDict({'b': (*, [*, *]), 'a': *, 'c': None, 'd': *})) ) >>> tree_flatten_with_accessor(tree, none_is_leaf=True) # doctest: +IGNORE_WHITESPACE ( [ PyTreeAccessor(*['b'][0], (MappingEntry(key='b', type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][0], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][1], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=1, type=))), PyTreeAccessor(*['a'], (MappingEntry(key='a', type=),)), PyTreeAccessor(*['c'], (MappingEntry(key='c', type=),)), PyTreeAccessor(*['d'], (MappingEntry(key='d', type=),)) ], [2, 3, 4, 1, None, 5], PyTreeSpec(OrderedDict({'b': (*, [*, *]), 'a': *, 'c': *, 'd': *}), NoneIsLeaf) ) Args: tree (pytree): A pytree to flatten. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A triple ``(accessors, leaves, treespec)``. The first element is a list of accessors to the leaf values. The second element is a list of leaf values and the last element is a treespec representing the structure of the pytree. rgrh accessors)rjrkrcrdleavestreespecs rlr#r#s4Bzz$yIFH     11rmc$|j|S)afReconstruct a pytree from the treespec and the leaves. The inverse of :func:`tree_flatten`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> leaves, treespec = tree_flatten(tree) >>> tree == tree_unflatten(treespec, leaves) True Args: treespec (PyTreeSpec): The treespec to reconstruct. leaves (iterable): The list of leaves to use for reconstruction. The list must match the number of leaves of the treespec. Returns: The reconstructed pytree, containing the ``leaves`` placed in the structure described by ``treespec``. ) unflatten)rurts rlr$r$vs&   f %%rmc2tj||||S)a(Get an iterator over the leaves of a pytree. See also :func:`tree_flatten` and :func:`tree_leaves`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> list(tree_iter(tree)) [1, 2, 3, 4, 5] >>> list(tree_iter(tree, none_is_leaf=True)) [1, 2, 3, 4, None, 5] >>> list(tree_iter(1)) [1] >>> list(tree_iter(None)) [] >>> list(tree_iter(None, none_is_leaf=True)) [None] Args: tree (pytree): A pytree to iterate over. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: An iterator over the leaf values. )rg PyTreeIterris rlr%r%sN ==w i @@rmc8tj||||dS)aGet the leaves of a pytree. See also :func:`tree_flatten` and :func:`tree_iter`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> tree_leaves(tree) [1, 2, 3, 4, 5] >>> tree_leaves(tree, none_is_leaf=True) [1, 2, 3, 4, None, 5] >>> tree_leaves(1) [1] >>> tree_leaves(None) [] >>> tree_leaves(None, none_is_leaf=True) [None] Args: tree (pytree): A pytree to flatten. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A list of leaf values. rrfris rlr&r&N ::dG\9 =a @@rmc8tj||||dS)aGet the treespec for a pytree. See also :func:`tree_flatten`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> tree_structure(tree) PyTreeSpec({'a': *, 'b': (*, [*, *]), 'c': None, 'd': *}) >>> tree_structure(tree, none_is_leaf=True) PyTreeSpec({'a': *, 'b': (*, [*, *]), 'c': *, 'd': *}, NoneIsLeaf) >>> tree_structure(1) PyTreeSpec(*) >>> tree_structure(None) PyTreeSpec(None) >>> tree_structure(None, none_is_leaf=True) PyTreeSpec(*, NoneIsLeaf) Args: tree (pytree): A pytree to flatten. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec object representing the structure of the pytree. rfris rlr'r'r{rmc8tj||||dS)aGet the path entries to the leaves of a pytree. See also :func:`tree_flatten`, :func:`tree_flatten_with_path`, and :func:`treespec_paths`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> tree_paths(tree) [('a',), ('b', 0), ('b', 1, 0), ('b', 1, 1), ('d',)] >>> tree_paths(tree, none_is_leaf=True) [('a',), ('b', 0), ('b', 1, 0), ('b', 1, 1), ('c',), ('d',)] >>> tree_paths(1) [()] >>> tree_paths(None) [] >>> tree_paths(None, none_is_leaf=True) [()] Args: tree (pytree): A pytree to flatten. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A list of the paths to the leaf values, while each path is a tuple of the index or keys. rroris rlr(r( s!N   g|Y G JJrmcTtj||||djS)a Get the accessors to the leaves of a pytree. See also :func:`tree_flatten`, :func:`tree_flatten_with_accessor`, and :func:`treespec_accessors`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5} >>> tree_accessors(tree) # doctest: +IGNORE_WHITESPACE [ PyTreeAccessor(*['a'], (MappingEntry(key='a', type=),)), PyTreeAccessor(*['b'][0], (MappingEntry(key='b', type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][0], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][1], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=1, type=))), PyTreeAccessor(*['d'], (MappingEntry(key='d', type=),)) ] >>> tree_accessors(tree, none_is_leaf=True) # doctest: +IGNORE_WHITESPACE [ PyTreeAccessor(*['a'], (MappingEntry(key='a', type=),)), PyTreeAccessor(*['b'][0], (MappingEntry(key='b', type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][0], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=0, type=))), PyTreeAccessor(*['b'][1][1], (MappingEntry(key='b', type=), SequenceEntry(index=1, type=), SequenceEntry(index=1, type=))), PyTreeAccessor(*['c'], (MappingEntry(key='c', type=),)), PyTreeAccessor(*['d'], (MappingEntry(key='d', type=),)) ] >>> tree_accessors(1) [PyTreeAccessor(*, ())] >>> tree_accessors(None) [] >>> tree_accessors(None, none_is_leaf=True) [PyTreeAccessor(*, ())] Args: tree (pytree): A pytree to flatten. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A list of accessors to the leaf values. r}rrris rlr)r)4s(j ::dG\9 =a @ J J LLrmc2tj||||S)aTest whether the given object is a leaf node. See also :func:`tree_flatten`, :func:`tree_leaves`, and :func:`all_leaves`. >>> tree_is_leaf(1) True >>> tree_is_leaf(None) False >>> tree_is_leaf(None, none_is_leaf=True) True >>> tree_is_leaf({'a': 1, 'b': (2, 3)}) False Args: tree (pytree): A pytree to check if it is a leaf node. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than a leaf. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A boolean indicating if the given object is a leaf node. )rgrkris rlr*r*lsH ::dG\9 ==rmc2tj||||S)a:Test whether all elements in the given iterable are all leaves. See also :func:`tree_flatten`, :func:`tree_leaves`, and :func:`tree_is_leaf`. >>> tree = {'a': [1, 2, 3]} >>> all_leaves(tree_leaves(tree)) True >>> all_leaves([tree]) False >>> all_leaves([1, 2, None, 3]) False >>> all_leaves([1, 2, None, 3], none_is_leaf=True) True Note that this function iterates and checks the elements in the input iterable object, which uses the :func:`iter` function. For dictionaries, ``iter(d)`` for a dictionary ``d`` iterates the keys of the dictionary, not the values. >>> list({'a': 1, 'b': (2, 3)}) ['a', 'b'] >>> all_leaves({'a': 1, 'b': (2, 3)}) True This function is useful in advanced cases. For example, if a library allows arbitrary map operations on a flat list of leaves it may want to check if the result is still a flat list of leaves. Args: iterable (iterable): A iterable of leaves. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than a leaf. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A boolean indicating if all elements in the input iterable are leaves. )rgr+)iterablerkrcrds rlr+r+sd ==7L) DDrmrkrcrdctj||||\}}|g|Dcgc]}|j|c}z} |jt |g| Scc}w)a Map a multi-input function over pytree args to produce a new pytree. See also :func:`tree_map_`, :func:`tree_map_with_path`, :func:`tree_map_with_path_`, and :func:`tree_broadcast_map`. >>> tree_map(lambda x: x + 1, {'x': 7, 'y': (42, 64)}) {'x': 8, 'y': (43, 65)} >>> tree_map(lambda x: x + 1, {'x': 7, 'y': (42, 64), 'z': None}) {'x': 8, 'y': (43, 65), 'z': None} >>> tree_map(lambda x: x is None, {'x': 7, 'y': (42, 64), 'z': None}) {'x': False, 'y': (False, False), 'z': None} >>> tree_map(lambda x: x is None, {'x': 7, 'y': (42, 64), 'z': None}, none_is_leaf=True) {'x': False, 'y': (False, False), 'z': True} If multiple inputs are given, the structure of the tree is taken from the first input; subsequent inputs need only have ``tree`` as a prefix: >>> tree_map(lambda x, y: [x] + y, [5, 6], [[7, 9], [1, 2]]) [[5, 7, 9], [6, 1, 2]] Args: func (callable): A function that takes ``1 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees. tree (pytree): A pytree to be mapped over, with each leaf providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new pytree with the same structure as ``tree`` but with the value at each leaf given by ``func(x, *xs)`` where ``x`` is the value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at corresponding nodes in ``rests``. )rgrh flatten_up_torwmap funcrjrkrcrdrestsrtrur flat_argss rlr,r,sahzz$yIFHuE!H2215EEI   c$33 44FsActj||||\}}|g|Dcgc]}|j|c}z} tt |g| d|Scc}w)aLike :func:`tree_map`, but do an inplace call on each leaf and return the original tree. See also :func:`tree_map`, :func:`tree_map_with_path`, and :func:`tree_map_with_path_`. Args: func (callable): A function that takes ``1 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees. tree (pytree): A pytree to be mapped over, with each leaf providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: The original ``tree`` with the value at each leaf is given by the side-effect of function ``func(x, *xs)`` (not the return value) where ``x`` is the value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at values at corresponding nodes in ``rests``. rmaxlen)rgrhrrrrs rlr-r-s_Hzz$yIFHuE!H2215EEI #d Y * KFsActj||||\}}}|g|D cgc]} |j| c} z} |jt ||g| Scc} w)a Map a multi-input function over pytree args as well as the tree paths to produce a new pytree. See also :func:`tree_map`, :func:`tree_map_`, and :func:`tree_map_with_path_`. >>> tree_map_with_path(lambda p, x: (len(p), x), {'x': 7, 'y': (42, 64)}) {'x': (1, 7), 'y': ((2, 42), (2, 64))} >>> tree_map_with_path(lambda p, x: x + len(p), {'x': 7, 'y': (42, 64), 'z': None}) {'x': 8, 'y': (44, 66), 'z': None} >>> tree_map_with_path(lambda p, x: p, {'x': 7, 'y': (42, 64), 'z': {1.5: None}}) {'x': ('x',), 'y': (('y', 0), ('y', 1)), 'z': {1.5: None}} >>> tree_map_with_path(lambda p, x: p, {'x': 7, 'y': (42, 64), 'z': {1.5: None}}, none_is_leaf=True) {'x': ('x',), 'y': (('y', 0), ('y', 1)), 'z': {1.5: ('z', 1.5)}} Args: func (callable): A function that takes ``2 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees with extra paths. tree (pytree): A pytree to be mapped over, with each leaf providing the second positional argument and the corresponding path providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new pytree with the same structure as ``tree`` but with the value at each leaf given by ``func(p, x, *xs)`` where ``(p, x)`` are the path and value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at corresponding nodes in ``rests``. )rgrprrwr rrjrkrcrdrpathsrtrurrs rlr.r.+sh\!224,PYZE68uE!H2215EEI   c$: : ;;FsActj||||\}}}|g|D cgc]} |j| c} z} tt ||g| d|Scc} w)aoLike :func:`tree_map_with_path`, but do an inplace call on each leaf and return the original tree. See also :func:`tree_map`, :func:`tree_map_`, and :func:`tree_map_with_path`. Args: func (callable): A function that takes ``2 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees with extra paths. tree (pytree): A pytree to be mapped over, with each leaf providing the second positional argument and the corresponding path providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: The original ``tree`` with the value at each leaf is given by the side-effect of function ``func(p, x, *xs)`` (not the return value) where ``(p, x)`` are the path and value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at values at corresponding nodes in ``rests``. rr)rgrprrrrs rlr/r/^sfL!224,PYZE68uE!H2215EEI #dE &I &q1 KFsActj||||\}}|g|Dcgc]}|j|c}z} |jt ||j g| Scc}w)a Map a multi-input function over pytree args as well as the tree accessors to produce a new pytree. See also :func:`tree_map`, :func:`tree_map_`, and :func:`tree_map_with_accessor_`. >>> tree_map_with_accessor(lambda a, x: f'{a.codify("tree")} = {x!r}', {'x': 7, 'y': (42, 64)}) {'x': "tree['x'] = 7", 'y': ("tree['y'][0] = 42", "tree['y'][1] = 64")} >>> tree_map_with_accessor(lambda a, x: x + len(a), {'x': 7, 'y': (42, 64), 'z': None}) {'x': 8, 'y': (44, 66), 'z': None} >>> tree_map_with_accessor( # doctest: +IGNORE_WHITESPACE,ELLIPSIS ... lambda a, x: a, ... {'x': 7, 'y': (42, 64), 'z': {1.5: None}}, ... ) { 'x': PyTreeAccessor(*['x'], ...), 'y': ( PyTreeAccessor(*['y'][0], ...), PyTreeAccessor(*['y'][1], ...) ), 'z': {1.5: None} } >>> tree_map_with_accessor( # doctest: +IGNORE_WHITESPACE,ELLIPSIS ... lambda a, x: a, ... {'x': 7, 'y': (42, 64), 'z': {1.5: None}}, ... none_is_leaf=True, ... ) { 'x': PyTreeAccessor(*['x'], ...), 'y': ( PyTreeAccessor(*['y'][0], ...), PyTreeAccessor(*['y'][1], ...) ), 'z': { 1.5: PyTreeAccessor(*['z'][1.5], ...) } } Args: func (callable): A function that takes ``2 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees with extra accessors. tree (pytree): A pytree to be mapped over, with each leaf providing the second positional argument and the corresponding path providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new pytree with the same structure as ``tree`` but with the value at each leaf given by ``func(a, x, *xs)`` where ``(a, x)`` are the accessor and value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at corresponding nodes in ``rests``. )rgrhrrwrrsrs rlr0r0slJzz$yIFHuE!H2215EEI   c$(:(:(<IyI JJFsA)ctj||||\}}|g|Dcgc]}|j|c}z} tt ||j g| d|Scc}w)aLike :func:`tree_map_with_accessor`, but do an inplace call on each leaf and return the original tree. See also :func:`tree_map`, :func:`tree_map_`, and :func:`tree_map_with_accessor`. Args: func (callable): A function that takes ``2 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees with extra accessors. tree (pytree): A pytree to be mapped over, with each leaf providing the second positional argument and the corresponding path providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: The original ``tree`` with the value at each leaf is given by the side-effect of function ``func(a, x, *xs)`` (not the return value) where ``(a, x)`` are the accessor and value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at values at corresponding nodes in ``rests``. rr)rgrhrrrrsrs rlr1r1sjLzz$yIFHuE!H2215EEI #dH&&( 59 5a@ KFsA'c0|Stfd|d|S)aReplace :data:`None` in ``tree`` with ``sentinel``. See also :func:`tree_flatten` and :func:`tree_map`. >>> tree_replace_nones(0, {'a': 1, 'b': None, 'c': (2, None)}) {'a': 1, 'b': 0, 'c': (2, 0)} >>> tree_replace_nones(0, None) 0 Args: sentinel (object): The value to replace :data:`None` with. tree (pytree): A pytree to be transformed. namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new pytree with the same structure as ``tree`` but with :data:`None` replaced. c||SSN)xsentinels rlz$tree_replace_nones..sq}!(rmTrbr,)rrjrds` rlr2r2s(0 | 2   rmcyrr) predicaterjrkrcrds rlr3r3"s14rmcyrrrrjrk fillvaluercrds rlr3r3.s+.rm)rrcrdcFtfd|td||||S)a( Partition a tree into the left and right part by the given predicate function. See also :func:`tree_transpose_map`. >>> left, right = tree_partition(lambda x: x > 10, {'x': 7, 'y': (42, 64)}) >>> left {'x': None, 'y': (42, 64)} >>> right {'x': 7, 'y': (None, None)} Instead of :data:`None`, one can also use a different sentinel value: >>> sentinel = object() >>> left, right = tree_partition(lambda x: x > 10, {'x': 7, 'y': (42, 64)}, fillvalue=sentinel) >>> left # doctest: +ELLIPSIS {'x': , 'y': (42, 64)} >>> right # doctest: +ELLIPSIS {'x': 7, 'y': (, )} Args: predicate (callable): A function that takes a leaf value as argument, and splits/partitions it into the left or right tree based on the predicates return value. tree (pytree): A pytree to be split, with each leaf providing the first positional argument to function ``predicate``. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. fillvalue (object, optional): A sentinel value to retain the tree structure. (default: :data:`None`) none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: Two pytrees with the same structure as ``tree`` but with orthogonal leaves based on the ``predicate`` function. The first pytree contains all leaves where ``predicate`` evaluates to ``True``, the second for ``False``. The removed nodes in both trees are filled with ``fillvalue`` to keep the original tree structure. c$|r|fS|fSrr)rrrs rlrz tree_partition..qsIaL1i.y!nrm)rr)rcinner_treespecrkrcrd)r5r'rs` ` rlr3r3;s,j D %f<H!  rmc|j|jk7r td|j}|j}|dk(s|dk(r td|jrK|jr?|j|jk7r&td|jd|jdt |||j|jxs |j\}}|j||zk7r#|j |}t d|d |dtd||z|D cgc] } || | |z } } t| } t|j| } |j| Scc} w) aTransform a tree having tree structure (outer, inner) into one having structure (inner, outer). See also :func:`tree_flatten`, :func:`tree_structure`, and :func:`tree_transpose_map`. >>> outer_treespec = tree_structure({'a': 1, 'b': 2, 'c': (3, 4)}) >>> outer_treespec PyTreeSpec({'a': *, 'b': *, 'c': (*, *)}) >>> inner_treespec = tree_structure((1, 2)) >>> inner_treespec PyTreeSpec((*, *)) >>> tree = {'a': (1, 2), 'b': (3, 4), 'c': ((5, 6), (7, 8))} >>> tree_transpose(outer_treespec, inner_treespec, tree) ({'a': 1, 'b': 3, 'c': (5, 7)}, {'a': 2, 'b': 4, 'c': (6, 8)}) For performance reasons, this function is only checks for the number of leaves in the input pytree, not the structure. The result is only enumerated up to the original order of leaves in ``tree``, then transpose depends on the number of leaves in structure (inner, outer). The caller is responsible for ensuring that the input pytree has a prefix structure of ``outer_treespec`` followed by a prefix structure of ``inner_treespec``. Otherwise, the result may be incorrect. >>> tree_transpose(outer_treespec, inner_treespec, list(range(1, 9))) ({'a': 1, 'b': 3, 'c': (5, 7)}, {'a': 2, 'b': 4, 'c': (6, 8)}) Args: outer_treespec (PyTreeSpec): A treespec object representing the outer structure of the pytree. inner_treespec (PyTreeSpec): A treespec object representing the inner structure of the pytree. tree (pytree): A pytree to be transposed. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. Returns: A new pytree with the same structure as ``inner_treespec`` but with the value at each leaf has the same structure as ``outer_treespec``. z6Tree structures must have the same none_is_leaf value.rz,Tree structures must have at least one leaf.z2Tree structures must have the same namespace, got z vs. .rz#Tree structure mismatch; expected: z, got: ) rc ValueError num_leavesrdr!compose TypeErrorrangeziprrw) outer_treespecrrjrk outer_size inner_sizertruexpected_treespecoffsetgrouped transposedsubtreess rlr4r4zsV""n&A&AAQRR**J**JQ*/GHH   $ $  $ $(@(@ @!++.eN4L4L3Oq R  $ #00 **Fn.F.F FH j:55*22>B=>O=PPWX`WaabcddAzJ6 C  v+,GgJ>++Z8H  # #H -- s$E$rctj||||\}}|jdk(rtd|d|g|D cgc]} |j | c} z} t t |g| } |t| d|||}|jdk(rtd|d| D cgc]} |j | } } t| }t |j|}|j|Scc} wcc} w)a Map a multi-input function over pytree args to produce a new pytree with transposed structure. See also :func:`tree_map`, :func:`tree_map_with_path`, and :func:`tree_transpose`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)} >>> tree_transpose_map( # doctest: +IGNORE_WHITESPACE ... lambda x: {'identity': x, 'double': 2 * x}, ... tree, ... ) { 'identity': {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)}, 'double': {'b': (4, [6, 8]), 'a': 2, 'c': (10, 12)} } >>> tree_transpose_map( # doctest: +IGNORE_WHITESPACE ... lambda x: {'identity': x, 'double': (x, x)}, ... tree, ... ) { 'identity': {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)}, 'double': ( {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)}, {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)} ) } >>> tree_transpose_map( # doctest: +IGNORE_WHITESPACE ... lambda x: {'identity': x, 'double': (x, x)}, ... tree, ... inner_treespec=tree_structure({'identity': 0, 'double': 0}), ... ) { 'identity': {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)}, 'double': {'b': ((2, 2), [(3, 3), (4, 4)]), 'a': (1, 1), 'c': ((5, 5), (6, 6))} } Args: func (callable): A function that takes ``1 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees. tree (pytree): A pytree to be mapped over, with each leaf providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. inner_treespec (PyTreeSpec, optional): The treespec object representing the inner structure of the result pytree. If not specified, the inner structure is inferred from the result of the function ``func`` on the first leaf. (default: :data:`None`) is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new nested pytree with the same structure as ``inner_treespec`` but with the value at each leaf has the same structure as ``tree``. The subtree at each leaf is given by the result of function ``func(x, *xs)`` where ``x`` is the value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at corresponding nodes in ``rests``. r6The outer structure must have at least one leaf. Got: rr6The inner structure must have at least one leaf. Got: ) rgrhrrrlistrr'rrwrrjrrkrcrdrrtrrroutputsorrrs rlr5r5sN ZZg|YOFN  A%QR`QaabcddUKN88;KKI3t(i()G' AJ%     A%QR`Qaabcdd8?@1~++A.@G@gJ>++Z8H  # #H --!LAs C1(C6ctj||||\}}} | jdk(rtd| d|g|D cgc]} | j | c} z} t t ||g| } |t| d|||}|jdk(rtd|d| D cgc]} |j | }} t|}t | j|}|j|Scc} wcc} w)a Map a multi-input function over pytree args as well as the tree paths to produce a new pytree with transposed structure. See also :func:`tree_map_with_path`, :func:`tree_transpose_map`, and :func:`tree_transpose`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)} >>> tree_transpose_map_with_path( # doctest: +IGNORE_WHITESPACE ... lambda p, x: {'depth': len(p), 'value': x}, ... tree, ... ) { 'depth': {'b': (2, [3, 3]), 'a': 1, 'c': (2, 2)}, 'value': {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)} } >>> tree_transpose_map_with_path( # doctest: +IGNORE_WHITESPACE ... lambda p, x: {'path': p, 'value': x}, ... tree, ... inner_treespec=tree_structure({'path': 0, 'value': 0}), ... ) { 'path': { 'b': (('b', 0), [('b', 1, 0), ('b', 1, 1)]), 'a': ('a',), 'c': (('c', 0), ('c', 1)) }, 'value': {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)} } Args: func (callable): A function that takes ``2 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees with extra paths. tree (pytree): A pytree to be mapped over, with each leaf providing the second positional argument and the corresponding path providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. inner_treespec (PyTreeSpec, optional): The treespec object representing the inner structure of the result pytree. If not specified, the inner structure is inferred from the result of the function ``func`` on the first leaf. (default: :data:`None`) is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new nested pytree with the same structure as ``inner_treespec`` but with the value at each leaf has the same structure as ``tree``. The subtree at each leaf is given by the result of function ``func(p, x, *xs)`` where ``(p, x)`` are the path and value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at corresponding nodes in ``rests``. rrrrr) rgrprrrrrr'rrw)rrjrrkrcrdrrrtrrrrrrrrs rlr6r6%sB%'$8$8w V_$`!E6>  A%QR`QaabcddUKN88;KKI3tU/Y/0G' AJ%     A%QR`Qaabcdd8?@1~++A.@G@gJ>++Z8H  # #H --!LAs C3*C8ctj||||\}}|jdk(rtd|d|g|D cgc]} |j | c} z} t t ||jg| } |t| d|||}|jdk(rtd|d| D cgc]} |j | } } t| }t |j|}|j|Scc} wcc} w)aMap a multi-input function over pytree args as well as the tree accessors to produce a new pytree with transposed structure. See also :func:`tree_map_with_accessor`, :func:`tree_transpose_map`, and :func:`tree_transpose`. >>> tree = {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)} >>> tree_transpose_map_with_accessor( # doctest: +IGNORE_WHITESPACE ... lambda a, x: {'depth': len(a), 'code': a.codify('tree'), 'value': x}, ... tree, ... ) { 'depth': { 'b': (2, [3, 3]), 'a': 1, 'c': (2, 2) }, 'code': { 'b': ("tree['b'][0]", ["tree['b'][1][0]", "tree['b'][1][1]"]), 'a': "tree['a']", 'c': ("tree['c'][0]", "tree['c'][1]") }, 'value': { 'b': (2, [3, 4]), 'a': 1, 'c': (5, 6) } } >>> tree_transpose_map_with_accessor( # doctest: +IGNORE_WHITESPACE,ELLIPSIS ... lambda a, x: {'path': a.path, 'accessor': a, 'value': x}, ... tree, ... inner_treespec=tree_structure({'path': 0, 'accessor': 0, 'value': 0}), ... ) { 'path': { 'b': (('b', 0), [('b', 1, 0), ('b', 1, 1)]), 'a': ('a',), 'c': (('c', 0), ('c', 1)) }, 'accessor': { 'b': ( PyTreeAccessor(*['b'][0], ...), [ PyTreeAccessor(*['b'][1][0], ...), PyTreeAccessor(*['b'][1][1], ...) ] ), 'a': PyTreeAccessor(*['a'], ...), 'c': ( PyTreeAccessor(*['c'][0], ...), PyTreeAccessor(*['c'][1], ...) ) }, 'value': {'b': (2, [3, 4]), 'a': 1, 'c': (5, 6)} } Args: func (callable): A function that takes ``2 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees with extra accessors. tree (pytree): A pytree to be mapped over, with each leaf providing the second positional argument and the corresponding path providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, each of which has the same structure as ``tree`` or has ``tree`` as a prefix. inner_treespec (PyTreeSpec, optional): The treespec object representing the inner structure of the result pytree. If not specified, the inner structure is inferred from the result of the function ``func`` on the first leaf. (default: :data:`None`) is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new nested pytree with the same structure as ``inner_treespec`` but with the value at each leaf has the same structure as ``tree``. The subtree at each leaf is given by the result of function ``func(a, x, *xs)`` where ``(a, x)`` are the accessor and value at the corresponding leaf in ``tree`` and ``xs`` is the tuple of values at corresponding nodes in ``rests``. rrrrr) rgrhrrrrrrsr'rrwrs rlr7r7|s#x ZZg|YOFN  A%QR`QaabcddUKN88;KKI3t^557D)DEG' AJ%     A%QR`Qaabcdd8?@1~++A.@G@gJ>++Z8H  # #H --!LAs D7Dc:dfd }t|||S)aT Return a pytree of same structure of ``full_tree`` with broadcasted subtrees in ``prefix_tree``. See also :func:`broadcast_prefix`, :func:`tree_broadcast_common`, and :func:`treespec_is_prefix`. If a ``prefix_tree`` is a prefix of a ``full_tree``, this means the ``full_tree`` can be constructed by replacing the leaves of ``prefix_tree`` with appropriate **subtrees**. This function returns a pytree with the same size as ``full_tree``. The leaves are replicated from ``prefix_tree``. The number of replicas is determined by the corresponding subtree in ``full_tree``. >>> tree_broadcast_prefix(1, [2, 3, 4]) [1, 1, 1] >>> tree_broadcast_prefix([1, 2, 3], [4, 5, 6]) [1, 2, 3] >>> tree_broadcast_prefix([1, 2, 3], [4, 5, 6, 7]) Traceback (most recent call last): ... ValueError: list arity mismatch; expected: 3, got: 4; list: [4, 5, 6, 7]. >>> tree_broadcast_prefix([1, 2, 3], [4, 5, (6, 7)]) [1, 2, (3, 3)] >>> tree_broadcast_prefix([1, 2, 3], [4, 5, {'a': 6, 'b': 7, 'c': (None, 8)}]) [1, 2, {'a': 3, 'b': 3, 'c': (None, 3)}] >>> tree_broadcast_prefix([1, 2, 3], [4, 5, {'a': 6, 'b': 7, 'c': (None, 8)}], none_is_leaf=True) [1, 2, {'a': 3, 'b': 3, 'c': (3, 3)}] Args: prefix_tree (pytree): A pytree with the prefix structure of ``full_tree``. full_tree (pytree): A pytree with the suffix structure of ``prefix_tree``. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A pytree of same structure of ``full_tree`` with broadcasted subtrees in ``prefix_tree``. ct|}|jtj||jSNrr'rw itertoolsrepeatrrsubtree subtreespecrkrdrcs rlbroadcast_leavesz/tree_broadcast_prefix..broadcast_leaves#?$ %  $$Y%5%5a9O9O%PQQrmr)rrr PyTree[S]return PyTree[T]r) prefix_tree full_treerkrcrdrs ``` rlr8r8s+jR$ !  rmcFgdfd }t|||S)a Return a list of broadcasted leaves in ``prefix_tree`` to match the number of leaves in ``full_tree``. See also :func:`tree_broadcast_prefix`, :func:`broadcast_common`, and :func:`treespec_is_prefix`. If a ``prefix_tree`` is a prefix of a ``full_tree``, this means the ``full_tree`` can be constructed by replacing the leaves of ``prefix_tree`` with appropriate **subtrees**. This function returns a list of leaves with the same size as ``full_tree``. The leaves are replicated from ``prefix_tree``. The number of replicas is determined by the corresponding subtree in ``full_tree``. >>> broadcast_prefix(1, [2, 3, 4]) [1, 1, 1] >>> broadcast_prefix([1, 2, 3], [4, 5, 6]) [1, 2, 3] >>> broadcast_prefix([1, 2, 3], [4, 5, 6, 7]) Traceback (most recent call last): ... ValueError: list arity mismatch; expected: 3, got: 4; list: [4, 5, 6, 7]. >>> broadcast_prefix([1, 2, 3], [4, 5, (6, 7)]) [1, 2, 3, 3] >>> broadcast_prefix([1, 2, 3], [4, 5, {'a': 6, 'b': 7, 'c': (None, 8)}]) [1, 2, 3, 3, 3] >>> broadcast_prefix([1, 2, 3], [4, 5, {'a': 6, 'b': 7, 'c': (None, 8)}], none_is_leaf=True) [1, 2, 3, 3, 3, 3] Args: prefix_tree (pytree): A pytree with the prefix structure of ``full_tree``. full_tree (pytree): A pytree with the suffix structure of ``prefix_tree``. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A list of leaves in ``prefix_tree`` broadcasted to match the number of leaves in ``full_tree``. ct|}jtj||jyr)r'extendrrr)rrrrkrdrcresults rl add_leavesz$broadcast_prefix..add_leavesus:$ %   i&&q+*@*@ABrmr)rrrrrNone)r-)rrrkrcrdrrs ``` @rlr9r9?s:hFCC$!  Mrmc tj|\}}tj|\}}|j|} t} | j t j | | j} dfd } |j t| ||j| } |j t| ||j| }| |fS)a< Return two pytrees of common suffix structure of ``tree`` and ``other_tree`` with broadcasted subtrees. See also :func:`broadcast_common`, :func:`tree_broadcast_prefix`, and :func:`treespec_is_prefix`. If a ``suffix_tree`` is a suffix of a ``tree``, this means the ``suffix_tree`` can be constructed by replacing the leaves of ``tree`` with appropriate **subtrees**. This function returns two pytrees with the same structure. The tree structure is the common suffix structure of ``tree`` and ``other_tree``. The leaves are replicated from ``tree`` and ``other_tree``. The number of replicas is determined by the corresponding subtree in the suffix structure. >>> tree_broadcast_common(1, [2, 3, 4]) ([1, 1, 1], [2, 3, 4]) >>> tree_broadcast_common([1, 2, 3], [4, 5, 6]) ([1, 2, 3], [4, 5, 6]) >>> tree_broadcast_common([1, 2, 3], [4, 5, 6, 7]) Traceback (most recent call last): ... ValueError: list arity mismatch; expected: 3, got: 4. >>> tree_broadcast_common([1, (2, 3), 4], [5, 6, (7, 8)]) ([1, (2, 3), (4, 4)], [5, (6, 6), (7, 8)]) >>> tree_broadcast_common([1, {'a': (2, 3)}, 4], [5, 6, {'a': 7, 'b': 8, 'c': (None, 9)}]) ([1, {'a': (2, 3)}, {'a': 4, 'b': 4, 'c': (None, 4)}], [5, {'a': (6, 6)}, {'a': 7, 'b': 8, 'c': (None, 9)}]) >>> tree_broadcast_common([1, {'a': (2, 3)}, 4], [5, 6, {'a': 7, 'b': 8, 'c': (None, 9)}], none_is_leaf=True) ([1, {'a': (2, 3)}, {'a': 4, 'b': 4, 'c': (4, 4)}], [5, {'a': (6, 6)}, {'a': 7, 'b': 8, 'c': (None, 9)}]) >>> tree_broadcast_common([1, None], [None, 2]) ([None, None], [None, None]) >>> tree_broadcast_common([1, None], [None, 2], none_is_leaf=True) ([1, None], [None, 2]) Args: tree (pytree): A pytree has a common suffix structure of ``other_tree``. other_tree (pytree): A pytree has a common suffix structure of ``tree``. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: Two pytrees of common suffix structure of ``tree`` and ``other_tree`` with broadcasted subtrees. ct|}|jtj||jSrrrs rlrz/tree_broadcast_common..broadcast_leavesrrm)rrrrrr) rgrhbroadcast_to_common_suffixobjectrwrrrrr)rj other_treerkrcrdrtru other_leavesother_treespeccommon_suffix_treespecrcommon_suffix_treerbroadcasted_treeother_broadcasted_trees ``` rlr:r:svzz$yIFH#%::j'>> broadcast_common(1, [2, 3, 4]) ([1, 1, 1], [2, 3, 4]) >>> broadcast_common([1, 2, 3], [4, 5, 6]) ([1, 2, 3], [4, 5, 6]) >>> broadcast_common([1, 2, 3], [4, 5, 6, 7]) Traceback (most recent call last): ... ValueError: list arity mismatch; expected: 3, got: 4. >>> broadcast_common([1, (2, 3), 4], [5, 6, (7, 8)]) ([1, 2, 3, 4, 4], [5, 6, 6, 7, 8]) >>> broadcast_common([1, {'a': (2, 3)}, 4], [5, 6, {'a': 7, 'b': 8, 'c': (None, 9)}]) ([1, 2, 3, 4, 4, 4], [5, 6, 6, 7, 8, 9]) >>> broadcast_common([1, {'a': (2, 3)}, 4], [5, 6, {'a': 7, 'b': 8, 'c': (None, 9)}], none_is_leaf=True) ([1, 2, 3, 4, 4, 4, 4], [5, 6, 6, 7, 8, None, 9]) >>> broadcast_common([1, None], [None, 2]) ([], []) >>> broadcast_common([1, None], [None, 2], none_is_leaf=True) ([1, None], [None, 2]) Args: tree (pytree): A pytree has a common suffix structure of ``other_tree``. other_tree (pytree): A pytree has a common suffix structure of ``tree``. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: Two lists of leaves in ``tree`` and ``other_tree`` broadcasted to match the number of leaves in the common suffix structure. rcJj|j|yr)append)rybroadcasted_leavesother_broadcasted_leavess rlrz$broadcast_common..add_leaves5s!!!$ ''*rm)rrrrrr)r:r-) rjrrkrcrdrrrrrs @@rlr;r;sdt0E ! 0,,#%(*+!  7 77rmc |s|fSt|dk(rt||d|||S|}t|}tdD]+}t |D]\}} t|| |||\}||<-|g|S)Nr}rr)lenr:rr enumerate) rjrkrcrdrrbroadcasted_rests_irests rl_tree_broadcast_commonrDs w 5zQ$  !H%   U  1X ' GAt5J )# 6 2 /2   10 11rmc Bt|gt|g||||d|||dS)a Map a multi-input function over pytree args to produce a new pytree. See also :func:`tree_broadcast_map_with_path`, :func:`tree_map`, :func:`tree_map_`, and :func:`tree_map_with_path`. If only one input is provided, this function is the same as :func:`tree_map`: >>> tree_broadcast_map(lambda x: x + 1, {'x': 7, 'y': (42, 64)}) {'x': 8, 'y': (43, 65)} >>> tree_broadcast_map(lambda x: x + 1, {'x': 7, 'y': (42, 64), 'z': None}) {'x': 8, 'y': (43, 65), 'z': None} >>> tree_broadcast_map(lambda x: x is None, {'x': 7, 'y': (42, 64), 'z': None}) {'x': False, 'y': (False, False), 'z': None} >>> tree_broadcast_map(lambda x: x is None, {'x': 7, 'y': (42, 64), 'z': None}, none_is_leaf=True) {'x': False, 'y': (False, False), 'z': True} If multiple inputs are given, all input trees will be broadcasted to the common suffix structure of all inputs: >>> tree_broadcast_map(lambda x, y: x * y, [5, 6, (3, 4)], [{'a': 7, 'b': 9}, [1, 2], 8]) [{'a': 35, 'b': 45}, [6, 12], (24, 32)] Args: func (callable): A function that takes ``1 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees. tree (pytree): A pytree to be mapped over, with each leaf providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, they should have a common suffix structure with each other and with ``tree``. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new pytree with the structure as the common suffix structure of ``tree`` and ``rests`` but with the value at each leaf given by ``func(x, *xs)`` where ``x`` is the value at the corresponding leaf (may be broadcasted) in ``tree`` and ``xs`` is the tuple of values at corresponding leaves (may be broadcasted) in ``rests``. r)r,rrrjrkrcrdrs rlr<r<gsMn       %   !  rmc Bt|gt|g||||d|||dS)a Map a multi-input function over pytree args as well as the tree paths to produce a new pytree. See also :func:`tree_broadcast_map`, :func:`tree_map`, :func:`tree_map_`, and :func:`tree_map_with_path`. If only one input is provided, this function is the same as :func:`tree_map`: >>> tree_broadcast_map_with_path(lambda p, x: (len(p), x), {'x': 7, 'y': (42, 64)}) {'x': (1, 7), 'y': ((2, 42), (2, 64))} >>> tree_broadcast_map_with_path(lambda p, x: x + len(p), {'x': 7, 'y': (42, 64), 'z': None}) {'x': 8, 'y': (44, 66), 'z': None} >>> tree_broadcast_map_with_path(lambda p, x: p, {'x': 7, 'y': (42, 64), 'z': {1.5: None}}) {'x': ('x',), 'y': (('y', 0), ('y', 1)), 'z': {1.5: None}} >>> tree_broadcast_map_with_path(lambda p, x: p, {'x': 7, 'y': (42, 64), 'z': {1.5: None}}, none_is_leaf=True) {'x': ('x',), 'y': (('y', 0), ('y', 1)), 'z': {1.5: ('z', 1.5)}} If multiple inputs are given, all input trees will be broadcasted to the common suffix structure of all inputs: >>> tree_broadcast_map_with_path( # doctest: +IGNORE_WHITESPACE ... lambda p, x, y: (p, x * y), ... [5, 6, (3, 4)], ... [{'a': 7, 'b': 9}, [1, 2], 8], ... ) [ {'a': ((0, 'a'), 35), 'b': ((0, 'b'), 45)}, [((1, 0), 6), ((1, 1), 12)], (((2, 0), 24), ((2, 1), 32)) ] Args: func (callable): A function that takes ``2 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees with extra paths. tree (pytree): A pytree to be mapped over, with each leaf providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, they should have a common suffix structure with each other and with ``tree``. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new pytree with the structure as the common suffix structure of ``tree`` and ``rests`` but with the value at each leaf given by ``func(p, x, *xs)`` where ``(p, x)`` are the path and value at the corresponding leaf (may be broadcasted) in and ``xs`` is the tuple of values at corresponding leaves (may be broadcasted) in ``rests``. r)r.rrs rlr=r=sM~       %   !  rmc Bt|gt|g||||d|||dS)aF Map a multi-input function over pytree args as well as the tree accessors to produce a new pytree. See also :func:`tree_broadcast_map`, :func:`tree_map`, :func:`tree_map_`, and :func:`tree_map_with_accessor`. If only one input is provided, this function is the same as :func:`tree_map`: >>> tree_broadcast_map_with_accessor(lambda a, x: (len(a), x), {'x': 7, 'y': (42, 64)}) {'x': (1, 7), 'y': ((2, 42), (2, 64))} >>> tree_broadcast_map_with_accessor(lambda a, x: x + len(a), {'x': 7, 'y': (42, 64), 'z': None}) {'x': 8, 'y': (44, 66), 'z': None} >>> tree_broadcast_map_with_accessor( # doctest: +IGNORE_WHITESPACE ... lambda a, x: a.codify('tree'), ... {'x': 7, 'y': (42, 64), 'z': {1.5: None}}, ... ) { 'x': "tree['x']", 'y': ("tree['y'][0]", "tree['y'][1]"), 'z': {1.5: None} } >>> tree_broadcast_map_with_accessor( # doctest: +IGNORE_WHITESPACE ... lambda a, x: a.codify('tree'), ... {'x': 7, 'y': (42, 64), 'z': {1.5: None}}, ... none_is_leaf=True, ... ) { 'x': "tree['x']", 'y': ("tree['y'][0]", "tree['y'][1]"), 'z': {1.5: "tree['z'][1.5]"} } If multiple inputs are given, all input trees will be broadcasted to the common suffix structure of all inputs: >>> tree_broadcast_map_with_accessor( # doctest: +IGNORE_WHITESPACE ... lambda a, x, y: f'{a.codify("tree")} = {x * y}', ... [5, 6, (3, 4)], ... [{'a': 7, 'b': 9}, [1, 2], 8], ... ) [ {'a': "tree[0]['a'] = 35", 'b': "tree[0]['b'] = 45"}, ['tree[1][0] = 6', 'tree[1][1] = 12'], ('tree[2][0] = 24', 'tree[2][1] = 32') ] Args: func (callable): A function that takes ``2 + len(rests)`` arguments, to be applied at the corresponding leaves of the pytrees with extra accessors. tree (pytree): A pytree to be mapped over, with each leaf providing the first positional argument to function ``func``. rests (tuple of pytree): A tuple of pytrees, they should have a common suffix structure with each other and with ``tree``. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A new pytree with the structure as the common suffix structure of ``tree`` and ``rests`` but with the value at each leaf given by ``func(a, x, *xs)`` where ``(a, x)`` are the accessor and value at the corresponding leaf (may be broadcasted) in and ``xs`` is the tuple of values at corresponding leaves (may be broadcasted) in ``rests``. r)r0rrs rlr>r>sM\ "      %   !  rmc$eZdZUdZded<ddZy)MissingSentinelrzClassVar[tuple[()]] __slots__cy)Nz r)selfs rl__repr__zMissingSentinel.__repr__]srmN)rstr)__name__ __module__ __qualname__r__annotations__rrrmrlrrZs%'I"'rmrr __MISSINGcyrr)rrjrkrcrds rlr?r?e rmcyrr)rrjinitialrkrcrds rlr?r?q rmct||||}|turtj||Stj|||S)aTraversal through a pytree and reduce the leaves in left-to-right depth-first order. See also :func:`tree_leaves` and :func:`tree_sum`. >>> tree_reduce(lambda x, y: x + y, {'x': 1, 'y': (2, 3)}) 6 >>> tree_reduce(lambda x, y: x + y, {'x': 1, 'y': (2, None), 'z': 3}) # `None` is a non-leaf node with arity 0 by default 6 >>> tree_reduce(lambda x, y: x and y, {'x': 1, 'y': (2, None), 'z': 3}) 3 >>> tree_reduce(lambda x, y: x and y, {'x': 1, 'y': (2, None), 'z': 3}, none_is_leaf=True) None Args: func (callable): A function that takes two arguments and returns a value of the same type. tree (pytree): A pytree to be traversed. initial (object, optional): An initial value to be used for the reduction. If not provided, the first leaf value is used as the initial value. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: The result of reducing the leaves of the pytree using ``func``. r)r&r functoolsreduce)rrjrrkrcrdrts rlr?r?~sFTw\U^ _F)f--   D&' 22rmct||||}t|trdj|g|St|tt frdj|g|St ||S)aSum ``start`` and leaf values in ``tree`` in left-to-right depth-first order and return the total. See also :func:`tree_leaves` and :func:`tree_reduce`. >>> tree_sum({'x': 1, 'y': (2, 3)}) 6 >>> tree_sum({'x': 1, 'y': (2, None), 'z': 3}) # `None` is a non-leaf node with arity 0 by default 6 >>> tree_sum({'x': 1, 'y': (2, None), 'z': 3}, none_is_leaf=True) Traceback (most recent call last): ... TypeError: unsupported operand type(s) for +: 'int' and 'NoneType' >>> tree_sum({'x': 'a', 'y': ('b', None), 'z': 'c'}, start='') 'abc' >>> tree_sum({'x': [1], 'y': ([2], [None]), 'z': [3]}, start=[], is_leaf=lambda x: isinstance(x, list)) [1, 2, None, 3] Args: tree (pytree): A pytree to be traversed. start (object, optional): An initial value to be used for the sum. (default: :data:`0`) is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: The total sum of ``start`` and leaf values in ``tree``. rrarm)r& isinstancerjoinbytes bytearraysum)rjstartrkrcrdrts rlr@r@sjVw\U^ _F%ww''((%%+,xx(()) vu rm)rkkeyrcrdcyrr)rjrkrrcrds rlrArArrm)defaultrrkrcrdcyrrrjrrrkrcrds rlrArArrmcft||||}|tur t||St|||S)aReturn the maximum leaf value in ``tree``. See also :func:`tree_leaves` and :func:`tree_min`. >>> tree_max({}) Traceback (most recent call last): ... ValueError: max() iterable argument is empty >>> tree_max({}, default=0) 0 >>> tree_max({'x': 0, 'y': (2, 1)}) 2 >>> tree_max({'x': 0, 'y': (2, 1)}, key=lambda x: -x) 0 >>> tree_max({'a': None}) # `None` is a non-leaf node with arity 0 by default Traceback (most recent call last): ... ValueError: max() iterable argument is empty >>> tree_max({'a': None}, default=0) # `None` is a non-leaf node with arity 0 by default 0 >>> tree_max({'a': None}, none_is_leaf=True) None >>> tree_max(None) # `None` is a non-leaf node with arity 0 by default Traceback (most recent call last): ... ValueError: max() iterable argument is empty >>> tree_max(None, default=0) 0 >>> tree_max(None, none_is_leaf=True) None Args: tree (pytree): A pytree to be traversed. default (object, optional): The default value to return if ``tree`` is empty. If the ``tree`` is empty and ``default`` is not specified, raise a :exc:`ValueError`. key (callable or None, optional): An one argument ordering function like that used for :meth:`list.sort`. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: The maximum leaf value in ``tree``. rrrr)r&rmaxrjrrrkrcrdrts rlrArA:zw\U^ _F)6s## vwC 00rm)rrkrcrdcyrr)rjrrkrcrds rlrBrB> rrmcyrrrs rlrBrBJ rrmcft||||}|tur t||St|||S)aReturn the minimum leaf value in ``tree``. See also :func:`tree_leaves` and :func:`tree_max`. >>> tree_min({}) Traceback (most recent call last): ... ValueError: min() iterable argument is empty >>> tree_min({}, default=0) 0 >>> tree_min({'x': 0, 'y': (2, 1)}) 0 >>> tree_min({'x': 0, 'y': (2, 1)}, key=lambda x: -x) 2 >>> tree_min({'a': None}) # `None` is a non-leaf node with arity 0 by default Traceback (most recent call last): ... ValueError: min() iterable argument is empty >>> tree_min({'a': None}, default=0) # `None` is a non-leaf node with arity 0 by default 0 >>> tree_min({'a': None}, none_is_leaf=True) None >>> tree_min(None) # `None` is a non-leaf node with arity 0 by default Traceback (most recent call last): ... ValueError: min() iterable argument is empty >>> tree_min(None, default=0) 0 >>> tree_min(None, none_is_leaf=True) None Args: tree (pytree): A pytree to be traversed. default (object, optional): The default value to return if ``tree`` is empty. If the ``tree`` is empty and ``default`` is not specified, raise a :exc:`ValueError`. key (callable or None, optional): An one argument ordering function like that used for :meth:`list.sort`. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: The minimum leaf value in ``tree``. rrr)r&rminrs rlrBrBW rrmc2tt||||S)a Test whether all leaves in ``tree`` are true (or if ``tree`` is empty). See also :func:`tree_leaves` and :func:`tree_any`. >>> tree_all({}) True >>> tree_all({'x': 1, 'y': (2, 3)}) True >>> tree_all({'x': 1, 'y': (2, None), 'z': 3}) # `None` is a non-leaf node by default True >>> tree_all({'x': 1, 'y': (2, None), 'z': 3}, none_is_leaf=True) False >>> tree_all(None) # `None` is a non-leaf node by default True >>> tree_all(None, none_is_leaf=True) False Args: tree (pytree): A pytree to be traversed. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: :data:`True` if all leaves in ``tree`` are true, or if ``tree`` is empty. Otherwise, :data:`False`. r)allr%ris rlrCrC &T  %   rmc2tt||||S)a_Test whether all leaves in ``tree`` are true (or :data:`False` if ``tree`` is empty). See also :func:`tree_leaves` and :func:`tree_all`. >>> tree_any({}) False >>> tree_any({'x': 0, 'y': (2, 0)}) True >>> tree_any({'a': None}) # `None` is a non-leaf node with arity 0 by default False >>> tree_any({'a': None}, none_is_leaf=True) # `None` is evaluated as false False >>> tree_any(None) # `None` is a non-leaf node with arity 0 by default False >>> tree_any(None, none_is_leaf=True) # `None` is evaluated as false False Args: tree (pytree): A pytree to be traversed. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: :data:`True` if any leaves in ``tree`` are true, otherwise, :data:`False`. If ``tree`` is empty, return :data:`False`. r)anyr%ris rlrDrD rrmc@eZdZUdZded< ded< ded< ded <y ) FlattenOneLevelOutput-The output of :func:`tree_flatten_one_level`.zlist[PyTree[T]]childrenrmetadataztuple[Any, ...]entrieszUnflattenFunc[PyTree[T]]unflatten_funcNrrr__doc__rrrmrlr#r# s)7:; 2,,ermr#c4eZdZUdZded< ded< ded<y) FlattenOneLevelOutputExr$zbuiltins.type[Collection[T]]typezbuiltins.type[PyTreeEntry]path_entry_typerkindNr)rrmrlr,r, s 7 &&&//9 &rmr,c t|}||s |||rtd|d|dddlm}|j ||}|td|d|dt |j |}t|dk(rg|d}n)t|d k7rtd |d t|d |\}} } t|}t | tt|n| } t|t| k7r'td |d t|dt| dt|| | |j} || _|j| _ |j| _| S)aOFlatten the pytree one level, returning a 4-tuple of children, metadata, path entries, and an unflatten function. See also :func:`tree_flatten`, :func:`tree_flatten_with_path`. >>> children, metadata, entries, unflatten_func = tree_flatten_one_level({'b': (2, [3, 4]), 'a': 1, 'c': None, 'd': 5}) >>> children, metadata, entries ([1, (2, [3, 4]), None, 5], ['a', 'b', 'c', 'd'], ('a', 'b', 'c', 'd')) >>> unflatten_func(metadata, children) {'a': 1, 'b': (2, [3, 4]), 'c': None, 'd': 5} >>> children, metadata, entries, unflatten_func = tree_flatten_one_level([{'a': 1, 'b': (2, 3)}, (4, 5)]) >>> children, metadata, entries ([{'a': 1, 'b': (2, 3)}, (4, 5)], None, (0, 1)) >>> unflatten_func(metadata, children) [{'a': 1, 'b': (2, 3)}, (4, 5)] Args: tree (pytree): A pytree to be traversed. is_leaf (callable, optional): An optionally specified function that will be called at each flattening step. It should return a boolean, with :data:`True` stopping the traversal and the whole subtree being treated as a leaf, and :data:`False` indicating the flattening should traverse the current object. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A 4-tuple ``(children, metadata, entries, unflatten_func)``. The first element is a list of one-level children of the pytree node. The second element is the metadata used to reconstruct the pytree node. The third element is a tuple of path entries to the children. The fourth element is a function that can be used to unflatten the metadata and children back to the pytree node. NzCannot flatten leaf-type: z (node: z).r)register_pytree_node)rdrz(PyTree custom flatten function for type z$ should return a 2- or 3-tuple, got rz+ returned inconsistent number of children (z) and number of entries ()r%r&r'r()r-roptree.registryr1gettuple flatten_funcr RuntimeErrorrrr,r(r.r/) rjrkrcrd node_typer1handler flattenedr%r&r'outputs rlrErE sVT I 7+>74=5i[PRSTT4"&&yI&FG5i[PRSTTg**401I 9~&i&& Y1 6ykBy>"! %  #,HhH~HGOE#h-(IG 8}G $6ykB##&x=/1J3w<.XZ \  %-- F FK$44F,,FK Mrmc"|jS)aReturn a list of paths to the leaves of a treespec. See also :func:`tree_flatten_with_path`, :func:`tree_paths`, and :meth:`PyTreeSpec.paths`. >>> treespec = tree_structure({'b': 3, 'a': (0, [1, 2]), 'c': (4, None)}) >>> treespec PyTreeSpec({'a': (*, [*, *]), 'b': *, 'c': (*, None)}) >>> treespec_paths(treespec) [('a', 0), ('a', 1, 0), ('a', 1, 1), ('b',), ('c', 0)] )rrus rlrFrFs s >> rmc"|jS)aReturn a list of accessors to the leaves of a treespec. See also :func:`tree_flatten_with_accessor`, :func:`tree_accessors`, and :meth:`PyTreeSpec.accessors`. >>> treespec = tree_structure({'b': 3, 'a': (0, [1, 2]), 'c': (4, None)}) >>> treespec PyTreeSpec({'a': (*, [*, *]), 'b': *, 'c': (*, None)}) >>> treespec_accessors(treespec) # doctest: +IGNORE_WHITESPACE,ELLIPSIS [ PyTreeAccessor(*['a'][0], ...), PyTreeAccessor(*['a'][1][0], ...), PyTreeAccessor(*['a'][1][1], ...), PyTreeAccessor(*['b'], ...), PyTreeAccessor(*['c'][0], ...) ] >>> treespec_accessors(treespec_leaf()) [PyTreeAccessor(*, ())] >>> treespec_accessors(treespec_none()) [] )rsr=s rlrGrG s,    rmc"|jS)aReturn a list of one-level entries of a treespec to its children. See also :func:`treespec_entry`, :func:`treespec_paths`, :func:`treespec_children`, and :meth:`PyTreeSpec.entries`. >>> treespec = tree_structure({'b': 3, 'a': (0, [1, 2]), 'c': (4, None)}) >>> treespec PyTreeSpec({'a': (*, [*, *]), 'b': *, 'c': (*, None)}) >>> treespec_entries(treespec) ['a', 'b', 'c'] )r'r=s rlrHrH s    rmc$|j|S)zReturn the entry of a treespec at the given index. See also :func:`treespec_entries`, :func:`treespec_children`, and :meth:`PyTreeSpec.entry`. )entryruindexs rlrIrI  >>%  rmc"|jS)aReturn a list of treespecs for the children of a treespec. See also :func:`treespec_child`, :func:`treespec_paths`, :func:`treespec_entries`, :func:`treespec_one_level`, and :meth:`PyTreeSpec.children`. >>> treespec = tree_structure({'b': 3, 'a': (0, [1, 2]), 'c': (4, None)}) >>> treespec PyTreeSpec({'a': (*, [*, *]), 'b': *, 'c': (*, None)}) >>> treespec_children(treespec) [PyTreeSpec((*, [*, *])), PyTreeSpec(*), PyTreeSpec((*, None))] )r%r=s rlrJrJ s    rmc$|j|S)zReturn the treespec of the child of a treespec at the given index. See also :func:`treespec_children`, :func:`treespec_entries`, and :meth:`PyTreeSpec.child`. )childrBs rlrKrK rDrmc"|jS)aReturn the one-level tree structure of the treespec or :data:`None` if the treespec is a leaf. See also :func:`treespec_children`, :func:`treespec_is_one_level`, and :meth:`PyTreeSpec.one_level`. >>> treespec = tree_structure({'b': 3, 'a': (0, [1, 2]), 'c': (4, None)}) >>> treespec PyTreeSpec({'a': (*, [*, *]), 'b': *, 'c': (*, None)}) >>> treespec_one_level(treespec) PyTreeSpec({'a': *, 'b': *, 'c': *}) ) one_levelr=s rlrLrL s    rmc&|j||S)aTransform a treespec by applying functions to its nodes and leaves. See also :func:`treespec_children`, :func:`treespec_is_leaf`, and :meth:`PyTreeSpec.transform`. >>> treespec = tree_structure({'b': 3, 'a': (0, [1, 2]), 'c': (4, None)}) >>> treespec PyTreeSpec({'a': (*, [*, *]), 'b': *, 'c': (*, None)}) >>> treespec_transform(treespec, lambda spec: treespec_dict(zip(spec.entries(), spec.children()))) PyTreeSpec({'a': {0: *, 1: {0: *, 1: *}}, 'b': *, 'c': {0: *, 1: {}}}) >>> treespec_transform( ... treespec, ... lambda spec: ( ... treespec_ordereddict(zip(spec.entries(), spec.children())) ... if spec.type is dict ... else spec ... ), ... ) PyTreeSpec(OrderedDict({'a': (*, [*, *]), 'b': *, 'c': (*, None)})) >>> treespec_transform( ... treespec, ... lambda spec: ( ... treespec_ordereddict(tree_unflatten(spec, spec.children())) ... if spec.type is dict ... else spec ... ), ... ) PyTreeSpec(OrderedDict({'b': (*, [*, *]), 'a': *, 'c': (*, None)})) >>> treespec_transform(treespec, lambda spec: treespec_tuple(spec.children())) PyTreeSpec(((*, (*, *)), *, (*, ()))) >>> treespec_transform( ... treespec, ... lambda spec: ( ... treespec_list(spec.children()) ... if spec.type is tuple ... else spec ... ), ... ) PyTreeSpec({'a': [*, [*, *]], 'b': *, 'c': [*, None]}) >>> treespec_transform(treespec, None, lambda spec: tree_structure((1, [2]))) PyTreeSpec({'a': ((*, [*]), [(*, [*]), (*, [*])]), 'b': (*, [*]), 'c': ((*, [*]), None)}) ) transform)ruf_nodef_leafs rlrMrM s^   ff --rmstrictcd|r |jdk(xr|jdk(S|jdk(S)aReturn whether the treespec is a leaf that has no children. See also :func:`treespec_is_strict_leaf` and :meth:`PyTreeSpec.is_leaf`. This function is equivalent to ``treespec.is_leaf(strict=strict)``. If ``strict=False``, it will return :data:`True` if and only if the treespec represents a strict leaf. If ``strict=False``, it will return :data:`True` if the treespec represents a strict leaf or :data:`None` or an empty container (e.g., an empty tuple). >>> treespec_is_leaf(tree_structure(1)) True >>> treespec_is_leaf(tree_structure((1, 2))) False >>> treespec_is_leaf(tree_structure(None)) False >>> treespec_is_leaf(tree_structure(None), strict=False) True >>> treespec_is_leaf(tree_structure(None, none_is_leaf=False)) False >>> treespec_is_leaf(tree_structure(None, none_is_leaf=True)) True >>> treespec_is_leaf(tree_structure(())) False >>> treespec_is_leaf(tree_structure(()), strict=False) True >>> treespec_is_leaf(tree_structure([])) False >>> treespec_is_leaf(tree_structure([]), strict=False) True Args: treespec (PyTreeSpec): A treespec. strict (bool, optional): Whether not to treat :data:`None` or an empty container (e.g., an empty tuple) as a leaf. (default: :data:`True`) Returns: :data:`True` if the treespec represents a leaf that has no children, otherwise, :data:`False`. r} num_nodesr)rurOs rlrNrN s:N!!Q&C8+>+>!+CC    ""rmcB|jdk(xr|jdk(S)aReturn whether the treespec is a strict leaf. See also :func:`treespec_is_leaf` and :meth:`PyTreeSpec.is_leaf`. This function respects the ``none_is_leaf`` setting in the treespec. It is equivalent to ``treespec.is_leaf(strict=True)``. It will return :data:`True` if and only if the treespec represents a strict leaf. >>> treespec_is_strict_leaf(tree_structure(1)) True >>> treespec_is_strict_leaf(tree_structure((1, 2))) False >>> treespec_is_strict_leaf(tree_structure(None)) False >>> treespec_is_strict_leaf(tree_structure(None, none_is_leaf=False)) False >>> treespec_is_strict_leaf(tree_structure(None, none_is_leaf=True)) True >>> treespec_is_strict_leaf(tree_structure(())) False >>> treespec_is_strict_leaf(tree_structure([])) False Args: treespec (PyTreeSpec): A treespec. Returns: :data:`True` if the treespec represents a strict leaf, otherwise, :data:`False`. r}rQr=s rlrOrO4 s%<    " ?x':':a'??rmcp|j|jdzk(xr|j|jk(S)aReturn whether the treespec is a one-level tree structure. See also :func:`treespec_is_leaf`, :func:`treespec_one_level`, and :meth:`PyTreeSpec.is_one_level`. >>> treespec_is_one_level(tree_structure(1)) False >>> treespec_is_one_level(tree_structure((1, 2))) True >>> treespec_is_one_level(tree_structure({'a': 1, 'b': 2, 'c': 3})) True >>> treespec_is_one_level(tree_structure({'a': 1, 'b': (2, 3), 'c': 4})) False >>> treespec_is_one_level(tree_structure(None)) True r})rR num_childrenrr=s rlrPrPU s;" h33a77 9   8#8#8 8rmc(|j||S)zReturn whether ``treespec`` is a prefix of ``other_treespec``. See also :func:`treespec_is_prefix` and :meth:`PyTreeSpec.is_prefix`. rN) is_prefixrurrOs rlrQrQk    nV  <>> treespec_leaf() PyTreeSpec(*) >>> treespec_leaf(none_is_leaf=True) PyTreeSpec(*, NoneIsLeaf) >>> treespec_leaf(none_is_leaf=False) == treespec_leaf(none_is_leaf=True) False >>> treespec_leaf() == tree_structure(1) True >>> treespec_leaf(none_is_leaf=True) == tree_structure(1, none_is_leaf=True) True >>> treespec_leaf(none_is_leaf=True) == tree_structure(None, none_is_leaf=True) True >>> treespec_leaf(none_is_leaf=True) == tree_structure(None, none_is_leaf=False) False >>> treespec_leaf(none_is_leaf=True) == treespec_none(none_is_leaf=True) True >>> treespec_leaf(none_is_leaf=True) == treespec_none(none_is_leaf=False) False >>> treespec_leaf(none_is_leaf=False) == treespec_none(none_is_leaf=True) False >>> treespec_leaf(none_is_leaf=False) == treespec_none(none_is_leaf=False) False Args: none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec representing a leaf node. )rg make_leafrbs rlrSrS sV << rmc.tj||S)a|Make a treespec representing a :data:`None` node. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_tuple`. >>> treespec_none() PyTreeSpec(None) >>> treespec_none(none_is_leaf=True) PyTreeSpec(*, NoneIsLeaf) >>> treespec_none(none_is_leaf=False) == treespec_none(none_is_leaf=True) False >>> treespec_none() == tree_structure(None) True >>> treespec_none() == tree_structure(1) False >>> treespec_none(none_is_leaf=True) == tree_structure(1, none_is_leaf=True) True >>> treespec_none(none_is_leaf=True) == tree_structure(None, none_is_leaf=True) True >>> treespec_none(none_is_leaf=True) == tree_structure(None, none_is_leaf=False) False >>> treespec_none(none_is_leaf=True) == treespec_leaf(none_is_leaf=True) True >>> treespec_none(none_is_leaf=False) == treespec_leaf(none_is_leaf=True) False >>> treespec_none(none_is_leaf=True) == treespec_leaf(none_is_leaf=False) False >>> treespec_none(none_is_leaf=False) == treespec_leaf(none_is_leaf=False) False Args: none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec representing a :data:`None` node. )rg make_nonerbs rlrTrT sZ << rmcBtjt|||S)a,Make a tuple treespec from an iterable of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. >>> treespec_tuple([treespec_leaf(), treespec_leaf()]) PyTreeSpec((*, *)) >>> treespec_tuple([treespec_leaf(), treespec_leaf(), treespec_none()]) PyTreeSpec((*, *, None)) >>> treespec_tuple() PyTreeSpec(()) >>> treespec_tuple([treespec_leaf(), treespec_tuple([treespec_leaf(), treespec_leaf()])]) PyTreeSpec((*, (*, *))) >>> treespec_tuple([treespec_leaf(), tree_structure({'a': 1, 'b': 2})]) PyTreeSpec((*, {'a': *, 'b': *})) >>> treespec_tuple([treespec_leaf(), tree_structure({'a': 1, 'b': 2}, none_is_leaf=True)]) Traceback (most recent call last): ... ValueError: Expected treespec(s) with `none_is_leaf=False`. Args: iterable (iterable of PyTreeSpec, optional): A iterable of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec representing a tuple node with the given children. )rgmake_from_collectionr5rrcrds rlrUrU s%N  " " h rmcBtjt|||S)a$Make a list treespec from an iterable of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. >>> treespec_list([treespec_leaf(), treespec_leaf()]) PyTreeSpec([*, *]) >>> treespec_list([treespec_leaf(), treespec_leaf(), treespec_none()]) PyTreeSpec([*, *, None]) >>> treespec_list() PyTreeSpec([]) >>> treespec_list([treespec_leaf(), treespec_tuple([treespec_leaf(), treespec_leaf()])]) PyTreeSpec([*, (*, *)]) >>> treespec_list([treespec_leaf(), tree_structure({'a': 1, 'b': 2})]) PyTreeSpec([*, {'a': *, 'b': *}]) >>> treespec_list([treespec_leaf(), tree_structure({'a': 1, 'b': 2}, none_is_leaf=True)]) Traceback (most recent call last): ... ValueError: Expected treespec(s) with `none_is_leaf=False`. Args: iterable (iterable of PyTreeSpec, optional): A iterable of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec representing a list node with the given children. )rgrarrbs rlrVrV s%N  " " X rmc Dtjt|fi|||S)aMake a dict treespec from a dict of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. >>> treespec_dict({'a': treespec_leaf(), 'b': treespec_leaf()}) PyTreeSpec({'a': *, 'b': *}) >>> treespec_dict([('b', treespec_leaf()), ('c', treespec_leaf()), ('a', treespec_none())]) PyTreeSpec({'a': None, 'b': *, 'c': *}) >>> treespec_dict() PyTreeSpec({}) >>> treespec_dict(a=treespec_leaf(), b=treespec_tuple([treespec_leaf(), treespec_leaf()])) PyTreeSpec({'a': *, 'b': (*, *)}) >>> treespec_dict({'a': treespec_leaf(), 'b': tree_structure([1, 2])}) PyTreeSpec({'a': *, 'b': [*, *]}) >>> treespec_dict({'a': treespec_leaf(), 'b': tree_structure([1, 2], none_is_leaf=True)}) Traceback (most recent call last): ... ValueError: Expected treespec(s) with `none_is_leaf=False`. Args: mapping (mapping of PyTreeSpec, optional): A mapping of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) **kwargs (PyTreeSpec, optional): Additional child treespecs to add to the mapping. Returns: A treespec representing a dict node with the given children. )rgradictmappingrcrdkwargss rlrWrWG s+R  " " W rmcdt|std|dtj|||S)a(Make a namedtuple treespec from a namedtuple of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. >>> from collections import namedtuple >>> Point = namedtuple('Point', ['x', 'y']) >>> treespec_namedtuple(Point(x=treespec_leaf(), y=treespec_leaf())) PyTreeSpec(Point(x=*, y=*)) >>> treespec_namedtuple(Point(x=treespec_leaf(), y=treespec_tuple([treespec_leaf(), treespec_leaf()]))) PyTreeSpec(Point(x=*, y=(*, *))) >>> treespec_namedtuple(Point(x=treespec_leaf(), y=tree_structure([1, 2]))) PyTreeSpec(Point(x=*, y=[*, *])) >>> treespec_namedtuple(Point(x=treespec_leaf(), y=tree_structure([1, 2], none_is_leaf=True))) Traceback (most recent call last): ... ValueError: Expected treespec(s) with `none_is_leaf=False`. Args: namedtuple (namedtuple of PyTreeSpec): A namedtuple of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec representing a dict node with the given children. z,Expected a namedtuple of PyTreeSpec(s), got r)rrrgra) namedtuplercrds rlrXrXw s?J "* -G ~UVWXX " " rmc Dtjt|fi|||S)a<Make an OrderedDict treespec from an OrderedDict of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. >>> treespec_ordereddict({'a': treespec_leaf(), 'b': treespec_leaf()}) PyTreeSpec(OrderedDict({'a': *, 'b': *})) >>> treespec_ordereddict([('b', treespec_leaf()), ('c', treespec_leaf()), ('a', treespec_none())]) PyTreeSpec(OrderedDict({'b': *, 'c': *, 'a': None})) >>> treespec_ordereddict() PyTreeSpec(OrderedDict()) >>> treespec_ordereddict(a=treespec_leaf(), b=treespec_tuple([treespec_leaf(), treespec_leaf()])) PyTreeSpec(OrderedDict({'a': *, 'b': (*, *)})) >>> treespec_ordereddict({'a': treespec_leaf(), 'b': tree_structure([1, 2])}) PyTreeSpec(OrderedDict({'a': *, 'b': [*, *]})) >>> treespec_ordereddict({'a': treespec_leaf(), 'b': tree_structure([1, 2], none_is_leaf=True)}) Traceback (most recent call last): ... ValueError: Expected treespec(s) with `none_is_leaf=False`. Args: mapping (mapping of PyTreeSpec, optional): A mapping of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) **kwargs (PyTreeSpec, optional): Additional child treespecs to add to the mapping. Returns: A treespec representing an OrderedDict node with the given children. )rgrarrfs rlrYrY s+R  " "G&v& rmc Ftjt||fi|||S)aMake a defaultdict treespec from a defaultdict of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. >>> treespec_defaultdict(int, {'a': treespec_leaf(), 'b': treespec_leaf()}) PyTreeSpec(defaultdict(, {'a': *, 'b': *})) >>> treespec_defaultdict(int, [('b', treespec_leaf()), ('c', treespec_leaf()), ('a', treespec_none())]) PyTreeSpec(defaultdict(, {'a': None, 'b': *, 'c': *})) >>> treespec_defaultdict() PyTreeSpec(defaultdict(None, {})) >>> treespec_defaultdict(int) PyTreeSpec(defaultdict(, {})) >>> treespec_defaultdict(int, a=treespec_leaf(), b=treespec_tuple([treespec_leaf(), treespec_leaf()])) PyTreeSpec(defaultdict(, {'a': *, 'b': (*, *)})) >>> treespec_defaultdict(int, {'a': treespec_leaf(), 'b': tree_structure([1, 2])}) PyTreeSpec(defaultdict(, {'a': *, 'b': [*, *]})) >>> treespec_defaultdict(int, {'a': treespec_leaf(), 'b': tree_structure([1, 2], none_is_leaf=True)}) Traceback (most recent call last): ... ValueError: Expected treespec(s) with `none_is_leaf=False`. Args: default_factory (callable or None, optional): A factory function that will be used to create a missing value. (default: :data:`None`) mapping (mapping of PyTreeSpec, optional): A mapping of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) **kwargs (PyTreeSpec, optional): Additional child treespecs to add to the mapping. Returns: A treespec representing a defaultdict node with the given children. )rgrar)default_factoryrgrcrdrhs rlrZrZ s-\  " "OW77 rmcFtjt||||S)aMake a deque treespec from a deque of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. >>> treespec_deque([treespec_leaf(), treespec_leaf()]) PyTreeSpec(deque([*, *])) >>> treespec_deque([treespec_leaf(), treespec_leaf(), treespec_none()], maxlen=5) PyTreeSpec(deque([*, *, None], maxlen=5)) >>> treespec_deque() PyTreeSpec(deque([])) >>> treespec_deque([treespec_leaf(), treespec_tuple([treespec_leaf(), treespec_leaf()])]) PyTreeSpec(deque([*, (*, *)])) >>> treespec_deque([treespec_leaf(), tree_structure({'a': 1, 'b': 2})], maxlen=5) PyTreeSpec(deque([*, {'a': *, 'b': *}], maxlen=5)) >>> treespec_deque([treespec_leaf(), tree_structure({'a': 1, 'b': 2}, none_is_leaf=True)], maxlen=5) Traceback (most recent call last): ... ValueError: Expected treespec(s) with `none_is_leaf=False`. Args: iterable (iterable of PyTreeSpec, optional): A iterable of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. maxlen (int or None, optional): The maximum size of a deque or :data:`None` if unbounded. (default: :data:`None`) none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec representing a deque node with the given children. r)rgrar)rrrcrds rlr[r[ s(T  " " hv& rmcdt|std|dtj|||S)aMake a PyStructSequence treespec from a PyStructSequence of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. Args: structseq (PyStructSequence of PyTreeSpec): A PyStructSequence of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec representing a PyStructSequence node with the given children. z2Expected a PyStructSequence of PyTreeSpec(s), got r)rrrgra) structseqrcrds rlr\r\; s>0 ! +Mi]Z[\]] " " rmc0tj|||S)aMake a treespec from a collection of child treespecs. See also :func:`tree_structure`, :func:`treespec_leaf`, and :func:`treespec_none`. >>> treespec_from_collection(None) PyTreeSpec(None) >>> treespec_from_collection(None, none_is_leaf=True) PyTreeSpec(*, NoneIsLeaf) >>> treespec_from_collection(object()) PyTreeSpec(*) >>> treespec_from_collection([treespec_leaf(), treespec_none()]) PyTreeSpec([*, None]) >>> treespec_from_collection({'a': treespec_leaf(), 'b': treespec_none()}) PyTreeSpec({'a': *, 'b': None}) >>> treespec_from_collection(deque([treespec_leaf(), tree_structure({'a': 1, 'b': 2})], maxlen=5)) PyTreeSpec(deque([*, {'a': *, 'b': *}], maxlen=5)) >>> treespec_from_collection({'a': treespec_leaf(), 'b': (treespec_leaf(), treespec_none())}) Traceback (most recent call last): ... ValueError: Expected a(n) dict of PyTreeSpec(s), got {'a': PyTreeSpec(*), 'b': (PyTreeSpec(*), PyTreeSpec(None))}. >>> treespec_from_collection([treespec_leaf(), tree_structure({'a': 1, 'b': 2}, none_is_leaf=True)]) Traceback (most recent call last): ... ValueError: Expected treespec(s) with `none_is_leaf=False`. Args: collection (collection of PyTreeSpec): A collection of child treespecs. They must have the same ``none_is_leaf`` and ``namespace`` values. none_is_leaf (bool, optional): Whether to treat :data:`None` as a leaf. If :data:`False`, :data:`None` is a non-leaf node with arity 0. Thus :data:`None` is contained in the treespec rather than in the leaves list and :data:`None` will be remain in the result pytree. (default: :data:`False`) namespace (str, optional): The registry namespace used for custom pytree node types. (default: :const:`''`, i.e., the global namespace) Returns: A treespec representing the same structure of the collection with the given children. )rgra) collectionrcrds rlr]r]\ s\  " ":|Y GGrmzfrozenset[type]STANDARD_DICT_TYPEScb dfd tt||S)zIReturn a list of errors that would be raised by :func:`broadcast_prefix`.c 3Kt!#"rytttvxrtv}tuxrtu}ur |s fdyt #"x}\}}}t #"x} \} } }|rt ur|n|dt ur| n| dt } t } | | k7rWt| j| }t| j| }d|rd|z |rd|z fdyDcgc]}| c}ttk7r fd y|| k7r||sz|sxt|t| tjd jtjj!j!d fd y|Dcgc]}|j#||j$!}}| Dcgc]}| j#|| j$!}}|s||k(s Jd|d|t'|D]\}}} |z||Ed{ycc}wcc}wcc}w7w)Nrc tdrj|n|dzd|dtdtd S)Nz8pytree structure error: different types at key path tree root% At that key path, the prefix pytree  has a subtree of type zN but at the same key path the full pytree has a subtree of different type r)rcodifyr-)nameaccessor full_subtreeprefix_subtrees rlrz/prefix_errors..helper.. s[z08xt,d\>QRS77;f=N+,-L)*! - rmrbr}raz missing key(s): z extra key(s): ctdrj|n|dzd|ddtdddtdS) Nz>pytree structure error: different pytree keys at key path rwrxry with z key(s) zD but at the same key path the full pytree has a subtree of type z but with rrzr)r{r|full_tree_keysfull_tree_typekey_differenceprefix_tree_keysprefix_tree_types rlrz/prefix_errors..helper.. s:4<8??40$BUVW;;?&A+,- 0123+,-)*+ #N 345)*>*: < $rmctdrj|n|dzd|ddtdtd S)NzMpytree structure error: different numbers of pytree children at key path rwrxryrz\ children, but at the same key path the full pytree has a subtree of the same type but with z children.r)r{r|full_tree_childrenprefix_tree_childrenrs rlrz/prefix_errors..helper.. siz08xt,d\>QRS77;f='()0123!!$%7!8 9 E rm z )prefixcjtdrj|n|dzd|dddd S)NzBpytree structure error: different pytree metadata at key path rwrxryz with metadata z_ but at the same key path the full pytree has a subtree of the same type but with metadata z6 so the diff in the metadata at these pytree nodes is )rrz)r{r|full_tree_metadata_repr metadata_diffprefix_tree_metadata_reprrs rlrz/prefix_errors..helper..sgz08xt,d\>QRS77;f='()012//0I / # rmz(equal pytree nodes gave different keys: z and )r*r-rsrrErsetsorted differencerreprtextwrapindentr difflibndiff splitlinesr.r/r)$r|r~r}both_standard_dict both_dequeprefix_tree_one_level_outputprefix_tree_metadataprefix_tree_entriesrfull_tree_one_level_outputfull_tree_metadatafull_tree_entriesprefix_tree_keys_setfull_tree_keys_set missing_keys extra_keysker'entries_t1t2rrrrrrrrrrhelperrkrdrcs$``` @@@@@@@@@@rlrzprefix_errors..helper sZ  %   /l+  3 3 ]J]8] &.J>U3J N 2&   # % $(   # % "&     $;6%)!, "4#'*  $''7#8 !$^!4 #'99%&:&E&EFX&YZ #$6$A$ABV$WX !#"(? ~&NNN"(=j\&JJN   (? ?   !$6 6')--A(B %&*+=&> #$OO MM1<<>/::< M   )   ) 8 8 ,11   '   ' 6 6*//    (" O6gYeH: N O #W&:rrr?r@rArBrCrDr#r,rErFrGrHrIrJrKrLrMrNrOrPrQrRrSrTrUrVrWrXrYrZr[r\r] frozensetrersr^rrmrlrs*#77LL+VV==,   B H11S1  dJ dF +/B>  B>(B> B>  B>  B> B>P+/GH  GH(GH GH  GH  GH7GHZ+/b2  b2(b2 b2  b2  b26b2J&2+/'A  'A('A 'A  'A  'A'AZ+/'A  'A('A 'A  'A  'A 'AZ+/'A  'A('A 'A  'A  'A'AZ+/'K  'K('K 'K  'K  'K'KZ+/5M  5M(5M 5M  5M  5M5Mv+/$>  $>($> $>  $>  $> $>T+/2E  2E(2E2E  2E  2E 2Et+/65 65 65  65 ( 65  656565|+/' ' '  ' ( '  '''^+/0< 0< 0<  0< ( 0<  0<0<0