uki LUddlmZddlZddlmZmZmZmZddlZddl Z ddl Z ddl m Z ddl Z ddlZddlmZmZddlmZddlmZddlmZmZdd lmZed Zej6eed Zed ee Zede Z eZ!eZ"ejFZ#ejHZ$e%e$_&de$_%ejNdddddZ(e%e(_&de(_%ejNdddddZ)e%e)_&de)_%e dd dedZ*edfdZ+e dd dgdZ,e dd dhdZ-edidZ.edjdZ/edkdZ0dkdZ1e dd dldZ2edee Z3ed e Z4ed!e Z5e6e5efZ7ee7Z8e6e5d"fZ9e dd dmd#Z:ednd$Z;edd% dod&Zej~d)d*d+gZ@e6e@d,d-eAe@d.d/eBe@d0d1ede@d2d3iZCd4eDd5<Gd6d7ZEeeEdf drd8ZFeEf dsd9ZGeeEdd: dtd;ZHedd%dud<ZIGd=d>ZJeGd?d@e jZKe:eKdAdBe dd dvdCZL dd dwdDZM dxdEZNdydFZO dzdGZP dd d{dHZQ dd d|dIZR d}dJZSdKZTejZUdeDdL<ejZVdeDdM<ejZWdeDdN<ejZXdeDdO<eddPdQd~dRZYddSZZe dd ddTZ[edndUZ\e d ddVZ]e[ejdWdXdYZ_e[eje_dZedd[Zae d dd\Zbe d dd]ZcecZdeddd^ dd_Zedd`Zf dd ddaZgGdbdcZhy)) annotationsN)CallableHashableIterableSequence)partial)AnyTypeVar)traceback_utilpytree)safe_zip set_module)unzip2z jax.tree_utilTTyp)boundHdefault_registryFT) enable_none enable_tupleenable_namedtuple enable_list enable_dictnone_leaf_registrydispatch_registryr c.tj||S)z"Alias of :func:`jax.tree.flatten`.rflattentreeis_leafs M/home/cdr/jupyterlab/.venv/lib/python3.12/site-packages/jax/_src/tree_util.py tree_flattenr$Js  ! !$ 00c$|j|S)z$Alias of :func:`jax.tree.unflatten`.) unflatten)treedefleavess r#tree_unflattenr*Rs   6 ""r%c4tj||dS)z!Alias of :func:`jax.tree.leaves`.rrr s r# tree_leavesr,X  ! !$ 0 33r%c4tj||dS)z$Alias of :func:`jax.tree.structure`.rr s r#tree_structurer0`r-r%cHtjtt|S)a Makes a tuple treedef from an iterable of child treedefs. Args: treedefs: iterable of PyTree structures Returns: a single treedef representing a tuple of the structures Examples: >>> import jax >>> x = [1, 2, 3] >>> y = {'a': 4, 'b': 5} >>> x_tree = jax.tree.structure(x) >>> y_tree = jax.tree.structure(y) >>> xy_tree = jax.tree_util.treedef_tuple([x_tree, y_tree]) >>> xy_tree == jax.tree.structure((x, y)) True See Also: - :func:`jax.tree_util.treedef_children` )r treedef_tuplerlist)treedefss r#r2r2hs.   .X ??r%c"|jS)aReturn a list of treedefs for immediate children Args: treedef: a single PyTreeDef Returns: a list of PyTreeDefs representing the children of treedef. Examples: >>> import jax >>> x = [(1, 2), 3, {'a': 4}] >>> treedef = jax.tree.structure(x) >>> jax.tree_util.treedef_children(treedef) [PyTreeDef((*, *)), PyTreeDef(*), PyTreeDef({'a': *})] >>> _ == [jax.tree.structure(vals) for vals in x] True See Also: - :func:`jax.tree_util.treedef_tuple` )childrenr(s r#treedef_childrenr8s,    r%c |jdk(S)aReturn True if the treedef represents a leaf. Args: treedef: tree to check Returns: True if treedef is a leaf (i.e. has a single node); False otherwise. Examples: >>> import jax >>> tree1 = jax.tree.structure(1) >>> jax.tree_util.treedef_is_leaf(tree1) True >>> tree2 = jax.tree.structure([1, 2]) >>> jax.tree_util.treedef_is_leaf(tree2) False r/) num_nodesr7s r#treedef_is_leafr;s&   a r%cB|jdk(xr|jdk(S)Nr/)r: num_leavesr7s r#treedef_is_strict_leafr>s#   a  ;G$6$6!$;;r%c|tjt|St|}t ||}t |t |k(xrt dt||dDS)a,Tests whether all elements in the given iterable are all leaves. This function is useful in advanced cases, for example if a library allows arbitrary map operations on a flat iterable of leaves it may want to check if the result is still a flat iterable of leaves. Args: iterable: Iterable of leaves. Returns: A boolean indicating if all elements in the input are leaves. Examples: >>> import jax >>> tree = {"a": [1, 2, 3]} >>> assert all_leaves(jax.tree_util.tree_leaves(tree)) >>> assert not all_leaves([tree]) c3*K|] \}}||u ywN).0itemleafs r# zall_leaves..s-#t -sTstrict)r all_leavesrr3r,lenallzip)iterabler"itemsr)s r#rIrIsi* _   -x 88 NE  (F v;#e* $ -'*5&'F-*r% _Children_AuxDataKeyEntry.ctj||||tj||||tj||||t ||t |<y)aC Extends the set of types that are considered internal nodes in pytrees. See :ref:`example usage `. Args: nodetype: a Python type to register as a pytree. flatten_func: a function to be used during flattening, taking a value of type ``nodetype`` and returning a pair, with (1) an iterable for the children to be flattened recursively, and (2) some hashable auxiliary data to be stored in the treedef and to be passed to the ``unflatten_func``. unflatten_func: a function taking two arguments: the auxiliary data that was returned by ``flatten_func`` and stored in the treedef, and the unflattened children. The function should return an instance of ``nodetype``. See also: - :func:`~jax.tree_util.register_static`: simpler API for registering a static pytree. - :func:`~jax.tree_util.register_dataclass`: simpler API for registering a dataclass. - :func:`~jax.tree_util.register_pytree_with_keys` - :func:`~jax.tree_util.register_pytree_node_class` - :func:`~jax.tree_util.register_pytree_with_keys_class` Examples: First we'll define a custom type: >>> class MyContainer: ... def __init__(self, size): ... self.x = jnp.zeros(size) ... self.y = jnp.ones(size) ... self.size = size If we try using this in a JIT-compiled function, we'll get an error because JAX does not yet know how to handle this type: >>> m = MyContainer(size=5) >>> def f(m): ... return m.x + m.y + jnp.arange(m.size) >>> jax.jit(f)(m) # doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ... TypeError: Cannot interpret value of type as an abstract array; it does not have a dtype attribute In order to make our object recognized by JAX, we must register it as a pytree: >>> def flatten_func(obj): ... children = (obj.x, obj.y) # children must contain arrays & pytrees ... aux_data = (obj.size,) # aux_data must contain static, hashable data. ... return (children, aux_data) ... >>> def unflatten_func(aux_data, children): ... # Here we avoid `__init__` because it has extra logic we don't require: ... obj = object.__new__(MyContainer) ... obj.x, obj.y = children ... obj.size, = aux_data ... return obj ... >>> jax.tree_util.register_pytree_node(MyContainer, flatten_func, unflatten_func) Now with this defined, we can use instances of this type in JIT-compiled functions. >>> jax.jit(f)(m) Array([1., 2., 3., 4., 5.], dtype=float32) N)r register_noderr_RegistryEntry _registry)nodetype flatten_funcunflatten_funcflatten_with_keys_funcs r#register_pytree_noderZsdR   n.D"" n.D!! n.D'|^D)Hr%cZt|tjd|j|S)aExtends the set of types that are considered internal nodes in pytrees. This function is a thin wrapper around ``register_pytree_node``, and provides a class-oriented interface. Args: cls: a type to register as a pytree Returns: The input class ``cls`` is returned unchanged after being added to JAX's pytree registry. This return value allows ``register_pytree_node_class`` to be used as a decorator. See also: - :func:`~jax.tree_util.register_static`: simpler API for registering a static pytree. - :func:`~jax.tree_util.register_dataclass`: simpler API for registering a dataclass. - :func:`~jax.tree_util.register_pytree_node` - :func:`~jax.tree_util.register_pytree_with_keys` - :func:`~jax.tree_util.register_pytree_with_keys_class` Examples: Here we'll define a custom container that will be compatible with :func:`jax.jit` and other JAX transformations: >>> import jax >>> @jax.tree_util.register_pytree_node_class ... class MyContainer: ... def __init__(self, x, y): ... self.x = x ... self.y = y ... def tree_flatten(self): ... return ((self.x, self.y), None) ... @classmethod ... def tree_unflatten(cls, aux_data, children): ... return cls(*children) ... >>> m = MyContainer(jnp.zeros(4), jnp.arange(4)) >>> def f(m): ... return m.x + 2 * m.y >>> jax.jit(f)(m) Array([0., 2., 4., 6.], dtype=float32) r$)rZop methodcallerr*)clss r#register_pytree_node_classr_2s%XsBOON;S=O=OP *r%r"ct||\}}|g|Dcgc]}|j|c}z}|jfdt|DScc}w)zAlias of :func:`jax.tree.map`.c3(K|] }| ywrArBrCxsfs r#rFztree_map..js=b1b6=)r$ flatten_up_tor'rL)rer!r"restr)r(rrIs` r#tree_maprjbsY !w//&'xTB7003BB*   =C,<= ==CsAc$|j|S)aBuild a treedef from a nested iterable structure DEPRECATED: Use :func:`jax.tree.unflatten` instead. Args: treedef: the PyTreeDef structure to build. xs: nested iterables matching the arity as the treedef Returns: object with structure defined by treedef See Also: - :func:`jax.tree.unflatten` Examples: >>> import jax >>> tree = [(1, 2), {'a': 3, 'b': 4}] >>> treedef = jax.tree.structure(tree) >>> jax.tree_util.tree_unflatten(treedef, [10, 11, 12, 13]) [(10, 11), {'a': 12, 'b': 13}] )from_iterable_tree)r(rds r# build_treermms.  # #B ''r%c t|\}}|t|j|d}|j}|j}|j||zk7r"|j |}t d|d|t |}t|D cgc]$} t|D cgc] } t|c} &} } } t| } ttt|| } t|| Scc} wcc} } w)z$Alias of :func:`jax.tree.transpose`.rz Mismatch z != ) r$r0rgr=compose TypeErroriterrangenextrLmaprr*) outer_treedef inner_treedefpytree_to_transposeflatr( inner_size outer_sizeexpected_treedef iter_flat___loltransposed_lolsubtreess r#tree_transposers23-$"=#>#>?R#STU#VWM''*''* J34$,,]; j 2B1CD EE4j)=B:=N 79j 121tI2 # 9. 7 H(  x 00 3 sC2%C- 7C2-C2rTto_iter from_iterc |dfSrArBrds r#rs b$Zr%ct|SrAtupler~rds r#rrs uRyr%c |dfSrArBrs r#rrs RJr%ct|SrA)r3rs r#rrs d2hr%cRtt|jdddS)N)rsortedrNrs r#rrsF6"((*+=$>tt$Dr%c,tt||SrA)dictrL)keysrds r#rrs$s4}*=r%cy)N)rBNrB)zs r#rrr%cyrArBrs r#rrrr%zdict[type[Any], _RegistryEntry]rUc eZdZy) UnspecifiedN)__name__ __module__ __qualname__rBr%r#rrsr%rct|tr!tj|t ||Stj|t |||S)z!Alias of :func:`jax.tree.reduce`.r`) isinstancer functoolsreducer,)functionr! initializerr"s r# tree_reducersD  [)   Hk$&H II   Hk$&H+ VVr%ct|}|dk(rt|tr td|S|dk(r|dS|dz}t |d|||}t ||d||}|||S)Nrz?Must specify identity for parallel reduction of empty sequence.r/)rJrrrp_parallel_reduce)sequence operationidentitylengthindexabs r#rrs x=& q[(K( W XX O { A; aKE&5)9h?A%&)9h?A Q?r%)rr"c6t||}t|||S)z-Alias of :func:`jax.tree.reduce_associative`.r`)r,r)rr!rr"rs r#tree_reduce_associativersw /( (Ix 88r%c.tt||S)zAlias of :func:`jax.tree.all`.r`)rKr,r s r#tree_allrs [w / 00r%c.eZdZdZdZdZdZdZdZy)_HashableCallableShimzGObject that delegates __call__, __hash__, and __eq__ to another object.c||_yrAfun)selfrs r#__init__z_HashableCallableShim.__init__s DHr%c&|j|i|SrAr)rargskws r#__call__z_HashableCallableShim.__call__s 488T R  r%c,t|jSrA)hashrrs r#__hash__z_HashableCallableShim.__hash__s >r%crt|tr|j|jk(S|j|k(SrA)rrrrothers r#__eq__z_HashableCallableShim.__eq__s/%./ XX "" 88u r%c"d|jdS)Nz_HashableCallableShim()rrs r#__repr__z_HashableCallableShim.__repr__s #DHH>> import jax.numpy as jnp >>> add_one = Partial(jnp.add, 1) >>> add_one(2) Array(3, dtype=int32, weak_type=True) Pytree compatibility means that the resulting partial function can be passed as an argument within transformed JAX functions, which is not possible with a standard ``functools.partial`` function: >>> from jax import jit >>> @jit ... def call_func(f, *args): ... return f(*args) ... >>> call_func(add_one, 2) Array(3, dtype=int32, weak_type=True) Passing zero arguments to ``Partial`` effectively wraps the original function, making it a valid argument in JAX transformed functions: >>> call_func(Partial(jnp.add), 1, 2) Array(3, dtype=int32, weak_type=True) Had we passed ``jnp.add`` to ``call_func`` directly, it would have resulted in a ``TypeError``. Note that if the result of ``Partial`` is used in the context where the value is traced, it results in all bound arguments being traced when passed to the partially-evaluated function: >>> print_zero = Partial(print, 0) >>> print_zero() 0 >>> call_func(print_zero) # doctest:+ELLIPSIS JitTracer(~int32[]) c t|tjrV|}t|}t |||g|i|}|j |_|j|_|j|_|St |||g|i|SrA) rrrrsuper__new__funcrkeywords)klassrrr original_funcout __class__s r#rzPartial.__new__&s $ ))*m "= 1d GOE4 5$ 5" 5c$$di$$di#,,dm j W_UD 64 62 66r%)rrrrr __classcell__)rs@r#rrs.`77r%rcJ|j|jf|jfSrA)rrr)partial_s r#rr:sx}}h&7&78(--Hr%c,t|g|di|dSNrr/)r)rrds r#rr;sWT3BqE3RU3r%cRt|||}t|j|S)z$Alias of :func:`jax.tree.broadcast`.r`)broadcast_prefixr0r') prefix_tree full_treer"broadcast_leavess r#tree_broadcastr?s* &k9gN  " , ,-= >>r%cgdfd} t||||S#t$rt||^}}|ddwxYw)aBroadcasts tree prefix leaves into the full set of leaves for a given full tree. Args: prefix_tree: a pytree that is a tree prefix of full_tree. full_tree: a pytree with the structure to broadcast the prefix leaves into. is_leaf: an optionally specified function that will be called at each flattening step for prefix_tree. It should return a boolean, with true stopping the traversal and the whole subtree being treated as a leaf, and false indicating the flattening should traverse the current object. Returns: A list of leaves matching the expected count for the full tree, with the leaf of each prefix tree being duplicated to match the count of its corresponding subtree. c,t|jSrA)r0r=)ts r#rz"broadcast_prefix..\s*55r%c:j|g|zSrA)extend)xsubtreer=results r#rz"broadcast_prefix..]s&--j6I0I"Jr%r`zbroadcast_prefix prefix_treeN)rj ValueError prefix_errors)rrr" add_leaveser~r=rs @@r#rrIs]$ &5*J*8 ZiA - 8K3ea! , -478s  !AcDgfd}||dt||S)a;Broadcasts tree prefix leaves into the full set of leaves for a given full treedef. Args: prefix_leaves: the leaves of a pytree that is a tree prefix of full_treedef. prefix_treedef: the PyTreeDef of a pytree that is a tree prefix of full_treedef. full_treedef: a PyTreeDef with the structure to broadcast the prefix leaves into. Returns: A list of leaves matching the expected count for the full tree, with each leaf of prefix tree being duplicated to match the count of its corresponding subtree. ct|r,||z dk(sJ j |||jzyt|r td|j }|j }||k7rtd|d||}t |j |j dD]-\}} |||||jz|| ||jz }/y)Nr/z2`prefix_treedef` is not a prefix of `full_treedef`z expected z, got TrG)r>rr=r node_datarLr6) broadcast_fn leaf_startleaf_endprefix_treedefr(prefix_node_datarprefix_i prefix_child tree_child prefix_leavesrets r# _broadcastz;broadcast_flattened_prefix_with_treedef.._broadcastsn-# )) ) jjz(3g6H6HHI g& K LL%//1!!#I9$ 9+V4D3EF GGH$'!7#3#3#5d%D* j<8l6M6M+M,)))h *r%r)rJ)rr full_treedefrrs` @r#'broadcast_flattened_prefix_with_treedefrgs+8 #*4 ZC . M *r%cbtj|}|tdt||S)aFlatten the given pytree node by one level. Args: tree: A valid pytree node, either built-in or registered via :func:`register_pytree_node` or related functions. Returns: A pair of the pytrees flattened children and its hashable metadata. Raises: ValueError: If the given pytree is not a built-in or registered container via ``register_pytree_node`` or ``register_pytree_with_keys``. Examples: >>> import jax >>> from jax._src.tree_util import flatten_one_level >>> flattened, meta = flatten_one_level({'a': [1, 2], 'b': {'c': 3}}) >>> flattened ([1, 2], {'c': 3}) >>> meta ('a', 'b') can't tree-flatten type: )rflatten_one_levelrtyper!rs r#rrs5. **40#[ 0d = >> Jr%cbtj|}|tdt||S)z6Flatten the given pytree node by one level, with keys.r)rflatten_one_level_with_keysrrrs r#rrs5 44T:#[ 0d = >> Jr%c0ttd|||SNrB)r3 _prefix_error)rrr"s r#rrs mB Y@ AAr%c#<Ktd|||Ed{y7w)aHelper to describe structural differences between two pytrees. Args: tree1, tree2: pytrees known to have different structure. Usage: raise Exception( "Value 1 and value 2 must have the same pytree structure, but they have " "the following structural differences: " + (" ".join( f" - {keystr(path)} is a {thing1} in value 1 and a {thing2} in " f" value 2, so {explanation}. " for path, thing1, thing2, explanation in equality_errors(val1, val2)))) rBN)_equality_errors)tree1tree2r"s r#equality_errorsr s&b% 888s c tdtftdddi}tt||g|jzt||g|jzS)z0Like `equality_errors` but invoked on PyTreeDef.LeafMetacy)Nz pytree leafrB)r~s r#rz+equality_errors_pytreedef..rr%)rLeafrB)rrr r*r=)rrrEs r#equality_errors_pytreedefrsj [ Jj4'41H#I J6SUWY Z \$ v8H8H/HI'v8H8H/HI KKr%c #Ktt||rtt||ryt|t|k7r-|tt|tt|dfyt |t t fr{t|t|k(sJt|t|k7rK|t|jdt|t|jdt|dfyt|\}}t|\}}t |}t |}t|t|} } djdt|jt| D} t|t|k7rh|t|dt|d t|d kDrd ndt|dt|d t|d kDrd ndd | xrd | dzfy||k7r%|t|d|t|d|dfy|| k(s Jd|d| t|||D]!\} } } tg|| | | |Ed{#y#d} YxYw7w)Nr`ztheir Python types differ of length zthe lengths do not match c3FK|]}t|jywrA)reprkeyrCks r#rFz#_equality_errors..sEADKE!z with z childr/renz$the numbers of children do not matchz., with the symmetric difference of key sets: {}z with pytree metadata z'the pytree node metadata does not matchz-equal pytree nodes gave different tree keys:  and )r>r0rstrrr3rrJrr _child_keysjoinsetsymmetric_differencerLr)patht1t2r" t1_childrent1_meta t2_childrent2_metat1_keyst2_keysdiffrc1c2s r#rrs^B@A^B@AF "Xb DH s48}.I II T5M" 8tBx   2w#b' R!!"+c"gY 7R!!"+c"gY 7 ' )) *2.+w*2.+wk"+k"+ _k"o7' 88EL55c'lCE ED [)) 2hZvc+./v;'!+e 4 62hZvc+./v;'!+e 4 6 1  OFtfBO Q      2hZ-gY 72hZ-gY 7 4 66  G N5gYeG9MN w [9=iaR $  BG<<<=3 D2=s+E I?9I4C%I?,I=-I?4I:8I? SequenceKeyDictKey GetAttrKeyFlattenedIndexKeyr)simple separatorcT|rtnt}|jt||S)a/Helper to pretty-print a tuple of keys. Args: keys: A tuple of ``KeyEntry`` or any class that can be converted to string. simple: If True, use a simplified string representation for keys. The simple representation of keys will be more compact than the default, but is ambiguous in some cases (for example "0" might refer to the first item in a list or a dictionary key for the integer 0 or string "0"). separator: The separator to use to join string representations of the keys. Returns: A string that joins all string representations of the keys. Examples: >>> import jax >>> params = {'foo': {'bar': {'baz': 1, 'bat': [2, 3]}}} >>> for path, _ in jax.tree_util.tree_leaves_with_path(params): ... print(jax.tree_util.keystr(path)) ['foo']['bar']['bat'][0] ['foo']['bar']['bat'][1] ['foo']['bar']['baz'] >>> for path, _ in jax.tree_util.tree_leaves_with_path(params): ... print(jax.tree_util.keystr(path, simple=True, separator='/')) foo/bar/bat/0 foo/bar/bat/1 foo/bar/baz )_simple_entrystrrrrt)rr1r2str_fns r#keystrr65s$: & 3& FD) **r%c|xtdx\n-xtdx\nxtdx\nxtdx\nn }t |S t |S)N)idxr)name)r-r.r/r0rr9s r#r4r4VsB   '  *  $  $ % Xo Xor%c4|sfd}|}t|||y)a Extends the set of types that are considered internal nodes in pytrees. This is a more powerful alternative to ``register_pytree_node`` that allows you to access each pytree leaf's key path when flattening and tree-mapping. Args: nodetype: a Python type to treat as an internal pytree node. flatten_with_keys: a function to be used during flattening, taking a value of type ``nodetype`` and returning a pair, with (1) an iterable for tuples of each key path and its child, and (2) some hashable auxiliary data to be stored in the treedef and to be passed to the ``unflatten_func``. unflatten_func: a function taking two arguments: the auxiliary data that was returned by ``flatten_func`` and stored in the treedef, and the unflattened children. The function should return an instance of ``nodetype``. flatten_func: an optional function similar to ``flatten_with_keys``, but returns only children and auxiliary data. It must return the children in the same order as ``flatten_with_keys``, and return the same aux data. This argument is optional and only needed for faster traversal when calling functions without keys like ``tree_map`` and ``tree_flatten``. Examples: First we'll define a custom type: >>> class MyContainer: ... def __init__(self, size): ... self.x = jnp.zeros(size) ... self.y = jnp.ones(size) ... self.size = size Now register it using a key-aware flatten function: >>> from jax.tree_util import register_pytree_with_keys_class, GetAttrKey >>> def flatten_with_keys(obj): ... children = [(GetAttrKey('x'), obj.x), ... (GetAttrKey('y'), obj.y)] # children must contain arrays & pytrees ... aux_data = (obj.size,) # aux_data must contain static, hashable data. ... return children, aux_data ... >>> def unflatten(aux_data, children): ... # Here we avoid `__init__` because it has extra logic we don't require: ... obj = object.__new__(MyContainer) ... obj.x, obj.y = children ... obj.size, = aux_data ... return obj ... >>> jax.tree_util.register_pytree_node(MyContainer, flatten_with_keys, unflatten) Now this can be used with functions like :func:`~jax.tree_util.tree_flatten_with_path`: >>> m = MyContainer(4) >>> leaves, treedef = jax.tree_util.tree_flatten_with_path(m) cT|\}}|Dcgc]\}}| c}}|fScc}}wrArB)r! key_childrenr(r~cflatten_with_keyss r#flatten_func_implz4register_pytree_with_keys..flatten_func_impls//5lG( )DAqa )7 22 )s $N)rZ)rVr?rXrWr@s ` r#register_pytree_with_keysrAcs'x 3%L n.?r%ct|drtjdnd}t|tjd|j||S)aoExtends the set of types that are considered internal nodes in pytrees. This function is similar to ``register_pytree_node_class``, but requires a class that defines how it could be flattened with keys. It is a thin wrapper around ``register_pytree_with_keys``, and provides a class-oriented interface: Args: cls: a type to register as a pytree Returns: The input class ``cls`` is returned unchanged after being added to JAX's pytree registry. This return value allows ``register_pytree_node_class`` to be used as a decorator. See also: - :func:`~jax.tree_util.register_static`: simpler API for registering a static pytree. - :func:`~jax.tree_util.register_dataclass`: simpler API for registering a dataclass. - :func:`~jax.tree_util.register_pytree_node` - :func:`~jax.tree_util.register_pytree_with_keys` - :func:`~jax.tree_util.register_pytree_node_class` Examples: >>> from jax.tree_util import register_pytree_with_keys_class, GetAttrKey >>> @register_pytree_with_keys_class ... class Special: ... def __init__(self, x, y): ... self.x = x ... self.y = y ... def tree_flatten_with_keys(self): ... return (((GetAttrKey('x'), self.x), (GetAttrKey('y'), self.y)), None) ... @classmethod ... def tree_unflatten(cls, aux_data, children): ... return cls(*children) r$Ntree_flatten_with_keys)hasattrr\r]rAr*)r^rWs r#register_pytree_with_keys_classrEsLN*1n)Eboon%4 2??3 4c6H6H *r%c|щduduk7rtdddtjstddtjDcgc]*}|jj dds |j ,c}tjDcgc]*}|jj ddr |j ,c}JJtttjrtjDchc]}|js|j }}|j|h|k7r5d}|hz x}r |d |d z }h|z x}r |d |dz }t|fd } fd } tjtttjtttjttt!| | t"<Scc}wcc}wcc}w)aExtends the set of types that are considered internal nodes in pytrees. This differs from ``register_pytree_with_keys_class`` in that the C++ registries use the optimized C++ dataclass builtin instead of the argument functions. See :ref:`pytrees-custom-pytree-nodes` for more information about registering pytrees. Args: nodetype: a Python type to treat as an internal pytree node. This is assumed to have the semantics of a :obj:`~dataclasses.dataclass`: namely, class attributes represent the whole of the object state, and can be passed as keywords to the class constructor to create a copy of the object. All defined attributes should be listed among ``meta_fields`` or ``data_fields``. meta_fields: metadata field names: these are attributes which will be treated as :term:`static` when this pytree is passed to :func:`jax.jit`. ``meta_fields`` is optional only if ``nodetype`` is a dataclass, in which case individual fields can be marked static via :func:`dataclasses.field` (see examples below). Metadata fields *must* be static, hashable, immutable objects, as these objects are used to generate JIT cache keys. In particular, metadata fields cannot contain :class:`jax.Array` or :class:`numpy.ndarray` objects. data_fields: data field names: these are attributes which will be treated as non-static when this pytree is passed to :func:`jax.jit`. ``data_fields`` is optional only if ``nodetype`` is a dataclass, in which case fields are assumed data fields unless marked via :func:`dataclasses.field` (see examples below). Data fields *must* be JAX-compatible objects such as arrays (:class:`jax.Array` or :class:`numpy.ndarray`), scalars, or pytrees whose leaves are arrays or scalars. Note that ``None`` is a valid data field, as JAX recognizes this as an empty pytree. Returns: The input class ``nodetype`` is returned unchanged after being added to JAX's pytree registry, so that :func:`register_dataclass` can be used as a decorator. Examples: In JAX v0.4.35 or older, you must specify ``data_fields`` and ``meta_fields`` in order to use this decorator: >>> import jax >>> from dataclasses import dataclass >>> from functools import partial ... >>> @partial(jax.tree_util.register_dataclass, ... data_fields=['x', 'y'], ... meta_fields=['op']) ... @dataclass ... class MyStruct: ... x: jax.Array ... y: jax.Array ... op: str ... >>> m = MyStruct(x=jnp.ones(3), y=jnp.arange(3), op='add') >>> m MyStruct(x=Array([1., 1., 1.], dtype=float32), y=Array([0, 1, 2], dtype=int32), op='add') Starting in JAX v0.4.36, the ``data_fields`` and ``meta_fields`` arguments are optional for :func:`~dataclasses.dataclass` inputs, with fields defaulting to ``data_fields`` unless marked as static using `static` metadata in :func:`dataclasses.field`. >>> import jax >>> from dataclasses import dataclass, field ... >>> @jax.tree_util.register_dataclass ... @dataclass ... class MyStruct: ... x: jax.Array # defaults to non-static data field ... y: jax.Array # defaults to non-static data field ... op: str = field(metadata=dict(static=True)) # marked as static meta field. ... >>> m = MyStruct(x=jnp.ones(3), y=jnp.arange(3), op='add') >>> m MyStruct(x=Array([1., 1., 1.], dtype=float32), y=Array([0, 1, 2], dtype=int32), op='add') Once this class is registered, it can be used with functions in :mod:`jax.tree` and :mod:`jax.tree_util`: >>> leaves, treedef = jax.tree.flatten(m) >>> leaves [Array([1., 1., 1.], dtype=float32), Array([0, 1, 2], dtype=int32)] >>> treedef PyTreeDef(CustomNode(MyStruct[('add',)], [*, *])) >>> jax.tree.unflatten(treedef, leaves) MyStruct(x=Array([1., 1., 1.], dtype=float32), y=Array([0, 1, 2], dtype=int32), op='add') In particular, this registration allows ``m`` to be passed seamlessly through code wrapped in :func:`jax.jit` and other JAX transformations, with ``data_fields`` being treated as dynamic arguments, and ``meta_fields`` being treated as static arguments: >>> @jax.jit ... def compiled_func(m): ... if m.op == 'add': ... return m.x + m.y ... else: ... raise ValueError(f"{m.op=}") ... >>> compiled_func(m) Array([1., 2., 3.], dtype=float32) Nzqregister_dataclass: data_fields and meta_fields must both be specified when either is specified. Got data_fields=z meta_fields=.zlregister_dataclass: data_fields and meta_fields are required when nodetype is not a dataclass. Got nodetype=staticFz_data_fields and meta_fields must include all dataclass fields with ``init=True`` and only them.z Missing fields: z1. Add them to drop_fields to suppress this error.z Unexpected fields: ctt|}tt|}t||z}di|Sr)rrLr)metadata meta_args data_argskwargs data_fields meta_fieldsrVs r#rXz*register_dataclass..unflatten_funchsBc+t,-Ic+t,-I )i' (F  f r%c^tfdD}tfdD}||fS)Nc36K|]}t|ywrAgetattrrCr:rs r#rFz;register_dataclass..flatten_func..o:dD!:c36K|]}t|ywrArSrUs r#rFz;register_dataclass..flatten_func..prVrWr)rrJrKrOrPs` r#rWz(register_dataclass..flatten_funcns- :k: :D :k: :D :r%)rp dataclasses is_dataclassfieldsmetadatagetr:rinitdifference_updaterrregister_dataclass_noder3rrrTrU) rVrOrP drop_fieldsre init_fieldsmsgmissing unexpectedrXrWs ``` r#register_dataclassrfswPK/t!45 E8C~^{nTUW XX  # #H - E;C+QH II#.#5#5h#?;a**..5966;K#.#5#5h#?7ajjnnXu5667K     k"+k"+h'#.#5#5h#?Ja166166JKJ!K!!;/##{#{2 *  ">K">+">> > > y)  43{3kA A A %j\33 sO  **8T+5F[HYZ,,XtK7H${J[\++Hd;6GkIZ[&|^D)H /];7Ks/H/'/H4#H95H9cztfdjDtjfS)Nc3>K|]}t||fywrAr.)rCrrs r#rFz..|s:Agaj!A$':)rr)rs`r#rr|s'u:::E!&&(OLr%c@tjt||SrA) collections OrderedDictr)rvaluess r#rr}s00$1GHr%cptt}tfd|Dj|ffS)Nc3>K|]}t||fywrAri)rCrds r#rFz1_flatten_defaultdict_with_keys..s0a AaD!0rj)rrdefault_factory)rqrs` r#_flatten_defaultdict_with_keysrss2 vay $ 040 013D3Dd2K KKr%cNtj|dt|d|Sr)rl defaultdictr)srns r#rrs"k--adHQqT64JKr%c,d}d}t||||S)a Registers `cls` as a pytree with no leaves. Instances are treated as static by :func:`jax.jit`, :func:`jax.pmap`, etc. This can be an alternative to labeling inputs as static using ``jit``'s ``static_argnums`` and ``static_argnames`` kwargs, ``pmap``'s ``static_broadcasted_argnums``, etc. Args: cls: type to be registered as static. Must be hashable, as defined in https://docs.python.org/3/glossary.html#term-hashable. Returns: The input class ``cls`` is returned unchanged after being added to JAX's pytree registry. This allows ``register_static`` to be used as a decorator. Examples: >>> import jax >>> @jax.tree_util.register_static ... class StaticStr(str): ... pass This static string can now be used directly in :func:`jax.jit`-compiled functions, without marking the variable static using ``static_argnums``: >>> @jax.jit ... def f(x, y, s): ... return x + y if s == 'add' else x - y ... >>> f(1, 2, StaticStr('add')) Array(3, dtype=int32, weak_type=True) c d|fSrrB)objs r#rz!register_static..s S r%c|SrArB)ryempty_iter_childrens r#rz!register_static..ssr%)rA)r^rr's r#register_staticr|s @ "'2)C)4 *r%cF}|sfd}tj||S)z,Alias of :func:`jax.tree.flatten_with_path`.c|SrArB)r~rr"s r#rz(tree_flatten_with_path..s 71:r%)rflatten_with_path)r!r"is_leaf_takes_pathis_leaf_with_kps ` r#tree_flatten_with_pathrs* 8?/  3-O  + +D/ BBr%c"t|||dS)z+Alias of :func:`jax.tree.leaves_with_path`.r)r)r!r"rs r#tree_leaves_with_pathrs g/A B1 EEr%)r"rct|||\}}tt|}||Dcgc]}|j|c}z}|j fdt|DScc}w)z(Alias of :func:`jax.tree.map_with_path`.c3(K|] }| ywrArBrcs r#rFz%tree_map_with_path..sEb1b6Erf)rr3rLrgr') rer!r"rrhkeypath_leavesr(riall_keypath_leavess ` r#tree_map_with_pathrsq3 G'.'^,-.%4(Pa)>)>q)A(PP   EC1C,DE EE)QsA%cjtt|rJtdt|dDS)Nc3&K|] \}}| ywrArB)rCrr~s r#rFz_child_keys..sDTQqDsr)r>r0rrr s r#rrs1 #N6$: ;; ; D8@CD DDr%c # Ktt|ryttk7r fdyt\}t\ }t t  t t  t ttfr-ttk7r_tfdy tjt  tt k7r fdy||k7rxt|t| tjdjtj j# j#d fdy k(s Jd d t% D] \}}}t'g|||Ed{"y#d YxYw7w) Nr`c ntd|td|dtdtd S)Nz8pytree structure error: different types at key path % 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 rGrr6r)r:rkey_pathrs r#rz_prefix_error..sPz F6(#$%--1F3 +   )_ Q  !r%ctdjd|td|djdtdtdS)Nz-pytree structure error: different lengths of z at key path rz has a subtree of type rzC, but the full pytree has a subtree of the same type but of length rG)rrr6rJ)r:rrrtys r#rz_prefix_error..sf 9"++Gvh'()1156M [[MS%5$67::=i.9I  LMr%c6td|td|dtdtddj dDdtddj d Dd d zSd dj d DzS)NzMpytree structure error: different numbers of pytree children at key path rrz with z child keys rc3FK|]}t|jywrArrrs r#rFz2_prefix_error....s=qAEE =rzR but at the same key path the full pytree has a subtree of the same type but with c3FK|]}t|jywrArrs r#rFz2_prefix_error....s;qAEE ;r rz/so the symmetric difference on key sets is c3FK|]}t|jywrArrs r#rFz2_prefix_error....s4!3quu:4r)rr6rrJr)r:r*full_tree_childrenfull_tree_keysrrprefix_tree_childrenprefix_tree_keyss r#rz_prefix_error..s fVH%&'//3f5K !"()*+xx=,<==>?/012xx;N;;.'saz F6(#$%--1F3 +   ! "#  !?   r%z4equal pytree nodes gave differing prefix_tree_keys: r)r>r0rrrrrr3rJrr rtextwrapindentrdifflibndiff splitlinesrLr)rrrr"prefix_tree_metafull_tree_metarr"r#r*rrrrrrrrs``` @@@@@@@@@r#rrsN;HI  +$y/) !! ,=[+I(('8'C$n34/0 -y). dE]+ ;3y>)  b MM   ! " 7 7N8K Ld  C(:$;; 9 9 9 '/0^,OO MM.99;,779 ; < M    ^ +1;~.01 +')=?QR5iaR^x^^R4445] d\5s+CG&#G6CG&G$G&G!G&ceZdZdZddZddZddZ ddZddZddZ e dZ dd Z e dd Z dd Zdd Zd ZdZdZdZy)FlatTreeaA FlatTree stores a treedef and a flat list of values. It's meant to be isomorphic to the corresponding pytree but we can map over it more easily. Compared to `tree_map`, FlatTree.map has these benefits: 1. It doesn't touch user flatten/unflatten code (which shouldn't have side effects but sometimes does in practice). 2. It can be faster, because it skips the recursive traversal. 3. It actually obeys the functor rules. For example, `flat_tree.map(lambda x: (f(x), g(x))).unzip2()[0]` will give the same result as `flat_tree.map(f)`, whereas in the `tree_map` version the tuple-returning function would change the tree structure and `unzip` wouldn't be able to recover it. cjt|tjsJ||_t ||_yrA)rr PyTreeDefr!rvals)rrr(s r#rzFlatTree.__init__Ls* gv// 00 0DId DIr%cg}|jD]}|j||t||jSrArappendrr!)rreans_valsrs r#rtz FlatTree.mapQs;H YYooad Hdii ((r%ct|}t||k(sJg}t|j|jD]\}}|j|||t ||j SrArJrLrrrr!)rrer#nrx1x2s r#map2z FlatTree.map2Wse D A r7a<<Hdii)!BooaBi ! Hdii ((r%ct|}t||k(rt||k(sJg}t|j|j|jD]\}}}|j||||!t ||j SrAr) rrer#t3rrrrx3s r#map3z FlatTree.map3`sz D A r7aF)<, ))0)  ) (r%rrA)r!r r"Callable[[Any], bool] | Nonerztuple[list[Leaf], PyTreeDef])r(rr)zIterable[Leaf]rr )r!r r"rrz list[Leaf])r!r r"zNone | Callable[[Any], bool]rr)r4zIterable[PyTreeDef]rr)r(rrzlist[PyTreeDef])r(rrbool)rMz Iterable[Any]r"rrr) rVtype[T]rWz)Callable[[T], tuple[_Children, _AuxData]]rXz"Callable[[_AuxData, _Children], T]rYz3Callable[[T], tuple[KeyLeafPairs, _AuxData]] | NonerNone)r^rrr) reCallable[..., Any]r!r rhr r"rrr )r(rrdr rr )rurrvzPyTreeDef | Nonerwr rr ) rzCallable[[T, Any], T]r!r rT | Unspecifiedr"rrr)rzlist[T]rCallable[[T, T], T]rrrr) rrr!r rrr"rrr)r!r r"rrr)rr rr r"rrr )rr rr r"rr list[Any])rrrrrrrr)r!r rztuple[Iterable[Any], Hashable])r!r rz&tuple[Iterable[KeyLeafPair], Hashable])rr rr r"rrz!list[Callable[[str], ValueError]])rr rr r"rr'Iterable[tuple[KeyPath, str, str, str]])rrrrrr)rKeyPathr1rr2rrr)rrQrr)rVrr?z5Callable[[T], tuple[Iterable[KeyLeafPair], _AuxData]]rXz&Callable[[_AuxData, Iterable[Any]], T]rWz4None | Callable[[T], tuple[Iterable[Any], _AuxData]])NNrB) rVrrOSequence[str] | NonerPrraz Sequence[str]rr)r^type[H]rr)NF)r!r r"Callable[..., bool] | Nonerrrz+tuple[list[tuple[KeyPath, Any]], PyTreeDef])r!r r"rrrrzlist[tuple[KeyPath, Any]]) rerr!r rhr r"rrrrr )r r rr) rrrr rr r"rrz%Iterable[Callable[[str], ValueError]])i __future__rrlcollections.abcrrrrrYrrroperatorr\rtypingr r jax._srcr jax._src.libr jax._src.utilrrrexportregister_exclusion__file__rrrrr rrrrrPyTreeRegistryrrr$r*r,r0r2r8r;r>rIrOrPrQr KeyLeafPair KeyLeafPairsrrZr_rjrmr namedtuplerTr3rrU__annotations__rrrrrrrrrrrrrr rrr-r.r/r0r6r4rArErfrmrsrur|rrgenerate_key_pathsrrrrrBr%r#rs`#BB#.  O $!!!(+ CL e49% Cx       *6**,'.+V**DD$(!)2*F))44$( (09=161211## 8<454448<454@I44@@20  ,<7;4@D< Kx} 5 :X . :S )HcM"  $ #  QEQE;QE7QE < QE QEQEh, , ^6:>>>3>?B>>((21(+10311.(''(89k:RS >/1H I..0F G.D= ?J35GH . *0;}8<WW,W6WBCWW!, " & !, ,0 9" 9  9 9 * 9  9 9CG11 22*@7i@7@7F H3;??8???>B:#<: : : :  : |> +;?B7B8BEI9 99%A9,9*K K K@K6=r%% S%~~## C#1131,1B++@  LP CCLC;CI CCL, , ^)-(,!# \\%\&\ \  \\~LH L"K" " J59$C C2CC1CC59$F F2FFFF + +/$ F F  F  F( F  F  F F E-1 ^5^5^5^5* ^5 + ^5Dp(p(r%