Deprecation: State_vector not wavefunction, wave_function, or state. (#…

…3022)

cirq/__init__.py

@@ -133,7 +133,6 @@
     kak_decomposition,
     kak_vector,
     KakDecomposition,
-    subwavefunction,
     kron,
     kron_bases,
     kron_factor_4x4_to_2x2s,
@@ -142,12 +141,15 @@
     match_global_phase,
     matrix_from_basis_coefficients,
     partial_trace,
+    partial_trace_of_state_vector_as_mixture,
     PAULI_BASIS,
     scatter_plot_normalized_kak_interaction_coefficients,
     pow_pauli_combination,
     reflection_matrix_pow,
     slice_for_qubits_equal_to,
     so4_to_magic_su2s,
+    subwavefunction,
+    sub_state_vector,
     targeted_conjugate_about,
     targeted_left_multiply,
     unitary_eig,
@@ -312,6 +314,8 @@
     to_valid_density_matrix,
     to_valid_state_vector,
     validate_normalized_state,
+    validate_normalized_state_vector,
+    validate_qid_shape,
     von_neumann_entropy,
 )
 
@@ -331,6 +335,7 @@
     measure_density_matrix,
     measure_state_vector,
     final_density_matrix,
+    final_state_vector,
     final_wavefunction,
     sample,
     sample_density_matrix,
@@ -339,12 +344,16 @@
     SimulatesAmplitudes,
     SimulatesFinalState,
     SimulatesIntermediateState,
+    SimulatesIntermediateStateVector,
     SimulatesIntermediateWaveFunction,
     SimulatesSamples,
     SimulationTrialResult,
     Simulator,
     SparseSimulatorStep,
     StateVectorMixin,
+    StateVectorSimulatorState,
+    StateVectorStepResult,
+    StateVectorTrialResult,
     StepResult,
     WaveFunctionSimulatorState,
     WaveFunctionStepResult,

cirq/circuits/circuit.py

@@ -37,6 +37,7 @@
 from cirq.circuits.qasm_output import QasmOutput
 from cirq.circuits.quil_output import QuilOutput
 from cirq.type_workarounds import NotImplementedType
+from cirq._compat import deprecated
 import cirq._version
 
 if TYPE_CHECKING:
@@ -64,7 +65,7 @@ class Circuit:
         are_all_matches_terminal
         are_all_measurements_terminal
         unitary
-        final_wavefunction
+        final_state_vector
         to_text_diagram
         to_text_diagram_drawer
 
@@ -1521,7 +1522,7 @@ def unitary(self,
         result = _apply_unitary_circuit(self, state, qs, dtype)
         return result.reshape((side_len, side_len))
 
-    def final_wavefunction(
+    def final_state_vector(
             self,
             initial_state: 'cirq.STATE_VECTOR_LIKE' = 0,
             qubit_order: 'cirq.QubitOrderOrList' = ops.QubitOrder.DEFAULT,
@@ -1602,6 +1603,22 @@ def final_wavefunction(
         result = _apply_unitary_circuit(self, state, qs, dtype)
         return result.reshape((state_len,))
 
+    @deprecated(deadline='v0.10.0', fix='Use final_state_vector instead.')
+    def final_wavefunction(
+            self,
+            initial_state: 'cirq.STATE_VECTOR_LIKE' = 0,
+            qubit_order: 'cirq.QubitOrderOrList' = ops.QubitOrder.DEFAULT,
+            qubits_that_should_be_present: Iterable['cirq.Qid'] = (),
+            ignore_terminal_measurements: bool = True,
+            dtype: Type[np.number] = np.complex128) -> np.ndarray:
+        """Deprecated. Please use `final_state_vector`."""
+        return self.final_state_vector(
+            initial_state=initial_state,
+            qubit_order=qubit_order,
+            qubits_that_should_be_present=qubits_that_should_be_present,
+            ignore_terminal_measurements=ignore_terminal_measurements,
+            dtype=dtype)
+
     def to_text_diagram(
             self,
             *,

cirq/circuits/circuit_test.py

@@ -23,6 +23,7 @@
 
 import cirq
 import cirq.google as cg
+import cirq.testing
 from cirq import ops
 
 
@@ -2373,83 +2374,83 @@ def test_apply_unitary_effect_to_state():
 
     # State ordering.
     cirq.testing.assert_allclose_up_to_global_phase(
-        cirq.Circuit(cirq.X(a)**0.5).final_wavefunction(),
+        cirq.Circuit(cirq.X(a)**0.5).final_state_vector(),
         np.array([1j, 1]) * np.sqrt(0.5),
         atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(
-        cirq.Circuit(cirq.X(a)**0.5).final_wavefunction(initial_state=0),
+        cirq.Circuit(cirq.X(a)**0.5).final_state_vector(initial_state=0),
         np.array([1j, 1]) * np.sqrt(0.5),
         atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(
-        cirq.Circuit(cirq.X(a)**0.5).final_wavefunction(initial_state=1),
+        cirq.Circuit(cirq.X(a)**0.5).final_state_vector(initial_state=1),
         np.array([1, 1j]) * np.sqrt(0.5),
         atol=1e-8)
 
     # Vector state.
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-        cirq.X(a)**0.5).final_wavefunction(initial_state=np.array([1j, 1]) *
+        cirq.X(a)**0.5).final_state_vector(initial_state=np.array([1j, 1]) *
                                            np.sqrt(0.5)),
                                                     np.array([0, 1]),
                                                     atol=1e-8)
 
     # Qubit ordering.
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(cirq.CNOT(
-        a, b)).final_wavefunction(initial_state=0),
+        a, b)).final_state_vector(initial_state=0),
                                                     np.array([1, 0, 0, 0]),
                                                     atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(cirq.CNOT(
-        a, b)).final_wavefunction(initial_state=1),
+        a, b)).final_state_vector(initial_state=1),
                                                     np.array([0, 1, 0, 0]),
                                                     atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(cirq.CNOT(
-        a, b)).final_wavefunction(initial_state=2),
+        a, b)).final_state_vector(initial_state=2),
                                                     np.array([0, 0, 0, 1]),
                                                     atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(cirq.CNOT(
-        a, b)).final_wavefunction(initial_state=3),
+        a, b)).final_state_vector(initial_state=3),
                                                     np.array([0, 0, 1, 0]),
                                                     atol=1e-8)
 
     # Measurements.
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-        cirq.measure(a)).final_wavefunction(),
+        cirq.measure(a)).final_state_vector(),
                                                     np.array([1, 0]),
                                                     atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-        cirq.X(a), cirq.measure(a)).final_wavefunction(),
+        cirq.X(a), cirq.measure(a)).final_state_vector(),
                                                     np.array([0, 1]),
                                                     atol=1e-8)
     with pytest.raises(ValueError):
         cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-            cirq.measure(a), cirq.X(a)).final_wavefunction(),
+            cirq.measure(a), cirq.X(a)).final_state_vector(),
                                                         np.array([1, 0]),
                                                         atol=1e-8)
     with pytest.raises(ValueError):
         cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-            cirq.measure(a)).final_wavefunction(
+            cirq.measure(a)).final_state_vector(
                 ignore_terminal_measurements=False),
                                                         np.array([1, 0]),
                                                         atol=1e-8)
 
     # Extra qubits.
     cirq.testing.assert_allclose_up_to_global_phase(
-        cirq.Circuit().final_wavefunction(), np.array([1]), atol=1e-8)
+        cirq.Circuit().final_state_vector(), np.array([1]), atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(
-        cirq.Circuit().final_wavefunction(qubits_that_should_be_present=[a]),
+        cirq.Circuit().final_state_vector(qubits_that_should_be_present=[a]),
         np.array([1, 0]),
         atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-        cirq.X(b)).final_wavefunction(qubits_that_should_be_present=[a]),
+        cirq.X(b)).final_state_vector(qubits_that_should_be_present=[a]),
                                                     np.array([0, 1, 0, 0]),
                                                     atol=1e-8)
 
     # Qubit order.
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-        cirq.Z(a), cirq.X(b)).final_wavefunction(qubit_order=[a, b]),
+        cirq.Z(a), cirq.X(b)).final_state_vector(qubit_order=[a, b]),
                                                     np.array([0, 1, 0, 0]),
                                                     atol=1e-8)
     cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-        cirq.Z(a), cirq.X(b)).final_wavefunction(qubit_order=[b, a]),
+        cirq.Z(a), cirq.X(b)).final_state_vector(qubit_order=[b, a]),
                                                     np.array([0, 0, 1, 0]),
                                                     atol=1e-8)
 
@@ -2459,7 +2460,7 @@ def test_apply_unitary_effect_to_state():
         dtypes.append(np.complex256)
     for dt in dtypes:
         cirq.testing.assert_allclose_up_to_global_phase(cirq.Circuit(
-            cirq.X(a)**0.5).final_wavefunction(initial_state=np.array([1j, 1]) *
+            cirq.X(a)**0.5).final_state_vector(initial_state=np.array([1j, 1]) *
                                                np.sqrt(0.5),
                                                dtype=dt),
                                                         np.array([0, 1]),
@@ -3756,3 +3757,10 @@ def _measurement_key_(self):
             cirq.measure(b, key='y'),
             cirq.measure(a, key='x'),
         ])).all_measurement_keys() == ('y', 'x')
+
+
+def test_deprecated():
+    q = cirq.NamedQubit('q')
+    circuit = cirq.Circuit([cirq.H(q)])
+    with cirq.testing.assert_logs('final_state_vector', 'deprecated'):
+        _ = circuit.final_wavefunction()

cirq/contrib/quantum_volume/quantum_volume.py

@@ -75,7 +75,7 @@ def compute_heavy_set(circuit: cirq.Circuit) -> List[int]:
     # Classically compute the probabilities of each output bit-string through
     # simulation.
     simulator = cirq.Simulator()
-    results = cast(cirq.WaveFunctionTrialResult,
+    results = cast(cirq.StateVectorTrialResult,
                    simulator.simulate(program=circuit))
 
     # Compute the median probability of the output bit-strings. Note that heavy

cirq/experiments/cross_entropy_benchmarking.py

@@ -274,13 +274,13 @@ def cross_entropy_benchmarking(
                                                   circuits_k)
 
         # Simulate each circuit with the Cirq simulator to obtain the
-        # wavefunction at the end of each circuit, from which the
+        # state vector at the end of each circuit, from which the
         # theoretically expected bit-string probabilities are obtained.
         probs_exp_k = []  # type: List[np.ndarray]
         for circ_k in circuits_k:
             res = simulator.simulate(circ_k, qubit_order=qubits)
-            state_probs = np.abs(np.asarray(res.final_state)  # type: ignore
-                                )**2
+            state_probs = np.abs(np.asarray(
+                res.final_state_vector))**2  # type: ignore
             probs_exp_k.append(state_probs)
 
         for i, num_cycle in enumerate(cycle_range):

cirq/experiments/fidelity_estimation.py

@@ -19,7 +19,7 @@
 
 from cirq.circuits import Circuit
 from cirq.ops import QubitOrder, QubitOrderOrList
-from cirq.sim import final_wavefunction
+from cirq.sim import final_state_vector
 
 
 def linear_xeb_fidelity_from_probabilities(
@@ -165,7 +165,7 @@ def xeb_fidelity(
             each circuit execution as integer array where each integer is
             formed from measured qubit values according to `qubit_order` from
             most to least significant qubit, i.e. in the order consistent with
-            `cirq.final_wavefunction`.
+            `cirq.final_state_vector`.
         qubit_order: Qubit order used to construct bitstrings enumerating
             qubits starting with the most sigificant qubit.
         amplitudes: Optional mapping from bitstring to output amplitude.
@@ -192,7 +192,7 @@ def xeb_fidelity(
                 f'on {len(circuit.qid_shape())} qubits.')
 
     if amplitudes is None:
-        output_state = final_wavefunction(circuit, qubit_order=qubit_order)
+        output_state = final_state_vector(circuit, qubit_order=qubit_order)
         output_probabilities = np.abs(output_state)**2
         bitstring_probabilities = output_probabilities[bitstrings]
     else:

cirq/experiments/fidelity_estimation_test.py

@@ -78,7 +78,7 @@ def test_xeb_fidelity(depolarization, estimator):
                                              repetitions=5000)
 
         f = cirq.xeb_fidelity(circuit, bitstrings, qubits, estimator=estimator)
-        amplitudes = cirq.final_wavefunction(circuit)
+        amplitudes = cirq.final_state_vector(circuit)
         f2 = cirq.xeb_fidelity(circuit,
                                bitstrings,
                                qubits,

cirq/interop/quirk/cells/arithmetic_cells_test.py

@@ -495,7 +495,7 @@ def test_with_registers():
                                atol=1e-8)
 
     op2 = op.with_registers([*cirq.LineQubit.range(3)], 5, 5)
-    np.testing.assert_allclose(cirq.final_wavefunction(cirq.Circuit(op2),
+    np.testing.assert_allclose(cirq.final_state_vector(cirq.Circuit(op2),
                                                        initial_state=0),
                                cirq.one_hot(index=25 % 8,
                                             shape=8,

cirq/interop/quirk/cells/testing.py

@@ -67,7 +67,7 @@ def assert_url_to_circuit_returns(
         ])
 
         np.testing.assert_allclose(
-            cirq.final_wavefunction(
+            cirq.final_state_vector(
                 parsed,
                 # Match Quirk's endian-ness for comparison purposes.
                 qubit_order=sorted(parsed.all_qubits(), reverse=True),
@@ -97,7 +97,7 @@ def _sparse_computational_basis_map(inputs: Sequence[int],
     input_state = np.zeros(1 << len(circuit.all_qubits()), dtype=np.complex128)
     for k, amp in zip(inputs, amps):
         input_state[k] = amp
-    output_state = cirq.final_wavefunction(circuit, initial_state=input_state)
+    output_state = cirq.final_state_vector(circuit, initial_state=input_state)
 
     # Find where each amplitude went.
     actual_map = {}

cirq/linalg/__init__.py

@@ -81,10 +81,12 @@
 
 from cirq.linalg.transformations import (
     apply_matrix_to_slices,
-    subwavefunction,
     match_global_phase,
     partial_trace,
+    partial_trace_of_state_vector_as_mixture,
     reflection_matrix_pow,
+    subwavefunction,
+    sub_state_vector,
     targeted_conjugate_about,
     targeted_left_multiply,
     wavefunction_partial_trace_as_mixture,