qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/quantum_info/states/utils.py

@@ -0,0 +1,247 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2020.
+#
+# 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.
+
+"""
+Quantum information utility functions for states.
+"""
+
+from __future__ import annotations
+import math
+
+import numpy as np
+
+from qiskit.exceptions import QiskitError
+from qiskit.quantum_info.states.statevector import Statevector
+from qiskit.quantum_info.states.densitymatrix import DensityMatrix
+from qiskit.quantum_info.operators.channel import SuperOp
+from qiskit.quantum_info.operators.predicates import ATOL_DEFAULT
+
+
+def partial_trace(state: Statevector | DensityMatrix, qargs: list) -> DensityMatrix:
+    """Return reduced density matrix by tracing out part of quantum state.
+
+    If all subsystems are traced over this returns the
+    :meth:`~qiskit.quantum_info.DensityMatrix.trace` of the
+    input state.
+
+    Args:
+        state (Statevector or DensityMatrix): the input state.
+        qargs (list): The subsystems to trace over.
+
+    Returns:
+        DensityMatrix: The reduced density matrix.
+
+    Raises:
+        QiskitError: if input state is invalid.
+    """
+    state = _format_state(state, validate=False)
+
+    # Compute traced shape
+    traced_shape = state._op_shape.remove(qargs=qargs)
+    # Convert vector shape to matrix shape
+    traced_shape._dims_r = traced_shape._dims_l
+    traced_shape._num_qargs_r = traced_shape._num_qargs_l
+
+    # If we are tracing over all subsystems we return the trace
+    if traced_shape.size == 0:
+        return state.trace()
+
+    # Statevector case
+    if isinstance(state, Statevector):
+        trace_systems = len(state._op_shape.dims_l()) - 1 - np.array(qargs)
+        arr = state._data.reshape(state._op_shape.tensor_shape)
+        rho = np.tensordot(arr, arr.conj(), axes=(trace_systems, trace_systems))
+        rho = np.reshape(rho, traced_shape.shape)
+        return DensityMatrix(rho, dims=traced_shape._dims_l)
+
+    # Density matrix case
+    # Empty partial trace case.
+    if not qargs:
+        return state.copy()
+    # Trace first subsystem to avoid coping whole density matrix
+    dims = state.dims(qargs)
+    tr_op = SuperOp(np.eye(dims[0]).reshape(1, dims[0] ** 2), input_dims=[dims[0]], output_dims=[1])
+    ret = state.evolve(tr_op, [qargs[0]])
+    # Trace over remaining subsystems
+    for qarg, dim in zip(qargs[1:], dims[1:]):
+        tr_op = SuperOp(np.eye(dim).reshape(1, dim**2), input_dims=[dim], output_dims=[1])
+        ret = ret.evolve(tr_op, [qarg])
+    # Remove traced over subsystems which are listed as dimension 1
+    ret._op_shape = traced_shape
+    return ret
+
+
+def shannon_entropy(pvec: list | np.ndarray, base: int = 2) -> float:
+    r"""Compute the Shannon entropy of a probability vector.
+
+    The shannon entropy of a probability vector
+    :math:`\vec{p} = [p_0, ..., p_{n-1}]` is defined as
+
+    .. math::
+
+        H(\vec{p}) = \sum_{i=0}^{n-1} p_i \log_b(p_i)
+
+    where :math:`b` is the log base and (default 2), and
+    :math:`0 \log_b(0) \equiv 0`.
+
+    Args:
+        pvec (array_like): a probability vector.
+        base (int): the base of the logarithm [Default: 2].
+
+    Returns:
+        float: The Shannon entropy H(pvec).
+    """
+    if base == 2:
+
+        def logfn(x):
+            return -x * math.log2(x)
+
+    elif base == np.e:
+
+        def logfn(x):
+            return -x * math.log(x)
+
+    else:
+        log_base = math.log(base)
+
+        def logfn(x):
+            return -x * math.log(x) / log_base
+
+    h_val = 0.0
+    for x in pvec:
+        if 0 < x < 1:
+            h_val += logfn(x)
+    return h_val
+
+
+def schmidt_decomposition(state, qargs):
+    r"""Return the Schmidt Decomposition of a pure quantum state.
+
+    For an arbitrary bipartite state:
+
+    .. math::
+         |\psi\rangle_{AB} = \sum_{i,j} c_{ij}
+                             |x_i\rangle_A \otimes |y_j\rangle_B,
+
+    its Schmidt Decomposition is given by the single-index sum over k:
+
+    .. math::
+        |\psi\rangle_{AB} = \sum_{k} \lambda_{k}
+                            |u_k\rangle_A \otimes |v_k\rangle_B
+
+    where :math:`|u_k\rangle_A` and :math:`|v_k\rangle_B` are an
+    orthonormal set of vectors in their respective spaces :math:`A` and :math:`B`,
+    and the Schmidt coefficients :math:`\lambda_k` are positive real values.
+
+    Args:
+        state (Statevector or DensityMatrix): the input state.
+        qargs (list): the list of Input state positions corresponding to subsystem :math:`B`.
+
+    Returns:
+        list: list of tuples ``(s, u, v)``, where ``s`` (float) are the Schmidt coefficients
+        :math:`\lambda_k`, and ``u`` (Statevector), ``v`` (Statevector) are the Schmidt vectors
+        :math:`|u_k\rangle_A`, :math:`|u_k\rangle_B`, respectively.
+
+    Raises:
+        QiskitError: if Input qargs is not a list of positions of the Input state.
+        QiskitError: if Input qargs is not a proper subset of Input state.
+
+    .. note::
+        In Qiskit, qubits are ordered using little-endian notation, with the least significant
+        qubits having smaller indices. For example, a four-qubit system is represented as
+        :math:`|q_3q_2q_1q_0\rangle`. Using this convention, setting ``qargs=[0]`` will partition the
+        state as :math:`|q_3q_2q_1\rangle_A\otimes|q_0\rangle_B`. Furthermore, qubits will be organized
+        in this notation regardless of the order they are passed. For instance, passing either
+        ``qargs=[1,2]`` or ``qargs=[2,1]`` will result in partitioning the state as
+        :math:`|q_3q_0\rangle_A\otimes|q_2q_1\rangle_B`.
+    """
+    state = _format_state(state, validate=False)
+
+    # convert to statevector if state is density matrix. Errors if state is mixed.
+    if isinstance(state, DensityMatrix):
+        state = state.to_statevector()
+
+    # reshape statevector into state tensor
+    dims = state.dims()
+    state_tens = state._data.reshape(dims[::-1])
+    ndim = state_tens.ndim
+    qudits = list(range(ndim))
+
+    # check if qargs are valid
+    if not isinstance(qargs, (list, np.ndarray)):
+        raise QiskitError("Input qargs is not a list of positions of the Input state")
+    qargs = set(qargs)
+    if qargs == set(qudits) or not qargs.issubset(qudits):
+        raise QiskitError("Input qargs is not a proper subset of Input state")
+
+    # define subsystem A and B qargs and dims
+    qargs_b = list(qargs)
+    qargs_a = [i for i in qudits if i not in qargs_b]
+    dims_b = state.dims(qargs_b)
+    dims_a = state.dims(qargs_a)
+    ndim_b = np.prod(dims_b)
+    ndim_a = np.prod(dims_a)
+
+    # permute state for desired qargs order
+    qargs_axes = [qudits[::-1].index(i) for i in qargs_b + qargs_a][::-1]
+    state_tens = state_tens.transpose(qargs_axes)
+
+    # convert state tensor to matrix of prob amplitudes and perform svd.
+    state_mat = state_tens.reshape([ndim_a, ndim_b])
+    u_mat, s_arr, vh_mat = np.linalg.svd(state_mat, full_matrices=False)
+
+    schmidt_components = [
+        (s, Statevector(u, dims=dims_a), Statevector(v, dims=dims_b))
+        for s, u, v in zip(s_arr, u_mat.T, vh_mat)
+        if s > ATOL_DEFAULT
+    ]
+
+    return schmidt_components
+
+
+def _format_state(state, validate=True):
+    """Format input state into class object"""
+    if isinstance(state, list):
+        state = np.array(state, dtype=complex)
+    if isinstance(state, np.ndarray):
+        ndim = state.ndim
+        if ndim == 1:
+            state = Statevector(state)
+        elif ndim == 2:
+            dim1, dim2 = state.shape
+            if dim2 == 1:
+                state = Statevector(state)
+            elif dim1 == dim2:
+                state = DensityMatrix(state)
+    if not isinstance(state, (Statevector, DensityMatrix)):
+        raise QiskitError("Input is not a quantum state")
+    if validate and not state.is_valid():
+        raise QiskitError("Input quantum state is not a valid")
+    return state
+
+
+def _funm_svd(matrix, func):
+    """Apply real scalar function to singular values of a matrix.
+
+    Args:
+        matrix (array_like): (N, N) Matrix at which to evaluate the function.
+        func (callable): Callable object that evaluates a scalar function f.
+
+    Returns:
+        ndarray: funm (N, N) Value of the matrix function specified by func
+                 evaluated at `A`.
+    """
+    import scipy.linalg as la
+
+    unitary1, singular_values, unitary2 = la.svd(matrix)
+    diag_func_singular = np.diag(func(singular_values))
+    return unitary1.dot(diag_func_singular).dot(unitary2)

qiskit/result/__init__.py

@@ -0,0 +1,61 @@
+# 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.
+
+"""
+=========================================
+Experiment Results (:mod:`qiskit.result`)
+=========================================
+
+.. currentmodule:: qiskit.result
+
+Core classes
+============
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   Result
+   ResultError
+   Counts
+
+Marginalization
+===============
+
+.. autofunction:: marginal_counts
+.. autofunction:: marginal_distribution
+.. autofunction:: marginal_memory
+
+Distributions
+=============
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   ProbDistribution
+   QuasiDistribution
+
+Expectation values
+==================
+
+.. autofunction:: sampled_expectation_value
+
+"""
+
+from .counts import Counts
+from .distributions import QuasiDistribution, ProbDistribution
+from .exceptions import ResultError
+from .models import MeasLevel, MeasReturnType
+from .result import Result
+from .sampled_expval import sampled_expectation_value
+from .utils import marginal_counts
+from .utils import marginal_distribution
+from .utils import marginal_memory

qiskit/result/counts.py

@@ -0,0 +1,189 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# 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.
+
+"""A container class for counts from a circuit execution."""
+
+import re
+
+from qiskit.result import postprocess
+from qiskit import exceptions
+
+
+# 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 Counts(dict):
+    """A class to store a counts result from a circuit execution."""
+
+    bitstring_regex = re.compile(r"^[01\s]+$")
+
+    def __init__(self, data, time_taken=None, creg_sizes=None, memory_slots=None):
+        """Build a counts object
+
+        Args:
+            data (dict): The dictionary input for the counts. Where the keys
+                represent a measured classical value and the value is an
+                integer the number of shots with that result.
+                The keys can be one of several formats:
+
+                     * A hexadecimal string of the form ``'0x4a'``
+                     * A bit string prefixed with ``0b`` for example ``'0b1011'``
+                     * A bit string formatted across register and memory slots.
+                       For example, ``'00 10'``.
+                     * A dit string, for example ``'02'``. Note for objects created
+                       with dit strings the ``creg_sizes`` and ``memory_slots``
+                       kwargs don't work and :meth:`hex_outcomes` and
+                       :meth:`int_outcomes` also do not work.
+
+            time_taken (float): The duration of the experiment that generated
+                the counts in seconds.
+            creg_sizes (list): a nested list where the inner element is a list
+                of tuples containing both the classical register name and
+                classical register size. For example,
+                ``[('c_reg', 2), ('my_creg', 4)]``.
+            memory_slots (int): The number of total ``memory_slots`` in the
+                experiment.
+        Raises:
+            TypeError: If the input key type is not an ``int`` or ``str``.
+            QiskitError: If a dit string key is input with ``creg_sizes`` and/or
+                ``memory_slots``.
+        """
+        bin_data = None
+        data = dict(data)
+        if not data:
+            self.int_raw = {}
+            self.hex_raw = {}
+            bin_data = {}
+        else:
+            first_key = next(iter(data.keys()))
+            if isinstance(first_key, int):
+                self.int_raw = data
+                self.hex_raw = {hex(key): value for key, value in self.int_raw.items()}
+            elif isinstance(first_key, str):
+                if first_key.startswith("0x"):
+                    self.hex_raw = data
+                    self.int_raw = {int(key, 0): value for key, value in self.hex_raw.items()}
+                elif first_key.startswith("0b"):
+                    self.int_raw = {int(key, 0): value for key, value in data.items()}
+                    self.hex_raw = {hex(key): value for key, value in self.int_raw.items()}
+                else:
+                    if not creg_sizes and not memory_slots:
+                        self.hex_raw = None
+                        self.int_raw = None
+                        bin_data = data
+                    else:
+                        hex_dict = {}
+                        int_dict = {}
+                        for bitstring, value in data.items():
+                            if not self.bitstring_regex.search(bitstring):
+                                raise exceptions.QiskitError(
+                                    "Counts objects with dit strings do not "
+                                    "currently support dit string formatting parameters "
+                                    "creg_sizes or memory_slots"
+                                )
+                            int_key = self._remove_space_underscore(bitstring)
+                            int_dict[int_key] = value
+                            hex_dict[hex(int_key)] = value
+                        self.hex_raw = hex_dict
+                        self.int_raw = int_dict
+            else:
+                raise TypeError(
+                    "Invalid input key type %s, must be either an int "
+                    "key or string key with hexadecimal value or bit string"
+                )
+        header = {}
+        self.creg_sizes = creg_sizes
+        if self.creg_sizes:
+            header["creg_sizes"] = self.creg_sizes
+        self.memory_slots = memory_slots
+        if self.memory_slots:
+            header["memory_slots"] = self.memory_slots
+        if not bin_data:
+            bin_data = postprocess.format_counts(self.hex_raw, header=header)
+        super().__init__(bin_data)
+        self.time_taken = time_taken
+
+    def most_frequent(self):
+        """Return the most frequent count
+
+        Returns:
+            str: The bit string for the most frequent result
+        Raises:
+            QiskitError: when there is >1 count with the same max counts, or
+                an empty object.
+        """
+        if not self:
+            raise exceptions.QiskitError("Can not return a most frequent count on an empty object")
+        max_value = max(self.values())
+        max_values_counts = [x[0] for x in self.items() if x[1] == max_value]
+        if len(max_values_counts) != 1:
+            raise exceptions.QiskitError(
+                f"Multiple values have the same maximum counts: {','.join(max_values_counts)}"
+            )
+        return max_values_counts[0]
+
+    def hex_outcomes(self):
+        """Return a counts dictionary with hexadecimal string keys
+
+        Returns:
+            dict: A dictionary with the keys as hexadecimal strings instead of
+                bitstrings
+        Raises:
+            QiskitError: If the Counts object contains counts for dit strings
+        """
+        if self.hex_raw:
+            return {key.lower(): value for key, value in self.hex_raw.items()}
+        else:
+            out_dict = {}
+            for bitstring, value in self.items():
+                if not self.bitstring_regex.search(bitstring):
+                    raise exceptions.QiskitError(
+                        "Counts objects with dit strings do not "
+                        "currently support conversion to hexadecimal"
+                    )
+                int_key = self._remove_space_underscore(bitstring)
+                out_dict[hex(int_key)] = value
+            return out_dict
+
+    def int_outcomes(self):
+        """Build a counts dictionary with integer keys instead of count strings
+
+        Returns:
+            dict: A dictionary with the keys as integers instead of bitstrings
+        Raises:
+            QiskitError: If the Counts object contains counts for dit strings
+        """
+        if self.int_raw:
+            return self.int_raw
+        else:
+            out_dict = {}
+            for bitstring, value in self.items():
+                if not self.bitstring_regex.search(bitstring):
+                    raise exceptions.QiskitError(
+                        "Counts objects with dit strings do not "
+                        "currently support conversion to integer"
+                    )
+                int_key = self._remove_space_underscore(bitstring)
+                out_dict[int_key] = value
+            return out_dict
+
+    @staticmethod
+    def _remove_space_underscore(bitstring):
+        """Removes all spaces and underscores from bitstring"""
+        return int(bitstring.replace(" ", "").replace("_", ""), 2)
+
+    def shots(self):
+        """Return the number of shots"""
+        return sum(self.values())

qiskit/result/distributions/__init__.py

@@ -0,0 +1,17 @@
+# 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.
+
+"""
+Distributions
+"""
+from .probability import ProbDistribution
+from .quasi import QuasiDistribution

qiskit/result/distributions/probability.py

@@ -0,0 +1,100 @@
+# 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 for probability distributions."""
+
+import re
+
+
+# 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 ProbDistribution(dict):
+    """A generic dict-like class for probability distributions."""
+
+    _bitstring_regex = re.compile(r"^[01]+$")
+
+    def __init__(self, data, shots=None):
+        """Builds a probability distribution object.
+
+        Args:
+            data (dict): Input probability data. Where the keys
+                represent a measured classical value and the value is a
+                float for the probability 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.
+
+        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._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 binary_probabilities(self, num_bits=None):
+        """Build a 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 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()}