Add utility methods for efficiently constructing circuits and moments

Author: maffoo

cirq-core/cirq/__init__.py

@@ -66,10 +66,12 @@
 from cirq.circuits import (
     AbstractCircuit,
     Alignment,
+    c,
     Circuit,
     CircuitOperation,
     FrozenCircuit,
     InsertStrategy,
+    m,
     Moment,
     PointOptimizationSummary,
     PointOptimizer,

cirq-core/cirq/circuits/__init__.py

@@ -20,6 +20,7 @@
 
 from cirq.circuits.circuit import AbstractCircuit, Alignment, Circuit
 from cirq.circuits.circuit_operation import CircuitOperation
+from cirq.circuits.circuit_util import c, m
 from cirq.circuits.frozen_circuit import FrozenCircuit
 from cirq.circuits.insert_strategy import InsertStrategy
 

cirq-core/cirq/circuits/circuit_util.py

@@ -0,0 +1,43 @@
+# 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 TYPE_CHECKING
+
+from cirq.circuits.frozen_circuit import FrozenCircuit
+from cirq.circuits.moment import Moment
+
+if TYPE_CHECKING:
+    import cirq
+
+
+def m(*ops: 'cirq.Operation') -> 'cirq.Moment':
+    """Constructs a Moment from Operations.
+
+    This is shorthand for calling Moment.from_ops.
+
+    Args:
+        *ops: Operations to be included in the new moment.
+    """
+    return Moment.from_ops(*ops)
+
+
+def c(*moments: 'cirq.Moment') -> 'cirq.FrozenCircuit':
+    """Constructs a FrozenCircuit from Moments.
+
+    This is shorthand for calling FrozenCircuit.from_moments.
+
+    Args:
+        *moments: Moments to be included in the new circuit.
+    """
+    return FrozenCircuit.from_moments(*moments)

cirq-core/cirq/circuits/circuit_util_test.py

@@ -0,0 +1,26 @@
+# 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
+
+
+def test_cirq_m():
+    moment = cirq.m(cirq.X(cirq.q(0)), cirq.Y(cirq.q(1)))
+    assert isinstance(moment, cirq.Moment)
+
+
+def test_cirq_c():
+    qubits = cirq.LineQubit.range(10)
+    circuit = cirq.c(cirq.m(*cirq.H.on_each(*qubits)), cirq.m(cirq.measure(*qubits)))
+    assert isinstance(circuit, cirq.FrozenCircuit)

cirq-core/cirq/circuits/moment.py

@@ -19,6 +19,7 @@
     AbstractSet,
     Any,
     Callable,
+    cast,
     Dict,
     FrozenSet,
     Iterable,
@@ -80,17 +81,26 @@ class Moment:
             are no such operations, returns an empty Moment.
     """
 
-    def __init__(self, *contents: 'cirq.OP_TREE') -> None:
+    def __init__(self, *contents: 'cirq.OP_TREE', _flatten_contents: bool = True) -> None:
         """Constructs a moment with the given operations.
 
         Args:
             contents: The operations applied within the moment.
                 Will be flattened and frozen into a tuple before storing.
+            _flatten_contents: If True, use flatten_to_ops to convert
+                the OP_TREE of contents into a tuple of Operation. If False,
+                we skip flattening and assume that contents already consists
+                of individual operations. This is used internally by helper
+                methods to avoid unnecessary validation.
 
         Raises:
             ValueError: A qubit appears more than once.
         """
-        self._operations = tuple(op_tree.flatten_to_ops(contents))
+        self._operations = (
+            tuple(op_tree.flatten_to_ops(contents))
+            if _flatten_contents
+            else cast(Tuple['cirq.Operation'], contents)
+        )
         self._sorted_operations: Optional[Tuple['cirq.Operation', ...]] = None
 
         # An internal dictionary to support efficient operation access by qubit.
@@ -106,6 +116,10 @@ def __init__(self, *contents: 'cirq.OP_TREE') -> None:
         self._measurement_key_objs: Optional[FrozenSet['cirq.MeasurementKey']] = None
         self._control_keys: Optional[FrozenSet['cirq.MeasurementKey']] = None
 
+    @classmethod
+    def from_ops(cls, *ops: 'cirq.Operation') -> 'cirq.Moment':
+        return cls(*ops, _flatten_contents=False)
+
     @property
     def operations(self) -> Tuple['cirq.Operation', ...]:
         return self._operations