class_docstr: Layer choice selects one of the ``candidates``, then apply it on inputs and return results.
  
  It allows users to put several candidate operations (e.g., PyTorch modules), one of them is chosen in each explored model.
  
  *New in v2.2:* Layer choice can be nested.
  
  Parameters
  ----------
  candidates : list of nn.Module or OrderedDict
      A module list to be selected from.
  weights : list of float
      Prior distribution used in random sampling.
  label : str
      Identifier of the layer choice.
  
  Attributes
  ----------
  length : int
      Deprecated. Number of ops to choose from. ``len(layer_choice)`` is recommended.
  names : list of str
      Names of candidates.
  choices : list of Module
      Deprecated. A list of all candidate modules in the layer choice module.
      ``list(layer_choice)`` is recommended, which will serve the same purpose.
  
  Examples
  --------
  
  ::
  
      # import nni.nas.nn.pytorch as nn
      # declared in `__init__` method
      self.layer = nn.LayerChoice([
          ops.PoolBN('max', channels, 3, stride, 1),
          ops.SepConv(channels, channels, 3, stride, 1),
          nn.Identity()
      ])
      # invoked in `forward` method
      out = self.layer(x)
  
  Notes
  -----
  ``candidates`` can be a list of modules or a ordered dict of named modules, for example,
  
  .. code-block:: python
  
      self.op_choice = LayerChoice(OrderedDict([
          ("conv3x3", nn.Conv2d(3, 16, 128)),
          ("conv5x5", nn.Conv2d(5, 16, 128)),
          ("conv7x7", nn.Conv2d(7, 16, 128))
      ]))
  
  Elements in layer choice can be modified or deleted. Use ``del self.op_choice["conv5x5"]`` or
  ``self.op_choice[1] = nn.Conv3d(...)``. Adding more choices is not supported yet.
class_docstr_tok: ["Layer","choice","selects","one","of","the","``","candidates","``",",","then","apply","it","on","inputs","and","return","results",".","It","allows","users","to","put","several","candidate","operations","(","e.g.",",","PyTorch","modules",")",",","one","of","them","is","chosen","in","each","explored","model",".","*","New","in","v2.2",":","*","Layer","choice","can","be","nested",".","Parameters","--","--","--","--","--","candidates",":","list","of","nn.Module","or","OrderedDict","A","module","list","to","be","selected","from",".","weights",":","list","of","float","Prior","distribution","used","in","random","sampling",".","label",":","str","Identifier","of","the","layer","choice",".","Attributes","--","--","--","--","--","length",":","int","Deprecated",".","Number","of","ops","to","choose","from",".","``","len","(","layer_choice",")","``","is","recommended",".","names",":","list","of","str","Names","of","candidates",".","choices",":","list","of","Module","Deprecated",".","A","list","of","all","candidate","modules","in","the","layer","choice","module",".","``","list","(","layer_choice",")","``","is","recommended",",","which","will","serve","the","same","purpose",".","Examples","--","--","--","--",":",":","#","import","nni.nas.nn.pytorch","as","nn","#","declared","in","`","__init__","`","method","self.layer","=","nn.LayerChoice","(","[","ops.PoolBN","(","'max","'",",","channels",",","3",",","stride",",","1",")",",","ops.SepConv","(","channels",",","channels",",","3",",","stride",",","1",")",",","nn.Identity","(",")","]",")","#","invoked","in","`","forward","`","method","out","=","self.layer","(","x",")","Notes","--","--","-","``","candidates","``","can","be","a","list","of","modules","or","a","ordered","dict","of","named","modules",",","for","example",",","..","code-block",":",":","python","self.op_choice","=","LayerChoice","(","OrderedDict","(","[","(","``","conv3x3","''",",","nn.Conv2d","(","3",",","16",",","128",")",")",",","(","``","conv5x5","''",",","nn.Conv2d","(","5",",","16",",","128",")",")",",","(","``","conv7x7","''",",","nn.Conv2d","(","7",",","16",",","128",")",")","]",")",")","Elements","in","layer","choice","can","be","modified","or","deleted",".","Use","``","del","self.op_choice","[","``","conv5x5","''","]","``","or","``","self.op_choice","[","1","]","=","nn.Conv3d","(","...",")","``",".","Adding","more","choices","is","not","supported","yet","."]
docstr: Restore the ``candidates`` parameters passed to the constructor.
  Useful when creating a new layer choices based on this one.
docstr_tok: ["Restore","the","``","candidates","``","parameters","passed","to","the","constructor",".","Useful","when","creating","a","new","layer","choices","based","on","this","one","."]
code: def candidates(self) -> Union[Dict[str, nn.Module], List[nn.Module]]:
      """Restore the ``candidates`` parameters passed to the constructor.
      Useful when creating a new layer choices based on this one.
      """
      if all(
          isinstance(name, int) for name in self.names
      ) and self.names == list(range(len(self))):
          return list(self)
      else:
          return {cast(str, name): self[name] for name in self.names}
  
imports: import functools
  import warnings
  from typing import Any, Iterator, List, Optional, Dict, Union, Tuple, cast
  from typing_extensions import Literal
  import torch
  import torch.nn
  from nni.mutable import Categorical, CategoricalMultiple, Sample, SampleValidationError, ensure_frozen
  from .base import MutableModule, recursive_freeze
label_desc: Use image node_id 3 for calling the LayerChoice obj's underlying member method code with example usage: obj.candidates() and returns: list, unknown