qpe_toolbox.circuit.controls
============================

.. py:module:: qpe_toolbox.circuit.controls

.. autoapi-nested-parse::

   Routines for quimb circuits and/or gates.



Functions
---------

.. autoapisummary::

   qpe_toolbox.circuit.controls.shift_control_gates


Module Contents
---------------

.. py:function:: shift_control_gates(gates, m_aux, k_ctrl)

   Shift gate targets and controls to account for an auxiliary qubit register.

   This function is used when an auxiliary (ancilla) register occupies the
   first ``m_aux`` qubits of a circuit. All gates acting on the data register
   are shifted by ``m_aux`` in their qubit indices, and an additional control
   qubit from the auxiliary register is added to each gate.

   :param gates: List of gates to shift.
   :type gates: iterable of :quimb-api:`Gate`
   :param m_aux: Number of auxiliary qubits occupying the lowest indices ``[0, m_aux - 1]``.
   :type m_aux: int
   :param k_ctrl: Index of the control qubit within the auxiliary register.
                  Must satisfy ``0 <= k_ctrl < m_aux``.
   :type k_ctrl: int

   :returns: **controlled_gates** -- New list of gate objects with shifted qubit indices and added control.
   :rtype: list of :quimb-api:`Gate`

   :raises ValueError: If ``k_ctrl`` lies outside the auxiliary register.

   .. rubric:: Notes

   - Target qubits ``q`` are mapped to ``q + m_aux``.
   - Existing control qubits are also shifted by ``m_aux``.
   - If a gate originally has no controls, it becomes singly controlled
     by ``k_ctrl``.
   - The original gate objects are not modified.