qpe_toolbox.estimation.quantum_phase_estimation =============================================== .. py:module:: qpe_toolbox.estimation.quantum_phase_estimation Functions --------- .. autoapisummary:: qpe_toolbox.estimation.quantum_phase_estimation.qpe_energy qpe_toolbox.estimation.quantum_phase_estimation.qpe_sample qpe_toolbox.estimation.quantum_phase_estimation.qpe_first_stage qpe_toolbox.estimation.quantum_phase_estimation.set_search_window Module Contents --------------- .. py:function:: qpe_energy(hamiltonian, initial_circ, n_steps, E_target, size_interval, *, trotter_order=1, write_gates=False, optimize='auto-hq', verbosity=0) Perform quantum phase estimation (QPE) to estimate the energy of a Hamiltonian. The algorithm encodes the phase corresponding to the Hamiltonian evolution into a phase register and samples it to extract the energy eigenvalue. :param hamiltonian: Hamiltonian object from the QPE-Toolbox ``Hamiltonian`` class. :type hamiltonian: Hamiltonian :param initial_circ: Initial circuit preparing the trial state in the data register. :type initial_circ: :quimb-api:`Circuit` or :quimb-api:`CircuitMPS` :param n_steps: Number of time steps for Trotterized evolution, or ``EXACT`` for exact evolution. :type n_steps: int or qpe_toolbox.EXACT :param E_target: Central target energy for the search window. :type E_target: float :param size_interval: Width of the energy search interval. :type size_interval: float :param trotter_order: Order of the Trotter decomposition. :type trotter_order: int, default ``1`` :param write_gates: If True, writes the gate sequence to a text file. :type write_gates: bool, default ``False`` :param optimize: Optimization strategy when computing marginals with tensor networks. :type optimize: str, default ``"auto-hq"`` :param verbosity: Verbosity level. If >= 1, print result summary. If >= 2, print additional debug information. :type verbosity: int, default ``0`` :returns: * **traces** (*dict*) -- Dictionary with computation information, including timing, bond dimensions, gate counts, and highest probability phase values. * **energy** (*float*) -- Estimated energy eigenvalue from the phase estimation. .. rubric:: Notes - The phase register is automatically determined as ``initial_circ.N - hamiltonian.n_qubits``. - The estimated energy is computed as .. math:: E = E_\mathrm{max} - \frac{2 \pi \theta}{t_\mathrm{evol}} - E_\mathrm{const} where :math:`\theta` corresponds to the phase of the most probable state. - Supports both Trotterized and exact evolution. .. py:function:: qpe_sample(hamiltonian, initial_circ, evolution_time, dt, global_phase, *, trotter_order=1, write_gates=False, rehearse=False, run_simulation=True, optimize='auto-hq', verbosity=0) Apply quantum phase estimation to a given initial circuit and sample the output. :param hamiltonian: Hamiltonian object from the QPE-Toolbox ``Hamiltonian`` class. :type hamiltonian: Hamiltonian :param initial_circ: Circuit preparing the trial state. :type initial_circ: :quimb-api:`Circuit` or :quimb-api:`CircuitMPS` :param evolution_time: Total evolution time for the controlled-U operations. :type evolution_time: float :param dt: Trotter step size; if ``EXACT``, evolution is exact. :type dt: float or qpe_toolbox.EXACT :param global_phase: Global phase added to the controlled-U operations. :type global_phase: float :param trotter_order: Order of Trotter decomposition for time evolution. :type trotter_order: int, default ``1`` :param write_gates: If True, saves the gates to a text file. :type write_gates: bool, default ``False`` :param rehearse: If True, precomputes marginals without measurement. :type rehearse: bool, default ``False`` :param run_simulation: Whether to perform full tensor network simulation or just track gates. :type run_simulation: bool, default ``True`` :param optimize: Optimization strategy for tensor network marginal computation. :type optimize: str, default ``"auto-hq"`` :param verbosity: If ``> 0``, prints timing and progress information. :type verbosity: int, default ``0`` :returns: * **traces** (*dict*) -- Dictionary containing bond dimensions, timing, and gate counts. * **result** (*array or list*) -- Either the probability tensor of phase qubits (if ``run_simulation`` is True) or a list of gate instructions. .. rubric:: Notes - Phase estimation is performed using a Hadamard wall followed by controlled-U operations. - IQFT is applied on the phase register to extract probabilities. - When ``run_simulation=False``, the function produces a gate list instead of simulating the circuit. .. py:function:: qpe_first_stage(hamiltonian, initial_circ, evolution_time, dt, global_phase, *, trotter_order=1, run_simulation=True, verbosity=0) Perform the first stage of the quantum phase estimation algorithm. This includes: * Applying a Hadamard wall on the phase register. * Controlled-U operations with the Hamiltonian evolution. * Optional Trotterization for approximate time evolution. :param hamiltonian: Hamiltonian object from the QPE-Toolbox ``Hamiltonian`` class. :type hamiltonian: Hamiltonian :param initial_circ: Initial state of the system. :type initial_circ: :quimb-api:`Circuit` or :quimb-api:`CircuitMPS` :param evolution_time: Total evolution time. :type evolution_time: float :param dt: Time step for Trotter decomposition; ``EXACT`` for exact evolution. :type dt: float or qpe_toolbox.EXACT :param global_phase: Global phase applied to controlled-U operations. :type global_phase: float :param trotter_order: Trotter order for time evolution. :type trotter_order: int, default ``1`` :param run_simulation: Whether to perform full tensor network simulation or just track gates. :type run_simulation: bool, default ``True`` :param verbosity: Verbosity level. If >= 1, print progress and bond dimension information. :type verbosity: int, default ``0`` :returns: * **traces** (*dict*) -- Contains bond dimensions, computation times, and optionally other metadata. * **circ_or_gates** (:quimb-api:`Circuit` or list) -- Updated circuit if ``run_simulation`` is True; otherwise, list of gate instructions. .. rubric:: Notes - The phase register size is inferred from ``initial_circ.N - hamiltonian.n_qubits``. - Warnings are raised if the Trotter step size exceeds the required evolution time. .. py:function:: set_search_window(hamiltonian, E_target, size_interval) Set up the energy search window for phase estimation. :param hamiltonian: Hamiltonian object from the QPE-Toolbox ``Hamiltonian`` class. :type hamiltonian: Hamiltonian :param E_target: Central target energy around which to search. :type E_target: float :param size_interval: Width of the energy interval (must be > 0). :type size_interval: float :returns: * **E_const** (*float*) -- Constant energy offset of the Hamiltonian (``hamiltonian.e_const`` or 0.0). * **Emax** (*float*) -- Upper edge of the energy interval for phase encoding. * **evolution_time** (*float*) -- Total evolution time corresponding to the search interval. * **global_phase** (*float*) -- Phase corresponding to ``Emax * evolution_time``. .. rubric:: Notes - Evolution time is chosen as ``2 * pi / size_interval`` to map the interval to [0, 2π]. - ``global_phase`` is added to ensure the phase encoding is centered around the target energy.