Add new method for single bitstring target when measuring stabilizerstate probabilities_dict

qiskit/quantum_info/states/stabilizerstate.py

@@ -386,8 +386,17 @@ def probabilities(self, qargs: None | list = None, decimals: None | int = None)
 
         return probs
 
-    def probabilities_dict(self, qargs: None | list = None, decimals: None | int = None) -> dict:
-        """Return the subsystem measurement probability dictionary.
+    def probabilities_dict_from_bitstring(
+        self,
+        outcome_bitstring: str,
+        qargs: None | list = None,
+        decimals: None | int = None,
+    ) -> dict[str, float]:
+        """Return the subsystem measurement probability dictionary utilizing
+        a targeted outcome_bitstring to perform the measurement for. This
+        will calculate a probability for only a single targeted
+        outcome_bitstring value, giving a performance boost over calculating
+        all possible outcomes.
 
         Measurement probabilities are with respect to measurement in the
         computation (diagonal) basis.
@@ -398,30 +407,44 @@ def probabilities_dict(self, qargs: None | list = None, decimals: None | int = N
         inserted between integers so that subsystems can be distinguished.
 
         Args:
+            outcome_bitstring (None or str): targeted outcome bitstring
+                to perform a measurement calculation for, this will significantly
+                reduce the number of calculation performed (Default: None)
             qargs (None or list): subsystems to return probabilities for,
-                if None return for all subsystems (Default: None).
+                    if None return for all subsystems (Default: None).
             decimals (None or int): the number of decimal places to round
-                values. If None no rounding is done (Default: None).
+                    values. If None no rounding is done (Default: None)
 
         Returns:
-            dict: The measurement probabilities in dict (ket) form.
+            dict[str, float]: The measurement probabilities in dict (ket) form.
         """
-        if qargs is None:
-            qubits = range(self.clifford.num_qubits)
-        else:
-            qubits = qargs
+        return self._get_probabilities_dict(
+            outcome_bitstring=outcome_bitstring, qargs=qargs, decimals=decimals
+        )
 
-        outcome = ["X"] * len(qubits)
-        outcome_prob = 1.0
-        probs = {}  # probabilities dictionary
+    def probabilities_dict(
+        self, qargs: None | list = None, decimals: None | int = None
+    ) -> dict[str, float]:
+        """Return the subsystem measurement probability dictionary.
 
-        self._get_probabilities(qubits, outcome, outcome_prob, probs)
+        Measurement probabilities are with respect to measurement in the
+        computation (diagonal) basis.
 
-        if decimals is not None:
-            for key, value in probs.items():
-                probs[key] = round(value, decimals)
+        This dictionary representation uses a Ket-like notation where the
+        dictionary keys are qudit strings for the subsystem basis vectors.
+        If any subsystem has a dimension greater than 10 comma delimiters are
+        inserted between integers so that subsystems can be distinguished.
 
-        return probs
+        Args:
+            qargs (None or list): subsystems to return probabilities for,
+                if None return for all subsystems (Default: None).
+            decimals (None or int): the number of decimal places to round
+                values. If None no rounding is done (Default: None).
+
+        Returns:
+            dict: The measurement probabilities in dict (key) form.
+        """
+        return self._get_probabilities_dict(outcome_bitstring=None, qargs=qargs, decimals=decimals)
 
     def reset(self, qargs: list | None = None) -> StabilizerState:
         """Reset state or subsystems to the 0-state.
@@ -644,22 +667,48 @@ def _rowsum_deterministic(clifford, aux_pauli, row):
     # -----------------------------------------------------------------------
     # Helper functions for calculating the probabilities
     # -----------------------------------------------------------------------
-    def _get_probabilities(self, qubits, outcome, outcome_prob, probs):
-        """Recursive helper function for calculating the probabilities"""
+    def _get_probabilities(
+        self,
+        qubits: range,
+        outcome: list[str],
+        outcome_prob: float,
+        probs: dict[str, float],
+        outcome_bitstring: str = None,
+    ):
+        """Recursive helper function for calculating the probabilities
 
-        qubit_for_branching = -1
-        ret = self.copy()
+        Args:
+            qubits (range): range of qubits
+            outcome (list[str]): outcome being built
+            outcome_prob (float): probabilitiy of the outcome
+            probs (dict[str, float]): holds the outcomes and probabilitiy results
+            outcome_bitstring (str): target outcome to measure which reduces measurements, None
+                if not targeting a specific target
+        """
+        qubit_for_branching: int = -1
 
+        ret: StabilizerState = self.copy()
+
+        # Find outcomes for each qubit
         for i in range(len(qubits)):
-            qubit = qubits[len(qubits) - i - 1]
             if outcome[i] == "X":
-                is_deterministic = not any(ret.clifford.stab_x[:, qubit])
-                if is_deterministic:
-                    single_qubit_outcome = ret._measure_and_update(qubit, 0)
-                    if single_qubit_outcome:
-                        outcome[i] = "1"
+                # Retrieve the qubit for the current measurement
+                qubit = qubits[(len(qubits) - i - 1)]
+                # Determine if the probabilitiy is deterministic
+                if not any(ret.clifford.stab_x[:, qubit]):
+                    single_qubit_outcome: np.int64 = ret._measure_and_update(qubit, 0)
+                    if outcome_bitstring is None or (
+                        int(outcome_bitstring[i]) == single_qubit_outcome
+                    ):
+                        # No outcome_bitstring target, or using outcome_bitstring target and
+                        # the single_qubit_outcome equals the desired outcome_bitstring target value,
+                        # then use current outcome_prob value
+                        outcome[i] = str(single_qubit_outcome)
                     else:
-                        outcome[i] = "0"
+                        # If the single_qubit_outcome does not equal the outcome_bitsring target
+                        # then we know that the probability will be 0
+                        outcome[i] = str(outcome_bitstring[i])
+                        outcome_prob = 0
                 else:
                     qubit_for_branching = i
 
@@ -668,15 +717,57 @@ def _get_probabilities(self, qubits, outcome, outcome_prob, probs):
             probs[str_outcome] = outcome_prob
             return
 
-        for single_qubit_outcome in range(0, 2):
+        for single_qubit_outcome in (
+            range(0, 2)
+            if (outcome_bitstring is None)
+            else [int(outcome_bitstring[qubit_for_branching])]
+        ):
             new_outcome = outcome.copy()
-            if single_qubit_outcome:
-                new_outcome[qubit_for_branching] = "1"
-            else:
-                new_outcome[qubit_for_branching] = "0"
+            new_outcome[qubit_for_branching] = str(single_qubit_outcome)
 
             stab_cpy = ret.copy()
             stab_cpy._measure_and_update(
-                qubits[len(qubits) - qubit_for_branching - 1], single_qubit_outcome
+                qubits[(len(qubits) - qubit_for_branching - 1)], single_qubit_outcome
+            )
+            stab_cpy._get_probabilities(
+                qubits, new_outcome, (0.5 * outcome_prob), probs, outcome_bitstring
             )
-            stab_cpy._get_probabilities(qubits, new_outcome, 0.5 * outcome_prob, probs)
+
+    def _get_probabilities_dict(
+        self,
+        outcome_bitstring: None | str = None,
+        qargs: None | list = None,
+        decimals: None | int = None,
+    ) -> dict[str, float]:
+        """Helper Function for calculating the subsystem measurement probability dictionary.
+        When the targeted outcome_bitstring value is set, then only the single outcome_bitstring
+        probability will be calculated.
+
+        Args:
+            outcome_bitstring (None or str): targeted outcome bitstring
+                to perform a measurement calculation for, this will significantly
+                reduce the number of calculation performed (Default: None)
+            qargs (None or list): subsystems to return probabilities for,
+                if None return for all subsystems (Default: None).
+            decimals (None or int): the number of decimal places to round
+                values. If None no rounding is done (Default: None).
+
+        Returns:
+            dict: The measurement probabilities in dict (key) form.
+        """
+        if qargs is None:
+            qubits = range(self.clifford.num_qubits)
+        else:
+            qubits = qargs
+
+        outcome = ["X"] * len(qubits)
+        outcome_prob = 1.0
+        probs: dict[str, float] = {}  # Probabilities dict to return with the measured values
+
+        self._get_probabilities(qubits, outcome, outcome_prob, probs, outcome_bitstring)
+
+        if decimals is not None:
+            for key, value in probs.items():
+                probs[key] = round(value, decimals)
+
+        return probs

releasenotes/notes/outcome_bitstring_target_for_probabilities_dict-e53f524d115bbcfc.yaml

@@ -0,0 +1,13 @@
+---
+features:
+  - |
+    The :class:'.StabilizerState' class now has a new method 
+    :meth:'~.StabilizerState.probabilities_dict_from_bitstring' allowing the 
+    user to pass single bitstring to measure an outcome for. Previouslly the 
+    :meth:'~.StabilizerState.probabilities_dict' would be utilized and would 
+    at worst case calculate (2^n) number of probabilbity calculations (depending
+    on the state), even if a user wanted a single result. With this new method 
+    the user can calculate just the single outcome bitstring value a user passes 
+    to measure the probability for. As the number of qubits increases, the more 
+    prevelant the performance enhancement may be (depending on the state) as only 
+    1 bitstring result is measured.