def __init__(
        self,
        sub_gate: cirq.Gate,
        num_controls: int | None = None,
        control_values: cv.AbstractControlValues | Sequence[int | Collection[int]] | None = None,
        control_qid_shape: Sequence[int] | None = None,
    ) -> None:
        """Initializes the controlled gate. If no arguments are specified for
           the controls, defaults to a single qubit control.

        Args:
            sub_gate: The gate to add a control qubit to.
            num_controls: Total number of control qubits.
            control_values: For which control qubit values to apply the sub
                gate.  Either an object that inherits from AbstractControlValues
                or a sequence of length `num_controls` where each
                entry is an integer (or set of integers) corresponding to the
                qubit value (or set of possible values) where that control is
                enabled.  When all controls are enabled, the sub gate is
                applied.  If unspecified, control values default to 1.
            control_qid_shape: The qid shape of the controls.  A tuple of the
                expected dimension of each control qid.  Defaults to
                `(2,) * num_controls`.  Specify this argument when using qudits.

        Raises:
            ValueError: If the `control_values` or `control_qid_shape` does not
                match with `num_controls`, if the `control_values` are out of
                bounds, or if the sub_gate is not a unitary or mixture.
        """
        _validate_sub_object(sub_gate)

        # Simplify a single SumOfProducts
        if isinstance(control_values, cv.SumOfProducts) and len(control_values._conjunctions) == 1:
            control_values = control_values._conjunctions[0]

        if num_controls is None:
            if control_values is not None:
                num_controls = (
                    control_values._num_qubits_()
                    if isinstance(control_values, cv.AbstractControlValues)
                    else len(control_values)
                )
            elif control_qid_shape is not None:
                num_controls = len(control_qid_shape)
            else:
                num_controls = 1
        if control_values is None:
            control_values = ((1,),) * num_controls

        # Convert to `cv.ProductOfSums` if input is a tuple of control values for each qubit.
        if not isinstance(control_values, cv.AbstractControlValues):
            control_values = cv.ProductOfSums(control_values)

        if num_controls != protocols.num_qubits(control_values):
            raise ValueError('cirq.num_qubits(control_values) != num_controls')

        if control_qid_shape is None:
            control_qid_shape = (2,) * num_controls
        if num_controls != len(control_qid_shape):
            raise ValueError('len(control_qid_shape) != num_controls')
        self._control_qid_shape = tuple(control_qid_shape)

        self._control_values = control_values

        # Verify control values not out of bounds
        self._control_values.validate(self.control_qid_shape)

        # Flatten nested ControlledGates.
        if isinstance(sub_gate, ControlledGate):
            self._sub_gate = sub_gate.sub_gate
            self._control_values = self._control_values & sub_gate.control_values
            self._control_qid_shape += sub_gate.control_qid_shape
        else:
            self._sub_gate = sub_gate
Initializes the controlled gate. If no arguments are specified for
           the controls, defaults to a single qubit control.

        Args:
            sub_gate: The gate to add a control qubit to.
            num_controls: Total number of control qubits.
            control_values: For which control qubit values to apply the sub
                gate.  Either an object that inherits from AbstractControlValues
                or a sequence of length `num_controls` where each
                entry is an integer (or set of integers) corresponding to the
                qubit value (or set of possible values) where that control is
                enabled.  When all controls are enabled, the sub gate is
                applied.  If unspecified, control values default to 1.
            control_qid_shape: The qid shape of the controls.  A tuple of the
                expected dimension of each control qid.  Defaults to
                `(2,) * num_controls`.  Specify this argument when using qudits.

        Raises:
            ValueError: If the `control_values` or `control_qid_shape` does not
                match with `num_controls`, if the `control_values` are out of
                bounds, or if the sub_gate is not a unitary or mixture.
        
cirq-core/cirq/ops/controlled_gate.py