Add CalibrationTag (#3423)

* Add CalibrationTag

- Adds a tag to designate a token on a tag to use a specific
calibration.
- Since we are adjusting the name from Focused Calibration to
Calibration API, I have changed this from the formerly named
FocusedCalibrationTag to CalibrationTag

cirq/google/__init__.py

@@ -55,6 +55,7 @@
 )
 
 from cirq.google.ops import (
+    CalibrationTag,
     PhysicalZTag,
     SycamoreGate,
     SYC,

cirq/google/ops/__init__.py

@@ -12,10 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from cirq.google.ops.calibration_tag import (
+    CalibrationTag,)
+
+from cirq.google.ops.physical_z_tag import (
+    PhysicalZTag,)
+
 from cirq.google.ops.sycamore_gate import (
     SycamoreGate,
     SYC,
 )
-
-from cirq.google.ops.physical_z_tag import (
-    PhysicalZTag,)

cirq/google/ops/calibration_tag.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.
+from typing import Any, Dict
+
+from cirq import protocols
+
+
+class CalibrationTag:
+    """Tag to add onto an Operation that specifies alternate parameters.
+
+    Google devices support the ability to run a procedure from calibration API
+    that can tune the device for a specific circuit.  This will return a token
+    as part of the result.  Attaching a `CalibrationTag` with that token
+    specifies that the gate should use parameters from that specific
+    calibration, instead of the default gate parameters.
+    """
+
+    def __init__(self, token: str):
+        self.token = token
+
+    def __str__(self) -> str:
+        return f'CalibrationTag({self.token!r})'
+
+    def __repr__(self) -> str:
+        return f'cirq.google.CalibrationTag({self.token!r})'
+
+    def _json_dict_(self) -> Dict[str, Any]:
+        return protocols.obj_to_dict_helper(self, ['token'])
+
+    def __eq__(self, other) -> bool:
+        return (isinstance(other, CalibrationTag) and self.token == other.token)

cirq/google/ops/calibration_tag_test.py

@@ -0,0 +1,29 @@
+# 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 cirq
+
+
+def test_equality():
+    eq = cirq.testing.EqualsTester()
+    eq.add_equality_group(cirq.google.CalibrationTag('blah'),
+                          cirq.google.CalibrationTag('blah'))
+    eq.add_equality_group(cirq.google.CalibrationTag('blah2'))
+
+
+def test_str_repr():
+    example_tag = cirq.google.CalibrationTag('foo')
+    assert str(example_tag) == 'CalibrationTag(\'foo\')'
+    assert repr(example_tag) == 'cirq.google.CalibrationTag(\'foo\')'
+    cirq.testing.assert_equivalent_repr(example_tag,
+                                        setup_code=('import cirq\n'))

cirq/protocols/json_serialization.py

@@ -85,6 +85,7 @@ def two_qubit_matrix_gate(matrix):
                 'CCXPowGate': cirq.CCXPowGate,
                 'CCZPowGate': cirq.CCZPowGate,
                 'CNotPowGate': cirq.CNotPowGate,
+                'CalibrationTag': cirq.google.CalibrationTag,
                 'ControlledGate': cirq.ControlledGate,
                 'ControlledOperation': cirq.ControlledOperation,
                 'CSwapGate': cirq.CSwapGate,

cirq/protocols/json_test_data/CalibrationTag.json

@@ -0,0 +1,4 @@
+{
+      "cirq_type": "CalibrationTag",
+      "token": "xeb"
+}

cirq/protocols/json_test_data/CalibrationTag.repr

@@ -0,0 +1 @@
+cirq.google.CalibrationTag('xeb')

rtd_docs/api.rst

@@ -524,6 +524,7 @@ Functionality specific to quantum hardware and services from Google.
     cirq.google.AnnealSequenceSearchStrategy
     cirq.google.Bristlecone
     cirq.google.Calibration
+    cirq.google.CalibrationTag
     cirq.google.ConvertToSqrtIswapGates
     cirq.google.ConvertToSycamoreGates
     cirq.google.ConvertToXmonGates