Add common gate families as part of adopting gatesets across Cirq.

cirq-core/cirq/__init__.py

@@ -176,6 +176,8 @@
 from cirq.ops import (
     amplitude_damp,
     AmplitudeDampingChannel,
+    AnyIntegerPowerGateFamily,
+    AnyUnitaryGateFamily,
     ArithmeticOperation,
     asymmetric_depolarize,
     AsymmetricDepolarizingChannel,
@@ -245,6 +247,7 @@
     OP_TREE,
     Operation,
     ParallelGate,
+    ParallelGateFamily,
     parallel_gate_op,
     ParallelGateOperation,
     Pauli,

cirq-core/cirq/ops/__init__.py

@@ -76,6 +76,12 @@
     ZPowGate,
 )
 
+from cirq.ops.common_gate_families import (
+    AnyUnitaryGateFamily,
+    AnyIntegerPowerGateFamily,
+    ParallelGateFamily,
+)
+
 from cirq.ops.controlled_gate import (
     ControlledGate,
 )

cirq-core/cirq/ops/common_gate_families.py

@@ -0,0 +1,162 @@
+# Copyright 2021 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.
+
+"""Common Gate Families used in cirq-core"""
+
+from typing import cast, Optional, Type, Union
+
+from cirq.ops import gateset, raw_types, parallel_gate, eigen_gate
+from cirq import protocols
+
+
+class AnyUnitaryGateFamily(gateset.GateFamily):
+    """GateFamily which accepts any N-Qubit unitary gate."""
+
+    def __init__(self, num_qubits: Optional[int] = None) -> None:
+        """Init AnyUnitaryGateFamily
+
+        Args:
+            num_qubits: The GateFamily will accept any unitary gate acting on `num_qubits`.
+                        If left `None`, the GateFamily will accept every unitary gate.
+        Raises:
+            ValueError: If `num_qubits` <= 0.
+        """
+        if num_qubits is not None and num_qubits <= 0:
+            raise ValueError(f'num_qubits: {num_qubits} must be a positive integer.')
+
+        self._num_qubits = num_qubits
+        name = f'{str(num_qubits) if num_qubits else "Any"}-Qubit UnitaryGateFamily'
+        description = 'Accepts any {}unitary gate'.format(
+            f'{num_qubits}-qubit ' if num_qubits else ''
+        )
+        super().__init__(raw_types.Gate, name=name, description=description)
+
+    def _predicate(self, g: raw_types.Gate) -> bool:
+        return (
+            self._num_qubits is None or protocols.num_qubits(g) == self._num_qubits
+        ) and protocols.has_unitary(g)
+
+    def __repr__(self) -> str:
+        return f'cirq.AnyUnitaryGateFamily(num_qubits = {self._num_qubits})'
+
+
+class AnyIntegerPowerGateFamily(gateset.GateFamily):
+    """GateFamily which accepts instances of a given `cirq.EigenGate`, raised to integer power."""
+
+    def __init__(self, gate: Type[eigen_gate.EigenGate]) -> None:
+        """Init AnyIntegerPowerGateFamily
+
+        Args:
+            gate: A subclass of `cirq.EigenGate` s.t. an instance `g` of `gate` will be
+                accepted if `g.exponent` is an integer.
+
+        Raises:
+            ValueError: If `gate` is not a subclass of `cirq.EigenGate`.
+        """
+        if not (isinstance(gate, type) and issubclass(gate, eigen_gate.EigenGate)):
+            raise ValueError(f'{gate} must be a subclass of `cirq.EigenGate`.')
+        super().__init__(
+            gate,
+            name=f'AnyIntegerPowerGateFamily: {gate}',
+            description=f'Accepts any instance `g` of `{gate}` s.t. `g.exponent` is an integer.',
+        )
+
+    def _predicate(self, g: raw_types.Gate) -> bool:
+        if protocols.is_parameterized(g) or not super()._predicate(g):
+            return False
+        exp = cast(eigen_gate.EigenGate, g).exponent  # for mypy
+        return int(exp) == exp
+
+    def __repr__(self) -> str:
+        return f'cirq.AnyIntegerPowerGateFamily({self._gate_str()})'
+
+
+class ParallelGateFamily(gateset.GateFamily):
+    """GateFamily which accepts instances of `cirq.ParallelGate` and it's sub_gate.
+
+    ParallelGateFamily is useful for description and validation of scenarios where multiple
+    copies of a unitary gate can act in parallel. `cirq.ParallelGate` is used to express
+    such a gate with a corresponding unitary `sub_gate` that acts in parallel.
+
+    ParallelGateFamily supports initialization via
+        a) Gate Instance that can be applied in parallel.
+        b) Gate Type whose instances can be applied in parallel.
+
+    In both the cases, the users can specify an additional parameter `max_parallel_allowed` which
+    is used to verify the maximum number of qubits on which any given gate instance can act on.
+
+    To verify containment of a given `cirq.Gate` instance `g`, the gate family verfies that
+        a) `cirq.num_qubits(g)` <= `max_parallel_allowed` if `max_parallel_allowed` is not None.
+        b) `g` or `g.sub_gate` (if `g` is an instance of `cirq.ParallelGate`) is an accepted gate
+            based on type or instance checks depending on the initialization gate type.
+    """
+
+    def __init__(
+        self,
+        gate: Union[Type[raw_types.Gate], raw_types.Gate],
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        max_parallel_allowed: Optional[int] = None,
+    ) -> None:
+        """Inits ParallelGateFamily
+
+        Args:
+            gate: The gate which can act in parallel. It can be a python `type` inheriting from
+                `cirq.Gate` or a non-parameterized instance of a `cirq.Gate`. If an instance of
+                `cirq.ParallelGate` is passed, then the corresponding `gate.sub_gate` is used.
+            name: The name of the gate family.
+            description: Human readable description of the gate family.
+            max_parallel_allowed: The maximum number of qubits on which a given gate `g`
+            can act on. If None, then any number of qubits are allowed.
+        """
+        if isinstance(gate, parallel_gate.ParallelGate):
+            if not max_parallel_allowed:
+                max_parallel_allowed = protocols.num_qubits(gate)
+            gate = cast(parallel_gate.ParallelGate, gate).sub_gate
+        self._max_parallel_allowed = max_parallel_allowed
+        super().__init__(gate, name=name, description=description)
+
+    def _max_parallel_str(self):
+        return self._max_parallel_allowed if self._max_parallel_allowed is not None else 'INF'
+
+    def _default_name(self) -> str:
+        return f'{self._max_parallel_str()} Parallel ' + super()._default_name()
+
+    def _default_description(self) -> str:
+        check_type = r'g == {}' if isinstance(self.gate, raw_types.Gate) else r'isinstance(g, {})'
+        return (
+            f'Accepts\n'
+            f'1. `cirq.Gate` instances `g` s.t. `{check_type.format(self._gate_str())}` OR\n'
+            f'2. `cirq.ParallelGate` instance `g` s.t. `g.sub_gate` satisfies 1. and '
+            f'`cirq.num_qubits(g) <= {self._max_parallel_str()}` OR\n'
+            f'3. `cirq.Operation` instance `op` s.t. `op.gate` satisfies 1. or 2.'
+        )
+
+    def _predicate(self, gate: raw_types.Gate) -> bool:
+        if (
+            self._max_parallel_allowed is not None
+            and protocols.num_qubits(gate) > self._max_parallel_allowed
+        ):
+            return False
+        gate = gate.sub_gate if isinstance(gate, parallel_gate.ParallelGate) else gate
+        return super()._predicate(gate)
+
+    def __repr__(self) -> str:
+        return (
+            f'cirq.ParallelGateFamily(gate={self._gate_str(repr)},'
+            f'name="{self.name}", '
+            f'description=r\'\'\'' + self.description + '\'\'\','
+            f'max_parallel_allowed="{self._max_parallel_allowed}")'
+        )

cirq-core/cirq/ops/common_gate_families_test.py

@@ -0,0 +1,91 @@
+# Copyright 2021 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 pytest
+import sympy
+import cirq
+from cirq.ops.gateset_test import CustomX, CustomXPowGate
+
+
+class UnitaryGate(cirq.Gate):
+    def __init__(self, num_qubits: int) -> None:
+        self._num_qubits = num_qubits
+
+    def _has_unitary_(self) -> bool:
+        return True
+
+    def _num_qubits_(self) -> int:
+        return self._num_qubits
+
+
+def test_any_unitary_gate_family():
+    with pytest.raises(ValueError, match='must be a positive integer'):
+        _ = cirq.AnyUnitaryGateFamily(0)
+
+    for num_qubits in range(1, 6, 2):
+        q = cirq.LineQubit.range(num_qubits)
+        gate = UnitaryGate(num_qubits)
+        for init_num_qubits in [None, num_qubits]:
+            gate_family = cirq.AnyUnitaryGateFamily(init_num_qubits)
+            cirq.testing.assert_equivalent_repr(gate_family)
+            assert gate in gate_family
+            assert gate(*q) in gate_family
+            if init_num_qubits:
+                assert f'{init_num_qubits}' in gate_family.name
+                assert f'{init_num_qubits}' in gate_family.description
+                assert UnitaryGate(num_qubits + 1) not in gate_family
+            else:
+                assert f'Any-Qubit' in gate_family.name
+                assert f'any unitary' in gate_family.description
+
+    assert cirq.SingleQubitGate() not in cirq.AnyUnitaryGateFamily()
+
+
+def test_any_integer_power_gate_family():
+    with pytest.raises(ValueError, match='subclass of `cirq.EigenGate`'):
+        cirq.AnyIntegerPowerGateFamily(gate=cirq.SingleQubitGate)
+    with pytest.raises(ValueError, match='subclass of `cirq.EigenGate`'):
+        cirq.AnyIntegerPowerGateFamily(gate=CustomXPowGate())
+    gate_family = cirq.AnyIntegerPowerGateFamily(CustomXPowGate)
+    cirq.testing.assert_equivalent_repr(gate_family)
+    assert CustomX in gate_family
+    assert CustomX ** 2 in gate_family
+    assert CustomX ** 1.5 not in gate_family
+    assert CustomX ** sympy.Symbol('theta') not in gate_family
+    assert 'CustomXPowGate' in gate_family.name
+    assert '`g.exponent` is an integer' in gate_family.description
+
+
+@pytest.mark.parametrize('gate', [CustomX, cirq.ParallelGate(CustomX, 2), CustomXPowGate])
+@pytest.mark.parametrize('name,description', [(None, None), ("Custom Name", "Custom Description")])
+@pytest.mark.parametrize('max_parallel_allowed', [None, 3])
+def test_parallel_gate_family(gate, name, description, max_parallel_allowed):
+    gate_family = cirq.ParallelGateFamily(
+        gate, name=name, description=description, max_parallel_allowed=max_parallel_allowed
+    )
+    cirq.testing.assert_equivalent_repr(gate_family)
+    for gate_to_test in [CustomX, cirq.ParallelGate(CustomX, 2)]:
+        assert gate_to_test in gate_family
+        assert gate_to_test(*cirq.LineQubit.range(cirq.num_qubits(gate_to_test))) in gate_family
+
+    if isinstance(gate, cirq.ParallelGate) and not max_parallel_allowed:
+        assert gate_family._max_parallel_allowed == cirq.num_qubits(gate)
+        assert cirq.ParallelGate(CustomX, 4) not in gate_family
+    else:
+        assert gate_family._max_parallel_allowed == max_parallel_allowed
+        assert (cirq.ParallelGate(CustomX, 4) in gate_family) == (max_parallel_allowed is None)
+
+    str_to_search = 'Custom' if name else 'Parallel'
+    assert str_to_search in gate_family.name
+    assert str_to_search in gate_family.description

cirq-core/cirq/protocols/json_test_data/spec.py

@@ -25,6 +25,8 @@
     resolver_cache=_class_resolver_dictionary(),
     not_yet_serializable=[
         'Alignment',
+        'AnyIntegerPowerGateFamily',
+        'AnyUnitaryGateFamily',
         'AxisAngleDecomposition',
         'CircuitDag',
         'CircuitDiagramInfo',
@@ -48,6 +50,7 @@
         'ListSweep',
         'DiagonalGate',
         'NeutralAtomDevice',
+        'ParallelGateFamily',
         'PauliInteractionGate',
         'PauliStringPhasor',
         'PauliSum',