Data processing

qiskit_experiments/data_processing/__init__.py

@@ -0,0 +1,22 @@
+# 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.
+
+"""Qiskit experiments calibration data processing roots."""
+
+from .base import DataAction
+from .nodes import (
+    Population,
+    ToImag,
+    ToReal,
+)
+
+from .data_processor import DataProcessor

qiskit_experiments/data_processing/base.py

@@ -0,0 +1,99 @@
+# 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.
+
+"""Defines the steps that can be used to analyse data."""
+
+from abc import ABCMeta, abstractmethod
+from typing import Any, Dict, List
+
+from qiskit_experiments.data_processing.exceptions import DataProcessorError
+
+
+class DataAction(metaclass=ABCMeta):
+    """
+    Abstract action which is a single action done on measured data to process it.
+    Each subclass of DataAction must define the type of data that it accepts as input
+    using decorators.
+    """
+
+    # Key under which the node will output the data.
+    __node_output__ = None
+
+    def __init__(self):
+        """Create new data analysis routine."""
+        self._child = None
+        self._accepted_inputs = []
+
+    @property
+    def node_inputs(self) -> List[str]:
+        """Returns a list of input data that the node can process."""
+        return self._accepted_inputs
+
+    def add_accepted_input(self, data_key: str):
+        """
+        Allows users to add an accepted input data format to this DataAction.
+
+        Args:
+            data_key: The key that the data action will require in the input data dict.
+        """
+        self._accepted_inputs.append(data_key)
+
+    @abstractmethod
+    def process(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Applies the data processing step to the data.
+
+        Args:
+            data: the data to which the data processing step will be applied.
+
+        Returns:
+            processed data: The data that has been processed.
+        """
+
+    def check_required(self, data: Dict[str, Any]):
+        """Checks that the given data contains the right key.
+
+        Args:
+            data: The data to check for the correct keys.
+
+        Raises:
+            DataProcessorError: if the key is not found.
+        """
+        for key in data.keys():
+            if key in self.node_inputs:
+                return
+
+        raise DataProcessorError(f"None of {self.node_inputs} are in the given data.")
+
+    def format_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Apply the data action of this node and call the child node's format_data method.
+
+        Args:
+            data: A dict containing the data. The action nodes in the data
+                processor will raise errors if the data does not contain the
+                appropriate data.
+
+        Returns:
+            processed data: The output data of the node contained in a dict.
+        """
+        self.check_required(data)
+        processed_data = self.process(data)
+        processed_data["metadata"] = data.get("metadata", {})
+        return processed_data
+
+    def __repr__(self):
+        """String representation of the node."""
+        return (
+            f"{self.__class__.__name__}(inputs: {self.node_inputs}, "
+            f"outputs: {self.__node_output__})"
+        )

qiskit_experiments/data_processing/data_processor.py

@@ -0,0 +1,105 @@
+# 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.
+
+"""Class that ties together actions on the data."""
+
+from typing import Any, Dict, List, Tuple, Union
+
+from qiskit_experiments.data_processing.base import DataAction
+from qiskit_experiments.data_processing.exceptions import DataProcessorError
+
+
+class DataProcessor:
+    """
+    Defines the actions done on the measured data to bring it in a form usable
+    by the calibration analysis classes.
+    """
+
+    def __init__(self, data_actions: List[DataAction] = None):
+        """Create a chain of data processing actions.
+
+        Args:
+            data_actions: A list of data processing actions to construct this data processor with.
+                If None is given an empty DataProcessor will be created.
+        """
+        self._nodes = []
+
+        if data_actions:
+            for node in data_actions:
+                self.append(node)
+
+        self._history = []
+
+    @property
+    def history(self) -> List[Tuple[str, Dict[str, Any]]]:
+        """
+        Returns:
+            The history of the data processor. The ith tuple in the history corresponds to the
+            output of the ith node. Each tuple corresponds to (node name, data dict).
+        """
+        return self._history
+
+    def append(self, node: DataAction):
+        """
+        Append new data action node to this data processor.
+
+        Args:
+            node: A DataAction that will process the data.
+
+        Raises:
+            DataProcessorError: if the output of the last node does not match the input required
+                by the node to be appended.
+        """
+        if len(self._nodes) == 0:
+            self._nodes.append(node)
+        else:
+            if self._nodes[-1].__node_output__ not in node.node_inputs:
+                raise DataProcessorError(
+                    f"Output of node {self._nodes[-1]} is not an acceptable " f"input to {node}."
+                )
+
+            self._nodes.append(node)
+
+    def output_key(self) -> Union[str, None]:
+        """Return the key to look for in the data output by the processor."""
+
+        if len(self._nodes) > 0:
+            return self._nodes[-1].__node_output__
+
+        return None
+
+    def format_data(self, data: Dict[str, Any], save_history: bool = False) -> Dict[str, Any]:
+        """
+        Format the given data.
+
+        This method sequentially calls stored child data processing nodes
+        with its `format_data` methods. Once all child nodes have called,
+        input data is converted into expected data format.
+
+        Args:
+            data: The data, typically from an ExperimentData instance, that needs to
+                be processed. This dict also contains the metadata of each experiment.
+            save_history: If set to true the history is saved under the history property.
+                If set to False the history will be empty.
+
+        Returns:
+            processed data: The data processed by the data processor..
+        """
+        self._history = []
+
+        for node in self._nodes:
+            data = node.format_data(data)
+
+            if save_history:
+                self._history.append((node.__class__.__name__, dict(data)))
+
+        return data

qiskit_experiments/data_processing/exceptions.py

@@ -0,0 +1,28 @@
+# 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.
+
+"""Exceptions for data processing."""
+
+from qiskit.exceptions import QiskitError
+
+
+class DataProcessorError(QiskitError):
+    """Errors raised by the calibration module."""
+
+    def __init__(self, *message):
+        """Set the error message."""
+        super().__init__(*message)
+        self.message = " ".join(message)
+
+    def __str__(self):
+        """Return the message."""
+        return repr(self.message)

qiskit_experiments/data_processing/nodes.py

@@ -0,0 +1,141 @@
+# 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.
+
+"""Different data analysis steps."""
+
+from abc import abstractmethod
+from typing import Any, Dict, Optional, Tuple
+import numpy as np
+
+from qiskit_experiments.data_processing.base import DataAction
+
+
+class IQPart(DataAction):
+    """Abstract class for IQ data post-processing."""
+
+    def __init__(self, scale: Optional[float] = 1.0, average: bool = False):
+        """
+        Args:
+            scale: scale by which to multiply the real part of the data.
+            average: if True the single-shots are averaged.
+        """
+        self.scale = scale
+        self.average = average
+        super().__init__()
+        self._accepted_inputs = ["memory"]
+
+    @abstractmethod
+    def _process(self, point: Tuple[float, float]) -> float:
+        """Defines how the IQ point will be processed.
+
+        Args:
+            point: An IQ point as a tuple of two float, i.e. (real, imaginary).
+
+        Returns:
+            Processed IQ point.
+        """
+
+    def process(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Modifies the data inplace by taking the real part of the memory and
+        scaling it by the given factor.
+
+        Args:
+            data: The data dict. IQ data is stored under memory.
+
+        Returns:
+            processed data: A dict with the data.
+        """
+
+        # Single shot data
+        if isinstance(data["memory"][0][0], list):
+            new_mem = []
+            for shot in data["memory"]:
+                new_mem.append([self.scale * self._process(iq_point) for iq_point in shot])
+
+            if self.average:
+                new_mem = list(np.mean(np.array(new_mem), axis=0))
+
+        # Averaged data
+        else:
+            new_mem = [self.scale * self._process(iq_point) for iq_point in data["memory"]]
+
+        return {self.__node_output__: new_mem}
+
+
+class ToReal(IQPart):
+    """IQ data post-processing. Isolate the real part of the IQ data."""
+
+    __node_output__ = "memory_real"
+
+    def _process(self, point: Tuple[float, float]) -> float:
+        """Defines how the IQ point will be processed.
+
+        Args:
+            point: An IQ point as a tuple of two float, i.e. (real, imaginary).
+
+        Returns:
+            The real part of the IQ point.
+        """
+        return point[0]
+
+
+class ToImag(IQPart):
+    """IQ data post-processing. Isolate the imaginary part of the IQ data."""
+
+    __node_output__ = "memory_imag"
+
+    def _process(self, point: Tuple[float, float]) -> float:
+        """Defines how the IQ point will be processed.
+
+        Args:
+            point: An IQ point as a tuple of two float, i.e. (real, imaginary).
+
+        Returns:
+            The imaginary part of the IQ point.
+        """
+        return point[1]
+
+
+class Population(DataAction):
+    """Count data post processing. This returns population."""
+
+    __node_output__ = "populations"
+
+    def __init__(self):
+        """Initialize a counts to population data conversion."""
+        super().__init__()
+        self._accepted_inputs = ["counts"]
+
+    def process(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Args:
+            data: The data dictionary. This will modify the dict in place,
+                taking the data under counts and adding the corresponding
+                populations.
+
+        Returns:
+            processed data: A dict with the populations.
+        """
+
+        counts = data.get("counts")
+
+        populations = np.zeros(len(list(counts.keys())[0]))
+
+        shots = 0
+        for bit_str, count in counts.items():
+            shots += count
+            for ind, bit in enumerate(bit_str):
+                if bit == "1":
+                    populations[ind] += count
+
+        return {self.__node_output__: populations / shots}