cirq-core 1.1.0.dev20221220224914__py3-none-any.whl → 1.2.0__py3-none-any.whl

cirq/sim/simulator_base_test.py

@@ -34,7 +34,7 @@ class CountingState(cirq.qis.QuantumStateRepresentation):
         self.measurement_count += 1
         return [self.gate_count]
 
-    def kron(self: 'CountingState', other: 'CountingState') -> 'CountingState':
+    def kron(self, other: 'CountingState') -> 'CountingState':
         return CountingState(
             self.data,
             self.gate_count + other.gate_count,
@@ -43,13 +43,13 @@ class CountingState(cirq.qis.QuantumStateRepresentation):
         )
 
     def factor(
-        self: 'CountingState', axes: Sequence[int], *, validate=True, atol=1e-07
+        self, axes: Sequence[int], *, validate=True, atol=1e-07
     ) -> Tuple['CountingState', 'CountingState']:
         return CountingState(
             self.data, self.gate_count, self.measurement_count, self.copy_count
         ), CountingState(self.data)
 
-    def reindex(self: 'CountingState', axes: Sequence[int]) -> 'CountingState':
+    def reindex(self, axes: Sequence[int]) -> 'CountingState':
         return CountingState(self.data, self.gate_count, self.measurement_count, self.copy_count)
 
     def copy(self, deep_copy_buffers: bool = True) -> 'CountingState':

cirq/sim/sparse_simulator.py

@@ -282,5 +282,5 @@ class SparseSimulatorStep(
         # Dtype doesn't have a good repr, so we work around by invoking __name__.
         return (
             f'cirq.SparseSimulatorStep(sim_state={self._sim_state!r},'
-            f' dtype=np.{self._dtype.__name__})'
+            f' dtype=np.{np.dtype(self._dtype)!r})'
         )

cirq/sim/sparse_simulator_test.py

@@ -255,7 +255,7 @@ def test_run_mixture(dtype: Type[np.complexfloating], split: bool):
     simulator = cirq.Simulator(dtype=dtype, split_untangled_states=split)
     circuit = cirq.Circuit(cirq.bit_flip(0.5)(q0), cirq.measure(q0))
     result = simulator.run(circuit, repetitions=100)
-    assert 20 < sum(result.measurements['q(0)'])[0] < 80  # type: ignore
+    assert 20 < sum(result.measurements['q(0)'])[0] < 80
 
 
 @pytest.mark.parametrize('dtype', [np.complex64, np.complex128])
@@ -265,8 +265,8 @@ def test_run_mixture_with_gates(dtype: Type[np.complexfloating], split: bool):
     simulator = cirq.Simulator(dtype=dtype, split_untangled_states=split, seed=23)
     circuit = cirq.Circuit(cirq.H(q0), cirq.phase_flip(0.5)(q0), cirq.H(q0), cirq.measure(q0))
     result = simulator.run(circuit, repetitions=100)
-    assert sum(result.measurements['q(0)'])[0] < 80  # type: ignore
-    assert sum(result.measurements['q(0)'])[0] > 20  # type: ignore
+    assert sum(result.measurements['q(0)'])[0] < 80
+    assert sum(result.measurements['q(0)'])[0] > 20
 
 
 @pytest.mark.parametrize('dtype', [np.complex64, np.complex128])
@@ -775,9 +775,9 @@ def test_sparse_simulator_repr():
     # No equality so cannot use cirq.testing.assert_equivalent_repr
     assert (
         repr(step) == "cirq.SparseSimulatorStep(sim_state=cirq.StateVectorSimulationState("
-        "initial_state=np.array([[0j, (1+0j)], [0j, 0j]], dtype=np.complex64), "
+        "initial_state=np.array([[0j, (1+0j)], [0j, 0j]], dtype=np.dtype('complex64')), "
         "qubits=(cirq.LineQubit(0), cirq.LineQubit(1)), "
-        "classical_data=cirq.ClassicalDataDictionaryStore()), dtype=np.complex64)"
+        "classical_data=cirq.ClassicalDataDictionaryStore()), dtype=np.dtype('complex64'))"
     )
 
 

cirq/sim/state_vector.py

@@ -19,7 +19,7 @@ from typing import List, Mapping, Optional, Tuple, TYPE_CHECKING, Sequence
 import numpy as np
 
 from cirq import linalg, qis, value
-from cirq.sim import simulator
+from cirq.sim import simulator, simulation_utils
 
 if TYPE_CHECKING:
     import cirq
@@ -35,7 +35,7 @@ class StateVectorMixin:
         """Inits StateVectorMixin.
 
         Args:
-            qubit_map: A map from the Qubits in the Circuit to the the index
+            qubit_map: A map from the Qubits in the Circuit to the index
                 of this qubit for a canonical ordering. This canonical ordering
                 is used to define the state (see the state_vector() method).
             *args: Passed on to the class that this is mixed in with.
@@ -102,7 +102,7 @@ class StateVectorMixin:
             and non-zero floats of the specified accuracy."""
         return qis.dirac_notation(self.state_vector(), decimals, qid_shape=self._qid_shape)
 
-    def density_matrix_of(self, qubits: List['cirq.Qid'] = None) -> np.ndarray:
+    def density_matrix_of(self, qubits: Optional[List['cirq.Qid']] = None) -> np.ndarray:
         r"""Returns the density matrix of the state.
 
         Calculate the density matrix for the system on the qubits provided.
@@ -215,7 +215,8 @@ def sample_state_vector(
     prng = value.parse_random_state(seed)
 
     # Calculate the measurement probabilities.
-    probs = _probs(state_vector, indices, shape)
+    probs = (state_vector * state_vector.conj()).real
+    probs = simulation_utils.state_probabilities_by_indices(probs, indices, shape)
 
     # We now have the probability vector, correctly ordered, so sample over
     # it. Note that we us ints here, since numpy's choice does not allow for
@@ -288,7 +289,8 @@ def measure_state_vector(
     initial_shape = state_vector.shape
 
     # Calculate the measurement probabilities and then make the measurement.
-    probs = _probs(state_vector, indices, shape)
+    probs = (state_vector * state_vector.conj()).real
+    probs = simulation_utils.state_probabilities_by_indices(probs, indices, shape)
     result = prng.choice(len(probs), p=probs)
     ###measurement_bits = [(1 & (result >> i)) for i in range(len(indices))]
     # Convert to individual qudit measurements.
@@ -321,34 +323,3 @@ def measure_state_vector(
     assert out is not None
     # We mutate and return out, so mypy cannot identify that the out cannot be None.
     return measurement_bits, out
-
-
-def _probs(state: np.ndarray, indices: Sequence[int], qid_shape: Tuple[int, ...]) -> np.ndarray:
-    """Returns the probabilities for a measurement on the given indices."""
-    tensor = np.reshape(state, qid_shape)
-    # Calculate the probabilities for measuring the particular results.
-    if len(indices) == len(qid_shape):
-        # We're measuring every qudit, so no need for fancy indexing
-        probs = np.abs(tensor) ** 2
-        probs = np.transpose(probs, indices)
-        probs = probs.reshape(-1)
-    else:
-        # Fancy indexing required
-        meas_shape = tuple(qid_shape[i] for i in indices)
-        probs = (
-            np.abs(
-                [
-                    tensor[
-                        linalg.slice_for_qubits_equal_to(
-                            indices, big_endian_qureg_value=b, qid_shape=qid_shape
-                        )
-                    ]
-                    for b in range(np.prod(meas_shape, dtype=np.int64))
-                ]
-            )
-            ** 2
-        )
-        probs = np.sum(probs, axis=tuple(range(1, len(probs.shape))))
-
-    # To deal with rounding issues, ensure that the probabilities sum to 1.
-    return probs / np.sum(probs)

cirq/sim/state_vector_simulation_state.py

@@ -11,6 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
 """Objects and methods for acting efficiently on a state vector."""
 from typing import Any, Callable, List, Optional, Sequence, Tuple, Type, TYPE_CHECKING, Union
 
@@ -355,6 +356,22 @@ class StateVectorSimulationState(SimulationState[_BufferedStateVector]):
         )
         super().__init__(state=state, prng=prng, qubits=qubits, classical_data=classical_data)
 
+    def add_qubits(self, qubits: Sequence['cirq.Qid']):
+        ret = super().add_qubits(qubits)
+        return (
+            self.kronecker_product(type(self)(qubits=qubits), inplace=True)
+            if ret is NotImplemented
+            else ret
+        )
+
+    def remove_qubits(self, qubits: Sequence['cirq.Qid']):
+        ret = super().remove_qubits(qubits)
+        if ret is not NotImplemented:
+            return ret
+        extracted, remainder = self.factor(qubits, inplace=True)
+        remainder._state._state_vector *= extracted._state._state_vector.reshape((-1,))[0]
+        return remainder
+
     def _act_on_fallback_(
         self, action: Any, qubits: Sequence['cirq.Qid'], allow_decompose: bool = True
     ) -> bool:
@@ -377,7 +394,7 @@ class StateVectorSimulationState(SimulationState[_BufferedStateVector]):
         raise TypeError(
             "Can't simulate operations that don't implement "
             "SupportsUnitary, SupportsConsistentApplyUnitary, "
-            "SupportsMixture or is a measurement: {!r}".format(action)
+            f"SupportsMixture or is a measurement: {action!r}"
         )
 
     def __repr__(self) -> str:

cirq/sim/state_vector_simulator.py

@@ -20,6 +20,7 @@ import numpy as np
 
 from cirq import _compat, ops, value, qis
 from cirq.sim import simulator, state_vector, simulator_base
+from cirq.protocols import qid_shape
 
 if TYPE_CHECKING:
     import cirq
@@ -31,7 +32,7 @@ TStateVectorStepResult = TypeVar('TStateVectorStepResult', bound='StateVectorSte
 class SimulatesIntermediateStateVector(
     Generic[TStateVectorStepResult],
     simulator_base.SimulatorBase[
-        TStateVectorStepResult, 'cirq.StateVectorTrialResult', 'cirq.StateVectorSimulationState',
+        TStateVectorStepResult, 'cirq.StateVectorTrialResult', 'cirq.StateVectorSimulationState'
     ],
     simulator.SimulatesAmplitudes,
     metaclass=abc.ABCMeta,
@@ -172,7 +173,7 @@ class StateVectorTrialResult(
             size = np.prod(shape, dtype=np.int64)
             final = final.reshape(size)
             if len([1 for e in final if abs(e) > 0.001]) < 16:
-                state_vector = qis.dirac_notation(final, 3)
+                state_vector = qis.dirac_notation(final, 3, qid_shape(substate.qubits))
             else:
                 state_vector = str(final)
             label = f'qubits: {substate.qubits}' if substate.qubits else 'phase:'

cirq/sim/state_vector_simulator_test.py

@@ -35,9 +35,9 @@ def test_state_vector_trial_result_repr():
     expected_repr = (
         "cirq.StateVectorTrialResult("
         "params=cirq.ParamResolver({'s': 1}), "
-        "measurements={'m': np.array([[1]], dtype=np.int32)}, "
+        "measurements={'m': np.array([[1]], dtype=np.dtype('int32'))}, "
         "final_simulator_state=cirq.StateVectorSimulationState("
-        "initial_state=np.array([0j, (1+0j)], dtype=np.complex64), "
+        "initial_state=np.array([0j, (1+0j)], dtype=np.dtype('complex64')), "
         "qubits=(cirq.NamedQubit('a'),), "
         "classical_data=cirq.ClassicalDataDictionaryStore()))"
     )
@@ -159,6 +159,28 @@ def test_str_big():
     assert 'output vector: [0.03125+0.j 0.03125+0.j 0.03125+0.j ..' in str(result)
 
 
+def test_str_qudit():
+    qutrit = cirq.LineQid(0, dimension=3)
+    final_simulator_state = cirq.StateVectorSimulationState(
+        prng=np.random.RandomState(0),
+        qubits=[qutrit],
+        initial_state=np.array([0, 0, 1]),
+        dtype=np.complex64,
+    )
+    result = cirq.StateVectorTrialResult(cirq.ParamResolver(), {}, final_simulator_state)
+    assert "|2⟩" in str(result)
+
+    ququart = cirq.LineQid(0, dimension=4)
+    final_simulator_state = cirq.StateVectorSimulationState(
+        prng=np.random.RandomState(0),
+        qubits=[ququart],
+        initial_state=np.array([0, 1, 0, 0]),
+        dtype=np.complex64,
+    )
+    result = cirq.StateVectorTrialResult(cirq.ParamResolver(), {}, final_simulator_state)
+    assert "|1⟩" in str(result)
+
+
 def test_pretty_print():
     final_simulator_state = cirq.StateVectorSimulationState(
         available_buffer=np.array([1]),

cirq/sim/state_vector_test.py

@@ -21,6 +21,7 @@ import numpy as np
 
 import cirq
 import cirq.testing
+from cirq import linalg
 
 
 def test_state_mixin():
@@ -172,7 +173,9 @@ def test_sample_no_indices_repetitions():
     )
 
 
-def test_measure_state_computational_basis():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_computational_basis(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     results = []
     for x in range(8):
         initial_state = cirq.to_valid_state_vector(x, 3)
@@ -183,7 +186,9 @@ def test_measure_state_computational_basis():
     assert results == expected
 
 
-def test_measure_state_reshape():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_reshape(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     results = []
     for x in range(8):
         initial_state = np.reshape(cirq.to_valid_state_vector(x, 3), [2] * 3)
@@ -194,7 +199,9 @@ def test_measure_state_reshape():
     assert results == expected
 
 
-def test_measure_state_partial_indices():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_partial_indices(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     for index in range(3):
         for x in range(8):
             initial_state = cirq.to_valid_state_vector(x, 3)
@@ -203,7 +210,9 @@ def test_measure_state_partial_indices():
             assert bits == [bool(1 & (x >> (2 - index)))]
 
 
-def test_measure_state_partial_indices_order():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_partial_indices_order(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     for x in range(8):
         initial_state = cirq.to_valid_state_vector(x, 3)
         bits, state = cirq.measure_state_vector(initial_state, [2, 1])
@@ -211,7 +220,9 @@ def test_measure_state_partial_indices_order():
         assert bits == [bool(1 & (x >> 0)), bool(1 & (x >> 1))]
 
 
-def test_measure_state_partial_indices_all_orders():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_partial_indices_all_orders(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     for perm in itertools.permutations([0, 1, 2]):
         for x in range(8):
             initial_state = cirq.to_valid_state_vector(x, 3)
@@ -220,7 +231,9 @@ def test_measure_state_partial_indices_all_orders():
             assert bits == [bool(1 & (x >> (2 - p))) for p in perm]
 
 
-def test_measure_state_collapse():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_collapse(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     initial_state = np.zeros(8, dtype=np.complex64)
     initial_state[0] = 1 / np.sqrt(2)
     initial_state[2] = 1 / np.sqrt(2)
@@ -243,7 +256,9 @@ def test_measure_state_collapse():
         assert bits == [False]
 
 
-def test_measure_state_seed():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_seed(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     n = 10
     initial_state = np.ones(2**n) / 2 ** (n / 2)
 
@@ -262,7 +277,9 @@ def test_measure_state_seed():
     np.testing.assert_allclose(state1, state2)
 
 
-def test_measure_state_out_is_state():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_out_is_state(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     initial_state = np.zeros(8, dtype=np.complex64)
     initial_state[0] = 1 / np.sqrt(2)
     initial_state[2] = 1 / np.sqrt(2)
@@ -273,7 +290,9 @@ def test_measure_state_out_is_state():
     assert state is initial_state
 
 
-def test_measure_state_out_is_not_state():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_out_is_not_state(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     initial_state = np.zeros(8, dtype=np.complex64)
     initial_state[0] = 1 / np.sqrt(2)
     initial_state[2] = 1 / np.sqrt(2)
@@ -283,14 +302,18 @@ def test_measure_state_out_is_not_state():
     assert out is state
 
 
-def test_measure_state_not_power_of_two():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_not_power_of_two(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     with pytest.raises(ValueError, match='3'):
         _, _ = cirq.measure_state_vector(np.array([1, 0, 0]), [1])
     with pytest.raises(ValueError, match='5'):
         cirq.measure_state_vector(np.array([0, 1, 0, 0, 0]), [1])
 
 
-def test_measure_state_index_out_of_range():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_index_out_of_range(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     state = cirq.to_valid_state_vector(0, 3)
     with pytest.raises(IndexError, match='-2'):
         cirq.measure_state_vector(state, [-2])
@@ -298,14 +321,18 @@ def test_measure_state_index_out_of_range():
         cirq.measure_state_vector(state, [3])
 
 
-def test_measure_state_no_indices():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_no_indices(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     initial_state = cirq.to_valid_state_vector(0, 3)
     bits, state = cirq.measure_state_vector(initial_state, [])
     assert [] == bits
     np.testing.assert_almost_equal(state, initial_state)
 
 
-def test_measure_state_no_indices_out_is_state():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_no_indices_out_is_state(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     initial_state = cirq.to_valid_state_vector(0, 3)
     bits, state = cirq.measure_state_vector(initial_state, [], out=initial_state)
     assert [] == bits
@@ -313,7 +340,9 @@ def test_measure_state_no_indices_out_is_state():
     assert state is initial_state
 
 
-def test_measure_state_no_indices_out_is_not_state():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_no_indices_out_is_not_state(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     initial_state = cirq.to_valid_state_vector(0, 3)
     out = np.zeros_like(initial_state)
     bits, state = cirq.measure_state_vector(initial_state, [], out=out)
@@ -323,7 +352,9 @@ def test_measure_state_no_indices_out_is_not_state():
     assert out is not initial_state
 
 
-def test_measure_state_empty_state():
+@pytest.mark.parametrize('use_np_transpose', [False, True])
+def test_measure_state_empty_state(use_np_transpose: bool):
+    linalg.can_numpy_support_shape = lambda s: use_np_transpose
     initial_state = np.array([1.0])
     bits, state = cirq.measure_state_vector(initial_state, [])
     assert [] == bits

cirq/study/__init__.py

@@ -38,6 +38,7 @@ from cirq.study.sweeps import (
     Sweep,
     UnitSweep,
     Zip,
+    ZipLongest,
     dict_to_product_sweep,
     dict_to_zip_sweep,
 )

cirq/study/flatten_expressions.py

@@ -40,7 +40,7 @@ def flatten(val: Any) -> Tuple[Any, 'ExpressionMap']:
         the name to avoid collision: `sympy.Symbol('<x + 1>_1')`.
 
     This function also creates a dictionary mapping from expressions and symbols
-    in `val` to the new symbols in the flattened copy of `val`.  E.g
+    in `val` to the new symbols in the flattened copy of `val`.  E.g.
     `cirq.ExpressionMap({sympy.Symbol('x')+1: sympy.Symbol('<x + 1>')})`.  This
     `ExpressionMap` can be used to transform a sweep over the symbols in `val`
     to a sweep over the flattened symbols e.g. a sweep over `sympy.Symbol('x')`
@@ -200,7 +200,7 @@ class _ParamFlattener(resolver.ParamResolver):
         self,
         param_dict: Optional[resolver.ParamResolverOrSimilarType] = None,
         *,  # Force keyword args
-        get_param_name: Callable[[sympy.Expr], str,] = None,
+        get_param_name: Optional[Callable[[sympy.Expr], str]] = None,
     ):
         """Initializes a new _ParamFlattener.
 

cirq/study/resolver.py

@@ -150,6 +150,8 @@ class ParamResolver:
         # The following resolves common sympy expressions
         # If sympy did its job and wasn't slower than molasses,
         # we wouldn't need the following block.
+        if isinstance(value, sympy.Float):
+            return float(value)
         if isinstance(value, sympy.Add):
             summation = self.value_of(value.args[0], recursive)
             for addend in value.args[1:]:

cirq/study/resolver_test.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 """Tests for parameter resolvers."""
+
 import fractions
 
 import numpy as np
@@ -241,7 +242,6 @@ def test_custom_resolved_value():
     assert r.value_of(b) == 'Baz'
 
 
-@pytest.mark.xfail(reason='this test requires sympy 1.12', strict=True)
 def test_custom_value_not_implemented():
     class Bar:
         def _resolved_value_(self):

cirq/study/result.py

@@ -140,7 +140,7 @@ class Result(abc.ABC):
             basis = 2 ** np.arange(n, dtype=dtype)[::-1]
             converted_dict[key] = np.sum(basis * bitstrings, axis=1)
 
-        # Use objects to accomodate more than 64 qubits if needed.
+        # Use objects to accommodate more than 64 qubits if needed.
         dtype = object if any(bs.shape[1] > 63 for _, bs in measurements.items()) else np.int64
         return pd.DataFrame(converted_dict, dtype=dtype)
 

cirq/study/sweeps.py

@@ -18,6 +18,7 @@ from typing import (
     Iterable,
     Iterator,
     List,
+    Optional,
     overload,
     Sequence,
     TYPE_CHECKING,
@@ -127,7 +128,7 @@ class Sweep(metaclass=abc.ABCMeta):
     def __getitem__(self, val: slice) -> 'Sweep':
         pass
 
-    def __getitem__(self, val):
+    def __getitem__(self, val: Union[int, slice]) -> Union[resolver.ParamResolver, 'Sweep']:
         n = len(self)
         if isinstance(val, int):
             if val < -n or val >= n:
@@ -292,7 +293,7 @@ class Zip(Sweep):
         self.sweeps = sweeps
 
     def __eq__(self, other):
-        if not isinstance(other, Zip):
+        if type(other) is not Zip:
             return NotImplemented
         return self.sweeps == other.sweeps
 
@@ -327,7 +328,62 @@ class Zip(Sweep):
 
     @classmethod
     def _from_json_dict_(cls, sweeps, **kwargs):
-        return Zip(*sweeps)
+        return cls(*sweeps)
+
+
+class ZipLongest(Zip):
+    """Iterate over constituent sweeps in parallel
+
+    Analogous to itertools.zip_longest.
+    Note that we iterate until all sweeps terminate,
+    so if the sweeps are different lengths, the
+    shorter sweeps will be filled by repeating their last value
+    until all sweeps have equal length.
+
+    Note that this is different from itertools.zip_longest,
+    which uses a fixed fill value.
+
+    Raises:
+        ValueError if an input sweep if completely empty.
+    """
+
+    def __init__(self, *sweeps: Sweep) -> None:
+        super().__init__(*sweeps)
+        if any(len(sweep) == 0 for sweep in self.sweeps):
+            raise ValueError('All sweeps must be non-empty for ZipLongest')
+
+    def __eq__(self, other):
+        if not isinstance(other, ZipLongest):
+            return NotImplemented
+        return self.sweeps == other.sweeps
+
+    def __len__(self) -> int:
+        if not self.sweeps:
+            return 0
+        return max(len(sweep) for sweep in self.sweeps)
+
+    def __hash__(self) -> int:
+        return hash((self.__class__.__name__, tuple(self.sweeps)))
+
+    def __repr__(self) -> str:
+        sweeps_repr = ', '.join(repr(s) for s in self.sweeps)
+        return f'cirq_google.ZipLongest({sweeps_repr})'
+
+    def __str__(self) -> str:
+        sweeps_repr = ', '.join(repr(s) for s in self.sweeps)
+        return f'ZipLongest({sweeps_repr})'
+
+    def param_tuples(self) -> Iterator[Params]:
+        def _iter_and_repeat_last(one_iter: Iterator[Params]):
+            last = None
+            for last in one_iter:
+                yield last
+            while True:
+                yield last
+
+        iters = [_iter_and_repeat_last(sweep.param_tuples()) for sweep in self.sweeps]
+        for values in itertools.islice(zip(*iters), len(self)):
+            yield tuple(item for value in values for item in value)
 
 
 class SingleSweep(Sweep):
@@ -366,9 +422,23 @@ class SingleSweep(Sweep):
 class Points(SingleSweep):
     """A simple sweep with explicitly supplied values."""
 
-    def __init__(self, key: 'cirq.TParamKey', points: Sequence[float]) -> None:
-        super(Points, self).__init__(key)
+    def __init__(
+        self, key: 'cirq.TParamKey', points: Sequence[float], metadata: Optional[Any] = None
+    ) -> None:
+        """Creates a sweep on a variable with supplied values.
+
+        Args:
+            key: sympy.Symbol or equivalent to sweep across.
+            points: sequence of floating point values that represent
+                the values to sweep across.  The length of the sweep
+                will be equivalent to the length of this sequence.
+            metadata: Optional metadata to attach to the sweep to
+                annotate the sweep or its variable.
+
+        """
+        super().__init__(key)
         self.points = points
+        self.metadata = metadata
 
     def _tuple(self) -> Tuple[Union[str, sympy.Expr], Sequence[float]]:
         return self.key, tuple(self.points)
@@ -380,25 +450,44 @@ class Points(SingleSweep):
         return iter(self.points)
 
     def __repr__(self) -> str:
-        return f'cirq.Points({self.key!r}, {self.points!r})'
+        metadata_repr = f', metadata={self.metadata!r}' if self.metadata is not None else ""
+        return f'cirq.Points({self.key!r}, {self.points!r}{metadata_repr})'
 
     def _json_dict_(self) -> Dict[str, Any]:
+        if self.metadata is not None:
+            return protocols.obj_to_dict_helper(self, ["key", "points", "metadata"])
         return protocols.obj_to_dict_helper(self, ["key", "points"])
 
 
 class Linspace(SingleSweep):
     """A simple sweep over linearly-spaced values."""
 
-    def __init__(self, key: 'cirq.TParamKey', start: float, stop: float, length: int) -> None:
+    def __init__(
+        self,
+        key: 'cirq.TParamKey',
+        start: float,
+        stop: float,
+        length: int,
+        metadata: Optional[Any] = None,
+    ) -> None:
         """Creates a linear-spaced sweep for a given key.
 
         For the given args, assigns to the list of values
             start, start + (stop - start) / (length - 1), ..., stop
+
+        Args:
+            key: sympy.Symbol or equivalent to sweep across.
+            start: minimum value of linear sweep.
+            stop: maximum value of linear sweep.
+            length: number of points in the sweep.
+            metadata: Optional metadata to attach to the sweep to
+                annotate the sweep or its variable.
         """
-        super(Linspace, self).__init__(key)
+        super().__init__(key)
         self.start = start
         self.stop = stop
         self.length = length
+        self.metadata = metadata
 
     def _tuple(self) -> Tuple[Union[str, sympy.Expr], float, float, int]:
         return (self.key, self.start, self.stop, self.length)
@@ -415,12 +504,17 @@ class Linspace(SingleSweep):
                 yield self.start * (1 - p) + self.stop * p
 
     def __repr__(self) -> str:
+        metadata_repr = f', metadata={self.metadata!r}' if self.metadata is not None else ""
         return (
             f'cirq.Linspace({self.key!r}, start={self.start!r}, '
-            f'stop={self.stop!r}, length={self.length!r})'
+            f'stop={self.stop!r}, length={self.length!r}{metadata_repr})'
         )
 
     def _json_dict_(self) -> Dict[str, Any]:
+        if self.metadata is not None:
+            return protocols.obj_to_dict_helper(
+                self, ["key", "start", "stop", "length", "metadata"]
+            )
         return protocols.obj_to_dict_helper(self, ["key", "start", "stop", "length"])