[cirqflow] Quantum runtime skeleton - part 2 (#4566)

Skeleton of the rest of `ExecutableGroupResult`

![RequestResponse2 (2)](https://user-images.githubusercontent.com/4967059/136300308-21dd2034-01f7-49a3-84a7-0b0d32928918.png)

Most of these dataclasses only have barebones attributes which may beg the question: "why do we need a class for this?". Rest assured: I have big plans for adding more attributes to things.

This follow #4565 ; splitting up #4556

Author: mpharrigan

cirq-google/cirq_google/__init__.py

@@ -127,6 +127,8 @@
     SharedRuntimeInfo,
     RuntimeInfo,
     ExecutableResult,
+    ExecutableGroupResult,
+    QuantumRuntimeConfiguration,
 )
 
 from cirq_google import experimental

cirq-google/cirq_google/json_resolver_cache.py

@@ -48,4 +48,6 @@ def _class_resolver_dictionary() -> Dict[str, ObjectFactory]:
         'cirq.google.SharedRuntimeInfo': cirq_google.SharedRuntimeInfo,
         'cirq.google.RuntimeInfo': cirq_google.RuntimeInfo,
         'cirq.google.ExecutableResult': cirq_google.ExecutableResult,
+        'cirq.google.ExecutableGroupResult': cirq_google.ExecutableGroupResult,
+        'cirq.google.QuantumRuntimeConfiguration': cirq_google.QuantumRuntimeConfiguration,
     }

cirq-google/cirq_google/json_test_data/spec.py

@@ -60,10 +60,20 @@
             'QuantumExecutableGroup',
             'KeyValueExecutableSpec',
             'ExecutableResult',
+            'ExecutableGroupResult',
+            'QuantumRuntimeConfiguration',
             'RuntimeInfo',
             'SharedRuntimeInfo',
         ]
     },
+    tested_elsewhere=[
+        # Until `AbstractEngineProcessor` is implemented, we are using
+        # `AbstractEngineProcessorShim` and a mocked implementation for the `processor` argument
+        # in tests for `QuantumRuntimeConfiguration` (which is copied into `ExecutableGroupResult`).
+        # Therefore, we test json roundtrippability for these two classes in quantum_runtime_test.py
+        'cirq.google.QuantumRuntimeConfiguration',
+        'cirq.google.ExecutableGroupResult',
+    ],
     resolver_cache=_class_resolver_dictionary(),
     deprecated={},
 )

cirq-google/cirq_google/workflow/__init__.py

@@ -10,4 +10,6 @@
     SharedRuntimeInfo,
     RuntimeInfo,
     ExecutableResult,
+    ExecutableGroupResult,
+    QuantumRuntimeConfiguration,
 )

cirq-google/cirq_google/workflow/_abstract_engine_processor_shim.py

@@ -0,0 +1,28 @@
+# Copyright 2021 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.
+
+
+import abc
+
+import cirq.work
+
+
+class AbstractEngineProcessorShim(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def get_device(self) -> cirq.Device:
+        pass
+
+    @abc.abstractmethod
+    def get_sampler(self) -> cirq.Sampler:
+        pass

cirq-google/cirq_google/workflow/quantum_runtime.py

@@ -15,11 +15,12 @@
 """Runtime information dataclasses that accompany execution of executables."""
 
 import dataclasses
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, List
 
 import cirq
 from cirq import _compat
 from cirq.protocols import dataclass_json_dict
+from cirq_google.workflow._abstract_engine_processor_shim import AbstractEngineProcessorShim
 from cirq_google.workflow.quantum_executable import (
     ExecutableSpec,
 )
@@ -85,3 +86,50 @@ def _json_dict_(self) -> Dict[str, Any]:
 
     def __repr__(self) -> str:
         return _compat.dataclass_repr(self, namespace='cirq_google')
+
+
+@dataclasses.dataclass
+class ExecutableGroupResult:
+    """Results for a `cg.QuantumExecutableGroup`.
+
+    Args:
+        runtime_configuration: The `cg.QuantumRuntimeConfiguration` describing how the
+            `cg.QuantumExecutableGroup` was requested to be executed.
+        shared_runtime_info: A `cg.SharedRuntimeInfo` dataclass containing information gathered
+            during execution of the `cg.QuantumExecutableGroup` which is relevant to all
+            `executable_results`.
+        executable_results: A list of `cg.ExecutableResult`. Each contains results and raw data
+            for an individual `cg.QuantumExecutable`.
+    """
+
+    runtime_configuration: 'QuantumRuntimeConfiguration'
+    shared_runtime_info: SharedRuntimeInfo
+    executable_results: List[ExecutableResult]
+
+    def _json_dict_(self) -> Dict[str, Any]:
+        return dataclass_json_dict(self, namespace='cirq.google')
+
+    def __repr__(self) -> str:
+        return _compat.dataclass_repr(self, namespace='cirq_google')
+
+
+@dataclasses.dataclass
+class QuantumRuntimeConfiguration:
+    """User-requested configuration of how to execute a given `cg.QuantumExecutableGroup`.
+
+    Args:
+        processor: The `cg.AbstractEngineProcessor` responsible for running circuits and providing
+            device information.
+        run_id: A unique `str` identifier for a run. If data already exists for the specified
+            `run_id`, an exception will be raised. If not specified, we will generate a UUID4
+            run identifier.
+    """
+
+    processor: AbstractEngineProcessorShim
+    run_id: Optional[str] = None
+
+    def _json_dict_(self) -> Dict[str, Any]:
+        return dataclass_json_dict(self, namespace='cirq.google')
+
+    def __repr__(self) -> str:
+        return _compat.dataclass_repr(self, namespace='cirq_google')

cirq-google/cirq_google/workflow/quantum_runtime_test.py

@@ -11,19 +11,34 @@
 # 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.
+from dataclasses import dataclass
 
 import cirq
 import cirq_google as cg
 import numpy as np
+from cirq_google.workflow._abstract_engine_processor_shim import AbstractEngineProcessorShim
 from cirq_google.workflow.quantum_executable_test import _get_example_spec
 
 
+@dataclass
+class _MockEngineProcessor(AbstractEngineProcessorShim):
+    def get_device(self) -> cirq.Device:
+        return cg.Sycamore23
+
+    def get_sampler(self) -> cirq.Sampler:
+        return cirq.ZerosSampler()
+
+    def _json_dict_(self):
+        return cirq.obj_to_dict_helper(self, attribute_names=[], namespace='cirq.google.testing')
+
+
 def cg_assert_equivalent_repr(value):
     """cirq.testing.assert_equivalent_repr with cirq_google.workflow imported."""
     return cirq.testing.assert_equivalent_repr(
         value,
         global_vals={
             'cirq_google': cg,
+            '_MockEngineProcessor': _MockEngineProcessor,
         },
     )
 
@@ -46,3 +61,62 @@ def test_executable_result():
         raw_data=cirq.Result(params=cirq.ParamResolver(), measurements={'z': np.ones((1_000, 4))}),
     )
     cg_assert_equivalent_repr(er)
+
+
+def _cg_read_json_gzip(fn):
+    def _testing_resolver(cirq_type: str):
+        if cirq_type == 'cirq.google.testing._MockEngineProcessor':
+            return _MockEngineProcessor
+
+    return cirq.read_json_gzip(fn, resolvers=[_testing_resolver] + cirq.DEFAULT_RESOLVERS)
+
+
+def _assert_json_roundtrip(o, tmpdir):
+    cirq.to_json_gzip(o, f'{tmpdir}/o.json')
+    o2 = _cg_read_json_gzip(f'{tmpdir}/o.json')
+    assert o == o2
+
+
+def test_quantum_runtime_configuration():
+    rt_config = cg.QuantumRuntimeConfiguration(
+        processor=_MockEngineProcessor(),
+        run_id='unit-test',
+    )
+
+    sampler = rt_config.processor.get_sampler()
+    result = sampler.run(cirq.Circuit(cirq.measure(cirq.LineQubit(0), key='z')))
+    assert isinstance(result, cirq.Result)
+
+    assert isinstance(rt_config.processor.get_device(), cirq.Device)
+
+
+def test_quantum_runtime_configuration_serialization(tmpdir):
+    rt_config = cg.QuantumRuntimeConfiguration(
+        processor=_MockEngineProcessor(),
+        run_id='unit-test',
+    )
+    cg_assert_equivalent_repr(rt_config)
+    _assert_json_roundtrip(rt_config, tmpdir)
+
+
+def test_executable_group_result(tmpdir):
+    egr = cg.ExecutableGroupResult(
+        runtime_configuration=cg.QuantumRuntimeConfiguration(
+            processor=_MockEngineProcessor(),
+            run_id='unit-test',
+        ),
+        shared_runtime_info=cg.SharedRuntimeInfo(run_id='my run'),
+        executable_results=[
+            cg.ExecutableResult(
+                spec=_get_example_spec(name=f'test-spec-{i}'),
+                runtime_info=cg.RuntimeInfo(execution_index=i),
+                raw_data=cirq.Result(
+                    params=cirq.ParamResolver(), measurements={'z': np.ones((1_000, 4))}
+                ),
+            )
+            for i in range(3)
+        ],
+    )
+    cg_assert_equivalent_repr(egr)
+    assert len(egr.executable_results) == 3
+    _assert_json_roundtrip(egr, tmpdir)