Add get_engine_device shortcut (#3225)

- Adds a function to get a device from a device specification
without having to initialize an Engine object.

cirq/google/__init__.py

@@ -34,6 +34,7 @@
     ProtoVersion,
     QuantumEngineSampler,
     get_engine,
+    get_engine_device,
     get_engine_sampler,
 )
 

cirq/google/engine/__init__.py

@@ -21,6 +21,7 @@
 from cirq.google.engine.engine import (
     Engine,
     get_engine,
+    get_engine_device,
     ProtoVersion,
 )
 

cirq/google/engine/engine.py

@@ -28,7 +28,8 @@
 import os
 import random
 import string
-from typing import Dict, List, Optional, Sequence, TypeVar, Union, TYPE_CHECKING
+from typing import (Dict, Iterable, List, Optional, Sequence, TypeVar, Union,
+                    TYPE_CHECKING)
 
 from google.protobuf import any_pb2
 
@@ -553,3 +554,11 @@ def get_engine(project_id: Optional[str] = None) -> Engine:
             f'Environment variable {env_project_id} is not set.')
 
     return Engine(project_id=project_id)
+
+
+def get_engine_device(processor_id: str,
+                      project_id: Optional[str] = None,
+                      gatesets: Iterable[sgs.SerializableGateSet] = ()
+                     ) -> 'cirq.Device':
+    return get_engine(project_id).get_processor(processor_id).get_device(
+        gatesets)

cirq/google/engine/engine_test.py

@@ -721,3 +721,54 @@ def test_get_engine(build):
         with pytest.raises(EnvironmentError, match='GOOGLE_CLOUD_PROJECT'):
             _ = cirq.google.get_engine()
         _ = cirq.google.get_engine('project!')
+
+
+@mock.patch('cirq.google.engine.engine_client.EngineClient.get_processor')
+def test_get_engine_device(get_processor):
+    device_spec = _to_any(
+        Merge(
+            """
+valid_gate_sets: [{
+    name: 'test_set',
+    valid_gates: [{
+        id: 'x',
+        number_of_qubits: 1,
+        gate_duration_picos: 1000,
+        valid_targets: ['1q_targets']
+    }]
+}],
+valid_qubits: ['0_0', '1_1'],
+valid_targets: [{
+    name: '1q_targets',
+    target_ordering: SYMMETRIC,
+    targets: [{
+        ids: ['0_0']
+    }]
+}]
+""", v2.device_pb2.DeviceSpecification()))
+
+    gate_set = cg.SerializableGateSet(
+        gate_set_name='x_gate_set',
+        serializers=[
+            cg.GateOpSerializer(gate_type=cirq.XPowGate,
+                                serialized_gate_id='x',
+                                args=[])
+        ],
+        deserializers=[
+            cg.GateOpDeserializer(serialized_gate_id='x',
+                                  gate_constructor=cirq.XPowGate,
+                                  args=[])
+        ],
+    )
+
+    get_processor.return_value = qtypes.QuantumProcessor(
+        device_spec=device_spec)
+    device = cirq.google.get_engine_device('rainbow',
+                                           'project',
+                                           gatesets=[gate_set])
+    assert set(device.qubits) == {cirq.GridQubit(0, 0), cirq.GridQubit(1, 1)}
+    device.validate_operation(cirq.X(cirq.GridQubit(0, 0)))
+    with pytest.raises(ValueError):
+        device.validate_operation(cirq.X(cirq.GridQubit(1, 2)))
+    with pytest.raises(ValueError):
+        device.validate_operation(cirq.Y(cirq.GridQubit(0, 0)))

docs/api.rst

@@ -501,6 +501,7 @@ Functionality specific to quantum hardware and services from Google.
     cirq.google.SYC_GATESET
     cirq.google.XMON
     cirq.google.get_engine
+    cirq.google.get_engine_device
     cirq.google.get_engine_sampler
     cirq.google.line_on_device
     cirq.google.optimized_for_sycamore