Energy estimation ================= The :class:`~qdk_chemistry.algorithms.EnergyEstimator` algorithm in QDK/Chemistry estimates the energy of a quantum state by measuring expectation values of Pauli operators. Following QDK/Chemistry's :doc:`algorithm design principles <../design/index>`, it takes an OpenQASM circuit (from :doc:`StatePreparation `) and a :class:`~qdk_chemistry.data.QubitHamiltonian` (from :doc:`QubitMapper `) as input and returns energy expectation values with statistical uncertainty. Overview -------- The :class:`~qdk_chemistry.algorithms.EnergyEstimator` evaluates the expectation value of a :class:`~qdk_chemistry.data.QubitHamiltonian` with respect to a given quantum circuit that loads a wavefunction onto qubits. It takes a Circuit object with target qubit Hamiltonians and automatically generates the corresponding measurement circuits. These circuits are executed on a selected backend simulator with the user-specified number of shots, and the resulting bitstring statistics are used to calculate per-term expectation values and the total energy. The algorithm supports: Multiple simulator backends QDK's native Q# simulator or Qiskit's Aer simulator Noise modeling Depolarizing noise, bit flip noise, Pauli noise, phase flip noise, and qubit loss simulation Grouped measurements Efficient measurement of commuting Pauli terms in a single circuit execution Classical coefficient handling Pre-computed classical contributions from Hamiltonian filtering A typical workflow connects :doc:`StatePreparation ` (which loads the wavefunction onto qubits) with EnergyEstimator (which measures the energy): 1. Prepare a :class:`~qdk_chemistry.data.Wavefunction` from a multi-configuration calculation 2. Generate an OpenQASM circuit using :doc:`StatePreparation ` 3. Map the Hamiltonian to qubit operators using :doc:`QubitMapper ` 4. Estimate the energy using EnergyEstimator Using the EnergyEstimator ------------------------- .. note:: This algorithm is currently available only in the Python API. This section demonstrates how to create, configure, and run an energy estimation. The ``run`` method returns an energy expectation value with variance and the raw measurement data. Input requirements ~~~~~~~~~~~~~~~~~~ The :class:`~qdk_chemistry.algorithms.EnergyEstimator` requires the following inputs: OpenQASM circuit A quantum circuit string in OpenQASM format that prepares the target quantum state. This is typically generated by the :doc:`StatePreparation ` algorithm from a :class:`~qdk_chemistry.data.Wavefunction`. QubitHamiltonian A :class:`~qdk_chemistry.data.QubitHamiltonian` instance containing the Pauli-string representation of the electronic Hamiltonian. This is obtained from the :doc:`QubitMapper ` algorithm. Number of shots The number of measurement repetitions to perform for statistical sampling. More shots reduce statistical uncertainty but increase computational cost. .. note:: The circuit and Hamiltonian must be compatible—they should use the same qubit encoding and be derived from the same underlying molecular system. The estimator automatically generates measurement circuits for each Pauli term in the Hamiltonian and performs the circuit sampling internally. .. rubric:: Creating an estimator .. tab:: Python API .. literalinclude:: ../../../_static/examples/python/energy_estimator.py :language: python :start-after: # start-cell-create :end-before: # end-cell-create .. rubric:: Configuring settings and running Settings vary by implementation. The QDK backend supports noise models and qubit loss, while the Qiskit backend supports custom Aer noise models. .. tab:: Python API (QDK Backend) .. literalinclude:: ../../../_static/examples/python/energy_estimator.py :language: python :start-after: # start-cell-qdk :end-before: # end-cell-qdk .. tab:: Python API (Qiskit Backend) .. literalinclude:: ../../../_static/examples/python/energy_estimator.py :language: python :start-after: # start-cell-qiskit :end-before: # end-cell-qiskit Available implementations ------------------------- QDK/Chemistry's :class:`~qdk_chemistry.algorithms.EnergyEstimator` provides a unified interface for quantum circuit simulation and energy measurement. You can discover available implementations programmatically: .. tab:: Python API .. literalinclude:: ../../../_static/examples/python/energy_estimator.py :language: python :start-after: # start-cell-list-implementations :end-before: # end-cell-list-implementations QDK base simulator ~~~~~~~~~~~~~~~~~~ .. rubric:: Factory name: ``"qdk_base_simulator"`` Native QDK/Chemistry implementation using the Q# simulator. Supports various noise models for realistic quantum hardware simulation. .. rubric:: Constructor parameters .. list-table:: :header-rows: 1 :widths: 25 25 50 * - Parameter - Type - Description * - ``seed`` - int - Random seed for reproducibility. Default is 42. * - ``noise_model`` - NoiseModel | None - Q# noise model (``DepolarizingNoise``, ``BitFlipNoise``, ``PauliNoise``, or ``PhaseFlipNoise``). Default is None (noiseless). * - ``qubit_loss`` - float - Probability of qubit loss per operation (0.0 to 1.0). Default is 0.0. .. rubric:: Run parameters .. list-table:: :header-rows: 1 :widths: 25 25 50 * - Parameter - Type - Description * - ``circuit_qasm`` - str - OpenQASM circuit string (from StatePreparation) * - ``qubit_hamiltonians`` - list[QubitHamiltonian] - List of qubit Hamiltonians to measure * - ``total_shots`` - int - Total number of measurement shots * - ``classical_coeffs`` - list | None - Pre-computed classical coefficients from Hamiltonian filtering. Default is None. Qiskit Aer Simulator ~~~~~~~~~~~~~~~~~~~~ .. rubric:: Factory name: ``"qiskit_aer_simulator"`` Energy estimation using Qiskit's Aer simulator backend. Provides access to Qiskit's extensive noise modeling capabilities. .. rubric:: Constructor parameters .. list-table:: :header-rows: 1 :widths: 25 25 50 * - Parameter - Type - Description * - ``backend`` - BackendV2 | None - Qiskit Aer backend instance with optional noise model. Default is None (uses default Aer simulator). * - ``seed`` - int - Random seed for reproducibility. Default is 42. For more details on how QDK/Chemistry interfaces with external packages, see the :ref:`plugin system ` documentation. Related classes --------------- - :class:`~qdk_chemistry.data.QubitHamiltonian`: Input qubit Hamiltonian from QubitMapper - :doc:`Wavefunction <../data/wavefunction>`: Source wavefunction for state preparation Further reading --------------- - The above examples can be downloaded as a complete `Python <../../../_static/examples/python/energy_estimator.py>`_ script. - :doc:`StatePreparation `: Load wavefunctions onto qubits as quantum circuits - :doc:`QubitMapper `: Map fermionic Hamiltonians to qubit operators - See the ``examples/state_prep_energy.ipynb`` notebook for an end-to-end workflow demonstration - :doc:`Settings `: Configuration settings for algorithms - :doc:`Factory Pattern `: Understanding algorithm creation