Add Parameter to cirq_google (quantumlib#6102)

* Add Parameter to cirq_google

- This object will be able to store device parameters
and is intended to be attached as a sweep meta-data.
- Add study __init__  as a cirq_google module.

Co-authored-by: Victory Omole <vtomole2@gmail.com>

cirq-google/cirq_google/__init__.py

@@ -131,6 +131,8 @@
     SimulatedProcessorWithLocalDeviceRecord,
 )
 
+from cirq_google import study
+
 from cirq_google import experimental
 
 

cirq-google/cirq_google/json_resolver_cache.py

@@ -84,4 +84,5 @@ def _old_xmon(*args, **kwargs):
         'cirq.google.EngineResult': cirq_google.EngineResult,
         'cirq.google.GridDevice': cirq_google.GridDevice,
         'cirq.google.GoogleCZTargetGateset': cirq_google.GoogleCZTargetGateset,
+        'cirq.google.DeviceParameter': cirq_google.study.device_parameter.DeviceParameter,
     }

cirq-google/cirq_google/json_test_data/cirq.google.DeviceParameter.json

@@ -0,0 +1,10 @@
+{
+  "cirq_type": "cirq.google.DeviceParameter",
+  "path": [
+    "test",
+    "subdir",
+    "key"
+  ],
+  "idx": 4,
+  "value": 7.5
+}

cirq-google/cirq_google/json_test_data/cirq.google.DeviceParameter.repr

@@ -0,0 +1 @@
+cirq_google.study.device_parameter.DeviceParameter(path=['test', 'subdir', 'key'], idx=4, value=7.5)

cirq-google/cirq_google/json_test_data/spec.py

@@ -63,6 +63,7 @@
             'EngineResult',
             'GridDevice',
             'GoogleCZTargetGateset',
+            'DeviceParameter',
         ]
     },
     resolver_cache=_class_resolver_dictionary(),

cirq-google/cirq_google/study/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2023 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.
+
+"""Classes for running sweeps particular to Google hardware."""
+
+from cirq_google.study.device_parameter import DeviceParameter

cirq-google/cirq_google/study/device_parameter.py

@@ -0,0 +1,70 @@
+# Copyright 2023 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, Optional, Sequence
+import dataclasses
+from typing_extensions import Protocol
+import cirq
+
+
+class SupportsDeviceParameter(Protocol):
+    """Protocol for using device parameter keys.
+
+    Args:
+       path: path of the key to modify, with each sub-folder as a string
+           entry in a list.
+       idx: If this key is an array, which index to modify.
+       value: value of the parameter to be set, if any.
+    """
+
+    path: Sequence[str]
+    idx: Optional[int] = None
+    value: Optional[Any] = None
+
+
+@dataclasses.dataclass
+class DeviceParameter(SupportsDeviceParameter):
+    """Class for specifying device parameters.
+
+    For instance, varying the length of pulses, timing, etc.
+    This class is intended to be attached to a cirq.Points
+    or cirq.Linspace sweep object as a metadata attribute.
+
+    Args:
+       path: path of the key to modify, with each sub-folder as a string
+           entry in a list.
+       idx: If this key is an array, which index to modify.
+       value: value of the parameter to be set, if any.
+    """
+
+    path: Sequence[str]
+    idx: Optional[int] = None
+    value: Optional[Any] = None
+
+    def __repr__(self) -> str:
+        return (
+            'cirq_google.study.DeviceParameter('
+            f'path={self.path!r}, idx={self.idx}, value={self.value!r})'
+        )
+
+    @classmethod
+    def _json_namespace_(cls) -> str:
+        return 'cirq.google'
+
+    @classmethod
+    def _from_json_dict_(cls, path, idx, value, **kwargs):
+        return DeviceParameter(path=path, idx=idx, value=value)
+
+    def _json_dict_(self) -> Dict[str, Any]:
+        return cirq.obj_to_dict_helper(self, ["path", "idx", "value"])

cirq-google/cirq_google/study/device_parameter_test.py

@@ -0,0 +1,20 @@
+# Copyright 2023 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
+import cirq_google
+
+
+def test_parameters():
+    param = cirq_google.study.DeviceParameter(path=('test', 'subdir'), idx=2, value='tmp')
+    cirq.testing.assert_equivalent_repr(param, global_vals={'cirq_google': cirq_google})