0VhuUdZddlmZddlZddlZddlZddlZddlmZm Z m Z m Z ddl m Z mZddlmZddlmZmZmZmZmZmZmZmZddlmZddlmZmZmZm Z m!Z!m"Z"dd l#m$Z$m%Z%m&Z&m'Z'm(Z(dd l)m*Z*m+Z+m,Z,er)ddl-Z-dd l.m/Z/m0Z0m1Z1dd l#m2Z2m3Z3m4Z4m5Z5m6Z6ed e7e4Z8gdZ9ejtdk\rddiniZ;ejxdKddddde;Gddee&Z=[;GddZ>e>Z?de@d<eZAde@d<[>er8ddlBmCZCeCdZDedZEeCdZFed ZGGd!d"eeDeEeFeGfZH dLd#ZIed$d% dMd&ZJe dNd$d% dOd'ZJ dNd$d% dPd(ZJeIeJed) dQd*ZK[J[Ie dNddd+ dRd,ZLe dSd-ZL dNddd+ dTd.ZLdUd/ZMejdVd0ZOdWd1ZPdXd2ZQdYd3ZRdZd4ZSd[d5ZTd\d6ZUd]d7ZVd^d8ZWd_d9ZX d^d:ZYd_d;ZZ d`d<Z[dad=Z\ dbd>Z] dcd?Z^ dbd@Z_ dcdAZ`dddBZadedCZbdfdDZcdgdEZddhdFZe didGZfe7de=e7deQeRe e$jHehe=eheSeTe!e$jHeje=ejeUeVe!e$jHele=eleWeXee$jHe e=e ecedee$jHee=ee[e\ee$jHe e=e e]e^ee$jHe e=e eaebe!e$jHe%e=e%eeefe"e$jHi ZsdIe@dJ<e=eleYeZee$jHZte=e e_e`ee$jHZuy)jz&Registry for custom pytree node types.) annotationsN) OrderedDict defaultdictdeque namedtuple) itemgetter methodcaller)Lock) TYPE_CHECKINGAnyCallableClassVarGeneric NamedTupleTypeVaroverload) AutoEntry MappingEntryNamedTupleEntry PyTreeEntry SequenceEntryStructSequenceEntry) PyTreeKindStructSequenceTis_namedtuple_classis_structseq_class)safe_ziptotal_order_sortedunzip2) Collection GeneratorIterable)KTVTCustomTreeNode FlattenFunc UnflattenFuncCustomTreeNodeType)bound)register_pytree_noderegister_pytree_node_classunregister_pytree_nodedict_insertion_ordered slotsT)initrepreqfrozenceZdZUdZded<ded<ded<ej dk\rd ed <eZd ed <e jZ d ed<dZ ded<y)PyTreeNodeRegistryEntryz>A dataclass that stores the information of a pytree node type.zbuiltins.type[Collection[T]]typeFlattenFunc[T] flatten_funcUnflattenFunc[T]unflatten_funcr/zdataclasses.KW_ONLY_zbuiltins.type[PyTreeEntry]path_entry_typerkindstr namespaceN) __name__ __module__ __qualname____doc____annotations__sys version_inforr?rCUSTOMr@rC?/home/dcms/DCMS/lib/python3.12/site-packages/optree/registry.pyr8r8@sPH &&  $$ 7" 2;O/;!((D*(IsrMr8c$eZdZUdZded<ddZy)GlobalNamespacerLzClassVar[tuple[()]] __slots__cy)NzrL)selfs rN__repr__zGlobalNamespace.__repr__Ws#rMN)returnrB)rDrErFrQrHrTrLrMrNrPrPTs%'I"'$rMrPrB__GLOBAL_NAMESPACEr __REGISTRY_LOCK) ParamSpec_P_T_GetP_GetTceZdZddZddZy)_CallableWithGetctNNotImplementedErrorrSargskwargss rN__call__z_CallableWithGet.__call__i% %rMctr`rarcs rNgetz_CallableWithGet.getmrgrMN)rdz_P.argsrez _P.kwargsrUrZ)rdz _GetP.argsrez _GetP.kwargsrUr\)rDrErFrfrirLrMrNr^r^hs  & &rMr^cdfd }|S)Nc|_|Sr`)ri)funcris rN decoratorz_add_get..decoratorxs rM)rlzCallable[_P, _T]rUz&_CallableWithGet[_P, _T, _GetP, _GetT]rL)rirms` rN_add_getrnqs rMrA)rCcyr`rLclsrCs rNpytree_node_registry_getrrs &)rMcyr`rLrps rNrrrrs +.rMcJ|turd}|,|tur$tj|st d|dt |t st d|d|t|dh}t5tjDcic]}|j|vr |j|}}dddtj|rtt <t"|t$<S|dk7rtj'||f}||Stj|r|t urtS|t$urt"Stj'|}||St)|rtj't*St-|rtj'tSycc}w#1swYxYw)aLookup the pytree node registry. >>> register_pytree_node.get() # doctest: +IGNORE_WHITESPACE,ELLIPSIS { : PyTreeNodeRegistryEntry( type=, flatten_func=, unflatten_func=, path_entry_type=, kind=, namespace='' ), : PyTreeNodeRegistryEntry( type=, flatten_func=, unflatten_func=, path_entry_type=, kind=, namespace='' ), : PyTreeNodeRegistryEntry( type=, flatten_func=, unflatten_func=, path_entry_type=, kind=, namespace='' ), ... } >>> register_pytree_node.get(defaultdict) # doctest: +IGNORE_WHITESPACE,ELLIPSIS PyTreeNodeRegistryEntry( type=, flatten_func=, unflatten_func=, path_entry_type=, kind=, namespace='' ) >>> register_pytree_node.get(frozenset) # frozenset is considered as a leaf node None Args: cls (type or None, optional): The class of the pytree node to retrieve. If not provided, all the registered pytree nodes in the namespace are returned. namespace (str, optional): The namespace of the registry to retrieve. If not provided, the global namespace is used. Returns: If the ``cls`` is not provided, a dictionary of all the registered pytree nodes in the namespace is returned. If the ``cls`` is provided, the corresponding registry entry is returned if the ``cls`` is registered as a pytree node. Otherwise, :data:`None` is returned, i.e., the ``cls`` is represented as a leaf node. rANzExpected a class or None, got .$The namespace must be a string, got )rVrinspectisclass TypeError isinstancerB frozensetrW_NODETYPE_REGISTRYvaluesrCr9_Cis_dict_insertion_ordered&_DICT_INSERTION_ORDERED_REGISTRY_ENTRYdict-_DEFAULTDICT_INSERTION_ORDERED_REGISTRY_ENTRYrrirrr)rqrC namespaceshandlerregistrys rNrrrrsx&&   z !$8qABB i %29-q A   { 2/   288:$$ 2 g%H   ' ' 2CHTN$QH[ !B$(()S)9:  N ##I. $;9 9 + @ @ $$S)G#!%%n553!%%j11 9  s-F"F&FFF")r?ctj|std|dtj|rt|tstd|d|t urt |tstd|d|dk(r td|t ur|}d}n||f}t5tj|||||t|||||t|<ddd|S#1swY|SxYw) aExtend the set of types that are considered internal nodes in pytrees. See also :func:`register_pytree_node_class` and :func:`unregister_pytree_node`. The ``namespace`` argument is used to avoid collisions that occur when different libraries register the same Python type with different behaviors. It is recommended to add a unique prefix to the namespace to avoid conflicts with other libraries. Namespaces can also be used to specify the same class in different namespaces for different use cases. .. warning:: For safety reasons, a ``namespace`` must be specified while registering a custom type. It is used to isolate the behavior of flattening and unflattening a pytree node type. This is to prevent accidental collisions between different libraries that may register the same type. Args: cls (type): A Python type to treat as an internal pytree node. flatten_func (callable): A function to be used during flattening, taking an instance of ``cls`` and returning a triple or optionally a pair, with (1) an iterable for the children to be flattened recursively, and (2) some hashable metadata to be stored in the treespec and to be passed to the ``unflatten_func``, and (3) (optional) an iterable for the tree path entries to the corresponding children. If the entries are not provided or given by :data:`None`, then `range(len(children))` will be used. unflatten_func (callable): A function taking two arguments: the metadata that was returned by ``flatten_func`` and stored in the treespec, and the unflattened children. The function should return an instance of ``cls``. path_entry_type (type, optional): The type of the path entry to be used in the treespec. (default: :class:`AutoEntry`) namespace (str): A non-empty string that uniquely identifies the namespace of the type registry. This is used to isolate the registry from other modules that might register a different custom behavior for the same type. Returns: The same type as the input ``cls``. Raises: TypeError: If the input type is not a class. TypeError: If the path entry class is not a subclass of :class:`PyTreeEntry`. TypeError: If the namespace is not a string. ValueError: If the namespace is an empty string. ValueError: If the type is already registered in the registry. Examples: >>> # Registry a Python type with lambda functions >>> register_pytree_node( ... set, ... lambda s: (sorted(s), None, None), ... lambda _, children: set(children), ... namespace='set', ... ) >>> # Register a Python type into a namespace >>> import torch >>> register_pytree_node( ... torch.Tensor, ... flatten_func=lambda tensor: ( ... (tensor.cpu().detach().numpy(),), ... {'dtype': tensor.dtype, 'device': tensor.device, 'requires_grad': tensor.requires_grad}, ... ), ... unflatten_func=lambda metadata, children: torch.tensor(children[0], **metadata), ... namespace='torch2numpy', ... ) >>> # doctest: +SKIP >>> tree = {'weight': torch.ones(size=(1, 2)).cuda(), 'bias': torch.zeros(size=(2,))} >>> tree {'weight': tensor([[1., 1.]], device='cuda:0'), 'bias': tensor([0., 0.])} >>> # Flatten without specifying the namespace >>> tree_flatten(tree) # `torch.Tensor`s are leaf nodes ([tensor([0., 0.]), tensor([[1., 1.]], device='cuda:0')], PyTreeSpec({'bias': *, 'weight': *})) >>> # Flatten with the namespace >>> tree_flatten(tree, namespace='torch2numpy') ( [array([0., 0.], dtype=float32), array([[1., 1.]], dtype=float32)], PyTreeSpec( { 'bias': CustomTreeNode(Tensor[{'dtype': torch.float32, 'device': device(type='cpu'), 'requires_grad': False}], [*]), 'weight': CustomTreeNode(Tensor[{'dtype': torch.float32, 'device': device(type='cuda', index=0), 'requires_grad': False}], [*]) }, namespace='torch2numpy' ) ) >>> # Register the same type with a different namespace for different behaviors >>> def tensor2flatparam(tensor): ... return [torch.nn.Parameter(tensor.reshape(-1))], tensor.shape, None ... ... def flatparam2tensor(metadata, children): ... return children[0].reshape(metadata) ... ... register_pytree_node( ... torch.Tensor, ... flatten_func=tensor2flatparam, ... unflatten_func=flatparam2tensor, ... namespace='tensor2flatparam', ... ) >>> # Flatten with the new namespace >>> tree_flatten(tree, namespace='tensor2flatparam') ( [ Parameter containing: tensor([0., 0.], requires_grad=True), Parameter containing: tensor([1., 1.], device='cuda:0', requires_grad=True) ], PyTreeSpec( { 'bias': CustomTreeNode(Tensor[torch.Size([2])], [*]), 'weight': CustomTreeNode(Tensor[torch.Size([1, 2])], [*]) }, namespace='tensor2flatparam' ) ) Expected a class, got ru(Expected a subclass of PyTreeEntry, got rvrA(The namespace cannot be an empty string.r?rCN)rwrxry issubclassrrVrzrB ValueErrorrWr~ register_noder8r|)rqr;r=r?rCregistration_keys rNr+r+s~ ??3 0q9:: OOO ,O[1YB?BUUVWXX**:i3M>ym1MNNBCDD&& %s+          0G   + 0 +,  J  Js '1C""C,rcyr`rLrqr?rCs rNr,r,s:=rMcyr`rLrs rNr,r,srMc6|tust|tr" td|dk(r tdd|c} tdturttst ddk(r td| dfd }|St j |st d|d t|d tt j rttst d d t|td |j |S)an Extend the set of types that are considered internal nodes in pytrees. See also :func:`register_pytree_node` and :func:`unregister_pytree_node`. The ``namespace`` argument is used to avoid collisions that occur when different libraries register the same Python type with different behaviors. It is recommended to add a unique prefix to the namespace to avoid conflicts with other libraries. Namespaces can also be used to specify the same class in different namespaces for different use cases. .. warning:: For safety reasons, a ``namespace`` must be specified while registering a custom type. It is used to isolate the behavior of flattening and unflattening a pytree node type. This is to prevent accidental collisions between different libraries that may register the same type. Args: cls (type, optional): A Python type to treat as an internal pytree node. path_entry_type (type, optional): The type of the path entry to be used in the treespec. (default: :class:`AutoEntry`) namespace (str, optional): A non-empty string that uniquely identifies the namespace of the type registry. This is used to isolate the registry from other modules that might register a different custom behavior for the same type. Returns: The same type as the input ``cls`` if the argument presents. Otherwise, return a decorator function that registers the class as a pytree node. Raises: TypeError: If the path entry class is not a subclass of :class:`PyTreeEntry`. TypeError: If the namespace is not a string. ValueError: If the namespace is an empty string. ValueError: If the type is already registered in the registry. This function is a thin wrapper around :func:`register_pytree_node`, and provides a class-oriented interface:: @register_pytree_node_class(namespace='foo') class Special: TREE_PATH_ENTRY_TYPE = GetAttrEntry def __init__(self, x, y): self.x = x self.y = y def tree_flatten(self): return ((self.x, self.y), None, ('x', 'y')) @classmethod def tree_unflatten(cls, metadata, children): return cls(*children) @register_pytree_node_class('mylist') class MyList(UserList): TREE_PATH_ENTRY_TYPE = SequenceEntry def tree_flatten(self): return self.data, None, None @classmethod def tree_unflatten(cls, metadata, children): return cls(*children) Nz?Cannot specify `namespace` when the first argument is a string.rArz.decorator s- /# rMrruTREE_PATH_ENTRY_TYPEr tree_flattenr)rqr)rUr))rVrzrBrryrwrxgetattrrrrr+r tree_unflatten)rqr?rCrms `` rNr,r,s/H   JsC$8  ^_ _ "9GH HsYWXX**:i3M>ymLMMBCDD {  ??3 0q9::!#'=yI OOO ,O[1YB?BUUVWXX ^$ '  JrMchtj|std|d|turt |t std|d|dk(r t d|tur|}d}n||f}t5tj||tj|cdddS#1swYyxYw)aRemove a type from the pytree node registry. See also :func:`register_pytree_node` and :func:`register_pytree_node_class`. This function is the inverse operation of function :func:`register_pytree_node`. Args: cls (type): A Python type to remove from the pytree node registry. namespace (str): The namespace of the pytree node registry to remove the type from. Returns: The removed registry entry. Raises: TypeError: If the input type is not a class. TypeError: If the namespace is not a string. ValueError: If the namespace is an empty string. ValueError: If the type is a built-in type that cannot be unregistered. ValueError: If the type is not found in the registry. Examples: >>> # Register a Python type with lambda functions >>> register_pytree_node( ... set, ... lambda s: (sorted(s), None, None), ... lambda _, children: set(children), ... namespace='temp', ... ) >>> # Unregister the Python type >>> unregister_pytree_node(set, namespace='temp') rrurvrArN) rwrxryrVrzrBrrWr~unregister_noder|pop)rqrCrs rNr-r-#sD ??3 0q9::**:i3M>ym1MNNBCDD&& %s+ 8 3 *!%%&67888s 3+B((B1c#K|turt|tstd|d|dk(r t d|turd}t 5t j|d}t jt||ddd dt 5t j|dddy#1swY4xYw#1swYyxYw#t 5t j|dddw#1swYwxYwxYww)aContext manager to temporarily set the dictionary sorting mode. This context manager is used to temporarily set the dictionary sorting mode for a specific namespace. The dictionary sorting mode is used to determine whether the keys of a dictionary should be sorted or keeping the insertion order when flattening a pytree. >>> 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': *}) ) >>> with dict_insertion_ordered(True, namespace='some-namespace'): # doctest: +IGNORE_WHITESPACE ... tree_flatten(tree, namespace='some-namespace') ( [2, 3, 4, 1, 5], PyTreeSpec({'b': (*, [*, *]), 'a': *, 'c': None, 'd': *}, namespace='some-namespace') ) .. warning:: The dictionary sorting mode is a global setting and is **not thread-safe**. It is recommended to use this context manager in a single-threaded environment. Args: mode (bool): The dictionary sorting mode to set. namespace (str): The namespace to set the dictionary sorting mode for. rvrurArF)inherit_global_namespaceN) rVrzrBryrrWr~rset_dict_insertion_orderedbool)moderCprevs rNr.r.Xs:**:i3M>ym1MNNBCDD&& =++IPUV %%d4j)<=;  ;  ) )$ : ; ;== ; ;_ ;  ) )$ : ; ; ;sfAD 7B4D C DC+ D4B=9DC D C?C3* C?3C< 8C??Dc.t|tdS)Nr)key)rr)itemss rN _sorted_itemsrs eA 77rMcy)N)rLNrL)r>s rN _none_flattenrs rMc\t}tt|||ur tdy)NzExpected no children.)objectnextiterr)r>childrensentinels rN_none_unflattenrs-xH DNH%X50116rMc |dfSr`rLtups rN_tuple_flattenr 9rMct|Sr`)tupler>rs rN_tuple_unflattenrs ?rMc |dfSr`rL)lsts rN _list_flattenrrrMct|Sr`)listrs rN_list_unflattenrs >rMchtt|j\}}|t||fSr`)r rrrdctkeysr}s rN _dict_flattenrs,- 45LD& 4:t ##rMc,tt||Sr`rrrr}s rN_dict_unflattenr v& ''rMcVt|j\}}|t||fSr`r rrrs rN_dict_insertion_ordered_flattenr)#))+&LD& 4:t ##rMc,tt||Sr`rrs rN!_dict_insertion_ordered_unflattenrrrMcVt|j\}}|t||fSr`rrs rN_ordereddict_flattenrrrMc,tt||Sr`)rrrs rN_ordereddict_unflattenrs xf- ..rMcBt|\}}}||j|f|fSr`)rdefault_factoryrr}rentriess rN_defaultdict_flattenrs-*#.FD' C''. 77rMc8|\}}t|t||Sr`)rrmetadatar}rrs rN_defaultdict_unflattenrs" %OT f(E FFrMcBt|\}}}||j|f|fSr`)rrrs rN&_defaultdict_insertion_ordered_flattenrs-rMc ||Sr`rLrqrs rN_namedtuple_unflattenrs >rMc|t|fSr`r)seqs rN_structseq_flattenr rrMc||Sr`rLrs rN_structseq_unflattenr s x=rM)r?r@z6dict[type | tuple[str, type], PyTreeNodeRegistryEntry]r|rL)rizCallable[_GetP, _GetT]rUzDCallable[[Callable[_P, _T]], _CallableWithGet[_P, _T, _GetP, _GetT]])rqr9rCrBrUzPyTreeNodeRegistryEntry | Noner`)rqNonerCrBrUz#dict[type, PyTreeNodeRegistryEntry])rqz type | NonerCrBrUzDdict[type, PyTreeNodeRegistryEntry] | PyTreeNodeRegistryEntry | None) r;r:r=r<rqtype[Collection[T]]r?ztype[PyTreeEntry]rCrBrUr)rq str | Noner?type[PyTreeEntry] | NonerCrrUz2Callable[[CustomTreeNodeType], CustomTreeNodeType])rqr)r?rrCrBrUr))rqzCustomTreeNodeType | str | Noner?rrCrrUzGCustomTreeNodeType | Callable[[CustomTreeNodeType], CustomTreeNodeType])rqr9rCrBrUr8)rrrCrBrUzGenerator[None])rzIterable[tuple[KT, VT]]rUzlist[tuple[KT, VT]])r>rrUztuple[tuple[()], None])r>rrz Iterable[Any]rUr)r tuple[T, ...]rUztuple[tuple[T, ...], None])r>rr Iterable[T]rUr)rlist[T]rUztuple[list[T], None])r>rrrrUr)r dict[KT, VT]rU/tuple[tuple[VT, ...], list[KT], tuple[KT, ...]])rlist[KT]r} Iterable[VT]rUr)rOrderedDict[KT, VT]rUr)rrr}rrUr)rdefaultdict[KT, VT]rUzOtuple[tuple[VT, ...], tuple[Callable[[], VT] | None, list[KT]], tuple[KT, ...]])rz!tuple[Callable[[], VT], list[KT]]r}rrUr)rdeque[T]rUztuple[deque[T], int | None])rz int | NonerrrUr)r NamedTuple[T]rUz)tuple[tuple[T, ...], type[NamedTuple[T]]])rqztype[NamedTuple[T]]rrrUr)rStructSequence[T]rUz-tuple[tuple[T, ...], type[StructSequence[T]]])rqztype[StructSequence[T]]rrrUr)vrG __future__r contextlib dataclassesrwrI collectionsrrrroperatorrr threadingr typingr r r rrrrr optree._Cr~optree.accessorsrrrrrr optree.typingrrrrr optree.utilsrrr builtinscollections.abcr!r"r#r$r%r&r'r(r9r)__all__rJSLOTS dataclassr8rPrVrHrWtyping_extensionsrXrYrZr[r\r^rnrrr+r,r-contextmanagerr.rrrrrrrrrrrrrrrrrrrrrrrNONErTUPLErLISTrDICT NAMEDTUPLE ORDEREDDICT DEFAULTDICTDEQUESTRUCTSEQUENCEr|rrrLrMrNrs-# CC-aaaa`==??PP!!5T.=QR ++w6$BKDtTKUK gaj L  $$*+C++ 4B B g E G E&72r5%#78&      ) ) ) $ ) ) . . . . ) . .h h h h J hV "#*3 ]!]% ] ] ' ]]]$]@h =15 = =. =  = 8 = =  .      ,0k15 k (k. k  k M k\28j +;+;\82 $ ( $  $ $( $  $ $/ 8  8 8G/G G G 8  8 8Y/Y Y Y*    J' T # __  " %      ! % __   ! $ __  ''  " " ($  # # ($  # #  " %     ++  & & s@NJ@F*A#%  *&1H*,    1-rM