Deprecate set_state_vector and set_density_matrix (#4906)

It was accepted at cirq sync that these are vestigial functions from a time when we didn't have initial_state or custom gates or classical controls that could be used for this. Now that we have all these, we can remove this function.

Fixes #4830

cirq-core/cirq/sim/density_matrix_simulator.py

@@ -17,7 +17,7 @@
 import numpy as np
 
 from cirq import ops, protocols, qis, study, value
-from cirq._compat import proper_repr
+from cirq._compat import deprecated, proper_repr
 from cirq.sim import (
     simulator,
     act_on_density_matrix_args,
@@ -302,6 +302,11 @@ def __init__(
     def _simulator_state(self) -> 'cirq.DensityMatrixSimulatorState':
         return DensityMatrixSimulatorState(self.density_matrix(copy=False), self._qubit_mapping)
 
+    # TODO: When removing, also remove `simulator` from the constructor, and the line
+    # `sim_state = step_result._sim_state` from `SimulatorBase._core_iterator()`.
+    @deprecated(
+        deadline="v0.15", fix='Use `initial_state` to prepare a new simulation on the suffix.'
+    )
     def set_density_matrix(self, density_matrix_repr: Union[int, np.ndarray]):
         """Set the density matrix to a new density matrix.
 

cirq-core/cirq/sim/density_matrix_simulator_test.py

@@ -841,7 +841,7 @@ def test_simulate_moment_steps_empty_circuit(dtype: Type[np.number], split: bool
 
 
 @pytest.mark.parametrize('dtype', [np.complex64, np.complex128])
-def test_simulate_moment_steps_set_state(dtype: Type[np.number]):
+def test_simulate_moment_steps_set_state_deprecated(dtype: Type[np.number]):
     q0, q1 = cirq.LineQubit.range(2)
     circuit = cirq.Circuit(cirq.H(q0), cirq.H(q1), cirq.H(q0), cirq.H(q1))
     simulator = cirq.DensityMatrixSimulator(dtype=dtype)
@@ -850,7 +850,8 @@ def test_simulate_moment_steps_set_state(dtype: Type[np.number]):
         if i == 0:
             zero_zero = np.zeros((4, 4), dtype=dtype)
             zero_zero[0, 0] = 1
-            step.set_density_matrix(zero_zero)
+            with cirq.testing.assert_deprecated('initial_state', deadline='v0.15'):
+                step.set_density_matrix(zero_zero)
 
 
 @pytest.mark.parametrize('dtype', [np.complex64, np.complex128])

cirq-core/cirq/sim/sparse_simulator.py

@@ -29,6 +29,7 @@
 import numpy as np
 
 from cirq import ops, protocols, qis
+from cirq._compat import deprecated
 from cirq.sim import (
     simulator,
     state_vector,
@@ -316,6 +317,11 @@ def state_vector(self, copy: bool = True):
                 self._state_vector = np.reshape(vector, size)
         return self._state_vector.copy() if copy else self._state_vector
 
+    # TODO: When removing, also remove `simulator` from the constructor, and the line
+    # `sim_state = step_result._sim_state` from `SimulatorBase._core_iterator()`.
+    @deprecated(
+        deadline="v0.15", fix='Use `initial_state` to prepare a new simulation on the suffix.'
+    )
     def set_state_vector(self, state: 'cirq.STATE_VECTOR_LIKE'):
         """Set the state vector.
 

cirq-core/cirq/sim/sparse_simulator_test.py

@@ -580,14 +580,15 @@ def test_simulate_moment_steps_empty_circuit(dtype: Type[np.number], split: bool
 
 
 @pytest.mark.parametrize('dtype', [np.complex64, np.complex128])
-def test_simulate_moment_steps_set_state(dtype):
+def test_simulate_moment_steps_set_state_deprecated(dtype):
     q0, q1 = cirq.LineQubit.range(2)
     circuit = cirq.Circuit(cirq.H(q0), cirq.H(q1), cirq.H(q0), cirq.H(q1))
     simulator = cirq.Simulator(dtype=dtype)
     for i, step in enumerate(simulator.simulate_moment_steps(circuit)):
         np.testing.assert_almost_equal(step.state_vector(), np.array([0.5] * 4))
         if i == 0:
-            step.set_state_vector(np.array([1, 0, 0, 0], dtype=dtype))
+            with cirq.testing.assert_deprecated('initial_state', deadline='v0.15'):
+                step.set_state_vector(np.array([1, 0, 0, 0], dtype=dtype))
 
 
 @pytest.mark.parametrize('dtype', [np.complex64, np.complex128])