Make _create_transformer_with_kwargs a public method

cirq-core/cirq/__init__.py

@@ -357,6 +357,7 @@
     CompilationTargetGateset,
     CZTargetGateset,
     compute_cphase_exponents_for_fsim_decomposition,
+    create_transformer_with_kwargs,
     decompose_clifford_tableau_to_operations,
     decompose_cphase_into_two_fsim,
     decompose_multi_controlled_x,

cirq-core/cirq/transformers/__init__.py

@@ -43,6 +43,7 @@
 )
 
 from cirq.transformers.target_gatesets import (
+    create_transformer_with_kwargs,
     CompilationTargetGateset,
     CZTargetGateset,
     SqrtIswapTargetGateset,

cirq-core/cirq/transformers/target_gatesets/__init__.py

@@ -15,6 +15,7 @@
 """Gatesets which can act as compilation targets in Cirq."""
 
 from cirq.transformers.target_gatesets.compilation_target_gateset import (
+    create_transformer_with_kwargs,
     CompilationTargetGateset,
     TwoQubitCompilationTargetGateset,
 )

cirq-core/cirq/transformers/target_gatesets/compilation_target_gateset.py

@@ -29,15 +29,44 @@
     import cirq
 
 
-def _create_transformer_with_kwargs(func: 'cirq.TRANSFORMER', **kwargs) -> 'cirq.TRANSFORMER':
-    """Hack to capture additional keyword arguments to transformers while preserving mypy type."""
+def create_transformer_with_kwargs(transformer: 'cirq.TRANSFORMER', **kwargs) -> 'cirq.TRANSFORMER':
+    """Method to capture additional keyword arguments to transformers while preserving mypy type.
+
+    Returns a `cirq.TRANSFORMER` which, when called with a circuit and transformer context, is
+    equivalent to calling `transformer(circuit, context=context, **kwargs)`. It is often useful to
+    capture keyword arguments of a transformer before passing them as an argument to an API that
+    expects `cirq.TRANSFORMER`. For example:
+
+    >>> def run_transformers(transformers: List[cirq.TRANSFORMER]):
+    >>>     for transformer in transformers:
+    >>>         transformer(circuit, context=context)
+    >>>
+    >>> transformers: List[cirq.TRANSFORMER] = []
+    >>> transformers.append(
+    >>>     cirq.create_transformer_with_kwargs(
+    >>>         cirq.expand_composite, no_decomp=lambda op: cirq.num_qubits(op) <= 2
+    >>>     )
+    >>> )
+    >>> transformers.append(cirq.create_transformer_with_kwargs(cirq.merge_k_qubit_gates, k=2))
+    >>> run_transformers(transformers)
+
+
+    Args:
+         transformer: A `cirq.TRANSFORMER` for which additional kwargs should be captured.
+         **kwargs: The keyword arguments which should be captured and passed to `transformer`.
+
+    Returns:
+        A `cirq.TRANSFORMER` method `transformer_with_kwargs`, s.t. executing
+        `transformer_with_kwargs(circuit, context=context)` is equivalent to executing
+        `transformer(circuit, context=context, **kwargs)`.
+    """
 
-    def transformer(
+    def transformer_with_kwargs(
         circuit: 'cirq.AbstractCircuit', *, context: Optional['cirq.TransformerContext'] = None
     ) -> 'cirq.AbstractCircuit':
-        return func(circuit, context=context, **kwargs)  # type: ignore
+        return transformer(circuit, context=context, **kwargs)  # type: ignore
 
-    return transformer
+    return transformer_with_kwargs
 
 
 class CompilationTargetGateset(ops.Gateset, metaclass=abc.ABCMeta):
@@ -93,11 +122,11 @@ def _intermediate_result_tag(self) -> Hashable:
     def preprocess_transformers(self) -> List['cirq.TRANSFORMER']:
         """List of transformers which should be run before decomposing individual operations."""
         return [
-            _create_transformer_with_kwargs(
+            create_transformer_with_kwargs(
                 expand_composite.expand_composite,
                 no_decomp=lambda op: protocols.num_qubits(op) <= self.num_qubits,
             ),
-            _create_transformer_with_kwargs(
+            create_transformer_with_kwargs(
                 merge_k_qubit_gates.merge_k_qubit_unitaries,
                 k=self.num_qubits,
                 rewriter=lambda op: op.with_tags(self._intermediate_result_tag),

cirq-google/cirq_google/transformers/target_gatesets/sycamore_gateset.py

@@ -19,9 +19,6 @@
 
 import cirq
 from cirq.protocols.decompose_protocol import DecomposeResult
-from cirq.transformers.target_gatesets.compilation_target_gateset import (
-    _create_transformer_with_kwargs,
-)
 from cirq_google import ops
 from cirq_google.transformers.analytical_decompositions import two_qubit_to_sycamore
 
@@ -137,10 +134,10 @@ def __init__(
     @property
     def preprocess_transformers(self) -> List[cirq.TRANSFORMER]:
         return [
-            _create_transformer_with_kwargs(
+            cirq.create_transformer_with_kwargs(
                 cirq.expand_composite, no_decomp=lambda op: cirq.num_qubits(op) <= self.num_qubits
             ),
-            _create_transformer_with_kwargs(
+            cirq.create_transformer_with_kwargs(
                 merge_swap_rzz_and_2q_unitaries,
                 intermediate_result_tag=self._intermediate_result_tag,
             ),

cirq-ionq/cirq_ionq/ionq_gateset.py

@@ -18,9 +18,6 @@
 from typing import List
 
 import cirq
-from cirq.transformers.target_gatesets.compilation_target_gateset import (
-    _create_transformer_with_kwargs,
-)
 
 
 class IonQTargetGateset(cirq.TwoQubitCompilationTargetGateset):
@@ -85,7 +82,7 @@ def _decompose_two_qubit_operation(self, op: cirq.Operation, _) -> cirq.OP_TREE:
     def preprocess_transformers(self) -> List['cirq.TRANSFORMER']:
         """List of transformers which should be run before decomposing individual operations."""
         return [
-            _create_transformer_with_kwargs(
+            cirq.create_transformer_with_kwargs(
                 cirq.expand_composite, no_decomp=lambda op: cirq.num_qubits(op) <= self.num_qubits
             )
         ]