Add device_specification to engine code (#2640)

* Add device_specification to engine code

- Adds a method to get the device specification for a
processor_id.

cirq/google/engine/engine.py

@@ -569,7 +569,7 @@ def get_job_results(self,
             return self._get_job_results_v1(result)
         if result_type == 'cirq.api.google.v2.Result':
             # Change path to the new path
-            result['@type'] = 'type.googleapis.com/cirq.google.api.v2.Result'
+            result['@type'] = TYPE_PREFIX + 'cirq.google.api.v2.Result'
             return self._get_job_results_v2(result)
         raise ValueError('invalid result proto version: {}'.format(
             self.proto_version))
@@ -709,6 +709,36 @@ def list_processors(self) -> List[Dict]:
             self.service.projects().processors().list(parent=parent))
         return response['processors']
 
+    def get_device_specification(
+            self,
+            processor_id: str) -> Optional[v2.device_pb2.DeviceSpecification]:
+        """Returns a device specification proto for use in determining
+        information about the device.
+
+        Params:
+            processor_id: The processor identifier within the resource name,
+                where name has the format:
+                `projects/<project_id>/processors/<processor_id>`.
+
+        Returns:
+            Device specification proto or None if it doesn't exist.
+        """
+        processor_name = 'projects/{}/processors/{}'.format(
+            self.project_id, processor_id)
+        response = self._make_request(
+            self.service.projects().processors().get(name=processor_name))
+
+        if 'deviceSpec' not in response:
+            return None
+
+        if '@type' in response['deviceSpec']:
+            del response['deviceSpec']['@type']
+
+        device_spec = v2.device_pb2.DeviceSpecification()
+        gp.json_format.ParseDict(response['deviceSpec'], device_spec)
+
+        return device_spec
+
     def get_latest_calibration(self, processor_id: str
                               ) -> Optional[calibration.Calibration]:
         """Returns metadata about the latest known calibration for a processor.

cirq/google/engine/engine_test.py

@@ -25,6 +25,7 @@
 
 import cirq
 import cirq.google as cg
+from cirq.google.api import v2
 
 _CIRCUIT = cirq.Circuit()
 
@@ -185,6 +186,29 @@
     }
 }
 
+_DEVICE_SPEC = {
+    '@type':
+    'type.googleapis.com/cirq.api.google.v2.DeviceSpecification',
+    'validGateSets': [{
+        'name':
+        'test_set',
+        'validGates': [{
+            'id': 'x',
+            'numberOfQubits': 1,
+            'gateDurationPicos': '1000',
+            'validTargets': ['1q_targets']
+        }]
+    }],
+    'validQubits': ['0_0', '1_1'],
+    'validTargets': [{
+        'name': '1q_targets',
+        'targetOrdering': 'SYMMETRIC',
+        'targets': [{
+            'ids': ['0_0']
+        }]
+    }],
+}
+
 
 def test_job_config_repr():
     v = cirq.google.JobConfig(job_id='my-job-id',
@@ -1050,6 +1074,50 @@ def test_calibration_from_job(build):
     assert calibrations.get.call_args[1]['name'] == calibrationName
 
 
+@mock.patch.object(discovery, 'build')
+def test_device_specification(build):
+    service = mock.Mock()
+    build.return_value = service
+    processors = service.projects().processors()
+    processors.get().execute.return_value = ({'deviceSpec': _DEVICE_SPEC})
+    device_spec = cg.Engine(
+        project_id='myproject').get_device_specification('x')
+    assert processors.get.call_args[1][
+        'name'] == 'projects/myproject/processors/x'
+
+    # Construct expected device proto based on JSON example
+    expected = v2.device_pb2.DeviceSpecification()
+    gs = expected.valid_gate_sets.add()
+    gs.name = 'test_set'
+    gates = gs.valid_gates.add()
+    gates.id = 'x'
+    gates.number_of_qubits = 1
+    gates.gate_duration_picos = 1000
+    gates.valid_targets.extend(['1q_targets'])
+    expected.valid_qubits.extend(['0_0', '1_1'])
+    target = expected.valid_targets.add()
+    target.name = '1q_targets'
+    target.target_ordering = v2.device_pb2.TargetSet.SYMMETRIC
+    new_target = target.targets.add()
+    new_target.ids.extend(['0_0'])
+
+    assert device_spec == expected
+
+
+@mock.patch.object(discovery, 'build')
+def test_missing_device_specification(build):
+    service = mock.Mock()
+    build.return_value = service
+    processors = service.projects().processors()
+    processors.get().execute.return_value = ({})
+    device_spec = cg.Engine(
+        project_id='myproject').get_device_specification('x')
+    assert processors.get.call_args[1][
+        'name'] == 'projects/myproject/processors/x'
+
+    assert device_spec == None
+
+
 @mock.patch.object(discovery, 'build')
 def test_alternative_api_and_key(build):
     disco = ('https://secret.googleapis.com/$discovery/rest?version=vfooo'