cirq_google.GridDevice, minus gateset and gate durations (#5203)

Part of #5050

* Implemented qubit set, qubit pairs, and op validation. Gateset and gate duration will be done in a follow-up.
* Added a `device_specification_validation` module shell, to be used by the QCS server side to validate the DeviceSpecification proto against things like: 
  * Qubit self-loops in qubit pairs
  * Qubit pairs contain qubits not in the valid qubit set.
  * Gate durations contains a gate which is missing in the gateset.

`__str__()` and `_repr_pretty_` are nearly all copied from `SerializableDevice`.

Part of #5050

Also fixes #5197

**Question:** Does this definition of device equality make sense, or should it contain device name as well? Implementing equality is convenient for json and repr tests but not sure if it make sense in general.

@dstrain115 @MichaelBroughton

Author: verult

cirq-core/cirq/devices/grid_device_metadata.py

@@ -189,7 +189,7 @@ def _from_json_dict_(
         return cls(
             qubit_pairs,
             gateset,
-            None if gate_durations is None else dict(gate_durations),
+            dict(gate_durations) if gate_durations is not None else None,
             all_qubits,
             compilation_target_gatesets,
         )

cirq-google/cirq_google/__init__.py

@@ -58,6 +58,7 @@
     Bristlecone,
     Foxtail,
     GoogleNoiseProperties,
+    GridDevice,
     NoiseModelFromGoogleNoiseProperties,
     SerializableDevice,
     Sycamore,

cirq-google/cirq_google/api/v2/device.proto

@@ -22,6 +22,7 @@ message DeviceSpecification {
   // A list of allowed ids for qubits within the Program.
   // Any programs with ids not in this list will be rejected.
   // If empty, all qubit values are allowed (e.g. in a simulator)
+  // Only grid qubits are supported. Strings must be in the form '<int>_<int>'.
   repeated string valid_qubits = 2;
 
   // A list of targets that gates can use.

cirq-google/cirq_google/devices/__init__.py

@@ -19,6 +19,8 @@
 
 from cirq_google.devices.known_devices import Bristlecone, Foxtail, Sycamore, Sycamore23
 
+from cirq_google.devices.grid_device import GridDevice
+
 from cirq_google.devices.serializable_device import SerializableDevice
 
 from cirq_google.devices.xmon_device import XmonDevice

cirq-google/cirq_google/devices/grid_device.py

@@ -0,0 +1,278 @@
+# Copyright 2022 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+
+"""Device object representing Google devices with a grid qubit layout."""
+
+import re
+
+from typing import Any, Set, Tuple, cast
+import cirq
+from cirq_google.api import v2
+
+
+def _validate_device_specification(proto: v2.device_pb2.DeviceSpecification) -> None:
+    """Raises a ValueError if the `DeviceSpecification` proto is invalid."""
+
+    qubit_set = set()
+    for q_name in proto.valid_qubits:
+        # Qubit names must be unique.
+        if q_name in qubit_set:
+            raise ValueError(
+                f"Invalid DeviceSpecification: valid_qubits contains duplicate qubit '{q_name}'."
+            )
+        # Qubit names must be in the form <int>_<int> to be parsed as cirq.GridQubits.
+        if re.match(r'^[0-9]+\_[0-9]+$', q_name) is None:
+            raise ValueError(
+                f"Invalid DeviceSpecification: valid_qubits contains the qubit '{q_name}' which is"
+                " not in the GridQubit form '<int>_<int>."
+            )
+        qubit_set.add(q_name)
+
+    for target_set in proto.valid_targets:
+
+        # Check for unknown qubits in targets.
+        for target in target_set.targets:
+            for target_id in target.ids:
+                if target_id not in proto.valid_qubits:
+                    raise ValueError(
+                        f"Invalid DeviceSpecification: valid_targets contain qubit '{target_id}'"
+                        " which is not in valid_qubits."
+                    )
+
+        # Symmetric and asymmetric targets should not have repeated qubits.
+        if (
+            target_set.target_ordering == v2.device_pb2.TargetSet.SYMMETRIC
+            or target_set.target_ordering == v2.device_pb2.TargetSet.ASYMMETRIC
+        ):
+            for target in target_set.targets:
+                if len(target.ids) > len(set(target.ids)):
+                    raise ValueError(
+                        f"Invalid DeviceSpecification: the target set '{target_set.name}' is either"
+                        " SYMMETRIC or ASYMMETRIC but has a target which contains repeated qubits:"
+                        f" {target.ids}."
+                    )
+
+        # A SUBSET_PERMUTATION target should contain exactly one qubit.
+        # SUBSET_PERMUTATION describes a target set (rather than a target), where a gate can have
+        # any subset of the targets, with each target being exactly 1 qubit.
+        # See the `DeviceSpecification` proto definition for a detailed description.
+        if target_set.target_ordering == v2.device_pb2.TargetSet.SUBSET_PERMUTATION:
+            for target in target_set.targets:
+                if len(target.ids) != 1:
+                    raise ValueError(
+                        f"Invalid DeviceSpecification: the target set '{target_set.name}' is of"
+                        " type SUBSET_PERMUTATION but contains a target which does not have exactly"
+                        f" 1 qubit: {target.ids}."
+                    )
+
+
+@cirq.value_equality
+class GridDevice(cirq.Device):
+    """Device object representing Google devices with a grid qubit layout.
+
+    For end users, instances of this class are typically accessed via
+    `Engine.get_processor('processor_name').get_device()`.
+
+    This class is compliant with the core `cirq.Device` abstraction. In particular:
+        * Device information is captured in the `metadata` property.
+        * An instance of `GridDevice` can be used to validate circuits, moments, and operations.
+
+    Example use cases:
+
+        * Get an instance of a Google grid device.
+        >>> device = cirq_google.get_engine().get_processor('processor_name').get_device()
+
+        * Print the grid layout of the device.
+        >>> print(device)
+
+        * Determine whether a circuit can be run on the device.
+        >>> device.validate_circuit(circuit)  # Raises a ValueError if the circuit is invalid.
+
+        * Determine whether an operation can be run on the device.
+        >>> device.validate_operation(operation)  # Raises a ValueError if the operation is invalid.
+
+        * Get the `cirq.Gateset` containing valid gates for the device, and inspect the full list
+          of valid gates.
+        >>> gateset = device.metadata.gateset
+        >>> print(gateset)
+
+        * Determine whether a gate is available on the device.
+        >>> gate in device.metadata.gateset
+
+        * Get a collection of valid qubits on the device.
+        >>> device.metadata.qubit_set
+
+        * Get a collection of valid qubit pairs for two-qubit gates.
+        >>> device.metadata.qubit_pairs
+
+        * Get a collection of isolated qubits, i.e. qubits which are not part of any qubit pair.
+        >>> device.metadata.isolated_qubits
+
+        * Get a collection of approximate gate durations for every gate supported by the device.
+        >>> device.metadata.gate_durations
+
+        TODO(#5050) Add compilation_target_gatesets example.
+
+    Notes for cirq_google internal implementation:
+
+    For Google devices, the
+    [DeviceSpecification proto](
+        https://github.com/quantumlib/Cirq/blob/master/cirq-google/cirq_google/api/v2/device.proto
+    )
+    is the main specification for device information surfaced by the Quantum Computing Service.
+    Thus, this class is should be instantiated using a `DeviceSpecification` proto via the
+    `from_proto()` class method.
+    """
+
+    def __init__(self, metadata: cirq.GridDeviceMetadata):
+        """Creates a GridDevice object.
+
+        This constructor typically should not be used directly. Use `from_proto()` instead.
+        """
+        self._metadata = metadata
+
+    @classmethod
+    def from_proto(cls, proto: v2.device_pb2.DeviceSpecification) -> 'GridDevice':
+        """Create a `GridDevice` from a `DeviceSpecification` proto.
+
+        Args:
+            proto: The `DeviceSpecification` proto describing a Google device.
+
+        Raises:
+            ValueError: If the given `DeviceSpecification` is invalid. It is invalid if:
+                * A `DeviceSpecification.valid_qubits` string is not in the form `<int>_<int>`, thus
+                  cannot be parsed as a `cirq.GridQubit`.
+                * `DeviceSpecification.valid_targets` refer to qubits which are not in
+                  `DeviceSpecification.valid_qubits`.
+                * A target set in `DeviceSpecification.valid_targets` has type `SYMMETRIC` or
+                  `ASYMMETRIC` but contains targets with repeated qubits, e.g. a qubit pair with a
+                  self loop.
+                * A target set in `DeviceSpecification.valid_targets` has type `SUBSET_PERMUTATION`
+                  but contains targets which do not have exactly one element. A `SUBSET_PERMUTATION`
+                  target set uses each target to represent a single qubit, and a gate can be applied
+                  to any subset of qubits in the target set.
+        """
+
+        _validate_device_specification(proto)
+
+        # Create qubit set
+        all_qubits = {v2.grid_qubit_from_proto_id(q) for q in proto.valid_qubits}
+
+        # Create qubit pair set
+        #
+        # While the `GateSpecification` proto message contains qubit target references, they are
+        # ignored here because the following assumptions make them unnecessary currently:
+        # * All valid qubit pairs work for all two-qubit gates.
+        # * All valid qubits work for all single-qubit gates.
+        # * Measurement gate can always be applied to all subset of qubits.
+        #
+        # TODO(#5050) Consider removing `GateSpecification.valid_targets` and
+        # ASYMMETRIC and SUBSET_PERMUTATION target types.
+        # If they are not removed, then their validation should be tightened.
+        qubit_pairs = [
+            (v2.grid_qubit_from_proto_id(target.ids[0]), v2.grid_qubit_from_proto_id(target.ids[1]))
+            for ts in proto.valid_targets
+            for target in ts.targets
+            if len(target.ids) == 2 and ts.target_ordering == v2.device_pb2.TargetSet.SYMMETRIC
+        ]
+
+        # TODO(#5050) implement gate durations
+        try:
+            metadata = cirq.GridDeviceMetadata(
+                qubit_pairs=qubit_pairs,
+                gateset=cirq.Gateset(),  # TODO(#5050) implement
+                all_qubits=all_qubits,
+            )
+        except ValueError as ve:  # coverage: ignore
+            # Spec errors should have been caught in validation above.
+            raise ValueError("DeviceSpecification is invalid.") from ve  # coverage: ignore
+
+        return GridDevice(metadata)
+
+    @property
+    def metadata(self) -> cirq.GridDeviceMetadata:
+        """Get metadata information for the device."""
+        return self._metadata
+
+    def validate_operation(self, operation: cirq.Operation) -> None:
+        """Raises an exception if an operation is not valid.
+
+        An operation is valid if
+            * The operation is in the device gateset.
+            * The operation targets a valid qubit
+            * The operation targets a valid qubit pair, if it is a two-qubit operation.
+
+        Args:
+            operation: The operation to validate.
+
+        Raises:
+            ValueError: The operation isn't valid for this device.
+        """
+        # TODO(#5050) uncomment once gateset logic is implemented
+        # if operation not in self._metadata.gateset:
+        #     raise ValueError(f'Operation {operation} is not a supported gate')
+
+        for q in operation.qubits:
+            if q not in self._metadata.qubit_set:
+                raise ValueError(f'Qubit not on device: {q!r}')
+
+        if (
+            len(operation.qubits) == 2
+            and frozenset(operation.qubits) not in self._metadata.qubit_pairs
+        ):
+            raise ValueError(f'Qubit pair is not valid on device: {operation.qubits!r}')
+
+    def __str__(self) -> str:
+        diagram = cirq.TextDiagramDrawer()
+
+        qubits = cast(Set[cirq.GridQubit], self._metadata.qubit_set)
+
+        # Don't print out extras newlines if the row/col doesn't start at 0
+        min_col = min(q.col for q in qubits)
+        min_row = min(q.row for q in qubits)
+
+        for q in qubits:
+            diagram.write(q.col - min_col, q.row - min_row, str(q))
+
+        # Find pairs that are connected by two-qubit gates.
+        Pair = Tuple[cirq.GridQubit, cirq.GridQubit]
+        pairs = sorted({cast(Pair, tuple(pair)) for pair in self._metadata.qubit_pairs})
+
+        # Draw lines between connected pairs. Limit to horizontal/vertical
+        # lines since that is all the diagram drawer can handle.
+        for q1, q2 in pairs:
+            if q1.row == q2.row or q1.col == q2.col:
+                diagram.grid_line(
+                    q1.col - min_col, q1.row - min_row, q2.col - min_col, q2.row - min_row
+                )
+
+        return diagram.render(horizontal_spacing=3, vertical_spacing=2, use_unicode_characters=True)
+
+    def _repr_pretty_(self, p: Any, cycle: bool) -> None:
+        """Creates ASCII diagram for Jupyter, IPython, etc."""
+        # There should never be a cycle, but just in case use the default repr.
+        p.text(repr(self) if cycle else str(self))
+
+    def __repr__(self) -> str:
+        return f'cirq_google.GridDevice({repr(self._metadata)})'
+
+    def _json_dict_(self):
+        return {'metadata': self._metadata}
+
+    @classmethod
+    def _from_json_dict_(cls, metadata, **kwargs):
+        return cls(metadata)
+
+    def _value_equality_values_(self):
+        return self._metadata