"""QDK/Chemistry expectation estimator abstractions and utilities."""
# --------------------------------------------------------------------------------------------
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License. See LICENSE.txt in the project root for license information.
# --------------------------------------------------------------------------------------------
from abc import abstractmethod
from qdk_chemistry.algorithms.base import Algorithm, AlgorithmFactory
from qdk_chemistry.data import (
AlgorithmRef,
Circuit,
EnergyExpectationResult,
MeasurementData,
QuantumErrorProfile,
QubitOperator,
Settings,
)
__all__: list[str] = ["ExpectationEstimator", "ExpectationEstimatorFactory"]
class ExpectationEstimatorSettings(Settings):
"""Settings for ExpectationEstimator algorithms."""
def __init__(self):
"""Initialize the ExpectationEstimatorSettings."""
super().__init__()
self._set_default(
"circuit_executor",
"algorithm_ref",
AlgorithmRef("circuit_executor", "qdk_sparse_state_simulator"),
"Circuit executor used to run quantum circuits for expectation-value estimation.",
)
[docs]
class ExpectationEstimator(Algorithm):
"""Abstract base class for expectation estimator algorithms."""
[docs]
def __init__(self):
"""Initialize the ExpectationEstimator."""
super().__init__()
self._settings = ExpectationEstimatorSettings()
[docs]
def type_name(self) -> str:
"""Return ``expectation_estimator`` as the algorithm type name."""
return "expectation_estimator"
@abstractmethod
def _run_impl(
self,
circuit: Circuit,
qubit_hamiltonian: QubitOperator,
total_shots: int,
noise_model: QuantumErrorProfile | None = None,
) -> tuple[EnergyExpectationResult, MeasurementData]:
"""Estimate the expectation value and variance of the Hamiltonian.
Args:
circuit: Circuit.
qubit_hamiltonian: ``QubitOperator`` to estimate.
total_shots: Total number of shots to allocate across the observable terms.
noise_model: Optional noise model to simulate noise in the quantum circuit.
Returns:
tuple[EnergyExpectationResult, MeasurementData]: Tuple containing:
* ``energy_result``: Energy expectation value and variance for the provided Hamiltonian.
* ``measurement_data``: Raw measurement counts and metadata used to compute the expectation value.
"""
[docs]
class ExpectationEstimatorFactory(AlgorithmFactory):
"""Factory class for creating ExpectationEstimator instances."""
[docs]
def algorithm_type_name(self) -> str:
"""Return ``expectation_estimator`` as the algorithm type name."""
return "expectation_estimator"
[docs]
def default_algorithm_name(self) -> str:
"""Return ``qdk`` as the default algorithm name."""
return "qdk"