HEAT experiments

docs/apidocs/index.rst

@@ -30,3 +30,4 @@ Experiment Modules
     mod_randomized_benchmarking
     mod_tomography
     mod_quantum_volume
+    mod_hamiltonian

docs/apidocs/mod_hamiltonian.rst

@@ -0,0 +1,6 @@
+.. _qiskit-experiments-hamiltonian:
+
+.. automodule:: qiskit_experiments.library.hamiltonian
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

qiskit_experiments/framework/composite/__init__.py

@@ -18,3 +18,5 @@
 # Composite experiment classes
 from .parallel_experiment import ParallelExperiment
 from .batch_experiment import BatchExperiment
+
+from .composite_experiment import sync_experiment_options, sync_transpile_options

qiskit_experiments/framework/composite/composite_experiment.py

@@ -13,8 +13,9 @@
 Composite Experiment abstract base class.
 """
 
-from typing import List, Sequence, Optional, Union
+from typing import List, Sequence, Optional, Union, Type
 from abc import abstractmethod
+import functools
 import warnings
 from qiskit.providers.backend import Backend
 from qiskit_experiments.framework import BaseExperiment, ExperimentData
@@ -131,3 +132,75 @@ def _postprocess_transpiled_circuits(self, circuits, **run_options):
         for expr in self._experiments:
             if not isinstance(expr, CompositeExperiment):
                 expr._postprocess_transpiled_circuits(circuits, **run_options)
+
+
+def sync_transpile_options(
+    composite_cls: Type[CompositeExperiment],
+) -> Type[CompositeExperiment]:
+    """A class decorator that overrides the transpile option setter method.
+
+    This method overrides the behavior of :meth:`set_transpile_options` method.
+    The option values set to the composite instance
+    will be propagated through all component experiments.
+
+    Args:
+        composite_cls: CompositeExperiment subclass to decorate.
+
+    Returns:
+        Composite experiment that implements option synchronization.
+
+    Raises:
+        TypeError: When class is not subclass of :class:`CompositeExperiment`
+    """
+    if not issubclass(composite_cls, CompositeExperiment):
+        raise TypeError("Class is not composite experiment. Cannot override method.")
+
+    options_setter = getattr(composite_cls, "set_transpile_options")
+
+    @functools.wraps(options_setter)
+    def sync_opts(instance, **fields):
+        options_setter(instance, **fields)
+        # set the same options to component experiments
+        for comp in instance.component_experiment():
+            comp.set_transpile_options(**fields)
+
+    # override set method
+    setattr(composite_cls, "set_transpile_options", sync_opts)
+
+    return composite_cls
+
+
+def sync_experiment_options(
+    composite_cls: Type[CompositeExperiment],
+) -> Type[CompositeExperiment]:
+    """A class decorator that overrides the experiment option setter method.
+
+    This method overrides the behavior of :meth:`set_experiment_options` method.
+    The option values set to the composite instance
+    will be propagated through all component experiments.
+
+    Args:
+        composite_cls: CompositeExperiment subclass to decorate.
+
+    Returns:
+        Composite experiment that implements option synchronization.
+
+    Raises:
+        TypeError: When class is not subclass of :class:`CompositeExperiment`
+    """
+    if not issubclass(composite_cls, CompositeExperiment):
+        raise TypeError("Class is not composite experiment. Cannot override method.")
+
+    options_setter = getattr(composite_cls, "set_experiment_options")
+
+    @functools.wraps(options_setter)
+    def sync_opts(instance, **fields):
+        options_setter(instance, **fields)
+        # set the same options to component experiments
+        for comp in instance.component_experiment():
+            comp.set_experiment_options(**fields)
+
+    # override set method
+    setattr(composite_cls, "set_experiment_options", sync_opts)
+
+    return composite_cls

qiskit_experiments/library/__init__.py

@@ -71,6 +71,10 @@
     ~characterization.RamseyXY
     ~characterization.FineFrequency
     ~characterization.ReadoutAngle
+    ~hamiltonian.ZXHeat
+    ~hamiltonian.ZX90HeatXError
+    ~hamiltonian.ZX90HeatYError
+    ~hamiltonian.ZX90HeatZError
 
 
 .. _calibration:
@@ -143,10 +147,12 @@ class instance to manage parameters and pulse schedules.
 from .tomography import StateTomography, ProcessTomography
 from .quantum_volume import QuantumVolume
 from .mitigation import ReadoutMitigationExperiment
+from .hamiltonian import ZXHeat, ZX90HeatXError, ZX90HeatYError, ZX90HeatZError
 
 # Experiment Sub-modules
 from . import calibration
 from . import characterization
 from . import randomized_benchmarking
 from . import tomography
 from . import quantum_volume
+from . import hamiltonian

qiskit_experiments/library/hamiltonian/__init__.py

@@ -0,0 +1,65 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""
+===============================================================================================
+Hamiltonian Characterization Experiments (:mod:`qiskit_experiments.library.hamiltonian`)
+===============================================================================================
+
+.. currentmodule:: qiskit_experiments.library.hamiltonian
+
+This module provides a set of experiments to characterize qubit Hamiltonians.
+
+HEAT Experiments
+================
+
+HEAT stands for `Hamiltonian Error Amplifying Tomography` which amplifies the
+dynamics of an entangling gate along a specified axis of the target qubit. Here,
+errors are typically amplified by repeating a sequence of gates which results in
+a ping-pong pattern when measuring the qubit population.
+
+HEAT for ZX Hamiltonian
+-----------------------
+
+.. autosummary::
+    :toctree: ../stubs/
+    :template: autosummary/experiment.rst
+
+    ZXHeat
+    ZX90HeatXError
+    ZX90HeatYError
+    ZX90HeatZError
+
+HEAT Analysis
+-------------
+
+.. autosummary::
+    :toctree: ../stubs/
+    :template: autosummary/analysis.rst
+
+    HeatElementAnalysis
+    HeatAnalysis
+
+HEAT Base Classes
+-----------------
+
+.. autosummary::
+    :toctree: ../stubs/
+    :template: autosummary/experiment.rst
+
+    HeatElement
+
+
+"""
+
+from .heat_base import HeatElement
+from .heat_zx import ZXHeat, ZX90HeatXError, ZX90HeatYError, ZX90HeatZError
+from .heat_analysis import HeatElementAnalysis, HeatAnalysis

qiskit_experiments/library/hamiltonian/heat_analysis.py

@@ -0,0 +1,157 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""
+Analysis for HEAT experiments.
+"""
+
+from typing import Tuple
+
+import numpy as np
+
+from qiskit_experiments.curve_analysis import ErrorAmplificationAnalysis, ParameterRepr
+from qiskit_experiments.exceptions import AnalysisError
+from qiskit_experiments.framework import (
+    CompositeAnalysis,
+    ExperimentData,
+    AnalysisResultData,
+    Options,
+    FitVal,
+)
+
+
+class HeatElementAnalysis(ErrorAmplificationAnalysis):
+    """An analysis class for HEAT experiment to define the fixed parameters.
+
+    # section: overview
+
+        This is standard error amplification analysis.
+
+    # section: see_also
+        qiskit_experiments.curve_analysis.ErrorAmplificationAnalysis
+    """
+
+    __fixed_parameters__ = ["angle_per_gate", "phase_offset", "amp"]
+
+    @classmethod
+    def _default_options(cls) -> Options:
+        """Default analysis options."""
+        options = super()._default_options()
+        options.angle_per_gate = np.pi
+        options.phase_offset = np.pi / 2
+        options.amp = 1.0
+
+        return options
+
+
+class HeatAnalysis(CompositeAnalysis):
+    r"""A composite error amplification analysis to get unitary error coefficients.
+
+    # section: fit_model
+
+        Heat experiment amplifies the dynamics of the entangling gate along the
+        experiment-specific error axis on the target qubit Bloch sphere.
+        This analysis takes two error amplification experiment results performed with
+        different states of the control qubit to distinguish the contribution
+        of local term (such as IX) from non-local term (such as ZX).
+
+        This analysis takes a set of `d_theta` parameters from child error amplification results
+        which might be represented by a unique name in the child experiment data.
+        With these fit parameters, two Hamiltonian coefficients will be computed as
+
+        .. math::
+
+            A_{I\beta} = \frac{1}{2}\left( d\theta_{\beta 0} + d\theta_{\beta 1} \right) \\
+
+            A_{Z\beta} = \frac{1}{2}\left( d\theta_{\beta 0} - d\theta_{\beta 1} \right)
+
+        where, :math:`\beta \in [X, Y, Z]` is a single-qubit Pauli term, and
+        :math:`d\theta_{\beta k}` is an angle error ``d_theta`` extracted from the HEAT experiment
+        with the control qubit in state :math:`|k\rangle \in [|0\rangle, |1\rangle]`.
+
+    # section: see_also
+        qiskit_experiments.library.hamiltonian.HeatElementAnalysis
+        qiskit_experiments.curve_analysis.ErrorAmplificationAnalysis
+
+    """
+
+    def __init__(
+        self,
+        fit_params: Tuple[str, str],
+        out_params: Tuple[str, str],
+    ):
+        """Create new HEAT analysis.
+
+        Args:
+            fit_params: Name of error parameters for each amplification sequence.
+            out_params: Name of Hamiltonian coefficients.
+
+        Raises:
+            AnalysisError: When size of ``fit_params`` or ``out_params`` are not 2.
+        """
+        if len(fit_params) != 2:
+            raise AnalysisError(
+                f"{self.__class__.__name__} assumes two fit parameters extracted from "
+                "a set of experiments with different control qubit state input. "
+                f"{len(fit_params)} input parameter names are specified."
+            )
+
+        if len(out_params) != 2:
+            raise AnalysisError(
+                f"{self.__class__.__name__} assumes two output parameters computed with "
+                "a set of experiment results with different control qubit state input. "
+                f"{len(out_params)} output parameter names are specified."
+            )
+
+        analyses = []
+        for fit_parm in fit_params:
+            sub_analysis = HeatElementAnalysis()
+            sub_analysis.set_options(result_parameters=[ParameterRepr("d_theta", fit_parm, "rad")])
+            analyses.append(sub_analysis)
+
+        super().__init__(analyses=analyses)
+
+        self._fit_params = fit_params
+        self._out_params = out_params
+
+    def _run_analysis(self, experiment_data: ExperimentData):
+
+        # wait for child experiments to complete
+        super()._run_analysis(experiment_data)
+
+        # extract d_theta parameters
+        fit_results = []
+        for i, pname in enumerate(self._fit_params):
+            fit_results.append(experiment_data.child_data(i).analysis_results(pname))
+
+        # Check data quality
+        is_good_quality = all(r.quality == "good" for r in fit_results)
+
+        # Compute unitary terms
+        ib = (fit_results[0].value.value + fit_results[1].value.value) / 2
+        zb = (fit_results[0].value.value - fit_results[1].value.value) / 2
+
+        # Compute new variance
+        sigma = np.sqrt(fit_results[0].value.stderr ** 2 + fit_results[1].value.stderr ** 2)
+
+        estimate_ib = AnalysisResultData(
+            name=self._out_params[0],
+            value=FitVal(value=ib, stderr=sigma, unit="rad"),
+            quality="good" if is_good_quality else "bad",
+        )
+
+        estimate_zb = AnalysisResultData(
+            name=self._out_params[1],
+            value=FitVal(value=zb, stderr=sigma, unit="rad"),
+            quality="good" if is_good_quality else "bad",
+        )
+
+        return [estimate_ib, estimate_zb], []