Add Counts object

qiskit/quantum_info/states/quantum_state.py

@@ -26,6 +26,7 @@
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 from qiskit.quantum_info.operators.operator import Operator
 from qiskit.quantum_info.operators.predicates import ATOL_DEFAULT, RTOL_DEFAULT
+from qiskit.result.counts import Counts
 
 
 class QuantumState(ABC):
@@ -383,7 +384,7 @@ def sample_counts(self, shots, qargs=None):
                                 subsystems (Default: None).
 
         Returns:
-            dict: sampled counts dictionary.
+            Counts: sampled counts dictionary.
 
         Additional Information:
 
@@ -400,7 +401,7 @@ def sample_counts(self, shots, qargs=None):
 
         # Combine all samples into a counts dictionary
         inds, counts = np.unique(samples, return_counts=True)
-        return dict(zip(inds, counts))
+        return Counts(zip(inds, counts))
 
     def measure(self, qargs=None):
         """Measure subsystems and return outcome and post-measure state.

qiskit/result/__init__.py

@@ -24,8 +24,12 @@
 
    Result
    ResultError
+   Counts
+   NoMostFrequentCount
 """
 
 from .result import Result
 from .exceptions import ResultError
 from .utils import marginal_counts
+from .counts import Counts
+from .exceptions import NoMostFrequentCount

qiskit/result/counts.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+
+# 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."""
+
+from qiskit.result import postprocess
+from qiskit.result import exceptions
+
+
+class Counts(dict):
+    """A class to store a counts result from a circuit execution."""
+
+    def __init__(self, data, name=None, shots=None, time_taken=None,
+                 creg_sizes=None, memory_slots=None, **metadata):
+        """Build a counts object
+
+        Args:
+            data (dict): The dictionary input for the counts. The key should
+                be a hexademical string of the form ``"0x4a"`` representing the
+                measured classical value from the experiment and the
+                dictionary's value is an integer representing the number of
+                shots with that result.
+            name (str): A string name for the counts object
+            shots (int): The number of shots used in the experiment
+            time_taken (float): The duration of the experiment that generated
+                the counts
+            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.
+            metadata: Any arbitrary key value metadata passed in as kwargs.
+        """
+        self.hex_raw = dict(data)
+        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
+        bin_data = postprocess.format_counts(self.hex_raw, header=header)
+        super().__init__(bin_data)
+        self.name = name
+        self.shots = shots
+        self.time_taken = time_taken
+        self.metadata = metadata
+
+    def most_frequent(self):
+        """Return the most frequent count
+
+        Returns:
+            str: The bit string for the most frequent result
+        Raises:
+            NoMostFrequentCount: when there is >1 count with the same max counts
+        """
+        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.NoMostFrequentCount(
+                "Multiple values have the same maximum counts: %s" %
+                ','.join(max_values_counts))
+        return max_values_counts[0]
+
+    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
+        """
+        return {int(key, 0): value for key, value in self.hex_raw.items()}

qiskit/result/exceptions.py

@@ -39,3 +39,8 @@ def __init__(self, error):
 
     def __str__(self):
         return '{}: {}'.format(self.code, self.message)
+
+
+class NoMostFrequentCount(QiskitError):
+    """Error raised by Counts.most_frequent if there is no most frequent result."""
+    pass

qiskit/result/result.py

@@ -19,7 +19,7 @@
 from qiskit.circuit.quantumcircuit import QuantumCircuit
 from qiskit.pulse.schedule import Schedule
 from qiskit.exceptions import QiskitError
-from qiskit.quantum_info.states import Statevector
+from qiskit.quantum_info.states import statevector
 from qiskit.result.models import ExperimentResult
 from qiskit.result import postprocess
 from qiskit.qobj.utils import MeasLevel
@@ -245,7 +245,7 @@ def get_counts(self, experiment=None):
                 dict_list.append(postprocess.format_counts(self.data(key)['counts'], header))
             elif 'statevector' in self.data(key).keys():
                 vec = postprocess.format_statevector(self.data(key)['statevector'])
-                dict_list.append(Statevector(vec).probabilities_dict(decimals=15))
+                dict_list.append(statevector.Statevector(vec).probabilities_dict(decimals=15))
             else:
                 raise QiskitError('No counts for experiment "{0}"'.format(key))
 

releasenotes/notes/add-counts-class-7c75bd94d12a161a.yaml

@@ -0,0 +1,14 @@
+---
+features:
+  - |
+    A new class, :class:`qiskit.result.Counts` has been added. This class
+    is a subclass of ``dict`` and . It is created by passing a dictionary
+    of counts with the keys being hexademical strings of the form ``'0x4a'``
+    and the value is the number of shots. For example::
+
+      from qiskit.result import Counts
+
+      counts = Counts({"0x0': 1, '0x1', 3, '0x2': 1020})
+
+    A Counts object can be treated as a dictionary of binary string keys
+    like the output of :meth:`qiskit.result.Result.get_counts`.