Add InternalTag to support non-public tags (#7040)

* Add InternalTag to support non-public tags

- This will be a container to support tags that are not
currently public, similar to how InternalGate works.

* Forgot to add json files.

* Update cirq-google/cirq_google/ops/internal_tag.py

Co-authored-by: Pavol Juhas <[email protected]>

* address comments

---------

Co-authored-by: Pavol Juhas <[email protected]>

Author: dstrain115

cirq-google/cirq_google/__init__.py

@@ -59,6 +59,7 @@
     FSimGateFamily as FSimGateFamily,
     FSimViaModelTag as FSimViaModelTag,
     InternalGate as InternalGate,
+    InternalTag as InternalTag,
     PhysicalZTag as PhysicalZTag,
     SYC as SYC,
     SycamoreGate as SycamoreGate,

cirq-google/cirq_google/json_resolver_cache.py

@@ -80,4 +80,5 @@ def _old_xmon(*args, **kwargs):
         'cirq.google.DeviceParameter': cirq_google.study.device_parameter.DeviceParameter,
         'cirq.google.Metadata': cirq_google.study.device_parameter.Metadata,
         'InternalGate': cirq_google.InternalGate,
+        'InternalTag': cirq_google.InternalTag,
     }

cirq-google/cirq_google/json_test_data/InternalTag.json

@@ -0,0 +1,7 @@
+{
+    "cirq_type": "InternalTag",
+    "name": "IdleWaitTag",
+    "package": "internal.module",
+    "phase_match": true,
+    "pad_ns": 20.0
+}

cirq-google/cirq_google/json_test_data/InternalTag.repr

@@ -0,0 +1 @@
+cirq_google.InternalTag(name="IdleWaitTag", package="internal.module", phase_match=True, pad_ns=20.0)

cirq-google/cirq_google/ops/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Qubit Gates, Operations, and Tags useful for Google devices. """
+"""Qubit Gates, Operations, and Tags useful for Google devices."""
 
 from cirq_google.ops.calibration_tag import CalibrationTag as CalibrationTag
 
@@ -28,6 +28,8 @@
 
 from cirq_google.ops.internal_gate import InternalGate as InternalGate
 
+from cirq_google.ops.internal_tag import InternalTag as InternalTag
+
 from cirq_google.ops.dynamical_decoupling_tag import (
     DynamicalDecouplingTag as DynamicalDecouplingTag,
 )

cirq-google/cirq_google/ops/internal_tag.py

@@ -0,0 +1,59 @@
+# Copyright 2025 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 value
+
+
+@value.value_equality
+class InternalTag:
+    """InternalTag is a placeholder tag for internal tags that
+    are not specified publicly.
+
+    These tags can hold the information needed to instantiate a
+    tag specified in an internal library.
+    """
+
+    def __init__(self, name: str, package: str, **kwargs):
+        """Instantiates an InternalTag.
+
+        Arguments:
+            name: Tag class name.
+            package: The python module of the tag.
+            **kwargs: Arbitrary keyword parameters that should be passed to the tag.
+        """
+        self.name = name
+        self.package = package
+        self.tag_args = kwargs
+
+    def __str__(self):
+        tag_args = ', '.join(f'{k}={v}' for k, v in self.tag_args.items())
+        return f'{self.package}.{self.name}({tag_args})'
+
+    def __repr__(self) -> str:
+        tag_args = ', '.join(f'{k}={v!r}' for k, v in self.tag_args.items())
+        if tag_args:
+            tag_args = ', ' + tag_args
+        return f"cirq_google.InternalTag(name='{self.name}', package='{self.package}'{tag_args})"
+
+    def _json_dict_(self) -> Dict[str, Any]:
+        return dict(name=self.name, package=self.package, **self.tag_args)
+
+    def _value_equality_values_(self):
+        try:
+            tag_args_eq_values = frozenset(self.tag_args.items())
+        except TypeError:
+            tag_args_eq_values = self.tag_args
+        return (self.name, self.package, tag_args_eq_values)

cirq-google/cirq_google/ops/internal_tag_test.py

@@ -0,0 +1,55 @@
+# Copyright 2025 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_google
+import pytest
+
+
+def test_internal_tag():
+    g = cirq_google.InternalTag(
+        name="IdleWaitTag",
+        package='internal_module',
+        phase_match=True,
+        pad_ns=10,
+        pad_start=True,
+        pad_end=False,
+    )
+    assert (
+        str(g) == "internal_module.IdleWaitTag("
+        "phase_match=True, pad_ns=10, pad_start=True, pad_end=False)"
+    )
+    assert (
+        repr(g) == "cirq_google.InternalTag(name='IdleWaitTag', "
+        "package='internal_module', phase_match=True, "
+        "pad_ns=10, pad_start=True, pad_end=False)"
+    )
+
+
+def test_internal_tag_with_no_args():
+    g = cirq_google.InternalTag(name="TagWithNoArgs", package='test')
+    assert str(g) == 'test.TagWithNoArgs()'
+    assert repr(g) == "cirq_google.InternalTag(name='TagWithNoArgs', package='test')"
+
+
+def test_internal_tag_with_hashable_args_is_hashable():
+    hashable = cirq_google.InternalTag(
+        name="TagWithHashableArgs", package='test', foo=1, bar="2", baz=(("a", 1),)
+    )
+    _ = hash(hashable)
+
+    unhashable = cirq_google.InternalTag(
+        name="TagWithUnHashableArgs", package='test', foo=1, bar="2", baz={"a": 1}
+    )
+    with pytest.raises(TypeError, match="unhashable"):
+        _ = hash(unhashable)