qpe_toolbox.circuit.gate_count
==============================

.. py:module:: qpe_toolbox.circuit.gate_count


Functions
---------

.. autoapisummary::

   qpe_toolbox.circuit.gate_count.count_gates
   qpe_toolbox.circuit.gate_count.count_swaps
   qpe_toolbox.circuit.gate_count.distance_qubits
   qpe_toolbox.circuit.gate_count.count_gates_by_qb


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

.. py:function:: count_gates(circ)

   Count quantum gates appearing in a circuit or gate-instruction list.

   Gates are grouped by label, with controlled gates prefixed by
   ``'C'`` for each control qubit (e.g. ``'CCX'`` for a doubly controlled X).

   An estimate of the number of SWAP gates required to implement the
   circuit on a 1D nearest-neighbor architecture is also included.

   :param circ: Circuit object or list of gate instructions of the form
                ``(label, params, qubits, controls)``.
   :type circ: :quimb-api:`Circuit`, :quimb-api:`CircuitMPS`, or list

   :returns: Dictionary mapping gate labels to their counts. The key ``'SWAP'``
             contains the estimated number of SWAP gates required due to
             connectivity constraints.
   :rtype: dict

   .. rubric:: Notes

   - SWAP counting assumes a linear qubit layout with nearest-neighbor
     connectivity.
   - For quimb circuits, gate information is extracted from ``circ.gates``.


.. py:function:: count_swaps(qubits, controls)

   Estimate the number of SWAP gates required for a gate.

   The estimate assumes a 1D nearest-neighbor qubit layout and counts
   the minimal number of SWAPs required to bring all involved qubits
   next to a common interaction point.

   :param qubits: Target qubit(s) of the gate.
   :type qubits: int or iterable of of int or None
   :param controls: Control qubits.
   :type controls: iterable of int or None

   :returns: Estimated number of SWAP gates required.
   :rtype: int

   .. rubric:: Notes

   - This is a heuristic estimate and does not correspond to an
     explicit routing algorithm.


.. py:function:: distance_qubits(i, j)

   Compute the distance between two qubits.

   This function defines the qubit connectivity metric and can be
   customized for different hardware topologies.

   :param i: Qubit indices.
   :type i: int
   :param j: Qubit indices.
   :type j: int

   :returns: Distance between qubits ``i`` and ``j``.
   :rtype: int


.. py:function:: count_gates_by_qb(gate_count)

   Group gate counts by the number of qubits they act on.

   Gates are classified as:
   - ``'1qb'``: single-qubit gates
   - ``'2qb'``: two-qubit gates (including singly controlled gates)
   - ``'3+qb'``: gates acting on three or more qubits

   :param gate_count: Dictionary mapping gate labels to counts as produced by
                      :func:`qpe_toolbox.estimation.quantum_phase_estimation.qpe_energy`.
   :type gate_count: dict

   :returns: Dictionary with keys ``'1qb'``, ``'2qb'``, and ``'3+qb'``.
   :rtype: dict