Deprecate basis state preparation

doc/development/deprecations.rst

@@ -85,6 +85,12 @@ Pending deprecations
   - Deprecated in v0.37
   - Will be removed in v0.39
 
+* The ``BasisStatePreparation`` template is deprecated.
+  Instead, use ``BasisState``.
+
+  - Deprecated in v0.39
+  - Will be removed in v0.40
+
 New operator arithmetic deprecations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/releases/changelog-dev.md

@@ -10,6 +10,10 @@
 
 <h3>Deprecations 👋</h3>
 
+* The ``BasisStatePreparation`` template is deprecated.
+  Instead, use ``BasisState``.
+  [(#6021)](https://github.com/PennyLaneAI/pennylane/pull/6021)
+
 <h3>Documentation 📝</h3>
 
 <h3>Bug fixes 🐛</h3>

pennylane/devices/tests/test_templates.py

@@ -225,6 +225,15 @@ def circuit():
             [math.fidelity_statevector(circuit(), exp_state)], [1.0], atol=tol(dev.shots)
         )
 
+    @pytest.fixture(scope="function", autouse=False)
+    def capture_warnings(self, recwarn):
+        """Capture warnings."""
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     def test_BasisStatePreparation(self, device, tol):
         """Test the BasisStatePreparation template."""
         dev = device(4)

pennylane/templates/state_preparations/basis.py

@@ -15,6 +15,8 @@
 Contains the BasisStatePreparation template.
 """
 
+import warnings
+
 import numpy as np
 
 import pennylane as qml
@@ -30,6 +32,8 @@ class BasisStatePreparation(Operation):
         ``basis_state`` influences the circuit architecture and is therefore incompatible with
         gradient computations.
 
+        ``BasisStatePreparation`` is deprecated and will be removed in version 0.39. Instead, please use ``BasisState``.
+
     Args:
         basis_state (array): Input array of shape ``(n,)``, where n is the number of wires
             the state preparation acts on.
@@ -59,6 +63,13 @@ def circuit(basis_state):
     ndim_params = (1,)
 
     def __init__(self, basis_state, wires, id=None):
+
+        warnings.warn(
+            "BasisStatePreparation is deprecated and will be removed in version 0.39. "
+            "Instead, please use BasisState.",
+            qml.PennyLaneDeprecationWarning,
+        )
+
         basis_state = qml.math.stack(basis_state)
 
         # check if the `basis_state` param is batched

tests/capture/test_templates.py

@@ -190,6 +190,15 @@ def enable_disable_plxpr():
 ]
 
 
+@pytest.fixture(scope="function", autouse=True)
+def capture_warnings(recwarn):
+    yield
+    if len(recwarn) > 0:
+        for w in recwarn:
+            assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+            assert "BasisStatePreparation is deprecated" in str(w.message)
+
+
 @pytest.mark.parametrize("template, args, kwargs", unmodified_templates_cases)
 def test_unmodified_templates(template, args, kwargs):
     """Test that templates with unmodified primitive binds are captured as expected."""

tests/ops/qubit/test_state_prep.py

@@ -36,6 +36,12 @@ def test_adjoint_error_exception(op):
         op.adjoint()
 
 
+def test_BasisStatePreparation_is_deprecated():
+    """Test that my_feature is deprecated."""
+    with pytest.warns(qml.PennyLaneDeprecationWarning, match="BasisStatePreparation is deprecated"):
+        _ = qml.BasisStatePreparation([1, 0], wires=[0, 1])
+
+
 @pytest.mark.parametrize(
     "op, mat, base",
     [

tests/templates/test_state_preparations/test_basis_state_prep.py

@@ -22,6 +22,15 @@
 import pennylane as qml
 
 
+@pytest.fixture(scope="function", autouse=True)
+def capture_warnings(recwarn):  # pylint: disable=function-redefined
+    yield
+    if len(recwarn) > 0:
+        for w in recwarn:
+            assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+            assert "BasisStatePreparation is deprecated" in str(w.message)
+
+
 def test_standard_validity():
     """Check the operation using the assert_valid function."""
 
@@ -36,6 +45,14 @@ def test_standard_validity():
 class TestDecomposition:
     """Tests that the template defines the correct decomposition."""
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     # fmt: off
     @pytest.mark.parametrize("basis_state,wires,target_wires", [
         ([0], [0], []),
@@ -61,6 +78,14 @@ def test_correct_pl_gates(self, basis_state, wires, target_wires):
             assert gate.name == "PauliX"
             assert gate.wires.tolist() == [target_wires[id]]
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     # fmt: off
     @pytest.mark.parametrize("basis_state,wires,target_state", [
         ([0], [0], [0, 0, 0]),
@@ -90,6 +115,14 @@ def circuit():
 
         assert np.allclose(output_state, target_state, atol=tol, rtol=0)
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     @pytest.mark.jax
     @pytest.mark.parametrize(
         "basis_state,wires,target_state",
@@ -117,6 +150,14 @@ def circuit(state):
 
         assert np.allclose(output_state, target_state, atol=tol, rtol=0)
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     @pytest.mark.tf
     @pytest.mark.parametrize(
         "basis_state,wires,target_state",
@@ -143,6 +184,14 @@ def circuit(state):
 
         assert np.allclose(output_state, target_state, atol=tol, rtol=0)
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     def test_custom_wire_labels(self, tol):
         """Test that template can deal with non-numeric, nonconsecutive wire labels."""
         basis_state = [0, 1, 0]
@@ -166,6 +215,14 @@ def circuit2():
         assert np.allclose(res1, res2, atol=tol, rtol=0)
         assert np.allclose(state1, state2, atol=tol, rtol=0)
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     def test_batched_decomposition_fails(self):
         """Test that attempting to decompose a BasisStatePreparation operation with
         broadcasting raises an error."""
@@ -182,6 +239,14 @@ def test_batched_decomposition_fails(self):
 class TestInputs:
     """Test inputs and pre-processing."""
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     # fmt: off
     @pytest.mark.parametrize("basis_state,wires", [
         ([0], [0, 1]),
@@ -195,6 +260,14 @@ def test_error_num_qubits(self, basis_state, wires):
         with pytest.raises(ValueError, match="Basis states must be of (shape|length)"):
             qml.BasisStatePreparation(basis_state, wires)
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     # fmt: off
     @pytest.mark.parametrize("basis_state,wires", [
         ([3], [0]),
@@ -208,6 +281,14 @@ def test_error_basis_state_format(self, basis_state, wires):
         with pytest.raises(ValueError, match="Basis states must only (contain|consist)"):
             qml.BasisStatePreparation(basis_state, wires)
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     def test_exception_wrong_dim(self):
         """Verifies that exception is raised if the
         number of dimensions of features is incorrect."""
@@ -230,6 +311,14 @@ def circuit(basis_state):
             basis_state = np.array([0, 2])
             circuit(basis_state)
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):  # pylint: disable=function-redefined
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     def test_id(self):
         """Tests that the id attribute can be set."""
         template = qml.BasisStatePreparation(np.array([0, 1]), wires=[0, 1], id="a")

tests/test_qnode.py

@@ -901,15 +901,15 @@ def test_sampling_with_mcm(self, basis_state, mocker):
         @qml.qnode(dev)
         def cry_qnode(x):
             """QNode where we apply a controlled Y-rotation."""
-            qml.BasisStatePreparation(basis_state, wires=[0, 1])
+            qml.BasisState(basis_state, wires=[0, 1])
             qml.CRY(x, wires=[0, 1])
             return qml.sample(qml.PauliZ(1))
 
         @qml.qnode(dev)
         def conditional_ry_qnode(x):
             """QNode where the defer measurements transform is applied by
             default under the hood."""
-            qml.BasisStatePreparation(basis_state, wires=[0, 1])
+            qml.BasisState(basis_state, wires=[0, 1])
             m_0 = qml.measure(0)
             qml.cond(m_0, qml.RY)(x, wires=1)
             return qml.sample(qml.PauliZ(1))

tests/test_qnode_legacy.py

@@ -1016,15 +1016,15 @@ def test_sampling_with_mcm(self, basis_state, mocker):
         @qml.qnode(dev)
         def cry_qnode(x):
             """QNode where we apply a controlled Y-rotation."""
-            qml.BasisStatePreparation(basis_state, wires=[0, 1])
+            qml.BasisState(basis_state, wires=[0, 1])
             qml.CRY(x, wires=[0, 1])
             return qml.sample(qml.PauliZ(1))
 
         @qml.qnode(dev)
         def conditional_ry_qnode(x):
             """QNode where the defer measurements transform is applied by
             default under the hood."""
-            qml.BasisStatePreparation(basis_state, wires=[0, 1])
+            qml.BasisState(basis_state, wires=[0, 1])
             m_0 = qml.measure(0)
             qml.cond(m_0, qml.RY)(x, wires=1)
             return qml.sample(qml.PauliZ(1))

tests/transforms/test_batch_input.py

@@ -200,6 +200,15 @@ def circuit2(data, weights):
     assert np.allclose(res, indiv_res)
 
 
+@pytest.fixture(scope="function", autouse=True)
+def capture_warnings(recwarn):
+    yield
+    if len(recwarn) > 0:
+        for w in recwarn:
+            assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+            assert "BasisStatePreparation is deprecated" in str(w.message)
+
+
 def test_basis_state_preparation(mocker):
     """Test that batching works for BasisStatePreparation"""
     dev = qml.device("default.qubit", wires=3)

tests/transforms/test_batch_params.py

@@ -174,6 +174,15 @@ def circuit2(data, weights):
     assert np.allclose(res, indiv_res)
 
 
+@pytest.fixture(scope="function", autouse=True)
+def capture_warnings(recwarn):
+    yield
+    if len(recwarn) > 0:
+        for w in recwarn:
+            assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+            assert "BasisStatePreparation is deprecated" in str(w.message)
+
+
 def test_basis_state_preparation(mocker):
     """Test that batching works for BasisStatePreparation"""
     dev = qml.device("default.qubit", wires=4)

tests/transforms/test_defer_measurements.py

@@ -1347,6 +1347,14 @@ def quantum_control_circuit(rads):
 class TestTemplates:
     """Tests templates being conditioned on mid-circuit measurement outcomes."""
 
+    @pytest.fixture(scope="function", autouse=True)
+    def capture_warnings(self, recwarn):
+        yield
+        if len(recwarn) > 0:
+            for w in recwarn:
+                assert isinstance(w.message, qml.PennyLaneDeprecationWarning)
+                assert "BasisStatePreparation is deprecated" in str(w.message)
+
     def test_basis_state_prep(self):
         """Test the basis state prep template conditioned on mid-circuit
         measurement outcomes."""