U Jce6@sZdZddlmZmZmZmZmZmZmZm Z m Z m Z m Z m Z mZmZmZmZmZddlmZmZddlmZddlmZddlmZd d d d gZe eZeeefZed Zeee eefZ erej!ee efZ"nej!Z"edddZ#Gdddej!Z$de e%e e%eee"gee$fddd Z&Gdd d Z'Gdd d Z(ej)dddd Z*dS)z.The user interface to define skip connections.) TYPE_CHECKINGAnyCallableClassVarDict FrozenSet GeneratorIterableListOptionalSetSequenceTupleTypeTypeVarUnioncast)Tensornn)Batch) Namespace)current_skip_tracker skippablestashpopverify_skippables)rrT Skippable)boundcs"eZdZUdZeeeed<eee ed<eee ed<e e ddfdd Z e d d d Z e e ee fd d dZee ee fd ddZee ee fd ddZddeeeee edddZee eegdfee geefdddZeee efedddZZS)rzThe base class for skippable modules. Do not use this class directly. Define a subclass by :func:`skippable` instead. module_clsstashable_namespoppable_namesN)argskwargsreturncs"t|j|||_i|_dSN)super__init__r!module namespaces)selfr$r% __class__R/tmp/pip-unpacked-wheel-gikjz4vx/torch/distributed/pipeline/sync/skip/skippable.pyr)@s zSkippable.__init__)r&cCsd|jdS)Nz @skippable())r*)r,r/r/r0__repr__EszSkippable.__repr__namer&cCs|j|}tt|}||fS)z+Prepends namespace for the given skip name.)r+getrr)r,r4nsr/r/r0 namespacedHs  zSkippable.namespacedccs|jD]}||VqdS)z2Iterates over namespaced skip names to be stashed.N)r"r7r,r4r/r/r0 stashableNs zSkippable.stashableccs|jD]}||VqdS)z1Iterates over namespaced skip names to be popped.N)r#r7r8r/r/r0poppableSs zSkippable.poppable)only)r,r6r;r&cCs6|dkr|j|jB}nt|}|D]}||j|<q"|S)aIsolates a specified subset or the whole set of skip tensors into a namespace. In a single sequential module, skip tensors with the same name are not allowed unless they are isolated by different namespaces. Here's an example using the same name for skip tensors twice. Each pair of ``Layer1`` and ``Layer2`` is isolated with its own namespace ``ns1`` and ``ns2``. There is no conflict anymore:: ns1 = Namespace() ns2 = Namespace() model = nn.Sequential( Layer1().isolate(ns1), Layer1().isolate(ns2), Layer2(), Layer3().isolate(ns2), Layer3().isolate(ns1), ) When `only` parameter is omitted, all skip tensors are isolated. You can isolate a subset of skip tensors by passing `only` parameter:: ns_alice = Namespace() ns_bob = Namespace() model = nn.Sequential( ... StashStashPop().isolate(ns_alice, only=['alice']) \ .isolate(ns_bob, only=['bob']), ... ) Args: ns (Namespace): namespace for isolation Keyword Args: only (iterable of strs): names of specific skip tensors to be isolated (omit this option to isolate all skip tensors declared in this module) Returns: this module itself N)r"r#setr+)r,r6r;namesr4r/r/r0isolateXs 0 zSkippable.isolate) handle_stash handle_popc Cs||}t|ts|}|Sz\t|}t|trH||j|jt|}q&t|trh||j}||}q&t d|q&Wn4t k r}z|j d}|WYSd}~XYnXdS)zlDispatches :class:`stash` or :class:`pop` commands generated by the module's ``forward()``. z#%r is not a command from @skippablerN) r* isinstancernextrr4tensorrsend TypeError StopIterationr$) r,inputr?r@ generatoroutputoprCstopr/r/r0dispatchs$       zSkippable.dispatch)rGr&c sPt}iit|}D]D\}}z|||||<Wqtk r`td|dYqXq|j}ttt ddfdd }ttt dfdd } |||}j  } | rd d d | D} t| d  } | rd dd | D} t| dt|}D]"\}}|} ||||| q"|j}|S)a Performs the forward propagation. :class:`stash` or :class:`pop` commands will be handled by portals silently. The portals won't be exposed to users. Raises: RuntimeError: illegal 'stash' or 'pop' is found. 'z' has not been stashedNr4rCr&cs&|jkrtd|d||<dS)NrMz$' has not been declared as stashable)r" RuntimeErrorr4rC)r,stashed_tensorsr/r0r?s z'Skippable.forward..handle_stashr3cs$|jkrtd|d|S)NrMz#' has not been declared as poppable)r#rOrr4)poppable_tensorsr,r/r0r@s z%Skippable.forward..handle_popz, css|]}d|VqdSz'%s'Nr/.0nr/r/r0 sz$Skippable.forward..z must be stashed but have notcss|]}d|VqdSrTr/rUr/r/r0rXsz must be popped but have not)rrr:loadKeyErrorrOvaluesstrr rrLr"keysjoinr9save) r,rGZ skip_trackerbatchr6r4r?r@rIZ not_stashedZ comma_namesZ not_poppedrCr/)rSr,rQr0forwards6 zSkippable.forward)__name__ __module__ __qualname____doc__rrSkippableModule__annotations__rr\rr)r2rrr7r r9r:rr r>rrrLrr TensorOrTensorsra __classcell__r/r/r-r0r4s "= $r/)rrr&cs2t|t|ttttdfdd }|S)aThe decorator to define a :class:`nn.Module ` with skip connections. Decorated modules are called "skippable". This functionality works perfectly fine even when the module is not wrapped by :class:`~torch.distributed.pipeline.sync.Pipe`. Each skip tensor is managed by its name. Before manipulating skip tensors, a skippable module must statically declare the names for skip tensors by `stash` and/or `pop` parameters. Skip tensors with pre-declared name can be stashed by ``yield stash(name, tensor)`` or popped by ``tensor = yield pop(name)``. Here is an example with three layers. A skip tensor named "1to3" is stashed and popped at the first and last layer, respectively:: @skippable(stash=['1to3']) class Layer1(nn.Module): def forward(self, input): yield stash('1to3', input) return f1(input) class Layer2(nn.Module): def forward(self, input): return f2(input) @skippable(pop=['1to3']) class Layer3(nn.Module): def forward(self, input): skip_1to3 = yield pop('1to3') return f3(input) + skip_1to3 model = nn.Sequential(Layer1(), Layer2(), Layer3()) One skippable module can stash or pop multiple skip tensors:: @skippable(stash=['alice', 'bob'], pop=['carol']) class StashStashPop(nn.Module): def forward(self, input): yield stash('alice', f_alice(input)) yield stash('bob', f_bob(input)) carol = yield pop('carol') return input + carol Every skip tensor must be associated with exactly one pair of `stash` and `pop`. :class:`~torch.distributed.pipeline.sync.Pipe` checks this restriction automatically when wrapping a module. You can also check the restriction by :func:`verify_skippables` without :class:`~torch.distributed.pipeline.sync.Pipe`. )r!r&cs$|j}tf}|d}t|||S)N)r!r"r#)rbrtype)r!r4basesattrsr#r"r/r0extend_skippable's z#skippable..extend_skippable) frozensetrrfr)rrrnr/rmr0rs4c@s*eZdZdZdZeeeddddZdS)raThe command to stash a skip tensor. :: def forward(self, input): yield stash('name', input) return f(input) Args: name (str): name of skip tensor input (torch.Tensor or None): tensor to pass to the skip connection rPNrNcCs||_||_dSr'rP)r,r4rCr/r/r0r)Aszstash.__init__) rbrcrdre __slots__r\r rr)r/r/r/r0r0sc@s$eZdZdZdZeddddZdS)ra+The command to pop a skip tensor. :: def forward(self, input): skip = yield pop('name') return f(input) + skip Args: name (str): name of skip tensor Returns: the skip tensor previously stashed by another layer under the same name rRNr3cCs ||_dSr'rRr8r/r/r0r)Ysz pop.__init__)rbrcrdrerpr\r)r/r/r/r0rFsN)r*r&c Cst}t}g}|D]\}}t|ts.q|j|j@D] }d|d|d}||q:|D]L\}}||jkrxqd||f|krd|d|d}||qd|||fqd| D]x\}}||jkrq||f|krd|d|d}||q||f|kr$d|d|d}||q|||fqq||D] \} }d|d }||q>|rt d d d d |DdS)uVerifies if the underlying skippable modules satisfy integrity. Every skip tensor must have only one pair of `stash` and `pop`. If there are one or more unmatched pairs, it will raise :exc:`TypeError` with the detailed messages. Here are a few failure cases. :func:`verify_skippables` will report failure for these cases:: # Layer1 stashes "1to3". # Layer3 pops "1to3". nn.Sequential(Layer1(), Layer2()) # └──── ? nn.Sequential(Layer2(), Layer3()) # ? ────┘ nn.Sequential(Layer1(), Layer2(), Layer3(), Layer3()) # └───────────────────┘ ^^^^^^ nn.Sequential(Layer1(), Layer1(), Layer2(), Layer3()) # ^^^^^^ └───────────────────┘ To use the same name for multiple skip tensors, they must be isolated by different namespaces. See :meth:`isolate() `. Raises: TypeError: one or more pairs of `stash` and `pop` are not matched. rMz ' declared 'z#' both as stashable and as poppablez' redeclared 'z,' as stashable but not isolated by namespacez+' as poppable but not isolated by namespacez$' as poppable but it was not stashedzno module declared 'z' as poppable but stashedz4one or more pairs of stash and pop do not match: %s css|]}d|VqdS)z* %sNr/)rVxr/r/r0rXsz$verify_skippables..N) r<Znamed_childrenrArr"r#appendr9addr:rEr^) r*ZstashedpoppedZmsgsZ layer_nameZlayerr4msgr6_r/r/r0r]sH"          )r/r/)+retypingrrrrrrrr r r r r rrrrrZtorchrrZ microbatchr namespacertrackerr__all__ZTensorsrhZStashPopZStashPopGeneratorModulerfrrr\rrrZ Sequentialrr/r/r/r0s4L      > @