qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/result/distributions/quasi.py

@@ -0,0 +1,154 @@
+# 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.
+"""Quasidistribution class"""
+
+from math import sqrt
+import re
+
+from .probability import ProbDistribution
+
+
+# NOTE: A dict subclass should not overload any dunder methods like __getitem__
+# this can cause unexpected behavior and issues as the cPython dict
+# implementation has many standard methods in C for performance and the dunder
+# methods are not always used as expected. For example, update() doesn't call
+# __setitem__ so overloading __setitem__ would not always provide the expected
+# result
+class QuasiDistribution(dict):
+    """A dict-like class for representing quasi-probabilities."""
+
+    _bitstring_regex = re.compile(r"^[01]+$")
+    __ndigits__ = 15
+
+    def __init__(self, data, shots=None, stddev_upper_bound=None):
+        """Builds a quasiprobability distribution object.
+
+        .. note::
+
+            The quasiprobability values might include floating-point errors.
+            ``QuasiDistribution.__repr__`` rounds using :meth:`numpy.round`
+            and the parameter ``ndigits`` can be manipulated with the
+            class attribute ``__ndigits__``. The default is ``15``.
+
+        Parameters:
+            data (dict): Input quasiprobability data. Where the keys
+                represent a measured classical value and the value is a
+                float for the quasiprobability of that result.
+                The keys can be one of several formats:
+
+                    * A hexadecimal string of the form ``"0x4a"``
+                    * A bit string e.g. ``'0b1011'`` or ``"01011"``
+                    * An integer
+
+            shots (int): Number of shots the distribution was derived from.
+            stddev_upper_bound (float): An upper bound for the standard deviation
+
+        Raises:
+            TypeError: If the input keys are not a string or int
+            ValueError: If the string format of the keys is incorrect
+        """
+        self.shots = shots
+        self._stddev_upper_bound = stddev_upper_bound
+        self._num_bits = 0
+        if data:
+            first_key = next(iter(data.keys()))
+            if isinstance(first_key, int):
+                # `self._num_bits` is not always the exact number of qubits measured,
+                # but the number of bits to represent the largest key.
+                self._num_bits = len(bin(max(data.keys()))) - 2
+            elif isinstance(first_key, str):
+                if first_key.startswith("0x") or first_key.startswith("0b"):
+                    data = {int(key, 0): value for key, value in data.items()}
+                    # `self._num_bits` is not always the exact number of qubits measured,
+                    # but the number of bits to represent the largest key.
+                    self._num_bits = len(bin(max(data.keys()))) - 2
+                elif self._bitstring_regex.search(first_key):
+                    # `self._num_bits` is the exact number of qubits measured.
+                    self._num_bits = max(len(key) for key in data)
+                    data = {int(key, 2): value for key, value in data.items()}
+                else:
+                    raise ValueError(
+                        "The input keys are not a valid string format, must either "
+                        "be a hex string prefixed by '0x' or a binary string "
+                        "optionally prefixed with 0b"
+                    )
+            else:
+                raise TypeError("Input data's keys are of invalid type, must be str or int")
+        super().__init__(data)
+
+    def nearest_probability_distribution(self, return_distance=False):
+        """Takes a quasiprobability distribution and maps
+        it to the closest probability distribution as defined by
+        the L2-norm.
+
+        Parameters:
+            return_distance (bool): Return the L2 distance between distributions.
+
+        Returns:
+            ProbDistribution: Nearest probability distribution.
+            float: Euclidean (L2) distance of distributions.
+
+        Notes:
+            Method from Smolin et al., Phys. Rev. Lett. 108, 070502 (2012).
+        """
+        sorted_probs = dict(sorted(self.items(), key=lambda item: item[1]))
+        num_elems = len(sorted_probs)
+        new_probs = {}
+        beta = 0
+        diff = 0
+        for key, val in sorted_probs.items():
+            temp = val + beta / num_elems
+            if temp < 0:
+                beta += val
+                num_elems -= 1
+                diff += val * val
+            else:
+                diff += (beta / num_elems) * (beta / num_elems)
+                new_probs[key] = sorted_probs[key] + beta / num_elems
+        if return_distance:
+            return ProbDistribution(new_probs, self.shots), sqrt(diff)
+        return ProbDistribution(new_probs, self.shots)
+
+    def binary_probabilities(self, num_bits=None):
+        """Build a quasi-probabilities dictionary with binary string keys
+
+        Parameters:
+            num_bits (int): number of bits in the binary bitstrings (leading
+                zeros will be padded). If None, a default value will be used.
+                If keys are given as integers or strings with binary or hex prefix,
+                the default value will be derived from the largest key present.
+                If keys are given as bitstrings without prefix,
+                the default value will be derived from the largest key length.
+
+        Returns:
+            dict: A dictionary where the keys are binary strings in the format
+                ``"0110"``
+        """
+        n = self._num_bits if num_bits is None else num_bits
+        return {format(key, "b").zfill(n): value for key, value in self.items()}
+
+    def hex_probabilities(self):
+        """Build a quasi-probabilities dictionary with hexadecimal string keys
+
+        Returns:
+            dict: A dictionary where the keys are hexadecimal strings in the
+                format ``"0x1a"``
+        """
+        return {hex(key): value for key, value in self.items()}
+
+    @property
+    def stddev_upper_bound(self):
+        """Return an upper bound on standard deviation of expval estimator."""
+        return self._stddev_upper_bound
+
+    def __repr__(self):
+        return str({key: round(value, ndigits=self.__ndigits__) for key, value in self.items()})

qiskit/result/exceptions.py

@@ -0,0 +1,40 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017.
+#
+# 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.
+
+"""
+Exception for errors when there's an error in the Result
+"""
+
+from qiskit.exceptions import QiskitError
+
+
+class ResultError(QiskitError):
+    """Exceptions raised due to errors in result output.
+
+    It may be better for the Qiskit API to raise this exception.
+
+    Args:
+        error (dict): This is the error record as it comes back from
+            the API. The format is like::
+
+                error = {'status': 403,
+                         'message': 'Your credits are not enough.',
+                         'code': 'MAX_CREDITS_EXCEEDED'}
+    """
+
+    def __init__(self, error):
+        super().__init__(error["message"])
+        self.status = error["status"]
+        self.code = error["code"]
+
+    def __str__(self):
+        return f"{self.code}: {self.message}"

qiskit/result/models.py

@@ -0,0 +1,241 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2018.
+#
+# 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.
+
+"""Schema and helper models for schema-conformant Results."""
+
+import copy
+from enum import Enum, IntEnum
+
+from qiskit.exceptions import QiskitError
+
+
+class MeasReturnType(str, Enum):
+    """meas_return allowed values defined by legacy PulseQobjConfig object but still used by Result."""
+
+    AVERAGE = "avg"
+    SINGLE = "single"
+
+
+class MeasLevel(IntEnum):
+    """MeasLevel allowed values defined by legacy PulseQobjConfig object but still used by Result."""
+
+    RAW = 0
+    KERNELED = 1
+    CLASSIFIED = 2
+
+
+class ExperimentResultData:
+    """Class representing experiment result data"""
+
+    def __init__(
+        self, counts=None, snapshots=None, memory=None, statevector=None, unitary=None, **kwargs
+    ):
+        """Initialize an ExperimentalResult Data class
+
+        Args:
+            counts (dict): A dictionary where the keys are the result in
+                hexadecimal as string of the format "0xff" and the value
+                is the number of counts for that result
+            snapshots (dict): A dictionary where the key is the snapshot
+                slot and the value is a dictionary of the snapshots for
+                that slot.
+            memory (list): A list of results per shot if the run had
+                memory enabled
+            statevector (list or numpy.array): A list or numpy array of the
+                statevector result
+            unitary (list or numpy.array): A list or numpy array of the
+                unitary result
+            kwargs (any): additional data key-value pairs.
+        """
+        self._data_attributes = []
+        if counts is not None:
+            self._data_attributes.append("counts")
+            self.counts = counts
+        if snapshots is not None:
+            self._data_attributes.append("snapshots")
+            self.snapshots = snapshots
+        if memory is not None:
+            self._data_attributes.append("memory")
+            self.memory = memory
+        if statevector is not None:
+            self._data_attributes.append("statevector")
+            self.statevector = statevector
+        if unitary is not None:
+            self._data_attributes.append("unitary")
+            self.unitary = unitary
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+            self._data_attributes.append(key)
+
+    def __repr__(self):
+        string_list = []
+        for field in self._data_attributes:
+            string_list.append(f"{field}={getattr(self, field)}")
+        return f"ExperimentResultData({', '.join(string_list)})"
+
+    def to_dict(self):
+        """Return a dictionary format representation of the ExperimentResultData
+
+        Returns:
+            dict: The dictionary form of the ExperimentResultData
+        """
+        out_dict = {}
+        for field in self._data_attributes:
+            out_dict[field] = getattr(self, field)
+        return out_dict
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create a new ExperimentResultData object from a dictionary.
+
+        Args:
+            data (dict): A dictionary representing the ExperimentResultData to
+                         create. It will be in the same format as output by
+                         :meth:`to_dict`
+        Returns:
+            ExperimentResultData: The ``ExperimentResultData`` object from the
+                                  input dictionary.
+        """
+        in_data = copy.copy(data)
+        return cls(**in_data)
+
+
+class ExperimentResult:
+    """Class representing an Experiment Result.
+
+    Attributes:
+        shots (int or tuple): the starting and ending shot for this data.
+        success (bool): if true, we can trust results for this experiment.
+        data (ExperimentResultData): results information.
+        meas_level (int): Measurement result level.
+    """
+
+    _metadata = {}
+
+    def __init__(
+        self,
+        shots,
+        success,
+        data,
+        meas_level=MeasLevel.CLASSIFIED,
+        status=None,
+        seed=None,
+        meas_return=None,
+        header=None,
+        **kwargs,
+    ):
+        """Initialize an ExperimentResult object.
+
+        Args:
+            shots(int or tuple): if an integer the number of shots or if a
+                tuple the starting and ending shot for this data
+            success (bool): True if the experiment was successful
+            data (ExperimentResultData): The data for the experiment's
+                result
+            meas_level (int): Measurement result level
+            status (str): The status of the experiment
+            seed (int): The seed used for simulation (if run on a simulator)
+            meas_return (str): The type of measurement returned
+            header (dict): A free form dictionary header for the experiment
+            kwargs: Arbitrary extra fields
+
+        Raises:
+            QiskitError: If meas_return or meas_level are not valid values
+        """
+        self._metadata = {}
+        self.shots = shots
+        self.success = success
+        self.data = data
+        self.meas_level = meas_level
+        if header is not None:
+            self.header = header
+        if status is not None:
+            self.status = status
+        if seed is not None:
+            self.seed = seed
+        if meas_return is not None:
+            if meas_return not in list(MeasReturnType):
+                raise QiskitError("%s not a valid meas_return value")
+            self.meas_return = meas_return
+        self._metadata.update(kwargs)
+
+    def __repr__(self):
+        out = (
+            f"ExperimentResult(shots={self.shots}, success={self.success},"
+            f" meas_level={self.meas_level}, data={self.data}"
+        )
+        if hasattr(self, "header"):
+            out += f", header={self.header}"
+        if hasattr(self, "status"):
+            out += f", status={self.status}"
+        if hasattr(self, "seed"):
+            out += f", seed={self.seed}"
+        if hasattr(self, "meas_return"):
+            out += f", meas_return={self.meas_return}"
+        for key, value in self._metadata.items():
+            if isinstance(value, str):
+                value_str = f"'{value}'"
+            else:
+                value_str = repr(value)
+            out += f", {key}={value_str}"
+        out += ")"
+        return out
+
+    def __getattr__(self, name):
+        try:
+            return self._metadata[name]
+        except KeyError as ex:
+            raise AttributeError(f"Attribute {name} is not defined") from ex
+
+    def to_dict(self):
+        """Return a dictionary format representation of the ExperimentResult
+
+        Returns:
+            dict: The dictionary form of the ExperimentResult
+        """
+        out_dict = {
+            "shots": self.shots,
+            "success": self.success,
+            "data": self.data.to_dict(),
+            "meas_level": self.meas_level,
+        }
+        if hasattr(self, "header"):
+            out_dict["header"] = self.header
+        if hasattr(self, "status"):
+            out_dict["status"] = self.status
+        if hasattr(self, "seed"):
+            out_dict["seed"] = self.seed
+        if hasattr(self, "meas_return"):
+            out_dict["meas_return"] = self.meas_return
+        out_dict.update(self._metadata)
+        return out_dict
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create a new ExperimentResult object from a dictionary.
+
+        Args:
+            data (dict): A dictionary representing the ExperimentResult to
+                         create. It will be in the same format as output by
+                         :meth:`to_dict`
+
+        Returns:
+            ExperimentResult: The ``ExperimentResult`` object from the input
+                              dictionary.
+        """
+
+        in_data = copy.copy(data)
+        data_obj = ExperimentResultData.from_dict(in_data.pop("data"))
+        shots = in_data.pop("shots")
+        success = in_data.pop("success")
+
+        return cls(shots, success, data_obj, **in_data)

qiskit/result/postprocess.py

@@ -0,0 +1,239 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2018.
+#
+# 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.
+
+"""Post-processing of raw result."""
+
+import numpy as np
+
+from qiskit.exceptions import QiskitError
+
+
+def _hex_to_bin(hexstring):
+    """Convert hexadecimal readouts (memory) to binary readouts."""
+    return str(bin(int(hexstring, 16)))[2:]
+
+
+def _bin_to_hex(bitstring):
+    """Convert bitstring readouts (memory) to hexadecimal readouts."""
+    return hex(int(bitstring, 2))
+
+
+def _pad_zeros(bitstring, memory_slots):
+    """If the bitstring is truncated, pad extra zeros to make its
+    length equal to memory_slots"""
+    return format(int(bitstring, 2), f"0{memory_slots}b")
+
+
+def _separate_bitstring(bitstring, creg_sizes):
+    """Separate a bitstring according to the registers defined in the result header."""
+    substrings = []
+    running_index = 0
+    for _, size in reversed(creg_sizes):
+        substrings.append(bitstring[running_index : running_index + size])
+        running_index += size
+    return " ".join(substrings)
+
+
+def format_counts_memory(shot_memory, header=None):
+    """
+    Format a single bitstring (memory) from a single shot experiment.
+
+    - The hexadecimals are expanded to bitstrings
+
+    - Spaces are inserted at register divisions.
+
+    Args:
+        shot_memory (str): result of a single experiment.
+        header (dict): the experiment header dictionary containing
+            useful information for postprocessing. creg_sizes
+            are a nested list where the inner element is a list
+            of creg name, creg size pairs. memory_slots is an integers
+            specifying the number of total memory_slots in the experiment.
+
+    Returns:
+        dict: a formatted memory
+    """
+    if shot_memory.startswith("0x"):
+        shot_memory = _hex_to_bin(shot_memory)
+    if header:
+        creg_sizes = header.get("creg_sizes", None)
+        memory_slots = header.get("memory_slots", None)
+        if memory_slots:
+            shot_memory = _pad_zeros(shot_memory, memory_slots)
+        if creg_sizes and memory_slots:
+            shot_memory = _separate_bitstring(shot_memory, creg_sizes)
+    return shot_memory
+
+
+def _list_to_complex_array(complex_list):
+    """Convert nested list of shape (..., 2) to complex numpy array with shape (...)
+
+    Args:
+        complex_list (list): List to convert.
+
+    Returns:
+        np.ndarray: Complex numpy array
+
+    Raises:
+        QiskitError: If inner most array of input nested list is not of length 2.
+    """
+    arr = np.asarray(complex_list, dtype=np.complex128)
+    if not arr.shape[-1] == 2:
+        raise QiskitError("Inner most nested list is not of length 2.")
+
+    return arr[..., 0] + 1j * arr[..., 1]
+
+
+def format_level_0_memory(memory):
+    """Format an experiment result memory object for measurement level 0.
+
+    Args:
+        memory (list): Memory from experiment with `meas_level==1`. `avg` or
+            `single` will be inferred from shape of result memory.
+
+    Returns:
+        np.ndarray: Measurement level 0 complex numpy array
+
+    Raises:
+        QiskitError: If the returned numpy array does not have 2 (avg) or 3 (single)
+            indices.
+    """
+    formatted_memory = _list_to_complex_array(memory)
+    # infer meas_return from shape of returned data.
+    if not 2 <= len(formatted_memory.shape) <= 3:
+        raise QiskitError("Level zero memory is not of correct shape.")
+    return formatted_memory
+
+
+def format_level_1_memory(memory):
+    """Format an experiment result memory object for measurement level 1.
+
+    Args:
+        memory (list): Memory from experiment with `meas_level==1`. `avg` or
+            `single` will be inferred from shape of result memory.
+
+    Returns:
+        np.ndarray: Measurement level 1 complex numpy array
+
+    Raises:
+        QiskitError: If the returned numpy array does not have 1 (avg) or 2 (single)
+            indices.
+    """
+    formatted_memory = _list_to_complex_array(memory)
+    # infer meas_return from shape of returned data.
+    if not 1 <= len(formatted_memory.shape) <= 2:
+        raise QiskitError("Level one memory is not of correct shape.")
+    return formatted_memory
+
+
+def format_level_2_memory(memory, header=None):
+    """Format an experiment result memory object for measurement level 2.
+
+    Args:
+        memory (list): Memory from experiment with `meas_level==2` and `memory==True`.
+        header (dict): the experiment header dictionary containing
+            useful information for postprocessing.
+
+    Returns:
+        list[str]: List of bitstrings
+    """
+    memory_list = []
+    for shot_memory in memory:
+        memory_list.append(format_counts_memory(shot_memory, header))
+    return memory_list
+
+
+def format_counts(counts, header=None):
+    """Format a single experiment result coming from backend to present
+    to the Qiskit user.
+
+    Args:
+        counts (dict): counts histogram of multiple shots
+        header (dict): the experiment header dictionary containing
+            useful information for postprocessing.
+
+    Returns:
+        dict: a formatted counts
+    """
+    counts_dict = {}
+    for key, val in counts.items():
+        key = format_counts_memory(key, header)
+        counts_dict[key] = val
+    return counts_dict
+
+
+def format_statevector(vec, decimals=None):
+    """Format statevector coming from the backend to present to the Qiskit user.
+
+    Args:
+        vec (list): a list of [re, im] complex numbers.
+        decimals (int): the number of decimals in the statevector.
+            If None, no rounding is done.
+
+    Returns:
+        list[complex]: a list of python complex numbers.
+    """
+    # pylint: disable=cyclic-import
+    from qiskit.quantum_info.states.statevector import Statevector
+
+    if isinstance(vec, Statevector):
+        if decimals:
+            return Statevector(np.around(vec.data, decimals=decimals), dims=vec.dims())
+        return vec
+    if isinstance(vec, np.ndarray):
+        if decimals:
+            return np.around(vec, decimals=decimals)
+        return vec
+    num_basis = len(vec)
+    if vec and isinstance(vec[0], complex):
+        vec_complex = np.array(vec, dtype=complex)
+    else:
+        vec_complex = np.zeros(num_basis, dtype=complex)
+        for i in range(num_basis):
+            vec_complex[i] = vec[i][0] + 1j * vec[i][1]
+
+    if decimals:
+        vec_complex = np.around(vec_complex, decimals=decimals)
+    return vec_complex
+
+
+def format_unitary(mat, decimals=None):
+    """Format unitary coming from the backend to present to the Qiskit user.
+
+    Args:
+        mat (list[list]): a list of list of [re, im] complex numbers
+        decimals (int): the number of decimals in the statevector.
+            If None, no rounding is done.
+
+    Returns:
+        list[list[complex]]: a matrix of complex numbers
+    """
+    # pylint: disable=cyclic-import
+    from qiskit.quantum_info.operators.operator import Operator
+
+    if isinstance(mat, Operator):
+        if decimals:
+            return Operator(
+                np.around(mat.data, decimals=decimals),
+                input_dims=mat.input_dims(),
+                output_dims=mat.output_dims(),
+            )
+        return mat
+    if isinstance(mat, np.ndarray):
+        if decimals:
+            return np.around(mat, decimals=decimals)
+        return mat
+    num_basis = len(mat)
+    mat_complex = np.zeros((num_basis, num_basis), dtype=complex)
+    for i, vec in enumerate(mat):
+        mat_complex[i] = format_statevector(vec, decimals)
+    return mat_complex