Data processing

qiskit_experiments/data_processing/__init__.py

@@ -0,0 +1,26 @@
+# 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 (
+    # data acquisition node
+    Discriminator,
+    Kernel,
+    # value formatter node
+    Population,
+    ToImag,
+    ToReal,
+)
+
+from .data_processor import DataProcessor

qiskit_experiments/data_processing/base.py

@@ -0,0 +1,170 @@
+# 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 enum import Enum
+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.
+    """
+
+    node_type = None
+    prev_node = ()
+
+    def __init__(self):
+        """Create new data analysis routine."""
+        self._child = None
+
+    @property
+    def child(self) -> "DataAction":
+        """Return the child of this data processing step."""
+        return self._child
+
+    def append(self, component: "DataAction"):
+        """Add new data processing routine.
+
+        Args:
+            component: New data processing routine.
+
+        Raises:
+            DataProcessorError: If the previous node is None (i.e. a root node)
+        """
+        if not component.prev_node:
+            raise DataProcessorError(
+                f"Analysis routine {component.__class__.__name__} is a root"
+                f"node. This routine cannot be appended to another node."
+            )
+
+        if self._child is None:
+            if isinstance(self, component.prev_node):
+                self._child = component
+            else:
+                raise DataProcessorError(
+                    f"Analysis routine {component.__class__.__name__} "
+                    f"cannot be appended after {self.__class__.__name__}"
+                )
+        else:
+            self._child.append(component)
+
+    @property
+    @abstractmethod
+    def node_output(self) -> str:
+        """Returns the key in the data dict where the DataAction added the processed data."""
+
+    @property
+    @abstractmethod
+    def node_inputs(self) -> List[str]:
+        """Returns a list of input data that the node can process."""
+
+    @abstractmethod
+    def process(self, data: Dict[str, Any]):
+        """
+        Applies the data processing step to the data.
+
+        Args:
+            data: the data to which the data processing step will be applied.
+        """
+
+    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]):
+        """
+        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.
+        """
+        self.check_required(data)
+
+        processed_data = self.process(data)
+
+        if self._child:
+            self._child.format_data(processed_data)
+
+
+class NodeType(Enum):
+    """Type of node that can be supported by the analysis steps."""
+
+    KERNEL = 1
+    DISCRIMINATOR = 2
+    IQDATA = 3
+    COUNTS = 4
+    POPULATION = 5
+
+
+def kernel(cls: DataAction):
+    """A decorator to give kernel attribute to node."""
+    cls.node_type = NodeType.KERNEL
+    return cls
+
+
+def discriminator(cls: DataAction):
+    """A decorator to give discriminator attribute to node."""
+    cls.node_type = NodeType.DISCRIMINATOR
+    return cls
+
+
+def iq_data(cls: DataAction):
+    """A decorator to give iqdata attribute to node."""
+    cls.node_type = NodeType.IQDATA
+    return cls
+
+
+def counts(cls: DataAction):
+    """A decorator to give counts attribute to node."""
+    cls.node_type = NodeType.COUNTS
+    return cls
+
+
+def population(cls: DataAction):
+    """A decorator to give population attribute to node."""
+    cls.node_type = NodeType.POPULATION
+    return cls
+
+
+def prev_node(*nodes: DataAction):
+    """A decorator to specify the available previous nodes."""
+
+    try:
+        nodes = list(nodes)
+    except TypeError:
+        nodes = [nodes]
+
+    def add_nodes(cls: DataAction):
+        cls.prev_node = tuple(nodes)
+        return cls
+
+    return add_nodes

qiskit_experiments/data_processing/data_processor.py

@@ -0,0 +1,115 @@
+# 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, Union
+
+from qiskit.qobj.utils import MeasLevel
+from qiskit_experiments.data_processing.nodes import Kernel, Discriminator
+from qiskit_experiments.data_processing.base import NodeType, DataAction
+
+
+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):
+        """Create an empty chain of data ProcessingSteps."""
+        self._root_node = None
+
+    def append(self, node: DataAction):
+        """
+        Append new data action node to this data processor.
+
+        Args:
+            node: A DataAction that will process the data.
+        """
+        if self._root_node:
+            self._root_node.append(node)
+        else:
+            self._root_node = node
+
+    def meas_level(self) -> MeasLevel:
+        """
+        Returns:
+            measurement level: MeasLevel.CLASSIFIED is returned if the end data is discriminated,
+                MeasLevel.KERNELED is returned if a kernel is defined but no discriminator, and
+                MeasLevel.RAW is returned is no kernel is defined.
+        """
+        kernel = DataProcessor.check_kernel(self._root_node)
+        if kernel and isinstance(kernel, Kernel):
+            discriminator = DataProcessor.check_discriminator(self._root_node)
+            if discriminator and isinstance(discriminator, Discriminator):
+
+                # classified level if both system kernel and discriminator are defined
+                return MeasLevel.CLASSIFIED
+
+            # kerneled level if only system kernel is defined
+            return MeasLevel.KERNELED
+
+        # otherwise raw level is requested
+        return MeasLevel.RAW
+
+    def output_key(self) -> str:
+        """Return the key to look for in the data output by the processor."""
+        if self._root_node:
+            node = self._root_node
+            while node.child:
+                node = node.child
+
+            return node.node_output
+
+        return "counts"
+
+    def format_data(self, data: Dict[str, Any]):
+        """
+        Format Qiskit result 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.
+        """
+        if self._root_node:
+            self._root_node.format_data(data)
+
+    @classmethod
+    def check_kernel(cls, node: DataAction) -> Union[None, DataAction]:
+        """Return the stored kernel in the workflow."""
+        if not node:
+            return None
+
+        if node.node_type == NodeType.KERNEL:
+            return node
+        else:
+            if not node.child:
+                return None
+            return cls.check_kernel(node.child)
+
+    @classmethod
+    def check_discriminator(cls, node: DataAction):
+        """Return stored discriminator in the workflow."""
+        if not node:
+            return None
+
+        if node.node_type == NodeType.DISCRIMINATOR:
+            return node
+        else:
+            if not node.child:
+                return None
+            return cls.check_discriminator(node.child)

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)