qpe_toolbox.estimation.quantum_phase_estimation

Functions

qpe_energy(hamiltonian, initial_circ, n_steps, ...[, ...])

Perform quantum phase estimation (QPE) to estimate the energy of a Hamiltonian.

qpe_sample(hamiltonian, initial_circ, evolution_time, ...)

Apply quantum phase estimation to a given initial circuit and sample the output.

qpe_first_stage(hamiltonian, initial_circ, ...[, ...])

Perform the first stage of the quantum phase estimation algorithm.

set_search_window(hamiltonian, E_target, size_interval)

Set up the energy search window for phase estimation.

Module Contents

qpe_toolbox.estimation.quantum_phase_estimation.qpe_energy(hamiltonian, initial_circ, n_steps, E_target, size_interval, *, trotter_order=1, write_gates=False, optimize='auto-hq', verbosity=0)[source]

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.

Parameters:

  • hamiltonian (Hamiltonian) – Hamiltonian object from the QPE-Toolbox Hamiltonian class.

  • initial_circ (Circuit or CircuitMPS) – Initial circuit preparing the trial state in the data register.

  • n_steps (int or qpe_toolbox.EXACT) – Number of time steps for Trotterized evolution, or EXACT for exact evolution.

  • E_target (float) – Central target energy for the search window.

  • size_interval (float) – Width of the energy search interval.

  • trotter_order (int, default 1) – Order of the Trotter decomposition.

  • write_gates (bool, default False) – If True, writes the gate sequence to a text file.

  • optimize (str, default "auto-hq") – Optimization strategy when computing marginals with tensor networks.

  • verbosity (int, default 0) – Verbosity level. If >= 1, print result summary. If >= 2, print additional debug information.

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.

Notes

  • The phase register is automatically determined as initial_circ.N - hamiltonian.n_qubits.

  • The estimated energy is computed as

    \[E = E_\mathrm{max} - \frac{2 \pi \theta}{t_\mathrm{evol}} - E_\mathrm{const}\]

    where \(\theta\) corresponds to the phase of the most probable state.

  • Supports both Trotterized and exact evolution.

qpe_toolbox.estimation.quantum_phase_estimation.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)[source]

Apply quantum phase estimation to a given initial circuit and sample the output.

Parameters:

  • hamiltonian (Hamiltonian) – Hamiltonian object from the QPE-Toolbox Hamiltonian class.

  • initial_circ (Circuit or CircuitMPS) – Circuit preparing the trial state.

  • evolution_time (float) – Total evolution time for the controlled-U operations.

  • dt (float or qpe_toolbox.EXACT) – Trotter step size; if EXACT, evolution is exact.

  • global_phase (float) – Global phase added to the controlled-U operations.

  • trotter_order (int, default 1) – Order of Trotter decomposition for time evolution.

  • write_gates (bool, default False) – If True, saves the gates to a text file.

  • rehearse (bool, default False) – If True, precomputes marginals without measurement.

  • run_simulation (bool, default True) – Whether to perform full tensor network simulation or just track gates.

  • optimize (str, default "auto-hq") – Optimization strategy for tensor network marginal computation.

  • verbosity (int, default 0) – If > 0, prints timing and progress information.

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.

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.

qpe_toolbox.estimation.quantum_phase_estimation.qpe_first_stage(hamiltonian, initial_circ, evolution_time, dt, global_phase, *, trotter_order=1, run_simulation=True, verbosity=0)[source]

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.

Parameters:

  • hamiltonian (Hamiltonian) – Hamiltonian object from the QPE-Toolbox Hamiltonian class.

  • initial_circ (Circuit or CircuitMPS) – Initial state of the system.

  • evolution_time (float) – Total evolution time.

  • dt (float or qpe_toolbox.EXACT) – Time step for Trotter decomposition; EXACT for exact evolution.

  • global_phase (float) – Global phase applied to controlled-U operations.

  • trotter_order (int, default 1) – Trotter order for time evolution.

  • run_simulation (bool, default True) – Whether to perform full tensor network simulation or just track gates.

  • verbosity (int, default 0) – Verbosity level. If >= 1, print progress and bond dimension information.

Returns:

  • traces (dict) – Contains bond dimensions, computation times, and optionally other metadata.

  • circ_or_gates (Circuit or list) – Updated circuit if run_simulation is True; otherwise, list of gate instructions.

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.

qpe_toolbox.estimation.quantum_phase_estimation.set_search_window(hamiltonian, E_target, size_interval)[source]

Set up the energy search window for phase estimation.

Parameters:

  • hamiltonian (Hamiltonian) – Hamiltonian object from the QPE-Toolbox Hamiltonian class.

  • E_target (float) – Central target energy around which to search.

  • size_interval (float) – Width of the energy interval (must be > 0).

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.

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.