qpe_toolbox.circuit.initialization
==================================

.. py:module:: qpe_toolbox.circuit.initialization


Functions
---------

.. autoapisummary::

   qpe_toolbox.circuit.initialization.make_circ
   qpe_toolbox.circuit.initialization.make_circMPS


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

.. py:function:: make_circ(n_phase_bits, psi_mps)

   Initialize a quimb quantum circuit with a phase register and a data register.

   The circuit is initialized in a product state consisting of:

   * A phase (auxiliary) register of ``n_phase_bits`` qubits
     in the computational ``|0...0⟩`` state.
   * A data register initialized in the given matrix product state ``psi_mps``.

   The phase register occupies the *lowest* qubit indices, while the data
   register is shifted to higher indices.

   :param n_phase_bits: Number of qubits in the phase (auxiliary) register.
   :type n_phase_bits: int
   :param psi_mps: Initial state of the data register as an MPS. Its sites will be
                   reindexed and retagged to follow the phase register.
   :type psi_mps: :quimb-api:`MatrixProductState`

   :returns: Quantum circuit initialized with the combined MPS state.
   :rtype: :quimb-api:`Circuit`

   .. rubric:: Notes

   - The physical qubits of ``psi_mps`` are shifted by ``n_phase_bits`` to
     avoid index collisions.
   - The resulting circuit has ``n_phase_bits + psi_mps.L`` qubits in total.


.. py:function:: make_circMPS(n_phase_bits, psi_mps, *, cutoff=1e-10, max_bond=None)

   Initialize a quimb ``CircuitMPS`` with a phase and data register.

   This function is equivalent to :func:`make_circ`, but returns a
   ``CircuitMPS`` object, enabling controlled bond-dimension growth
   and truncation during circuit simulation.

   :param n_phase_bits: Number of qubits in the phase (ancilla) register.
   :type n_phase_bits: int
   :param psi_mps: Initial data-register state as an MPS.
   :type psi_mps: :quimb-api:`MatrixProductState`
   :param cutoff: Singular-value truncation threshold used during tensor compression.
                  Default is ``1e-10``.
   :type cutoff: float, optional
   :param max_bond: Maximum allowed bond dimension. If ``None``, no explicit limit
                    is imposed.
   :type max_bond: int or None, optional

   :returns: Quantum circuit initialized with an MPS backend.
   :rtype: :quimb-api:`CircuitMPS`

   .. rubric:: Notes

   - ``CircuitMPS`` is more efficient than ``Circuit`` for large systems
     or deep circuits, at the cost of controlled approximation.
   - The phase register qubits precede the data register in qubit ordering.