Add EngineProcessorTimeSlot to cirq.google.engine (#2794)

* Add EngineProcessorTimeSlot to cirq.google.engine

- This class will be a wrapper to hold timeslots for reservations.

cirq/google/__init__.py

@@ -37,6 +37,7 @@
     EngineJob,
     EngineProgram,
     EngineProcessor,
+    EngineTimeSlot,
     ProtoVersion,
     QuantumEngineSampler,
 )

cirq/google/engine/__init__.py

@@ -32,6 +32,9 @@
 from cirq.google.engine.engine_processor import (
     EngineProcessor,)
 
+from cirq.google.engine.engine_timeslot import (
+    EngineTimeSlot,)
+
 from cirq.google.engine.engine_program import (
     EngineProgram,)
 

cirq/google/engine/client/quantum_v1alpha1/gapic/enums.py

@@ -95,6 +95,26 @@ class Health(enum.IntEnum):
         UNAVAILABLE = 3
 
 
+class QuantumTimeSlot(object):
+
+    class TimeSlotType(enum.IntEnum):
+        """
+        -
+
+        Attributes:
+        TIME_SLOT_TYPE_UNSPECIFIED (int): Default value for compatibility.
+        MAINTENANCE (int): Reserved to run calibration or make changes.
+        OPEN_SWIM (int): Time for anyone to create jobs.
+        RESERVATION (int): One project has exclusive hold to create jobs.
+        UNALLOCATED (int):  Available for reservations to be made
+        """
+        TIME_SLOT_TYPE_UNSPECIFIED = 0
+        MAINTENANCE = 1
+        OPEN_SWIM = 2
+        RESERVATION = 3
+        UNALLOCATED = 4
+
+
 class StreamError(object):
 
     class Code(enum.IntEnum):

cirq/google/engine/engine_timeslot.py

@@ -0,0 +1,42 @@
+# Copyright 2020 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 dataclasses
+import datetime
+
+from typing import Optional
+from cirq.google.engine.client.quantum_v1alpha1.gapic import enums
+
+_DEFAULT_TYPE = enums.QuantumTimeSlot.TimeSlotType.TIME_SLOT_TYPE_UNSPECIFIED
+
+
+@dataclasses.dataclass(frozen=True)
+class EngineTimeSlot:
+    """A python wrapping of a Quantum Engine timeslot.
+
+    Args:
+       start_time: starting datetime of the time slot, usually in local time.
+       end_time: ending datetime of the time slot, usually in local time.
+       slot_type: type of time slot (reservation, open swim, etc)
+       project_id: Google Cloud Platform id of the project, as a string
+       maintenance_title: If a MAINTENANCE period, a string title describing the
+          type of maintenance being done.
+       maintenance_description: If a MAINTENANCE period, a string describing the
+          particulars of the maintenancethe title of the slot
+    """
+    start_time: datetime.datetime
+    end_time: datetime.datetime
+    slot_type: enums.QuantumTimeSlot.TimeSlotType = _DEFAULT_TYPE
+    project_id: Optional[str] = None
+    maintenance_title: Optional[str] = None
+    maintenance_description: Optional[str] = None

cirq/google/engine/engine_timeslot_test.py

@@ -0,0 +1,54 @@
+# Copyright 2020 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 datetime
+
+import cirq
+import cirq.google as cg
+
+from cirq.google.engine.client.quantum_v1alpha1.gapic import enums
+
+
+def test_timeslot_equality():
+    start = datetime.datetime.fromtimestamp(1582592400)
+    end = datetime.datetime.fromtimestamp(1582596000)
+    eq = cirq.testing.equals_tester.EqualsTester()
+    eq.add_equality_group(
+        cg.EngineTimeSlot(start_time=start, end_time=end),
+        cg.EngineTimeSlot(start_time=start, end_time=end),
+        cg.EngineTimeSlot(start_time=start,
+                          end_time=end,
+                          slot_type=enums.QuantumTimeSlot.TimeSlotType.
+                          TIME_SLOT_TYPE_UNSPECIFIED))
+    eq.add_equality_group(
+        cg.EngineTimeSlot(start_time=start, end_time=end, project_id='123456'))
+    eq.add_equality_group(
+        cg.EngineTimeSlot(
+            start_time=start,
+            end_time=end,
+            slot_type=enums.QuantumTimeSlot.TimeSlotType.RESERVATION,
+            project_id='123456'))
+    eq.add_equality_group(
+        cg.EngineTimeSlot(
+            start_time=start,
+            end_time=end,
+            slot_type=enums.QuantumTimeSlot.TimeSlotType.MAINTENANCE,
+            project_id='123456'))
+    eq.add_equality_group(
+        cg.EngineTimeSlot(
+            start_time=start,
+            end_time=end,
+            slot_type=enums.QuantumTimeSlot.TimeSlotType.MAINTENANCE,
+            project_id='123456',
+            maintenance_title="Testing",
+            maintenance_description="Testing some new configuration."))

cirq/protocols/json_serialization_test.py

@@ -195,6 +195,7 @@ def test_fail_to_resolve():
     'EngineJob',
     'EngineProcessor',
     'EngineProgram',
+    'EngineTimeSlot',
     'QuantumEngineSampler',
 
     # enums

docs/api.rst

@@ -500,6 +500,7 @@ Functionality specific to quantum hardware and services from Google.
     cirq.google.EngineJob
     cirq.google.EngineProcessor
     cirq.google.EngineProgram
+    cirq.google.EngineTimeSlot
     cirq.google.Foxtail
     cirq.google.GateOpDeserializer
     cirq.google.GateOpSerializer