Calibrations Definition

qiskit_experiments/calibration/__init__.py

@@ -0,0 +1,123 @@
+# 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.
+
+r"""
+Qiskit Experiments Calibration Root.
+
+.. warning::
+    The calibrations interface is still in active development. It may have
+    breaking API changes without deprecation warnings in future releases until
+    otherwise indicated.
+
+Calibrations are managed by the Calibrations class. This class stores schedules which are
+intended to be fully parameterized, including the index of the channels. This class:
+- supports having different schedules share parameters
+- allows default schedules for qubits that can be overridden for specific qubits.
+
+The following code illustrates how a user can create a parameterized schedule, add
+values to the parameters and query a schedule.
+
+.. code-block:: python
+
+    dur = Parameter("dur")
+    amp = Parameter("amp")
+    sigma = Parameter("σ")
+
+    with pulse.build(name="xp") as xp:
+        pulse.play(Gaussian(dur, amp, sigma), DriveChannel(Parameter("ch0")))
+
+    cals = Calibrations()
+    cals.add_schedule(xp)
+
+    # add duration and sigma parameter values for all qubits.
+    cals.add_parameter_value(160, "dur", schedule="xp")
+    cals.add_parameter_value(35.5, "σ", schedule="xp")
+
+    # Add an amplitude for qubit 3.
+    cals.add_parameter_value(0.2+0.05j, "amp", (3, ), "xp")
+
+    # Retrieve an xp pulse with all parameters assigned
+    cals.get_schedule("xp", (3, ))
+
+    # Retrieve an xp pulse with unassigned amplitude
+    cals.get_schedule("xp", (3, ), free_params=["amp"])
+
+The Calibrations make a couple of assumptions which are discussed below.
+
+Parametric channel naming convention
+=========================
+
+Parametrized channel indices must be named according to a predefined pattern to properly
+identify the channels and control channels when assigning values to the parametric
+channel indices. A channel must have a name that starts with `ch` followed by an integer.
+For control channels this integer can be followed by a sequence `.integer`.
+Optionally, the name can end with `$integer` to specify the index of a control channel
+for the case when a set of qubits share multiple control channels. For example,
+valid channel names include "ch0", "ch1", "ch0.1", "ch0$", "ch2$3", and "ch1.0.3$2".
+The "." delimiter is used to specify the different qubits when looking for control
+channels. The optional $ delimiter is used to specify which control channel to use
+if several control channels work together on the same qubits. For example, if the
+control channel configuration is {(3,2): [ControlChannel(3), ControlChannel(12)]}
+then given qubits (2, 3) the name "ch1.0$1" will resolve to ControlChannel(12) while
+"ch1.0$0" will resolve to ControlChannel(3). A channel can only have one parameter.
+
+Parameter naming restriction
+===================
+
+Each parameter must have a unique name within each schedule. For example, it is
+acceptable to have a parameter named 'amp' in the schedule 'xp' and a different
+parameter instance named 'amp' in the schedule named 'xm'. It is not acceptable
+to have two parameters named 'amp' in the same schedule. The naming restriction
+only applies to parameters used in the immediate scope of the schedule. Schedules
+called by Call instructions have their own scope for Parameter names.
+
+The code block below illustrates the creation of a template schedule for a echoed cross-
+resonance gate.
+
+.. code-block:: python
+
+    amp_cr = Parameter("amp")
+    amp = Parameter("amp")
+    d0 = DriveChannel(Parameter("ch0"))
+    c1 = ControlChannel(Parameter("ch0.1"))
+    sigma = Parameter("σ")
+    width = Parameter("w")
+    dur_xp = Parameter("duration")
+    dur_cr = Parameter("duration")
+
+    with pulse.build(name="xp") as xp:
+        pulse.play(Gaussian(dur_xp, amp, sigma), d0)
+
+    with pulse.build(name="cr") as cr:
+        with pulse.align_sequential():
+                pulse.play(GaussianSquare(dur_cr, amp_cr, sigma, width), c1)
+                pulse.call(xp)
+                pulse.play(GaussianSquare(dur_cr, -amp_cr, sigma, width), c1)
+                pulse.call(xp)
+
+    cals = Calibrations()
+    cals.add_schedule(xp)
+    cals.add_schedule(cr)
+
+Note that a registered template schedule can be retrieve by doing
+
+.. code-block:: python
+
+    xp = cals.get_template("xp")
+
+which would return the default xp schedule block template for all qubits.
+"""
+
+from .calibrations import Calibrations
+from .backend_calibrations import BackendCalibrations
+from .exceptions import CalibrationError
+from .parameter_value import ParameterValue

qiskit_experiments/calibration/backend_calibrations.py

@@ -0,0 +1,149 @@
+# 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.
+
+"""Store and manage the results of calibration experiments in the context of a backend."""
+
+from datetime import datetime
+from enum import Enum
+from typing import List
+import copy
+
+from qiskit.providers.backend import BackendV1 as Backend
+from qiskit.circuit import Parameter
+from qiskit_experiments.calibration.calibrations import Calibrations, ParameterKey
+from qiskit_experiments.calibration.exceptions import CalibrationError
+
+
+class FrequencyElement(Enum):
+    """An extendable enum for components that have a frequency."""
+
+    QUBIT = "Qubit"
+    READOUT = "Readout"
+
+
+class BackendCalibrations(Calibrations):
+    """
+    A Calibrations class to enable a seamless interplay with backend objects.
+    This class enables users to export their calibrations into a backend object.
+    Additionally, it creates frequency parameters for qubits and readout resonators.
+    The parameters are named `qubit_lo_freq` and `meas_lo_freq` to be consistent
+    with the naming in backend.defaults(). These two parameters are not attached to
+    any schedule.
+    """
+
+    def __init__(self, backend: Backend):
+        """Setup an instance to manage the calibrations of a backend."""
+        super().__init__(backend.configuration().control_channels)
+
+        # Use the same naming convention as in backend.defaults()
+        self.qubit_freq = Parameter("qubit_lo_freq")
+        self.meas_freq = Parameter("meas_lo_freq")
+        self._register_parameter(self.qubit_freq, ())
+        self._register_parameter(self.meas_freq, ())
+
+        self._qubits = set(range(backend.configuration().n_qubits))
+        self._backend = backend
+
+    def _get_frequencies(
+        self,
+        element: FrequencyElement,
+        group: str = "default",
+        cutoff_date: datetime = None,
+    ) -> List[float]:
+        """Internal helper method."""
+
+        if element == FrequencyElement.READOUT:
+            param = self.meas_freq.name
+        elif element == FrequencyElement.QUBIT:
+            param = self.qubit_freq.name
+        else:
+            raise CalibrationError(f"Frequency element {element} is not supported.")
+
+        freqs = []
+        for qubit in self._qubits:
+            if ParameterKey(None, param, (qubit,)) in self._params:
+                freq = self.get_parameter_value(param, (qubit,), None, True, group, cutoff_date)
+            else:
+                if element == FrequencyElement.READOUT:
+                    freq = self._backend.defaults().meas_freq_est[qubit]
+                elif element == FrequencyElement.QUBIT:
+                    freq = self._backend.defaults().qubit_freq_est[qubit]
+                else:
+                    raise CalibrationError(f"Frequency element {element} is not supported.")
+
+            freqs.append(freq)
+
+        return freqs
+
+    def get_qubit_frequencies(
+        self,
+        group: str = "default",
+        cutoff_date: datetime = None,
+    ) -> List[float]:
+        """
+        Get the most recent qubit frequencies. They can be passed to the run-time
+        options of :class:`BaseExperiment`. If no calibrated frequency value of a
+        qubit is found then the default value from the backend defaults is used.
+        Only valid parameter values are returned.
+
+        Args:
+            group: The calibration group from which to draw the
+                parameters. If not specified, this defaults to the 'default' group.
+            cutoff_date: Retrieve the most recent parameter up until the cutoff date. Parameters
+                generated after the cutoff date will be ignored. If the cutoff_date is None then
+                all parameters are considered. This allows users to discard more recent values
+                that may be erroneous.
+
+        Returns:
+            A List of qubit frequencies for all qubits of the backend.
+        """
+        return self._get_frequencies(FrequencyElement.QUBIT, group, cutoff_date)
+
+    def get_meas_frequencies(
+        self,
+        group: str = "default",
+        cutoff_date: datetime = None,
+    ) -> List[float]:
+        """
+        Get the most recent measurement frequencies. They can be passed to the run-time
+        options of :class:`BaseExperiment`. If no calibrated frequency value of a
+        measurement is found then the default value from the backend defaults is used.
+        Only valid parameter values are returned.
+
+        Args:
+            group: The calibration group from which to draw the
+                parameters. If not specified, this defaults to the 'default' group.
+            cutoff_date: Retrieve the most recent parameter up until the cutoff date. Parameters
+                generated after the cutoff date will be ignored. If the cutoff_date is None then
+                all parameters are considered. This allows users to discard more recent values
+                that may be erroneous.
+
+        Returns:
+            A List of measurement frequencies for all qubits of the backend.
+        """
+        return self._get_frequencies(FrequencyElement.READOUT, group, cutoff_date)
+
+    def export_backend(self) -> Backend:
+        """
+        Exports the calibrations to a backend object that can be used.
+
+        Returns:
+            calibrated backend: A backend with the calibrations in it.
+        """
+        backend = copy.deepcopy(self._backend)
+
+        backend.defaults().qubit_freq_est = self.get_qubit_frequencies()
+        backend.defaults().meas_freq_est = self.get_meas_frequencies()
+
+        # TODO: build the instruction schedule map using the stored calibrations
+
+        return backend