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

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))