Deprecate PauliTable and StabilizerTable (Qiskit#9547)

* Deprecate PauliTable and StabilizerTable

* Update qiskit/quantum_info/operators/symplectic/pauli_table.py

Co-authored-by: Julien Gacon <gaconju@gmail.com>

* use deprecate_func instead of deprecate_function

---------

Co-authored-by: Julien Gacon <gaconju@gmail.com>

qiskit/quantum_info/operators/symplectic/clifford.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017--2022
+# (C) Copyright IBM 2017--2023
 #
 # 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
@@ -27,6 +27,7 @@
 from qiskit.quantum_info.operators.operator import Operator
 from qiskit.quantum_info.operators.scalar_op import ScalarOp
 from qiskit.quantum_info.operators.symplectic.base_pauli import _count_y
+from qiskit.utils.deprecation import deprecate_func
 
 from .base_pauli import BasePauli
 from .clifford_circuits import _append_circuit, _append_operation
@@ -145,7 +146,7 @@ def __init__(self, data, validate=True, copy=True):
             num_qubits = data.num_qubits
             self.tableau = Clifford.from_circuit(data).tableau
 
-        # DEPRECATE in the future: data is StabilizerTable
+        # DEPRECATED: data is StabilizerTable
         elif isinstance(data, StabilizerTable):
             self.tableau = self._stack_table_phase(data.array, data.phase)
             num_qubits = data.num_qubits
@@ -212,20 +213,37 @@ def copy(self):
     # Attributes
     # ---------------------------------------------------------------------
 
+    # pylint: disable=bad-docstring-quotes
+
+    @deprecate_func(
+        since="0.24.0",
+        additional_msg="Instead, index or iterate through the Clifford.tableau attribute.",
+    )
     def __getitem__(self, key):
         """Return a stabilizer Pauli row"""
         return self.table.__getitem__(key)
 
+    @deprecate_func(since="0.24.0", additional_msg="Use Clifford.tableau property instead.")
     def __setitem__(self, key, value):
         """Set a stabilizer Pauli row"""
         self.tableau.__setitem__(key, self._stack_table_phase(value.array, value.phase))
 
     @property
+    @deprecate_func(
+        since="0.24.0",
+        additional_msg="Use Clifford.stab and Clifford.destab properties instead.",
+        is_property=True,
+    )
     def table(self):
         """Return StabilizerTable"""
         return StabilizerTable(self.symplectic_matrix, phase=self.phase)
 
     @table.setter
+    @deprecate_func(
+        since="0.24.0",
+        additional_msg="Use Clifford.stab and Clifford.destab properties instead.",
+        is_property=True,
+    )
     def table(self, value):
         """Set the stabilizer table"""
         # Note this setter cannot change the size of the Clifford
@@ -237,27 +255,47 @@ def table(self, value):
         self.phase = value._table._phase
 
     @property
+    @deprecate_func(
+        since="0.24.0",
+        additional_msg="Use Clifford.stab properties instead.",
+        is_property=True,
+    )
     def stabilizer(self):
         """Return the stabilizer block of the StabilizerTable."""
         array = self.tableau[self.num_qubits : 2 * self.num_qubits, :-1]
         phase = self.tableau[self.num_qubits : 2 * self.num_qubits, -1].reshape(self.num_qubits)
         return StabilizerTable(array, phase)
 
     @stabilizer.setter
+    @deprecate_func(
+        since="0.24.0",
+        additional_msg="Use Clifford.stab properties instead.",
+        is_property=True,
+    )
     def stabilizer(self, value):
         """Set the value of stabilizer block of the StabilizerTable"""
         if not isinstance(value, StabilizerTable):
             value = StabilizerTable(value)
         self.tableau[self.num_qubits : 2 * self.num_qubits, :-1] = value.array
 
     @property
+    @deprecate_func(
+        since="0.24.0",
+        additional_msg="Use Clifford.destab properties instead.",
+        is_property=True,
+    )
     def destabilizer(self):
         """Return the destabilizer block of the StabilizerTable."""
         array = self.tableau[0 : self.num_qubits, :-1]
         phase = self.tableau[0 : self.num_qubits, -1].reshape(self.num_qubits)
         return StabilizerTable(array, phase)
 
     @destabilizer.setter
+    @deprecate_func(
+        since="0.24.0",
+        additional_msg="Use Clifford.destab properties instead.",
+        is_property=True,
+    )
     def destabilizer(self, value):
         """Set the value of destabilizer block of the StabilizerTable"""
         if not isinstance(value, StabilizerTable):

qiskit/quantum_info/operators/symplectic/pauli_table.py

@@ -28,7 +28,7 @@
 
 
 class PauliTable(BaseOperator, AdjointMixin):
-    r"""Symplectic representation of a list Pauli matrices.
+    r"""DEPRECATED: Symplectic representation of a list Pauli matrices.
 
     **Symplectic Representation**
 
@@ -127,7 +127,7 @@ class PauliTable(BaseOperator, AdjointMixin):
            `arXiv:quant-ph/0406196 <https://arxiv.org/abs/quant-ph/0406196>`_
     """
 
-    @deprecate_func(additional_msg="Instead, use the class PauliList", since="0.23.0", pending=True)
+    @deprecate_func(additional_msg="Instead, use the class PauliList", since="0.24.0")
     def __init__(self, data):
         """Initialize the PauliTable.
 

qiskit/quantum_info/operators/symplectic/stabilizer_table.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017, 2020
+# (C) Copyright IBM 2017, 2023
 #
 # 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
@@ -23,7 +23,7 @@
 
 
 class StabilizerTable(PauliTable, AdjointMixin):
-    r"""Symplectic representation of a list Stabilizer matrices.
+    r"""DEPRECATED: Symplectic representation of a list Stabilizer matrices.
 
     **Symplectic Representation**
 
@@ -169,7 +169,7 @@ class StabilizerTable(PauliTable, AdjointMixin):
            `arXiv:quant-ph/0406196 <https://arxiv.org/abs/quant-ph/0406196>`_
     """
 
-    @deprecate_func(additional_msg="Instead, use the class PauliList", since="0.23.0", pending=True)
+    @deprecate_func(additional_msg="Instead, use the class PauliList", since="0.24.0")
     def __init__(self, data, phase=None):
         """Initialize the StabilizerTable.
 

releasenotes/notes/deprecate-pauli-table-fc6dcdb5eeb6e0c4.yaml

@@ -0,0 +1,9 @@
+---
+deprecations:
+  - |
+    The :class:`~qiskit.quantum_info.PauliTable` and :class:`~qiskit.quantum_info.StabilizerTable`
+    are deprecated and will be removed in a future release.
+    Instead, the :class:`~qiskit.quantum_info.PauliList` should be used.
+    With this change, :meth:`~qiskit.quantum_info.Clifford.table` has been deprecated
+    so that you should operate directly from :meth:`~qiskit.quantum_info.Clifford.tableau`
+    without it.

test/python/quantum_info/operators/symplectic/test_clifford.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017, 2020.
+# (C) Copyright IBM 2017, 2023.
 #
 # 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
@@ -241,10 +241,11 @@ def test_append_1_qubit_gate(self):
             with self.subTest(msg="append gate %s" % gate_name):
                 cliff = Clifford([[1, 0], [0, 1]])
                 cliff = _append_operation(cliff, gate_name, [0])
-                value_table = cliff.table._array
-                value_phase = cliff.table._phase
-                value_stabilizer = cliff.stabilizer.to_labels()
-                value_destabilizer = cliff.destabilizer.to_labels()
+                with self.assertWarns(DeprecationWarning):
+                    value_table = cliff.table._array
+                    value_phase = cliff.table._phase
+                    value_stabilizer = cliff.stabilizer.to_labels()
+                    value_destabilizer = cliff.destabilizer.to_labels()
                 self.assertTrue(np.all(np.array(value_table == target_table[gate_name])))
                 self.assertTrue(np.all(np.array(value_phase == target_phase[gate_name])))
                 self.assertTrue(

test/python/quantum_info/operators/symplectic/test_pauli_list.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2017, 2020.
+# (C) Copyright IBM 2017, 2023.
 #
 # 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
@@ -231,12 +231,14 @@ def test_pauli_table_init(self):
     def test_stabilizer_table_init(self):
         """Test table initialization."""
         with self.subTest(msg="PauliTable"):
-            target = StabilizerTable.from_labels(["+II", "-XZ"])
+            with self.assertWarns(DeprecationWarning):
+                target = StabilizerTable.from_labels(["+II", "-XZ"])
             value = PauliList(target)
             self.assertEqual(value, target)
 
         with self.subTest(msg="PauliTable no copy"):
-            target = StabilizerTable.from_labels(["+YY", "-XZ", "XI"])
+            with self.assertWarns(DeprecationWarning):
+                target = StabilizerTable.from_labels(["+YY", "-XZ", "XI"])
             value = PauliList(target)
             value[0] = "II"
             self.assertEqual(value, target)