Add a new proto DeviceParametersDiff which provides a compact way to …

…bundle multiple DeviceParameters and their values (#6583)

The new proto `DeviceParametersDiff` is for a user to compose a RunJobRequest
for invoking RunJob rpc on a Cirq server, in particular to populate the
`RunJobRequest.run_context` field with device parameters overrides to 
customize the circuit(s) execution with some control on the device's samples data.

This is based on a design reviews to add "device parameters overrides"
before executing circuits sweeping.

I renamed some proto type names from similar internal data structure
to prevent reference to internal infrastructures.

cirq-google/cirq_google/api/v2/run_context.proto

@@ -1,5 +1,7 @@
 syntax = "proto3";
 
+import "cirq_google/api/v2/program.proto";
+
 package cirq.google.api.v2;
 
 option java_package = "com.google.cirq.google.api.v2";
@@ -10,6 +12,13 @@ option java_multiple_files = true;
 message RunContext {
   // The parameters for operations in a program.
   repeated ParameterSweep parameter_sweeps = 1;
+
+  // Optional override of select device parameters before program
+  // execution. Note it is permissible to specify the same device parameter
+  // here and in a parameter_sweeps, as sweep.single_sweep.parameter.
+  // If the same parameter is supplied in both places, the provision here in
+  // device_parameters_override will have no effect.
+  DeviceParametersDiff device_parameters_override = 2;
 }
 
 // Specifies how to repeatedly sample a circuit, with or without sweeping over
@@ -100,6 +109,41 @@ message DeviceParameter {
     // by the sweep values themselves.
 }
 
+// A bundle of multiple DeviceParameters and their values.
+// The main use case is to set those parameters with the
+// values from this bundle before executing a circuit sweep.
+// Note multiple device parameters may have common ancestor paths
+// and/or share the same parameter names. A DeviceParametersDiff
+// stores the resource groups hierarchy extracted from the DeviceParameters'
+// paths and maintains a table of strings; thereby storing ancestor resource
+// groups only once, and avoiding repeated storage of common parameter names.
+message DeviceParametersDiff {
+  // A resource group a device parameter belongs to.
+  // The identifier of a resource group is DeviceParameter.path without the
+  // last component.
+  message ResourceGroup {
+    // parent resource group, as an index into the groups repeated field.
+    int32 parent = 1;
+    // as index into the strs repeated field.
+    int32 name = 2;
+  }
+  message Param {
+    // the resource group hosting this parameter key, as index into groups
+    // repeated field.
+    int32 resource_group = 1;
+    // name of this param, as index into the strs repeated field.
+    int32 name = 2;
+    // this param's new value, as message ArgValue to allow variant types,
+    // including bool, string, double, float and arrays.
+    ArgValue value = 3;
+  }
+  repeated ResourceGroup groups = 1;
+  repeated Param params = 2;
+
+  // List of all key, dir, and deletion names in these contents.
+  // ResourceGroup.name, Param.name, and Deletion.name are indexes into this list.
+  repeated string strs = 4;
+}
 
 // A set of values to loop over for a particular parameter.
 message SingleSweep {

cirq-google/cirq_google/api/v2/run_context.py

@@ -0,0 +1,69 @@
+# Copyright 2024 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 functools
+from typing import Sequence
+from cirq_google.api.v2 import program_pb2
+from cirq_google.api.v2 import run_context_pb2
+
+
+# The special index of an empty directory path [].
+_EMPTY_RESOURCE_PATH_IDX = -1
+
+
+def to_device_parameters_diff(
+    device_params: Sequence[tuple[run_context_pb2.DeviceParameter, program_pb2.ArgValue]]
+) -> run_context_pb2.DeviceParametersDiff:
+    """Constructs a DeviceParametersDiff from multiple DeviceParameters and values.
+
+    Args:
+        device_params: a list of (DeviceParameter, value) pairs.
+
+    Returns:
+        a DeviceParametersDiff, which comprises the entire device_params.
+    """
+    diff = run_context_pb2.DeviceParametersDiff()
+
+    @functools.lru_cache(maxsize=None)
+    def token_id(s: str) -> int:
+        """Computes the index of s in the string table diff.strs."""
+        idx = len(diff.strs)
+        diff.strs.append(s)
+        return idx
+
+    # Maps a resource group path to its index in diff.groups.
+    resource_groups_index: dict[tuple[str, ...], int] = {tuple(): _EMPTY_RESOURCE_PATH_IDX}
+
+    def resource_path_id(path: tuple[str, ...]) -> int:
+        """Computes the index of a path in diff.groups."""
+        idx = resource_groups_index.get(path, None)
+        if idx is not None:
+            return idx
+        # Recursive call to get the assigned index of the parent. Note the base case
+        # of the empty path, which returns _EMPTY_RESOURCE_PATH_IDX.
+        parent_id = resource_path_id(path[:-1])
+        # This path has not been seen. It will be appended to diff.groups, with idx as
+        # the size of diff.groups before appending.
+        idx = len(diff.groups)
+        diff.groups.add(parent=parent_id, name=token_id(path[-1]))
+        resource_groups_index[path] = idx
+        return idx
+
+    for device_param, value in device_params:
+        resource_path = tuple(device_param.path[:-1])
+        param_name = device_param.path[-1]
+        path_id = resource_path_id(resource_path)
+        diff.params.add(name=token_id(param_name), resource_group=path_id, value=value)
+
+    return diff