docs: def map_channels(mapping, cdim):
      """Create a :class:`CPermuation` based on a dict of channel mappings
  
      For a given mapping in form of a dictionary, generate the channel
      permutating circuit that achieves the specified mapping while leaving the
      relative order of all non-specified channels intact.
  
      Args:
          mapping (dict): Input-output mapping of indices (zero-based)
              ``{in1:out1, in2:out2,...}``
          cdim (int): The circuit dimension (number of channels)
  
      Returns:
          CPermutation: Circuit mapping the channels as specified
      """
      n = cdim
      free_values = list(range(n))
  
      for v in mapping.values():
          if v >= n:
              raise ValueError('the mapping cannot take on values larger than '
                               'cdim - 1')
          free_values.remove(v)
      for k in mapping:
          if k >= n:
              raise ValueError('the mapping cannot map keys larger than '
                               'cdim - 1')
      permutation = []
      for k in range(n):
          if k in mapping:
              permutation.append(mapping[k])
          else:
              permutation.append(free_values.pop(0))
  
      return CPermutation.create(tuple(permutation))